rosa/vernier
1
0
Fork 0
Code Issues 8 Pull requests 1 Projects Releases Packages 1 Wiki Activity Actions

domain: Anchor mint/displace vocabulary for password-reset confirmations in the glossary #82

New issue
Closed
opened 2026-07-04 02:02:40 +00:00 by rosa · 2 comments
rosa commented 2026-07-04 02:02:40 +00:00
Owner
Copy link

This was generated by AI during triage.

Split out of #79, which resolved the authorization-code claim/redeem/consume drift; the reviews of PR #76 noted the same kind of glossary gap here.

Location: password-reset confirmation doc comments, port docs, and conformance-test names across the domain port, service, adapters, and test suites
Severity: Code health — ubiquitous-language gap

Problem

The password-reset confirmation flow speaks a consistent two-term vocabulary that the glossary never anchors:

  • mint — creating a confirmation (and, more broadly, access tokens and authorization codes: "mint a 30-minute confirmation", "Mint a new access token").
  • displace — the replacement semantics: minting a new reset confirmation atomically displaces any prior reset confirmation for the same user, so at most one reset link is valid per user (issue #59, PR #76).

Unlike #79 this is not drift — usage is already consistent across the port, service, Postgres adapter, mocks, and test suites — but neither term has a CONTEXT.md entry, and CONTEXT.md has no Confirmation entry at all. New code (or reviews) have no written anchor to check against, which is exactly how #79's "claim" happened.

Suggested fix

A small /domain-modeling pass:

  1. Add a Confirmation entry to the CONTEXT.md glossary (the identifier + hashed-verifier credential used for email confirmation and password reset, with its action types).
  2. Anchor mint and displace — either within that entry or as glossary terms — stating the displacement rule: minting a reset confirmation displaces prior reset confirmations for that user only, leaving other action types and other users untouched.
  3. Decide whether "mint" is confirmation-specific or the general term for creating any credential (its current usage spans tokens and codes), and word the entry accordingly.
  4. Sweep for stray synonyms (create/issue/replace/revoke used where mint/displace is meant) once the anchor exists.

No behavior changes — documentation, naming, and glossary only.

> *This was generated by AI during triage.* Split out of #79, which resolved the authorization-code claim/redeem/consume drift; the reviews of PR #76 noted the same kind of glossary gap here. **Location:** password-reset confirmation doc comments, port docs, and conformance-test names across the domain port, service, adapters, and test suites **Severity:** Code health — ubiquitous-language gap ## Problem The password-reset confirmation flow speaks a consistent two-term vocabulary that the glossary never anchors: - **mint** — creating a confirmation (and, more broadly, access tokens and authorization codes: "mint a 30-minute confirmation", "Mint a new access token"). - **displace** — the replacement semantics: minting a new reset confirmation atomically displaces any prior reset confirmation for the same user, so at most one reset link is valid per user (issue #59, PR #76). Unlike #79 this is not drift — usage is already consistent across the port, service, Postgres adapter, mocks, and test suites — but neither term has a CONTEXT.md entry, and CONTEXT.md has no **Confirmation** entry at all. New code (or reviews) have no written anchor to check against, which is exactly how #79's "claim" happened. ## Suggested fix A small `/domain-modeling` pass: 1. Add a **Confirmation** entry to the CONTEXT.md glossary (the identifier + hashed-verifier credential used for email confirmation and password reset, with its action types). 2. Anchor **mint** and **displace** — either within that entry or as glossary terms — stating the displacement rule: minting a reset confirmation displaces prior reset confirmations for that user only, leaving other action types and other users untouched. 3. Decide whether "mint" is confirmation-specific or the general term for creating any credential (its current usage spans tokens and codes), and word the entry accordingly. 4. Sweep for stray synonyms (create/issue/replace/revoke used where mint/displace is meant) once the anchor exists. No behavior changes — documentation, naming, and glossary only.
rosa commented 2026-07-04 02:20:31 +00:00
Author
Owner
Copy link

Agent Brief

Category: enhancement
Summary: Anchor Confirmation, mint, and displace in the CONTEXT.md glossary, then sweep for stray synonyms

Current behavior:
The code already speaks a consistent vocabulary that the glossary never anchors:

  • mint is the verb for creating a credential, and it is not confirmation-specific — doc comments and test helpers use it for confirmations, access tokens, and authorization codes alike ("mint a 30-minute confirmation", "Mint a new access token", "the domain mints a single-use code"). Treat this as settled: mint is the general credential-creation term.
  • displace names the replacement semantics of reset minting: minting a password-reset confirmation atomically displaces any prior reset confirmations for the same user, so at most one reset link is valid per user (issue #59, PR #76). It appears in the domain port doc, the service doc, the in-memory mock, the Postgres adapter, and the conformance-test names (e.g. reset_mint_displaces_prior_reset_only).

CONTEXT.md has no Confirmation entry and mentions neither verb. The ### Authorization section's Authorization Code entry (which anchors consumes) shows the house style: bold the verb inline within the owning entry.

Desired behavior:
CONTEXT.md's glossary defines Confirmation and anchors both verbs, so future code and reviews have a written reference — the same protection #79 added for the authorization-code vocabulary.

  1. A Confirmation entry: the identifier + hashed-verifier credential mailed to a user to prove control of an email address, carrying an action type — EmailConfirmation or PasswordReset (the ConfirmationAction enum) — plus details and an expiry.
  2. mint anchored as the general term for creating any credential (confirmation, access token, authorization code), worded so it reads naturally from whichever entry hosts it.
  3. displace anchored with the full rule: minting a reset confirmation displaces prior reset confirmations for that user only — other action types and other users are untouched.
  4. A synonym sweep across doc comments, port docs, and test names in the domain, infra, and server crates: where create/issue/replace/revoke is used but mint/displace is meant, rename to the anchored term. Genuine other meanings (e.g. revoking an access token at logout) stay as they are.

Key interfaces:

  • CONTEXT.md ## Language glossary — follow the existing entry format (**Term**: under a ### section heading, related verbs bolded inline, cross-references to other entries where helpful)
  • Confirmation / ConfirmationAction / ConfirmationId / ConfirmationVerifierHash in the domain models — the entry should describe this shape behaviorally, not restate the struct
  • The repository port method that mints reset confirmations (create_password_reset_confirmation) and its conformance suite — the doc comments there are the reference wording for the displacement rule

Acceptance criteria:

  • CONTEXT.md has a Confirmation glossary entry covering both action types
  • mint is anchored in CONTEXT.md as the general credential-creation verb, consistent with its existing use for confirmations, tokens, and codes
  • displace is anchored in CONTEXT.md with the user-scoped, action-type-scoped displacement rule
  • Doc comments and test names use mint/displace consistently where those concepts are meant; no stray create/issue/replace/revoke synonyms remain for these two concepts
  • No behavior changes: cargo build output is identical in function, and the ci mise task passes

Out of scope:

  • Any behavior, schema, or signature changes — this is documentation, naming, and glossary only
  • Renaming the port method or domain types themselves (e.g. create_password_reset_confirmation staying "create_" in the identifier is acceptable; the sweep targets prose and test names, and identifier renames are only in scope where they are trivial and purely mechanical)
  • The authorization-code claim/redeem/consume vocabulary — already resolved by #79
  • Email-confirmation flow changes or new confirmation action types
## Agent Brief **Category:** enhancement **Summary:** Anchor **Confirmation**, **mint**, and **displace** in the CONTEXT.md glossary, then sweep for stray synonyms **Current behavior:** The code already speaks a consistent vocabulary that the glossary never anchors: - **mint** is the verb for creating a credential, and it is *not* confirmation-specific — doc comments and test helpers use it for confirmations, access tokens, and authorization codes alike ("mint a 30-minute confirmation", "Mint a new access token", "the domain mints a single-use code"). Treat this as settled: mint is the general credential-creation term. - **displace** names the replacement semantics of reset minting: minting a password-reset confirmation atomically displaces any prior reset confirmations for the same user, so at most one reset link is valid per user (issue #59, PR #76). It appears in the domain port doc, the service doc, the in-memory mock, the Postgres adapter, and the conformance-test names (e.g. `reset_mint_displaces_prior_reset_only`). CONTEXT.md has no **Confirmation** entry and mentions neither verb. The `### Authorization` section's **Authorization Code** entry (which anchors **consumes**) shows the house style: bold the verb inline within the owning entry. **Desired behavior:** CONTEXT.md's glossary defines Confirmation and anchors both verbs, so future code and reviews have a written reference — the same protection #79 added for the authorization-code vocabulary. 1. A **Confirmation** entry: the identifier + hashed-verifier credential mailed to a user to prove control of an email address, carrying an action type — `EmailConfirmation` or `PasswordReset` (the `ConfirmationAction` enum) — plus details and an expiry. 2. **mint** anchored as the general term for creating any credential (confirmation, access token, authorization code), worded so it reads naturally from whichever entry hosts it. 3. **displace** anchored with the full rule: minting a reset confirmation displaces prior *reset* confirmations for *that user only* — other action types and other users are untouched. 4. A synonym sweep across doc comments, port docs, and test names in the domain, infra, and server crates: where create/issue/replace/revoke is used but mint/displace is meant, rename to the anchored term. Genuine other meanings (e.g. revoking an access token at logout) stay as they are. **Key interfaces:** - CONTEXT.md `## Language` glossary — follow the existing entry format (`**Term**:` under a `###` section heading, related verbs bolded inline, cross-references to other entries where helpful) - `Confirmation` / `ConfirmationAction` / `ConfirmationId` / `ConfirmationVerifierHash` in the domain models — the entry should describe this shape behaviorally, not restate the struct - The repository port method that mints reset confirmations (`create_password_reset_confirmation`) and its conformance suite — the doc comments there are the reference wording for the displacement rule **Acceptance criteria:** - [ ] CONTEXT.md has a **Confirmation** glossary entry covering both action types - [ ] **mint** is anchored in CONTEXT.md as the general credential-creation verb, consistent with its existing use for confirmations, tokens, and codes - [ ] **displace** is anchored in CONTEXT.md with the user-scoped, action-type-scoped displacement rule - [ ] Doc comments and test names use mint/displace consistently where those concepts are meant; no stray create/issue/replace/revoke synonyms remain for these two concepts - [ ] No behavior changes: `cargo` build output is identical in function, and the `ci` mise task passes **Out of scope:** - Any behavior, schema, or signature changes — this is documentation, naming, and glossary only - Renaming the port method or domain types themselves (e.g. `create_password_reset_confirmation` staying "create_" in the *identifier* is acceptable; the sweep targets prose and test names, and identifier renames are only in scope where they are trivial and purely mechanical) - The authorization-code claim/redeem/consume vocabulary — already resolved by #79 - Email-confirmation *flow* changes or new confirmation action types
rosa commented 2026-07-04 02:35:56 +00:00
Author
Owner
Copy link

Implemented on branch domain/authorization-code-vocabulary in two commits:

  • a3c3f1c adds a Credentials section to the CONTEXT.md glossary anchoring Confirmation, Mint (the general credential-creation verb, per the agent brief), and Displace (the user- and action-scoped replacement rule), and rewords doc comments that said a code or token "was issued" where minting was meant.
  • 225ece1 retires the remaining synonyms from the API surface: the service's issue_* methods, the port's credential create_* methods, and their CreateRequest payload types are now mint_/Mint*Request, with test names and Postgres error contexts following.

No behavior changes; the full ci task passes on both commits.

Implemented on branch domain/authorization-code-vocabulary in two commits: - a3c3f1c adds a Credentials section to the CONTEXT.md glossary anchoring **Confirmation**, **Mint** (the general credential-creation verb, per the agent brief), and **Displace** (the user- and action-scoped replacement rule), and rewords doc comments that said a code or token "was issued" where minting was meant. - 225ece1 retires the remaining synonyms from the API surface: the service's issue_* methods, the port's credential create_* methods, and their Create*Request payload types are now mint_*/Mint*Request, with test names and Postgres error contexts following. No behavior changes; the full ci task passes on both commits.
rosa closed this issue 2026-07-04 02:35:56 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
passkey-login
No results found.
Labels
Clear labels   
bug
Something is broken

  
enhancement
New feature or improvement

  
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Fully specified, waiting for an AFK agent

  
ready-for-human
Requires human implementation

  
wontfix
Will not be actioned

No labels
bug
enhancement
needs-info
needs-triage
ready-for-agent
ready-for-human
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
rosa/vernier#82
No description provided.