domain: authorization-code docs name one concept three ways (claim/redeem/consume) #79

New issue

Closed

opened 2026-07-03 21:25:56 +00:00 by rosa · 1 comment

rosa commented

2026-07-03 21:25:56 +00:00

Owner

This was generated by AI during triage.

Found during the standards review of PR #77 (atomic authorization-code consumption, issues #49/#61).

Location: authorization-code doc comments and test names across the domain port, service, and conformance suite
Severity: Code health — ubiquitous-language drift

Problem

The authorization-code flow now names one concept three ways:

redeem — the CONTEXT.md glossary term and the service method (redeem_authorization_code), covering the whole exchange (binding checks + consumption + grant).
consume — the port method (consume_authorization_code) and ADR-0008's word for the single-use removal.
claim — introduced by PR #77's doc comments and prose ("wins the claim", "the row count is the claim") for the atomic-removal step, with no glossary entry.

"Redeem" (the whole exchange) and "consume" (the removal step) are arguably two distinct concepts and both have written anchors; "claim" is a third, unanchored synonym for the same step "consume" names.

Suggested fix

A small /domain-modeling pass:

Decide the canonical term for the atomic single-use removal (likely consume, since the port method and ADR-0008 already use it) and whether redeem remains the distinct whole-exchange term.
Update CONTEXT.md so the glossary states the chosen term(s) and the redeem/consume distinction explicitly.
Sweep the PR #77 doc comments, test names, and prose to replace "claim" with the canonical vocabulary.

Related: the reviews of PR #76 noted the same kind of glossary gap for "mint"/"displace" in the password-reset confirmation flow — worth resolving in the same pass if convenient, but this issue is scoped to the authorization-code terms.

No behavior changes — documentation, naming, and glossary only. Should land after PR #77 merges, since it edits that PR's doc comments.

> *This was generated by AI during triage.* Found during the standards review of PR #77 (atomic authorization-code consumption, issues #49/#61). **Location:** authorization-code doc comments and test names across the domain port, service, and conformance suite **Severity:** Code health — ubiquitous-language drift ## Problem The authorization-code flow now names one concept three ways: - **redeem** — the CONTEXT.md glossary term and the service method (`redeem_authorization_code`), covering the whole exchange (binding checks + consumption + grant). - **consume** — the port method (`consume_authorization_code`) and ADR-0008's word for the single-use removal. - **claim** — introduced by PR #77's doc comments and prose ("wins the claim", "the row count is the claim") for the atomic-removal step, with no glossary entry. "Redeem" (the whole exchange) and "consume" (the removal step) are arguably two distinct concepts and both have written anchors; "claim" is a third, unanchored synonym for the same step "consume" names. ## Suggested fix A small `/domain-modeling` pass: 1. Decide the canonical term for the atomic single-use removal (likely **consume**, since the port method and ADR-0008 already use it) and whether **redeem** remains the distinct whole-exchange term. 2. Update CONTEXT.md so the glossary states the chosen term(s) and the redeem/consume distinction explicitly. 3. Sweep the PR #77 doc comments, test names, and prose to replace "claim" with the canonical vocabulary. Related: the reviews of PR #76 noted the same kind of glossary gap for "mint"/"displace" in the password-reset confirmation flow — worth resolving in the same pass if convenient, but this issue is scoped to the authorization-code terms. No behavior changes — documentation, naming, and glossary only. Should land after PR #77 merges, since it edits that PR's doc comments.

rosa added the

needs-triage

label

2026-07-03 21:25:56 +00:00

rosa referenced this issue

2026-07-04 02:02:40 +00:00

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

rosa commented

2026-07-04 02:03:16 +00:00

Author

Owner

Agent Brief

Category: enhancement
Summary: Retire the unanchored "claim" vocabulary in the authorization-code flow in favour of the canonical redeem/consume distinction, and state that distinction in the glossary

Current behavior:
The authorization-code flow names one concept three ways. The maintainer has decided the canonical vocabulary:

redeem — the whole exchange: a Client presents a code (with PKCE verifier, client id, redirect URI) and receives an access token or the user's identity. This is the service-level term (redeem_authorization_code) and the glossary's existing usage.
consume — the atomic single-use removal that a successful redemption performs. This is the port-level term (consume_authorization_code) and ADR-0008's word ("consumed on first successful redemption").
claim — a third, unanchored synonym for what "consume" names, introduced by the atomic-consumption change (PR #77). It appears in doc comments and code comments on the port's consume method, the domain service's redemption path, and the Postgres adapter ("the row count is the claim"), and in the authorization-code conformance suite's behaviour/test names (consume_claims_the_code_exactly_once, consume_of_an_unknown_code_claims_nothing).

The CONTEXT.md glossary's Authorization Code entry uses both canonical terms ("The Client redeems it once … and it is consumed on first use") but never states the redeem/consume distinction explicitly, and its Avoid list does not mention "claim".

Desired behavior:
"claim" no longer appears as authorization-code vocabulary anywhere in the workspace — doc comments, code comments, prose, or test names — replaced by "consume" (when naming the atomic removal) or "redeem"/"redemption" (when naming the whole exchange), whichever the sentence actually means. The glossary's Authorization Code entry defines both terms explicitly: redeem is the whole exchange, consume is the atomic single-use removal a successful redemption performs, and "claim" is listed under Avoid.

Key interfaces:

CONTEXT.md's Authorization Code glossary entry — extend to state the redeem/consume distinction and add "claim" to Avoid. Follow the entry format documented at the top of the glossary and in docs/agents/domain.md.
The AppRepository port's consume method doc, the domain service's redemption-path comments, and the Postgres adapter's consume comment — reword "claim" out; the winning/losing-a-race framing can stay, expressed in consume terms (e.g. "the first consume wins; concurrent redemptions find nothing").
The authorization-code conformance suite's behaviour functions and both_adapters! wrapper names — rename to consume/redeem vocabulary (e.g. consume_claims_the_code_exactly_once → a name saying consume removes the code exactly once). Renaming these tests is expected and in scope; behaviour bodies and assertions are not.

Acceptance criteria:

A case-insensitive search for "claim" across the workspace's Rust sources and CONTEXT.md finds no authorization-code usages (currently ~16 across the port, service, Postgres adapter, and conformance suite).
The glossary's Authorization Code entry states the redeem/consume distinction explicitly and lists "claim" under Avoid.
ADR-0008 is unchanged (it already speaks the canonical vocabulary).
No behaviour changes: test bodies and assertions are untouched apart from renames, and the ci mise task passes.

Out of scope:

The mint/displace glossary gap in the password-reset confirmation flow — tracked separately in #82.
Renaming any Rust method, type, or other identifier that already uses canonical vocabulary (redeem_authorization_code, consume_authorization_code are already correct).
Any change to redemption or consumption semantics, error mapping, or ADR-0008.

## Agent Brief **Category:** enhancement **Summary:** Retire the unanchored "claim" vocabulary in the authorization-code flow in favour of the canonical redeem/consume distinction, and state that distinction in the glossary **Current behavior:** The authorization-code flow names one concept three ways. The maintainer has decided the canonical vocabulary: - **redeem** — the whole exchange: a Client presents a code (with PKCE verifier, client id, redirect URI) and receives an access token or the user's identity. This is the service-level term (`redeem_authorization_code`) and the glossary's existing usage. - **consume** — the atomic single-use removal that a successful redemption performs. This is the port-level term (`consume_authorization_code`) and ADR-0008's word ("consumed on first successful redemption"). - **claim** — a third, unanchored synonym for what "consume" names, introduced by the atomic-consumption change (PR #77). It appears in doc comments and code comments on the port's consume method, the domain service's redemption path, and the Postgres adapter ("the row count is the claim"), and in the authorization-code conformance suite's behaviour/test names (`consume_claims_the_code_exactly_once`, `consume_of_an_unknown_code_claims_nothing`). The CONTEXT.md glossary's **Authorization Code** entry uses both canonical terms ("The Client redeems it once … and it is consumed on first use") but never states the redeem/consume distinction explicitly, and its _Avoid_ list does not mention "claim". **Desired behavior:** "claim" no longer appears as authorization-code vocabulary anywhere in the workspace — doc comments, code comments, prose, or test names — replaced by "consume" (when naming the atomic removal) or "redeem"/"redemption" (when naming the whole exchange), whichever the sentence actually means. The glossary's Authorization Code entry defines both terms explicitly: redeem is the whole exchange, consume is the atomic single-use removal a successful redemption performs, and "claim" is listed under _Avoid_. **Key interfaces:** - CONTEXT.md's **Authorization Code** glossary entry — extend to state the redeem/consume distinction and add "claim" to _Avoid_. Follow the entry format documented at the top of the glossary and in `docs/agents/domain.md`. - The `AppRepository` port's consume method doc, the domain service's redemption-path comments, and the Postgres adapter's consume comment — reword "claim" out; the winning/losing-a-race framing can stay, expressed in consume terms (e.g. "the first consume wins; concurrent redemptions find nothing"). - The authorization-code conformance suite's behaviour functions and `both_adapters!` wrapper names — rename to consume/redeem vocabulary (e.g. `consume_claims_the_code_exactly_once` → a name saying consume removes the code exactly once). Renaming these tests is expected and in scope; behaviour bodies and assertions are not. **Acceptance criteria:** - [ ] A case-insensitive search for "claim" across the workspace's Rust sources and CONTEXT.md finds no authorization-code usages (currently ~16 across the port, service, Postgres adapter, and conformance suite). - [ ] The glossary's Authorization Code entry states the redeem/consume distinction explicitly and lists "claim" under _Avoid_. - [ ] ADR-0008 is unchanged (it already speaks the canonical vocabulary). - [ ] No behaviour changes: test bodies and assertions are untouched apart from renames, and the `ci` mise task passes. **Out of scope:** - The mint/displace glossary gap in the password-reset confirmation flow — tracked separately in #82. - Renaming any Rust method, type, or other identifier that already uses canonical vocabulary (`redeem_authorization_code`, `consume_authorization_code` are already correct). - Any change to redemption or consumption semantics, error mapping, or ADR-0008.

rosa added

enhancement

ready-for-agent

and removed

needs-triage

labels

2026-07-04 02:03:16 +00:00

rosa referenced this issue from a commit

2026-07-04 02:14:20 +00:00

docs: Retire 'claim' from the authorization-code vocabulary

rosa referenced this issue from a pull request that will close it,

2026-07-04 02:15:25 +00:00