feat(gateway): R9 agent-plan routes — validate (live R10) and accept (seam → VCR deal binding → one R13 consume); money-path gated, 503 until wired

[LamaSu]

Round 2 (2026-09-29): astra's findings on 3f68ab7 (pack B-391-r1, SHIP-WITH-FIXES) fixed at 1601cae

• Receiver: the seam's members are read once and called on the ORIGINAL seam; only the clock is replaced. A #private-field seam class is tested.
• Hygiene: only PUBLIC_CONSUME_REASONS (the R13 store's codes for the caller's own reservation) reach the client, as 409. Anything else is logged and answered with a generic 500.
• Binding: the node-to-unit bijection is checked ("binding-not-one-to-one", "unit-count"). Interleaved same-operator nodes are tested.
• Ordering: the success body is built before the commit.
• Production gates (accept stays 503 until they close):
  • recovery of the sealed deal after lost delivery;
  • the real fix(gateway)!: WP-A scope hardening — wildcard is not money/admin authority, fail-closed scopes, identity binding (P0 MUST-CLOSE 6-10) #326 scope tests;
  • durable-store concurrency (feat(db,gateway): R13 one-use budget reservations: durable store + atomic consume (SCHEMA CHANGE, approved under operator item 26) #402);
  • escrow encoder to VCR acceptance.
• Evidence: gateway 3052 passed; mutations 6 of 6 killed.
• Round-2 pack: 71-composition-391-r2-1601cae7.md.

---

Draft, stacked on #357 (PlanPresentation) → #356 (accept seam) → #355 (R10) → #351 (compiler). Reconciliation row R9, the HTTP half. It cannot merge before gateway's WP-A (R28, #326), and merging is the operator's call (steward #2461, #2643). Retarget the stack to master before merge (board rule 4).

What it does

An arbitrary external agent submits the plan it composed. The server decides what it costs, who is paid, and what is sealed.

Route	What it does	Production today
POST /api/agent-plans/validate	Read-only R10 pre-check: each node's claim against the live row, with the live re-quote when it is stale. Moves nothing.	Wired: live capability and kernel rows (repos.*.findByIds) and the CSD registry.
POST /api/settlement/agent-plans/accept	The accept seam (R10 → R11 → R12), then escrow's unit ids and VCR's deal binding, then ONE atomic R13 consume that seals acceptedDealDigest.	503 accept-not-wired, listing what is missing. Consumes nothing.

Accept stays 503 until every piece exists:

• the R13 reservation store (its table is operator decision #2240);
• evidence's program resolver and gate (feat(spec): committed programs per CSD tier and the pre-funding assurance gate (must-close 6) #349);
• evidence's CSD-tier → requirement map;
• the server fee policy;
• escrow's encoder (feat(contracts): freeze the V-next settlement ABI + canonical compiler @pcc/contracts/vnext (R14) #367), plus oracle's termsHash and acceptedPolicyDigest (a unit id derives from its escrow clone's identity).

Authority

• Principal. authenticatedPrincipal(req) is the API gate's identity: the key's operatorId, else the SIWE wallet, lowercased. It is never a body field. R13's reservation-issue route must use the same function.
• Tenant. R10 visibility uses the gate's req.tenantId. A tenantId in the body is ignored (tested).
• Gating. /api/settlement/ is a money-path prefix, so the scope checker default-denies its writes. After WP-A a caller needs an explicit settlement (or admin) scope, and a wildcard key no longer counts. This PR adds no scope rule; that is WP-A's table.
• No existence oracle. Another principal's reservation gets exactly the same 404 as a missing one, in the refusal and in the presentation (tested byte-level: wrong-principal never appears).

Order on accept, and what fails closed

1. One clock reading per request. The seam, the consume and asOf all use it; the seam receives it through a prototype wrapper, so method-style dependencies keep their receiver. A non-finite or negative clock is 500 clock-unavailable.
2. The seam. Its refusals map to status codes: malformed → 400; not-found/wrong-principal → 404; not-issued/expired → 409; everything else → 422. Each carries the verdicts and a PlanPresentation: a stale plan shows needs-requote, Layer C.
3. The deal binding (services/agent-plan-deal.ts, pure):
   • VCR's 64-unit limit is checked BEFORE the encoder: 422 too-many-units-for-deal.
   • Then escrow's unit ids, read once and checked against the deal: the same jobs, in the same order, one bytes32 per unit, all distinct. Anything else is 500 deal-binding-failed.
   • Edges come from the submission exactly as the seam evaluated it: the route re-snapshots the body and matches the seam's submissionDigest.
4. The consume (R13's atomic re-check, digest recompute, consume once and seal). Only an explicit { ok: true } is a seal; anything else is 409 reservation-conflict. A plan that cannot be bound never consumes its reservation.
5. 200 returns the plan (bigints as decimal strings), the deal bindings, submissionDigest, the seal record, and a PlanPresentation (Layer B, sealed).

• A thrown server fault is a generic 500 internal-error. Its message is logged, never returned (tested).

VCR deal binding (#2475, #2674; board N22, N25, N37)

binding(node) = { digest: acceptedDealDigest, units: every unit id of the deal in plan order (1..64, distinct), nodeId, requires: unit ids of the node's DIRECT predecessors }.

• For print → mail: mail requires [unit(print)], and print requires [].
• A diamond a→b, a→c, b→d, c→d gives d requires [unit(b), unit(c)], in the deal's unit order, and never the unit itself.
• The direction is as proposed to VCR in #2763; VCR's confirmation is pending. If VCR wants successors instead, the change is one line and its mutation (D3) is already tested.

Tests (src/__tests__/agent-plans-route.test.ts, 17 tests)

REAL on the path: the route, R10, the seam, R12 and PlanPresentation. STAND-INS, labelled as such: the live rows, evidence's gate, the evidence map, the R13 consume PROTOCOL (the trace's, unchanged) and a deterministic encoder. The real escrow compiler (#367) is proven in composition's R14 probe. Covered:

• validate: current; stale plus re-quote; the gate's tenant, not the body's; 401 and 400.
• accept:
  • production 503;
  • the whole path, with the seal, the bindings and Layer B;
  • principal from the gate only, and the existence-oracle closure;
  • exactly once: sequential 409, and of two concurrent accepts one 200 and one 409;
  • stale → needs-requote, nothing consumed;
  • 64 units accepted, 65 refused before the encoder;
  • eight encoder mismatches → 500, nothing consumed;
  • four malformed or refusing consumes → 409, never "sealed";
  • one clock read, four broken clocks, a fault that leaks nothing;
  • method-style wiring.
• bindDeal: the diamond; edge mismatches before the encoder; a throwing encoder propagates.
• authenticatedPrincipal unit cases.
• N25 over HTTP (918fefb): each node's inputs come back sealed in its canonicalPlan, and the Layer-B presentation shows the same execution. A non-object or over-bound inputs is 400 and consumes nothing.
• 21 mutation checks, all killed. Route (10): principal from the body, wrong-principal not hidden, consume before the binding, a truthy consume counted as sealed, the seam given the live clock, a broken clock accepted, a fault message leaked, wiring called detached, tenant from the body, validate without auth. Deal binder (11): the cap off by one, the cap after the encoder, requires direction flipped, duplicate ids, job id or bytes32 or unit count unchecked (the phantom-unit case was added for the last), unsorted requires, unknown or self-loop edges, the encoder before the edge check.
• Typecheck clean for the route, the binder and the test. Full gateway suite: 3033 passed and 6 skipped, the same as feat(gateway): PlanPresentation read model for caller-authored plans (product section 5) #357 plus these 16. The two capture suites fail to load because @pcc/verifier/dist is not built (as on master); completion-real-tier timed out once at load average 27 and passes alone (3/3).

Not in this PR

• Economics' netSplitterFor binding. The seam takes no splitNet yet; it needs server facts (#2755), and unitFacts stay empty until kits' resolver exists.
• The reservation-issue route (R13).
• A read route for a sealed deal.
• Emitting the DAG's edges from the compiler itself. requires is derived from the evaluated submission today, whose edges compositionRoot commits.
• Any scope-table change (WP-A).

Cross-family status: round 1 is queued for the 19:43 PDT codex window at 3f68ab7 (#3177). That head only merges the stack below; the route's own code is 918fefb's.

pcc-composition 8a0f4de0, goal pcc-reconciliation.

🤖 Generated with Claude Code

https://claude.ai/code/session_0171FftEAfqjwbJHowVTqAbz