feat(gateway): accept seam for externally authored plans + end-to-end trace (R9 pure part)

[LamaSu]

Round 3 (2026-09-29): astra's findings on a16095a (pack B-356-r2b, DO-NOT-SHIP) fixed at 184a0e3

• A (authority): R10's nested callables (loadCapabilities, loadKernels, csdForType) are captured and validated before ANY submission property is read. R10 gets frozen pinned wrappers that use the original receiver.
• C (authority): ctx.principal and ctx.tenantId are read once, before the submission.
• B (digest): leaf() turns a symbol into NOT_DATA and -0 into 0, so the snapshot never keeps two values that encode alike.
• Evidence: gateway 3020 passed; mutations 6 of 6 killed. One mutant first survived, which exposed a missing test; that test is now added.
• Round-3 pack: 70-composition-356-r3-184a0e39.md.

---

Reconciliation row R9, pure part (goal pcc-reconciliation; ledger item 27, "no path for an externally authored plan"): the accept seam that chains R10 → R11 → R12. It also carries the composition return contract's end-to-end trace.

Stacked on #355 (R10), which is stacked on #351 (R12).

What it does

acceptExternalPlan(submission, { principal, tenantId }, deps) injects every read, so the accept decision is a pure function of (submission, principal, live state).

What the agent supplies: only the plan's shape and what it believes each node costs.

What the server decides: every settlement term.

term	source
operator and payout address	R10 live re-read
gross, currency	R10 live re-read
program	R11, resolved server-side and checked by evidence's gate
evidence requirements	the CSD tier (evidence owns this mapping)
payer	the durable reservation
fee, reclaim time	server policy
plan id	derived from the reservation. A caller cannot pick job ids that collide with another plan's.

Refusals are typed by stage:

• submission
• reservation: not-found, not-issued, expired, wrong-principal, wrong-request
• revalidation: the non-current verdicts. A stale verdict carries the re-quote.
• currency
• program: the claimed program doesn't match
• evidence: no evidence contract for the tier
• compile

The trace (external-plan-trace.test.ts)

1. Agent DAG. The nodes are listed mail-first, although print must run first.
2. R10 → R11 → R12 → accepted deal. The result is 2 V-next jobs, one per operator, in canonical order. Economics are bigint: g/f/n = 6.50 → 152,750 / 6,347,250 at 235 bps. The deal digest is sealed.
3. Reservation consumed exactly once.
4. V-next units ready. Each unit conserves exactly and carries its step id, the root and reclaimAt.

PCC_TRACE_OUT=<path> writes the happy path as JSON. The current run is at /mnt/sparkbulk/pcc-reconciliation/returns/pcc-composition-trace.json.

Charter negatives, through the whole seam:

• forged cheaper snapshot
• unapproved program (a claimed mismatch, or none registered)
• expired reservation
• principal or request A used for B
• obligation over the reservation
• double consume: exactly one lands
• duplicate node: no double obligation
• a plan altered after acceptance: digest-mismatch at consume
• caller-chosen planId or payout: ignored
• currency and evidence refusals
• malformed input: typed, never a throw

/api/compose is one planner among many (f2d74b3)

submissionFromComposeResponse() restates a ComposeResponse as the claims an agent would submit:

• nodes become step-<index>
• dependsOn becomes edges
• the composer's float price is passed through verbatim

Those claims then go through the same seam, so the composer gets no shortcut:

• Drift from the live rows returns stale with a re-quote.
• An exponent-form float such as 1e-7 is a malformed claim.
• Refused before the seam:
  • expired or non-proposed proposals
  • dangling dependencies
  • duplicate step indices

Tests: 3 new. 4 mutation checks, each caught by a failing test.

Cross-family review (astra): SHIP-WITH-FIXES, fixed in 190bf9a

Confirmed:

• Where each term comes from:
  • payer: the reservation
  • operator and payout: the live kernel
  • gross, currency, program, evidence, fee, reclaim time, plan id: the server
• The reservation ID is only a lookup key. Authority is the stored record plus the authenticated principal. This satisfies the charter's "no caller reservation ID as authority".

Fixed:

• Tier. The tier is the principal's purchase choice, constrained by the live offer. A reservation may carry a minTier floor, and a delegate cannot downgrade it.
• Compose adapter. Values whose coercion throws now get a typed refusal. The validation boundary is explicit: structure is checked here, meaning in R10.
• Seam:
  • an empty principal matches nothing
  • the clock is floored
  • a non-finite clock fails closed
• R13 stand-in consume. It now re-checks plan id and each job's payer, and derives the obligation from the units. "A recomputed digest proves integrity, not authority."

Tests: 23, with 7 new; the fix-driven tests fail against f2d74b3. Mutation checks: seam 10/10 caught, adapter 6/6 caught.

Read-once seam (70f9582), confirmation queued

This applies the pattern that closed #351 and #355.

• The submission is copied once by snapshotSubmission. The program cross-check, R10 and the compile use only that copy.
• The reservation record is read once. A malformed record is refused as malformed-reservation.
• Dependencies and policy are read once. An unreadable one is a defined TypeError. Dependencies are called with their receiver.
• Every outcome carries submissionDigest, a type-tagged sha256 of the submission exactly as evaluated, and verdicts. The presentation (feat(gateway): PlanPresentation read model for caller-authored plans (product section 5) #357) uses the digest to bind what it displays.
• Tests: 30 in the trace file (7 new).
• Mutation checks: 17/17 caught. That is 7 new plus the 10 earlier ones, re-anchored.

N25: execution inputs reach the sealed deal (4f30bb1)

• A node may carry inputs and constraints: plain JSON, the caller's content (e.g. which document and how many pages), never authority.
• The snapshot reads each one once through @pcc/spec's copyPlanJson, as absent, an owned frozen copy, or the refusal reason.
• submissionDigest v2 encodes them. Absent, {} and invalid all differ, and invalid evaluates to its reason.
• Invalid execution JSON is refused as {stage:"submission", reason:"invalid-execution-json", fields}. It names EVERY bad field in (nodeId, field) order, before any reservation read.
• The compiler (feat(spec): accepted-plan compiler — composition half of MS-01 (R12) #351) seals them in each node's canonicalPlan and planHash.
• 5 tests; 8 mutation checks, all killed.

R15 economics binding, option (b) royalties on top (a16095a)

• The dependency. Optional SeamDeps.economics = { unitGross, splitNet }: economics' agreementUnitGross and netSplitterFor, bound per request by the route to the agreement and the server's facts. It is read once, and both functions are called with the binding as receiver.
• Gross vs quote. Each node's gross must exist and cover the operator's live quote from R10. Otherwise it is a typed refusal at the new economics stage before the compile: agreement-refused (with economics' code), agreement-unreadable, unit-gross-missing or quote-not-covered.
• The compile. The compiler gets gross = the agreement's, quoteBaseUnits = the live quote, and splitNet, so the reservation must cover the grossed-up total.
• Without an agreement nothing changes.
• 4 tests; 8 mutation checks, all killed. The route's production wiring of economics waits on an agreement source and the server facts store.

Cross-family status: round 2 (the read-once seam + N25 + economics) is queued for the 19:43 PDT codex window at a16095a (#3177).

Stand-ins (labelled in the test)

• Live rows: in memory, not the db repos.
• Program registry and gate: evidence's feat(spec): committed programs per CSD tier and the pre-funding assurance gate (must-close 6) #349 is still a draft.
• CSD tier → evidence map: evidence owns it.
• The R13 reservation store: its table is operator decision #2240. The stand-in implements the consume protocol the real store must follow: re-check, recompute the digest, consume once, seal. It does not prove database atomicity; that is R13's own test.

Not in this PR

• The HTTP route (R9). It needs R28 money scopes (Gate A). I'll ask the steward before landing it.
• The real R13 store.
• Escrow's R14 encoder.

Tests

• 23 tests (seam, trace, compose adapter).
• 7 mutation checks, each caught by a failing test:
  • principal check
  • expiry check
  • node-currency check
  • program cross-check
  • caller-chosen planId
  • missing evidence tolerated
  • request check
• The scoped tsc is clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_0171FftEAfqjwbJHowVTqAbz