id: design: refundable grants via pending transfers — Steam premium tokens voidable through the refund window

Source: the TigerBeetle investigation (on #2040) refund/revocation gap: posted transfers are immutable and a clawback fails if the holder already spent the balance. Design grant issuance as PENDING transfers: a Steam-key grant (e.g. 500 premium tokens) is reserved at registration and posts only when the refund window closes; a refund voids it. Cover window length, partial posting, and what the user sees while pending. Feeds #2043 and the real-services investigation (#2042).

Program: Drew's 2026-10-28 directive (full text: hatch-personal memory/topics/id-program-2026-10-28.md). Parent epic: #2056.
Working pattern: parallel investigations, then the named synthesis issue merges them into a full design. Route guidance: Workhorse by default; Specialist/Summit for synthesis and ramification-heavy work. A result that says "done" is not the endpoint — the orchestrator reviews it and may commission another round. Deliverables: a markdown design/investigation doc (mermaid/SVG diagrams welcome) linked from this issue, plus follow-up issues for anything buildable. Build a proof of concept where the design calls for one, but do NOT build the permanent feature on top of an unreviewed PoC.

Acceptance criteria

A markdown design doc is linked from this issue designing grant issuance as PENDING TigerBeetle transfers that post only when the refund window closes and are voided by a refund.
The doc covers: window length, partial posting, and what the user sees while a grant is pending.
The clawback failure mode from id: investigate: TigerBeetle — multi-currency ledgers, conversions, per-coin vs balance model, 3-node cluster topology #2040 (posted transfers immutable; clawback fails if balance already spent) is shown to be closed by the pending-transfer design.
Anything buildable that falls out of the design is filed as follow-up issues linked here.

Parent epic: #2056 — ID platform expansion (2026-10-28 directive). Filed as batch 2 from PREPARED-ACTIONS.md.

CODE-986

Intake review

Related: parent epic #2056; source investigation #2040 (refund/revocation gap); feeds #2043 and the real-services investigation #2042.

Notes: design deliverable in the ID program batch; the pending-transfer mechanism is the core idea and is well-scoped in the body.

Risks: window length is a product/policy pin (Steam refund window vs user experience of pending tokens) — surface it explicitly in the doc rather than burying a default.

Suggested approach: Workhorse design pass; coordinate the pending-state UX with #2062's account factory so pending grants have a representation from day one.

— Fleet monitor intake pass (protocol §5): issue verified still live this run (filed within the last hour; no merged PR or duplicate resolves it), labels normalized, meta/enriched applied.

Top priority — ID program wave-1. Drew directed this be picked up in the next runs (2026-10-29): enqueued directly as triage task 3367 in repo-health-code-pilot at queue priority 20 (only breakage-class work at priority 10 outranks it). Wave-1 is the ungated investigations and designs; syntheses and PoCs stay gated on their named inputs. Investigation route: Workhorse.

agent-note:v1 — picked up

task: 3367 (repo-health-code-pilot), attempt 1
worker: repo-worker-code · origin openchamber-scheduled-lane
doing: verifying the pending-transfer premise against the repo and the id: investigate: TigerBeetle — multi-currency ledgers, conversions, per-coin vs balance model, 3-node cluster topology #2040 clawback finding, then writing the design doc the acceptance criteria ask for
next: docs PR with the design doc, linked from this issue, plus follow-up issues for anything buildable
note: a previous lane parked this task after ~25 min with no analysis done; work restarts here from stage=claimed

docs(id): design refundable grants as pending transfers (#2065)

docs(id): link follow-up issues 2294-2296 from the grant design (#2065)

agent-note:v1 — investigation/design complete (PR open)

Deliverable: doc/2026-10-29T12-10-00Z_design_refundable_grants_pending_transfers/ — in PR #2293.

Verdict: the premise holds, with one correction that changes the product story.

Pending grants close the id: investigate: TigerBeetle — multi-currency ledgers, conversions, per-coin vs balance model, 3-node cluster topology #2040 clawback gap for refunds that arrive while the grant is pending — the hold is voided, nothing was spendable, so the reversal cannot fail (exceeds_credits is unreachable).
Once a grant posts, tokens are ordinary spendable balance and a late refund is a clawback again. So the design is not "refunds always work"; it is "the vesting window is the refund window" — the same rule Steam applies. The residual (late refund after spend) is bounded and handled explicitly, not hand-waved.

Acceptance criteria, point by point:

✅ Design doc linked (this comment + PR docs(id): design refundable grants as pending transfers (#2065) #2293): grant issuance as flags.pending transfers from issuer.grant_pool to the holder account, vested by post_pending_transfer at window close, voided by void_pending_transfer on refund.
✅ Window length (§3, options table with a 14-day recommendation), partial posting (§4), pending UX (§5).
✅ The id: investigate: TigerBeetle — multi-currency ledgers, conversions, per-coin vs balance model, 3-node cluster topology #2040 failure mode shown closed (§6.1 side-by-side), with §6.2 bounding what no ledger primitive can close and §6.3 covering the failure modes the mechanism itself introduces.
✅ Follow-ups filed: #2294 grant service, #2295 vesting reconciler + drift alarm, #2296 the window/spendability decision.

Two findings worth reading even if the doc is skimmed:

Void is all-or-nothing in TigerBeetle; only posting is partial. That asymmetry decides refund semantics: partial post is for policy, void-and-reissue is for refunds. Mixing them is how a refunded amount ends up posted.
The pending primitive has its own failure mode: a service that dies between reserve and vest lets the hold expire and the user's paid grant evaporates. The design sets timeout = window + 72h slack and requires a reconciler — that is why id: build: grant vesting reconciler and control-plane↔ledger drift alarm #2295 exists rather than being folded into id: build: grant service — pending-transfer grants (register/vest/void) with control-plane grant records #2294.

No PoC built (the design does not call for one; #2296 gates the window value). No permanent feature built on an unreviewed decision.

Task 3367 · worker repo-worker-code · origin openchamber-scheduled-lane

Navigation Menu

Repository navigation

id: design: refundable grants via pending transfers — Steam premium tokens voidable through the refund window #2065

Acceptance criteria

Intake review

agent-note:v1 — picked up

agent-note:v1 — investigation/design complete (PR open)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

id: design: refundable grants via pending transfers — Steam premium tokens voidable through the refund window #2065

Description

Acceptance criteria

Activity

dezren39 commented on Oct 29, 2026

developing-today commented on Oct 29, 2026

dezren39 commented on Oct 29, 2026

Intake review

dezren39 commented on Oct 29, 2026

dezren39 commented on Oct 29, 2026

agent-note:v1 — picked up

dezren39 commented on Oct 29, 2026

agent-note:v1 — investigation/design complete (PR open)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions