feat(db,gateway): R13 one-use budget reservations: durable store + atomic consume (SCHEMA CHANGE, approved under operator item 26)

[LamaSu]

Current state (2026-10-06, pcc-composition)

• Base is now master. The old base, feat(gateway): R9 agent-plan routes — validate (live R10) and accept (seam → VCR deal binding → one R13 consume); money-path gated, 503 until wired #391 (feat/agent-plans-route), merged at ff71067.
• Head: 238da2a. It is a plain merge of master 2f5b21d into the reviewed head 2cf0219, with no edits: its tree equals git merge-tree of the two (8cc5e013).
• Review: pack 254 confirmed the last MEDIUM closed at 2cf0219. Verdict: SHIP, with no open findings. It came from the automated review runner, an OpenAI model on Claude-written code, so the review is cross-family (bus #7106). The verdict file doesn't name the exact model.
  • The rounds after round 3 (below):
    • 698de5b fixed pack 92's MEDIUM: the DDL records its schema version only in the run that creates the table.
    • 2cf0219 fixed pack 252's MEDIUM: every schema check matches the table name with COLLATE NOCASE.
• Schema: the budget_reservations DDL is approved (operator-queue item 26).
• Checks on the merge commit:
  • master's own scripts/ci/secret-scan.mjs: OK on --tree and on --range 2f5b21dc..head;
  • CI's build-and-test steps, run locally on the merge commit: all green at 17:16 PDT. The steps were a frozen install, pnpm build --concurrency=1, pnpm -r --no-bail test, pnpm -r exec tsc --noEmit and gateway's typecheck:browser. The test step ran 54 packages with 0 failures: spec 3479/3479, store (db) 240/240, and gateway 5848 passed, 13 skipped, 3 todo.
• Next in the stack: feat(gateway): R13 reservation ISSUE + READ routes — server terms only, exact money; 503 until store, exact ceiling and payer binding exist #410 (the issue and read routes), then feat(gateway): MC 9 bounded child authority — a composite operator carves a child reservation from one sealed unit (503 until the sealed deal is stored) #415 (MC 9 child authority). Each is retargeted after its parent merges.

---

Round 3 (2026-09-29): astra's pack-45 findings (DO-NOT-SHIP on ac3db65), each REPRODUCED first, then fixed at 638bc3d

Under the review loop, the new tests were run at 45d0cde (byte-identical store and parser to ac3db65) BEFORE any change: store 9 failed, parser 3 failed.

• A (HIGH), repeated reads. Every issue and consume input, including the nested parent, is now read ONCE into an owned copy.
  • Reproduced: the amount was read 4 times and 100 USDC inserted.
  • Reproduced: consume's checks ran on one reservation and consumed ANOTHER principal's.
• B (HIGH), schema repair. It now runs in ONE immediate transaction and uses a RECORDED schema version (pcc_schema_versions, v2), never SQL text.
  • Reproduced: an interleaved writer's committed row was lost.
  • Reproduced: a correct, differently written table was refused.
• C (MEDIUM), direct writers. The insert guard refuses a reused id, and id is NOT NULL.
  • Reproduced: INSERT OR REPLACE reopened a consumed row, and a NULL id was accepted.
• D (MEDIUM), the parser. parseSealedDeal enforces the compiler's assurance structure (bad-assurance).
  • Reproduced: a forged tier-2 deal with no program was consumed under a floor-2 reservation.
• Not here: the compiler's reclaimAt above uint64 (reproduced) goes to feat(spec): accepted-plan compiler — composition half of MS-01 (R12) #351's next round. It is fail-closed at consume today.
• Evidence: db 231, spec 912, gateway 3066; mutations 10 of 10 killed.
• Delta pack: 92-composition-r13-r3-6dadaf8b.md. Migration 0004 is regenerated from the runtime DDL.

---

Schema change: approved under operator-queue item 26

(Historical note, kept as written before the approval:)
This PR adds the table budget_reservations. Once merged and deployed, the gateway's runtime migration (migrateDatabase) creates it at startup. The design is operator decision #2240, amended by #2301 (payer, parent binding, a currency check on consume, the app-level digest recompute, an exact ceiling) and #2302 (min_tier). The steward recommends approve as amended. Nothing is applied until you merge and deploy. If you change the design, this draft changes with it.

Round 2 (the operator's cross-family review, 2026-09-28)

The operator's ChatGPT review of #402/#410/#415 at 0b8adda9 was DO-NOT-SHIP (H1, H2, H3, M4, M5, M6). This PR fixes the store side of every finding except M4 (that one's #410's); the routes follow in #410 and #415.

• H1 — child terms come from the sealed deal, never the caller. issue now takes parent: { reservationId, unit } only. Inside its BEGIN IMMEDIATE transaction it reads the consumed parent, re-checks sha256(stored deal) == stored digest, parses the deal strictly and requires it to be that reservation's deal, then finds the exact unit and derives its operator, net n and reclaimAt. The identity checks come first, so a non-operator only ever sees the not-found family. A child also fits its own request's ceiling.
• H2 — durable expiry, and the store's own clock. The clock is injected at construction and read inside each transaction; no caller passes now. Before an issue frees an expired reservation's share, it moves that reservation issued → expired in the same transaction, in both the request scope and the sibling scope. A consume that finds an expiry records it; consume requires issued. Tested on two connections, in both orders, and for siblings.
• H3 — the migration and the runtime schema now agree. 0004_budget_reservations.sql is BUDGET_RESERVATIONS_DDL, statement for statement (test-asserted). migrateDatabase runs ensureBudgetReservationsSchema, which rebuilds an EMPTY table of another shape and refuses to boot on one that holds rows. Test: 0004, then the runtime migration, then a real consume.
• M5 — the table refuses what its invariants forbid. CHECKs: amount > 0 and ≤ uint256; a canonical digest; consumed ⇔ digest ⇔ deal ⇔ consumed_at; created < expires; integer times and tier. Triggers: inserts only as issued, and a child only under a consumed parent; updates only issued → consumed | expired | released, with no term changed; no DELETE. SQL has no sha256, so the trusted readers re-check the hash, parse, and check the reservation.
• M6 — the consume seals only a real deal, for this reservation. New @pcc/spec parseSealedDeal checks: canonical bytes; the domain; exact keys; lowercase hex; at most 64 units, 16 per job, 16 legs per unit and 16 KiB per unit; the f/n arithmetic; legs == n; total == sum of g; jobId = planId:operator; milestones; stepId = keccak(node); a bijective binding; planHash == canonicalPlanHash. The consume takes the request, currency, payers, obligation and lowest tier FROM THE DEAL — the input is now { reservationId, principal, dealDigest, dealPreimage }. The gateway adapter throws when the store refuses the server's own compiled deal: a generic 500, never a 409.

The sealed deal itself (amendment #3231, steward condition #3235). budget_reservations gains consumed_deal_json, written in the same transaction as the digest (450b575). The stored bytes are acceptedDealDigest's own canonical PREIMAGE, and consume refuses unless sha256(bytes) == digest (deal-preimage-mismatch). SQL has no sha256, so the table cannot check the hash itself; its CHECKs hold presence and size. The bytes are never on the reservation object — only server-side sealedDealPreimage(id) reads them, for MC 9's parent terms, funding and VCR delivery — and are capped at 1 MiB, enforced by both the store and a table CHECK. The gateway adapter (af14e2a) recomputes the digest as sha256 of #351's acceptedDealPreimage(plan) and hands the store both the digest and the preimage bytes; the store re-checks that they hash to each other before keeping the bytes as the sealed deal.

Tests: spec 909/909, db 222/222, gateway R13 129/129. The new files typecheck. New tests cover every finding, including the reviewer's exact inputs: a MiB of y with its hash, an invented unit with a forged operator/net/reclaim, 0004 then migrate then consume, and the skewed-clock interleaving. 39 mutation checks: 38 killed. The one survivor is EQUIVALENT — SD14, the parser's one-job-per-operator check: two jobs with one operator share a jobId, so their unit refs collide and the bijective binding check refuses the deal; it's kept for its clearer diagnosis. A first-run survivor, ST6 (the sibling expiry sweep), was a TEST GAP: every sibling test shared a request; siblings under two requests now kill it.

Round-2 pack: 45-composition-r13-402-410-415-r2-ac3db658.md (covers #402, #410 and #415).

Known cost of the stack: until #351 → #355 → #356 → #357 → #391 merges up, #402's diff against #391 temporarily includes #351's 9d7686a.

---

Was stacked on #391 (the R9 route) → #357 → #356 → #355 → #351; all of them are on master now. Reconciliation row R13 (Gate B keystone; MUST-CLOSE 7 and 8). Retarget the stack to master before merge (rule 4).

What it does

@pcc/store: BudgetReservationStore (packages/db/src/repositories/budget-reservations.ts). It is self-contained over the raw SQLite handle; the shared IRepositories aggregate is untouched.

• Exact money. SQLite has no numeric(78,0), so amounts are canonical decimal TEXT and compared as BigInt in code, never in SQL and never as a float. A test with values around 2^200 would fail under float rounding.
• issue, in ONE BEGIN IMMEDIATE transaction:
  • The request's issued and consumed top-level reservations, plus the new one, must fit the request's authorized ceiling (fix(gateway): honest operator-relay evidence, claim authentication, immutable authorized ceiling (LO-GW-4/3a, R-06) #335 R-06, passed in by the server in exact base units).
  • MC 9 child authority (#2301, hardened in round 2 / H1). issue takes parent: { reservationId, unit } only — never caller-supplied terms. Inside the transaction it re-reads the consumed parent, re-checks its sealed-deal digest, and derives the unit's operator, net n and reclaimAt from THAT deal. The parent must be consumed and in the same currency. All children of one unit fit its net n, none outlives its reclaimAt, and the child inherits max(parent's floor, its own) — and now also fits its own request's ceiling.
• consume, in ONE BEGIN IMMEDIATE transaction (round 2, M6): takes { reservationId, principal, dealDigest, dealPreimage } — never a caller-supplied payer or obligation. parseSealedDeal (new @pcc/spec, a strict total parser of the accepted-deal preimage) checks the deal's canonical bytes, domain, exact keys, and unit/leg/size bounds, and the request, currency, every job's payer, the obligation and the lowest tier all come FROM THE DEAL. The store still re-checks principal, issued-and-unexpired and floor against the stored row, then seals the deal digest: the UPDATE is conditional on state = 'issued', and exactly one row must change.
• Table constraints (SQL CHECK): canonical digits only (1–78, no leading zero), the known states, consumed ⇔ digest present, min_tier in 0..3, and both halves of a parent binding or neither — extended in round 2 (M5) with created < expires, integer times/tier, and insert/update/no-DELETE triggers (see above).

Gateway: services/reservation-store.ts implements the trace stand-in's consume PROTOCOL, made durable.

• loadReservation feeds the seam.
• consumeReservation feeds the route. Before touching the store it refuses a plan it did not compile:
  • another reservation's plan (wrong-binding);
  • a digest that differs from the one RECOMPUTED from the content, as sha256 of feat(spec): accepted-plan compiler — composition half of MS-01 (R12) #351's acceptedDealPreimage (digest-mismatch, the feat(spec): accepted-plan compiler — composition half of MS-01 (R12) #351 consumer contract);
  • a carried total the units do not sum to (obligation-mismatch).
• Then the atomic store consume runs. Since round 2 (M6), the store parses the preimage and takes the request, currency, every payer, the obligation and the lowest tier FROM THE DEAL. A RESEALED plan passes integrity but not authority: another payer, principal, expiry or floor is still refused, with the same answers as before.
• If the store refuses the server's OWN compiled deal as malformed (invalid-deal, wrong-reservation, a preimage mismatch or invalid input), the adapter throws. That is a generic 500, never a client-facing 409.

Tests

• @pcc/store: 13 tests against real SQLite.

  • Exact uint256 round-trip; malformed input.
  • The ceiling: exact at the boundary; consumed counts; released frees its share; per request; float-proof at 2^200.
  • Exactly-once consume; every A-for-B refusal; expired; over the maximum; below the floor.
  • Two connections on one file: while one holds the write lock the other cannot interleave, and exactly one consume wins.
  • The table's CHECKs reject raw bad rows.
  • MC 9 child rules; createStore runs the DDL idempotently.

• The db package's full suite passes with the new migration.

• Gateway: 5 tests.

  • The whole route on the durable store: 200 seals the recomputed digest; a second accept is 409; of two concurrent accepts, exactly one is sealed.
  • loadReservation mapping.
  • The protocol's refusals, and authority after a reseal, including one job of several paying from another wallet.

• Mutation checks, 20: 18 killed, 2 survivors explained.

  • Store (14): 12 killed.

  • The 2 survivors are layered concurrency defenses that single-threaded tests cannot tell apart:

    • BEGIN IMMEDIATE vs deferred. Under a deferred transaction, SQLite's snapshot isolation makes a racing read-then-write fail with SQLITE_BUSY rather than double-consume.
    • The UPDATE's state = 'issued' guard, which is redundant under the immediate lock.

    Each is kept as defence in depth.

  • Adapter (6): all killed. The per-job payer survivor led to the one-job-of-several test.

  (These are round-1 counts, scoped to what round 1 added. Round 2's own numbers — spec 909/909, db 222/222, gateway R13 129/129, 39 mutation checks/38 killed — are in the Round 2 section above and supersede these as the head's totals.)

Self-review fixes (e6975e4), before the cross-family round

• Expired reservations stop holding money. An issued reservation past its expiry no longer holds its share of the request ceiling (or of its parent unit, for a child). It can never be consumed, and no housekeeping runs, so the share was held forever.
• No parent payer for a child. A child may not name the parent's payer (#2301: never the parent payer's credentials).
• 2 tests; 4 mutation checks, all killed.

Issue and read routes: #410, stacked on this PR.

Cross-family status: round 1 was DO-NOT-SHIP at 0b8adda9 (see Round 2 above, which fixes it). Round 2 goes through the operator's ChatGPT review as pack 45-composition-r13-402-410-415-r2-ac3db658.md.

Not in this PR

• The reservation-ISSUE route: now draft feat(gateway): R13 reservation ISSUE + READ routes — server terms only, exact money; 503 until store, exact ceiling and payer binding exist #410. It needs an exact, no-default ceiling from gateway (fix(gateway): honest operator-relay evidence, claim authentication, immutable authorized ceiling (LO-GW-4/3a, R-06) #335) and the payer binding (#3202).
• Release and expiry housekeeping (round 2 adds lazy expiry transitions inside issue/consume; a background sweeper is still not built).
• Wiring the store into feat(gateway): R9 agent-plan routes — validate (live R10) and accept (seam → VCR deal binding → one R13 consume); money-path gated, 503 until wired #391's production deps. Accept still needs feat(spec): committed programs per CSD tier and the pre-funding assurance gate (must-close 6) #349, the evidence map, the fee policy and escrow's encoder.

pcc-composition 8a0f4de0, goal pcc-reconciliation.

🤖 Generated with Claude Code

https://claude.ai/code/session_0171FftEAfqjwbJHowVTqAbz