@volter/twin-oa-treasury

Legacy connector helpers: this package still has callable helpers using the retired v1 syncPull API. Those paths require migration before use on the current kernel; older helper descriptions below do not establish current compatibility. Check the generated index for protocol standing and use the shared model for current state semantics.

Local twin of the Open Autonomy treasury (agent-model-proxy — the economy layer of volter-ai/open-autonomy, one Cloudflare Worker): the money boundary every OA consumer crosses, twinned so RH2's treasury-supplier client, the future issuing bridge, and the autonomous org's finance loop rehearse against twinned money from their first commit. Built on the shared @volter/world-core kernel:

• The funding-account tree — mint / grant / accrue with the hard conservation invariant (total minted = total consumed + total still held), public funding snapshots (GET /v1/accounts/:id with balance / categories / reserves / spendable / Bayesian runway) and the Camo-safe runway.svg badge.
• The generic supplier API — admin-registered suppliers with scoped bearer credentials (sup.<id>.<secret>, hash-only storage), itemized consume (idempotent keys that a refusal never burns), two-phase reserve → settle/release with TTL'd holds (remainder release, late-settle 409), and per-supplier exposure caps (in-flight + rolling window).
• Coupons — bearer/deferred grants (SPON-XXXX-XXXX-XXXX), mint-backed or issuer-backed, with the full probed error ladder.
• The GitHub Sponsors webhook — real x-hub-signature-256 HMAC verification over a twin-side secret (see the trust boundary below), recurring upsert / one-time mint / cancellation semantics, and the monthly accrue.
• The run-token ledger — POST /admin/runs/mint with HMAC run tokens, active-run lanes (user + system), per-day caps, revoke/reap, the repo-scoped live session window, and the admin limits/status observability dump.
• An accept-and-ledger model endpoint — POST /v1/messages (Anthropic wire, unary + SSE) reproduces the FULL ledger contract (allowlist, worst-case reservation, request slots, fractional-cent settle-down, remaining-budget headers, supplier-#0 account debits) around a deterministic [twin-stub:oa-treasury] completion. No real model inference — see Coverage.

This is a self-twin: the vendor is our own service, so the twin was built from the vendor's own source (read line-level from a read-only clone of PR #294) and pinned by live probes against the real worker under wrangler dev --local (2026-08-23, four probe batches — see spec-sources.json). The conformance lane and the live parity lane replay one probe script against the twin and the real worker respectively; at build time the real service answered all 34 vendor-side steps with zero divergence.

bun packages/twin/oa-treasury/src/cli.ts            # serve
bun packages/twin/oa-treasury/src/cli.ts conformance

The conservation invariant (the signature property)

checkOaTreasuryConservation(root) asserts, at any instant, over every account the twin holds:

Σ minted == Σ consumed + Σ balance — grants telescope (granted_in ↔ granted_out), reserves are holds inside balances, and only mint moves the total.

Honest scope (§9-reviewed): balances are derived (granted_in − granted_out − consumed), so the consumed term cancels algebraically — the runtime teeth of the equation are the mint/grant books: the twin's independent monotone Σ-minted counter must equal Σ granted_in − Σ granted_out across all accounts (a corrupted mint, a one-sided grant, a coupon that mints without counting, or a lost account row all redden it). The consumed/held half of the vendor's invariant holds by construction in this single-entry design — the vendor's own DO derives balances identically and never runtime-asserts the identity either; debit-path correctness (double-charge, mis-attribution) is carried by the value-asserting capability verifies and the parity script's balance assertions. The conformance lane asserts the equation after replaying the full probe script. It binds twin-authored books only; a connector pull imports foreign books whose mint history is not observable, so a pulled-into root is outside the equation's domain (stated on the check itself).

Faithful quirks the probes pinned (deliberately reproduced)

• Two error envelopes. Route-level errors are nested {"error":{"code":...}}; ledger-level errors are flat {"ok":false,"error":"...", ...extra}. Supplier auth can fail in either (an unparseable bearer vs a wrong secret) — both 401, different shapes.
• grant burns its idempotency key BEFORE the balance check — a keyed grant refused with insufficient_balance has already burned its key; the funded retry reports {idempotent:true} and moves no money. supplierConsume is the opposite: a refused attempt never burns its key. Both directions are capability-pinned.
• Derived supplier ids are random (sup-<8 alnum>), never slugged from the name.
• Rotate-after-revoke returns 200 + a fresh token — which is unusable, because auth fails closed on revoked. A revoked id can never be re-created.
• Unknown /v1/* paths fall through to the model-token gate: 401 auth_failed without a token, 404 not_found with a valid one.
• GET /admin/runs/:id on an unknown run answers 200 with the empty {claims:null} snapshot.
• The applied-keys ledger remembers the last 500 keys — a 501-keys-ago key is re-appliable.
• Every register refusal maps to HTTP 429 on /admin/runs/mint, including account_banned and (with enforcement on) account_unfunded.
• Exact Bayesian runway floats — the twin reproduces the service's Normal–Inverse-Gamma posterior to the digit (probe-pinned: balance 7500 at zero observed days → runway_lo_days: 92.26164377619254).

ENFORCE_ACCOUNT_BALANCE rollout semantics

Enforcement defaults off (the vendor's env default — the bootstrap phase): unfunded spend is allowed through and balances go negative, so a tree can be funded before the gate turns on. With limits: { enforce_account_balance: true } (per server or per request options), spend beyond balance − reserved refuses 402 account_balance_exhausted on every path — supplier consume, supplier reserve, and the model plane alike — and run mints on unfunded repos refuse 429 account_unfunded. Both modes are probe-pinned against the real worker.

The webhook trust boundary (twin-side secret)

The real service verifies GitHub's x-hub-signature-256 against GITHUB_SPONSORS_WEBHOOK_SECRET. The twin verifies the same algorithm (hex HMAC-SHA256 over the raw body, constant-time compare) against its own twin-side secret (default twin-webhook-secret, configurable via webhookSecret). A consumer rehearsing the webhook signs with the twin's secret — GitHub's real secret never enters the twin, and a signature produced for the real endpoint will (correctly) not verify here. oaTreasuryWebhookSignature() is exported so tests can sign exactly as GitHub would.

Coverage

Run bun scripts/twin-capabilities.ts from the repo root for the live table. The manifest (oa-treasury-capabilities.ts) is the REAL surface of the vendor's router (this is a self-twin — src/index.ts of the service is first-party ground truth), authored top-down: 127 capabilities, 104 done, the storefront/OIDC/profile-sync surface tracked as honest todos. Partial by design; growing the denominator later is success, not regression.

No UI mirror

oa-treasury's money surface is API-first: everyone who does this vendor's core job writes code — RH2's treasury-supplier client posts debits, OA's runtime mints/revokes run tokens over fetch, README badges hot-link runway.svg. The vendor's server-rendered funding storefront (explore/project pages at open-autonomy.org) is real surface, but it is the vendor's own HTML-over-the-same-ledger, tracked as storefront todos in the manifest — not a dashboard a separate React mirror should duplicate. No UI capabilities are declared (ui-scope.json: needsUi false).

Todos worth knowing about

The OpenAI-wire model routes (/v1/chat/completions, /v1/responses), the storefront HTML pages, /health org-fleet aggregation, profile set/sync, OIDC success paths, the provider failure paths (503 provider_not_configured, 502 upstream_unavailable/auth, 429 provider_rate_limited and the release-on-network-error request-slot refund), scenario scripting, and the connector's limits-status pull + push leg — all real surface, all filed as manifest todos (never fake successes: each fails today exactly as an unmodeled op should).

Rate budget

Declared at the kernel's conservative fallback (60 weighted units / 60s, all calls weight 2): the vendor is our own worker and publishes no scalar request-rate limit (its MAX_* vars bound run slots and spend, not request rates) — stated in OA_TREASURY_RATE_BUDGET.reason. The connector guards every injected client unconditionally (guardOaTreasuryClient, idempotent, no opt-out); proofs run against injected counting fakes, offline.

Live parity lane

oa-treasury-live.integration.test.ts starts the REAL worker (wrangler dev --local, read-only vendor clone, fresh --persist-to state) and replays the twin's exact conformance probe script against it. Skips loudly when the clone/wrangler is unavailable — a skip is never a verified pass. The accept-and-ledger stub step is twinOnly (disclosed divergence: the real service needs a provider key where the twin IS the provider).