id: grant lifecycle implementation spec (#2254) by dezren39 · Pull Request #2722 · developing-today/code

dezren39 · 2026-10-30T11:55:45Z

Design spec for #2254 (implementation spec follow-on from the #2042 investigation, queue task 3353). Spec only — no code, per the #2056 program rule against building permanent features on an unreviewed investigation.

What

New doc pkgs/id/doc/2026-10-30T11-55-00Z_design_grant_lifecycle.md covering all five points #2254 names:

PendingHold mechanics — decision made: TigerBeetle two-phase pending transfers (grant sub-account rejected, with reasons); window parameters per grant source as configuration snapshotted onto the grant record; post flow (idempotent scheduler sweep + timeout-void re-issuance fail-safe) and void flow.
Fingerprint registry — domain-separated SHA-256 over the canonicalised key (raw key never stored or logged), grant_keys table whose primary key is the one-grant-per-key enforcement, first-registration-wins, append-only rows, signed publisher-revocation batch intake using precomputed fingerprints (publishers never send raw keys).
External-event attestations — service-signed record format for refund / chargeback / publisher-revocation with authenticated intake and (source, external_ref) idempotency, plus the exact state transitions each event type may trigger.
Clawback + Shortfall + debt — the amount_outstanding attribution figure (consumption decrements, transfers do not; liability is personal to the grantee), partial-clawback choreography, signed debt record format, FIFO offset against future grants/earnings, suspension effects, public signed write-off.
revocation_policy enforcement — the none | for-cause | issuer-discretion ladder, the issuance-time snapshot rule (no retroactive power), a refusal table checked at execution with auditable refusals, and the signed revocation-notice + grace-window flow. Delisting specified as a separate acceptance act that never touches a balance.

Plus: a state-machine implementation map covering every #2042 state and transition (no orphan states), an abuse-case trace for cases 1–6 (each to a mechanism or an explicitly accepted residual risk), and eight open parameters (OP-1…OP-8) routed to #2043/operator instead of being silently defaulted.

Implementation work is filed as its own issue and linked from #2254 — this PR delivers the spec only.

Queue task 3409 · repo-worker-code Lane C

^{Need help on this PR? Tag @codesmith-bot with what you need.}

…registry, clawback/shortfall, revocation policy (#2254)

coderabbitai · 2026-10-30T11:55:54Z

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 46 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: 01cca7e6-d18b-4edd-9c4f-34993bd4b745

Commits

Reviewing files that changed from the base of the PR and between a062548 and 4c01caf.

Files selected for processing: 1

doc/2026-10-30T11-55-00Z_design_grant_lifecycle.md

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

chatgpt-codex-connector · 2026-10-30T11:55:55Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T12:27:16.773667Z	`4c01caf`	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 317f287fa1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…ation, frozen canonicalisation, intent-first ledger protocol, sweep resolution, registry-stamped grace, all-debts suspension recompute, expiry shortfall (#2254)

dezren39 · 2026-10-30T12:04:11Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bb04ccae8d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…tion into clawback (#2254, Codex round 2)

dezren39 · 2026-10-30T12:09:09Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 736471d462

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…ecompute-on-rejection, attestation scoping, expiry check on re-issuance (#2254)

dezren39 · 2026-10-30T12:16:27Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6feead06b5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…g Presented intent are processed at confirmation (#2254)

dezren39 · 2026-10-30T12:23:30Z

@codex review

chatgpt-codex-connector · 2026-10-30T12:27:15Z

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: 4c01caf614

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

id: grant lifecycle implementation spec — pending holds, fingerprint …

317f287

…registry, clawback/shortfall, revocation policy (#2254)

dezren39 requested a review from a team as a code owner October 30, 2026 11:55

dezren39 mentioned this pull request Oct 30, 2026

id: design: grant lifecycle implementation spec — pending-hold grants, key-fingerprint registry, clawback/shortfall, revocation policy (from #2042) #2254

Closed

5 tasks

chatgpt-codex-connector Bot reviewed Oct 30, 2026

View reviewed changes

id: grant lifecycle spec — disposition Codex review: purchase verific…

bb04cca

…ation, frozen canonicalisation, intent-first ledger protocol, sweep resolution, registry-stamped grace, all-debts suspension recompute, expiry shortfall (#2254)

chatgpt-codex-connector Bot reviewed Oct 30, 2026

View reviewed changes

Comment thread doc/2026-10-30T11-55-00Z_design_grant_lifecycle.md Resolved

id: grant lifecycle spec — void/post race routes the recorded attesta…

736471d

…tion into clawback (#2254, Codex round 2)

chatgpt-codex-connector Bot reviewed Oct 30, 2026

View reviewed changes

id: grant lifecycle spec — Codex round 3: partial refunds, clawback r…

6feead0

…ecompute-on-rejection, attestation scoping, expiry check on re-issuance (#2254)

chatgpt-codex-connector Bot reviewed Oct 30, 2026

View reviewed changes

Comment thread doc/2026-10-30T11-55-00Z_design_grant_lifecycle.md Resolved

id: grant lifecycle spec — Codex round 4: attestations arriving durin…

4c01caf

…g Presented intent are processed at confirmation (#2254)

dezren39 merged commit ec02aa1 into main Oct 30, 2026
1 check passed

dezren39 deleted the queue/3409-2254-grant-lifecycle-spec branch October 30, 2026 12:29

dezren39 mentioned this pull request Oct 30, 2026

id: implement grant lifecycle per #2254 spec — registry, pending holds, attestations, clawback/debt, revocation policy #2723

Open

dezren39 restored the queue/3409-2254-grant-lifecycle-spec branch November 1, 2026 09:07

dezren39 deleted the queue/3409-2254-grant-lifecycle-spec branch November 1, 2026 16:45

Conversation

dezren39 commented Oct 30, 2026 • edited by blacksmith-sh Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Uh oh!

coderabbitai Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

chatgpt-codex-connector Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dezren39 commented Oct 30, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

dezren39 commented Oct 30, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dezren39 commented Oct 30, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

dezren39 commented Oct 30, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 30, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dezren39 commented Oct 30, 2026 •

edited by blacksmith-sh Bot

Loading

coderabbitai Bot commented Oct 30, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Oct 30, 2026 •

edited

Loading