feat(gateway): R13 reservation ISSUE + READ routes — server terms only, exact money; 503 until store, exact ceiling and payer binding exist

[LamaSu]

Round 3 (2026-09-29): merges #402's fixes for astra's pack-45 findings

This head merges #402 @638bc3dc (A, B, C, D, each reproduced first). The R13 delta pack is 92-composition-r13-r3-6dadaf8b.md, and the full tests pass at #415's head 6dadaf8.

---

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. This is the #410 half of the round-2 fixes (bbe03e3); the store half is #402 @45d0cde3, merged in e7a49b6.

• M4 — the assurance floor. requestCeiling becomes requestTerms(requestId, principal) -> { currency, ceilingBaseUnits, minTier }: the request's own server-held terms, neither with a default. The body's minTier can only RAISE the request's floor, never lower it. A malformed server floor is a wiring fault, answered with a generic 500, never a default. Production stays 503 until gateway provides exact request terms, floor included — the requests table stores no floor today, and the 503's missing list says so.
• H2 — no route-side time. The route passes no time; the store's own clock stamps issue time and the bounded expiry.

Tests: gateway R13 134/134 (+1: the floor comes from the request, the body only raises it, a malformed server floor is a 500). tsc is clean apart from two pre-existing unrelated errors. 4 mutation checks, all killed: the body lowers the floor; the request floor is ignored (the old code); a malformed server floor is accepted; the ceiling is not the request's.

---

Draft, stacked on #402 (R13 store). R13's other half over HTTP. #402 lets the accept route CONSUME a reservation; this lets a principal ISSUE and READ one. It cannot merge before #402 (operator decision #2240, queue item 26), WP-A (R28) and the two decisions below.

What it does

Route	Behaviour
POST /api/settlement/reservations	Issues a reservation for the authenticated principal. The body is {requestId, currency, maxAmountBaseUnits: "<canonical base units>", purpose, expiresInSec, minTier?}. Returns 201 with the reservation (amounts as exact decimal strings).
GET /api/settlement/reservations/:id	Reads one of the principal's OWN reservations.

Authority. Every term that grants money authority is the server's:

• principal: the API gate's identity (authenticatedPrincipal).
• payer: payerFor(principal), the wallet bound to that principal. A request's requesterWallet is caller data and is never used (invariant 10).
• ceiling and floor: requestTerms(requestId, principal) (round 2, M4) — the principal's OWN request's server-held terms: its authorized ceiling in EXACT base units, and its assurance floor. Neither has a default. It must be the principal's own request; another principal's request is a 404, exactly like a missing one. The body's minTier can only RAISE the request's floor, never lower it.
• id: server-generated. Issue time and expiry: the store's own clock plus the bounded lifetime (round 2, H2) — the route passes no time.

A body reservationId, principal, payer or ceiling is ignored (tested).

• No existence oracle. Another principal's request or reservation gets the same 404 as a missing one.
• Exact money. maxAmountBaseUnits must be a canonical base-unit STRING. A JSON number (a float), "0", a leading zero, a sign, an exponent or 79 digits is 400. The ceiling check is the store's exact one (feat(db,gateway): R13 one-use budget reservations: durable store + atomic consume (SCHEMA CHANGE, approved under operator item 26) #402).
• Bounds. TTL is 60 s to 7 days, the floor 0..3, and the currency must be the request's.
• Gating. It is a money path, so the scope checker default-denies it. On top, it answers 503 issue-not-wired and writes nothing until EVERY production piece exists: the reservation store (operator decision #2240, PR feat(db,gateway): R13 one-use budget reservations: durable store + atomic consume (SCHEMA CHANGE, approved under operator item 26) #402); exact request terms — an exact ceiling in base units AND the request's assurance floor, no defaults (fix(gateway): honest operator-relay evidence, claim authentication, immutable authorized ceiling (LO-GW-4/3a, R-06) #335's authorizedCeiling is a JS number defaulting to 1000; the requests table stores no floor today); and the payer-wallet binding (gateway N1/N21).
• Server faults are a generic 500. Nothing leaks (tested).

⚡ Decisions this needs (not mine)

1. Exact request terms — ceiling AND assurance floor (gateway, fix(gateway): honest operator-relay evidence, claim authentication, immutable authorized ceiling (LO-GW-4/3a, R-06) #335 R-06). Today authorizedCeiling = body.budget ?? 1000: a JS number with a DEFAULT, and the requests table stores no floor at all. For money authority both must be:

   • exact: base units of the request's currency for the ceiling, 0..3 for the floor;
   • explicit: a request without a stated budget has NO ceiling and issuance is refused, never 1000 — and no stated floor is refused, never defaulted;
   • immutable, which fix(gateway): honest operator-relay evidence, claim authentication, immutable authorized ceiling (LO-GW-4/3a, R-06) #335 already makes the ceiling.

   Production stays 503 until gateway provides both (round 2, M4).

2. The payer-wallet binding (gateway N1/N21). Which wallet pays for a principal's reservation? It is never a body field.

Tests (src/__tests__/reservations-route.test.ts, 4)

• End to end on ONE durable store: issue (201, server terms, body authority ignored) → accept (200, sealed) → read (consumed, the same digest) → accept again (409).

• Authority: 401; the 404 existence-oracle closure for requests and reservations; no bound wallet is 409.

• Exactness and bounds: eight malformed amounts; the TTL and floor bounds; currency mismatch; the ceiling exact to one base unit.

• Production and faults: 503 on both endpoints; a thrown resolver is a generic 500.

• 9 mutation checks, all killed:

  • principal, payer or id from the body
  • fix(gateway): honest operator-relay evidence, claim authentication, immutable authorized ceiling (LO-GW-4/3a, R-06) #335's default-1000 ceiling for an unknown request
  • JSON-number amounts
  • currency unmatched
  • TTL unbounded
  • GET showing another principal's reservation
  • a leaked fault message

  (Round 1 counts. Round 2 — M4 and the store clock — adds its own test and 4 mutation checks; see the Round 2 section above.)

pcc-composition 8a0f4de0, goal pcc-reconciliation.

🤖 Generated with Claude Code

https://claude.ai/code/session_0171FftEAfqjwbJHowVTqAbz