id: implement: pkgs/id currency client API — the §7 app-facing function surface from #2041 (gated on #2251 spec)

From the #2041 investigation (token issuance in the ID graph)

The landed investigation doc for #2041 (doc/2026-10-30T19-18-00Z_investigation_token_issuance_id_graph/, §7) fixes the semantic contract for the app-facing currency function surface — one API across both bindings (graph-native and ledger-anchored):

define_currency / issue / award / pay / balance / supply / accept_payment / convert / snapshot

This issue implements that surface as a client library in pkgs/id. Gated on the #2251 spec, which fixes the wire formats and the API signatures/error semantics this library implements — do not start implementation until #2251's spec has landed; the shape of this issue may need amending to match it.

Scope

Client-side library only: graph object construction/signing for the graph-native binding; gateway client (signed intents, persisted idempotency IDs per the id: design: currency as the centralised exception — how the hosted (Workers) edition reaches the currency service #2066 boundary rules) for the ledger-anchored binding.
accept_payment handler registration with the §7 verification order (signature → unforked chain → funded → full currency identity), including the pending-hold hook the grant lifecycle spec hangs off.
NOT the currency service, gateway, or registry themselves (id: design: currency control plane — registry, account factory, gateway #2062 follow-ups F1–F5 own those), and no permanent feature built on an unreviewed PoC (program rule, epic epic: ID platform expansion — apps, comms, currency, hosting, boards (2026-10-28 directive, LIST 6–15) #2056).

Acceptance criteria

Library implements the full §7 surface against id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251's specced signatures, for both bindings
Worked examples from the investigation (§8: issue 100 self-tokens to another ID; §9: game awards coins to a winner) run end-to-end against the library in tests or a demo harness
Idempotency discipline verified: a retried mutating call reuses its persisted ID and cannot double-issue/double-pay

Program: ID platform expansion, epic #2056. Parent investigation: #2041. Gate: #2251 (object-format + API spec). Related: #2062 (control plane), #2066 (centralised exception), #2043 (currencies v1 synthesis).

Intake review

Fleet monitor intake pass (2026-10-30).

Related: id: investigate: token issuance in the ID graph — per-ID issuance, issuer snapshots, authorized conversion rates #2041 (parent investigation, landed), id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251 (GATE — object-format + API spec), id: design: currency control plane — registry, account factory, gateway #2062, id: design: currency as the centralised exception — how the hosted (Workers) edition reaches the currency service #2066, id: design: ID currencies v1 #2043, epic epic: ID platform expansion — apps, comms, currency, hosting, boards (2026-10-28 directive, LIST 6–15) #2056.
Notes: Acceptance criteria already present; no body change made. Labelled status/waiting-dependency: the issue itself says do not start implementation until id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251's spec lands, and its shape may need amending to match that spec.
Risks: Building against the pre-spec §7 surface risks rework; the gate is explicit in the body.
Suggested approach: No lane pickup until id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251 lands; on landing, re-read this issue against the spec and amend scope before enqueueing a fix packet.

agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 40 (priority/normal). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-h
Session / ID: task 8674
Found via: queue claim
Task: task 8674 (small_fix, issue id: implement: pkgs/id currency client API — the §7 app-facing function surface from #2041 (gated on #2251 spec) #2803 — pkgs/id currency client API §7) claimed by lane code-h; execution lane assigned opencode per §1b — handed off to the opencode claimant, not worked directly. Revalidated fresh: issue id: implement: pkgs/id currency client API — the §7 app-facing function surface from #2041 (gated on #2251 spec) #2803 OPEN, gate issue id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251 CLOSED (spec landed); dependencies id(currency): currency registry schema + ledger-u32 allocator (from #2062) #2317 and id(currency): gateway request envelope — canonical encoding, verify_strict, nonce window, idempotency IDs (from #2062) #2319 still open per prior progress — gateway half parks until they close, graph-native binding first. Attempt 23/24, near cap.
Expectation: claimant launches the bound opencode session for task 8674 and resumes from the preserved ordering note.
Links: issue id: implement: pkgs/id currency client API — the §7 app-facing function surface from #2041 (gated on #2251 spec) #2803

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-k
Session / ID: task 8674
Found via: queue claim
Task: small_fix for issue id: implement: pkgs/id currency client API — the §7 app-facing function surface from #2041 (gated on #2251 spec) #2803 (pkgs/id currency client API, §7 app-facing surface) — execution lane assigned to opencode; handed off to the opencode claimant. Fresh check: issue id: implement: pkgs/id currency client API — the §7 app-facing function surface from #2041 (gated on #2251 spec) #2803 OPEN, no hard-stop labels; dependencies issue id(currency): currency registry schema + ledger-u32 allocator (from #2062) #2317 and issue id(currency): gateway request envelope — canonical encoding, verify_strict, nonce window, idempotency IDs (from #2062) #2319 both still OPEN, so the gateway half stays gated; the graph-native binding half is unblocked.
Expectation: effort l; claimant session drives task 8674 to its terminal state.
Links: task 8674 (repo-health-code-pilot queue)

🤖 Agent note · handed off

Agent: fleet monitor
Session / ID: task 8674 (repo-fleet-monitor run 2026-11-05T15:45:48Z)
Found via: monitor reconciliation (Duty 1 claim/label divergence repair)
Task: Claim evaporated: task 8674 is queued and unclaimed in repo-health-code-pilot, but this issue still carried claimed labels. Labels reset to the truth (queue/queued + status/needs-triage). Checkpoint stage at evaporation: handed_off.
Expectation: The next lane claim picks task 8674 up from the queued state and posts a fresh pickup note.

Navigation Menu

Repository navigation

id: implement: pkgs/id currency client API — the §7 app-facing function surface from #2041 (gated on #2251 spec) #2803

From the #2041 investigation (token issuance in the ID graph)

Scope

Acceptance criteria

Intake review

69 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

id: implement: pkgs/id currency client API — the §7 app-facing function surface from #2041 (gated on #2251 spec) #2803

Description

From the #2041 investigation (token issuance in the ID graph)

Scope

Acceptance criteria

Activity

dezren39 commented on Oct 30, 2026

Intake review

developing-today commented on Nov 3, 2026

69 remaining items

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions