feat(spec): accepted-plan compiler — composition half of MS-01 (R12)

[LamaSu]

Round 7 (2026-09-29): astra's round-6 findings fixed at 59ee4ae

astra's round-6 review of 9d7686a returned SHIP-WITH-FIXES. Every finding is fixed in one commit, 59ee4ae:

Finding	Fix
F (HIGH) operator-below-quote was bypassable by omitting the quote	One quoteOf(node, gross) = quoteBaseUnits ?? gross feeds BOTH the splitter and the floor. An omitted quote is the gross everywhere, so it leaves no room for a royalty. The royalty fixtures now carry explicit quotes below the gross.
B (MEDIUM) the key list was enumerated before the bound, and keys sorted before their lengths were checked	Reflect.ownKeys is read once, and its count is checked before any descriptor read. Key checks run before the sort, with a fixed priority. The residual proxy and getter limits are documented.
B (LOW) an inherited index could fill an array hole	Every element must be the array's own.
D (pre-existing) a non-array edges became []	It is refused as invalid-plan-field edges.
E test gaps, including lone surrogates	The tests are added. Plan JSON refuses ill-formed UTF-16 in values and keys.

Evidence. Full spec suite 904/904, with the golden vectors unchanged. Mutations: 12 of 12 killed.

The round-7 pack is B-composition-351-r7-59ee4aef.md. It quotes the round-6 verdict verbatim, with one question per finding.

Still deferred to accepted-deal v3 (steward #3590 and #3591): ONE program per JOB instead of per plan. The compiler's per-plan refusal and the commitment's single plan-level program change together with the commitment's shape.

---

Reconciliation row R12 (goal pcc-reconciliation): the composition half of MS-01's accepted-deal compiler. This PR is a draft. The full external-plan path also needs:

• R10: live provider re-read
• R13: one-use reservations. The schema is an operator decision (bus #2240).
• escrow's R14 canonical V-next compiler. This PR deliberately does not duplicate it.

What it does

compileAcceptedPlan(input, { assertProgramForTier }) takes a plan that an external agent wrote, after the server has re-read its providers and resolved its programs. It outputs two things: the deterministic structure the V-next encoder consumes, and the node → execution-unit map that VCR consumes. PCC does no decomposition here.

Every guarantee is a check that fails closed with a typed violation:

• One V-next job per operator. PolicyIdentity has exactly one operator, and that operator signs the JobPolicy (escrow's frozen ABI §2–3). A payee who isn't the operator never signs. So a plan with several operators compiles to one job per operator. It never becomes one escrow that binds one operator's signature over another operator's terms.
• Canonical unit order. Unit order is money-significant, because unitsRoot folds the unit ids in array order. The order is a topological sort with ties broken by nodeId, so the order an LLM listed the nodes in cannot move a unit.
• Exact bigint economics. f = floor(g·feeBps/10000) and n = g − f. Payouts must conserve exactly for each unit (R34 ===). No JS Number touches the money path.
• Bounded authority. Σ g must fit inside the server-issued reservation, in its currency, for this request.
• Assurance. A non-zero tier needs a program hash, and the hash must pass the injected program gate (evidence's assertAcceptedProgramForTier, feat(spec): committed programs per CSD tier and the pre-funding assurance gate (must-close 6) #349). A missing hash is refused even if a permissive gate would approve it. With no gate injected, a non-zero tier is refused. Two different programs are refused under v3 rather than silently collapsed into one.
• A sealed deal. acceptedDealDigest is sha256 over the canonical form of the entire compiled deal. That covers every unit field (tier, fee, gross/fee/net, payees, order), the signing operators, the payer, the reservation, the currency and its decimals, and both v3 roots. The v3 compositionRoot commits the plan (contract, providers, prices, wallets, program) and is echoed into every unit. It does not commit the settlement terms: two deals that differ only in a tier, the fee or the signing operator share a compositionRoot but get different acceptedDealDigests.
• Server-resolved decimals. Decimals come from SETTLEMENT_TOKEN_DECIMALS (USDC = 6), never from the caller. An unknown currency is refused.
• Typed rejection. Malformed runtime input is refused with a typed violation, never with a throw or a coercion. That includes a non-string id and an array that stringifies to a valid id, currency or tier. Every node occurrence is validated, including duplicates, and the violations are sorted. So the diagnostics depend neither on input order nor on which duplicate came first.
• Frozen-ABI limits.
  • at most 16 units per job
  • 5 ≤ g ≤ 2^128−1
  • feeBps ≤ 1000
  • n > 0
  • operator ≠ payer
  • no zero addresses

Economics split hook (af425ed, R12 ↔ R15)

Economics asked where compileAcceptedPlan meets its compileEconomics (#2252). Composition adopts economics' own output shape: CompiledEconomics.units[] {unitRef, gross, fee, net, payouts[]} plus economicTermsHash and rightsTermsHash. It is injected as CompileDeps.splitNet, with unitRef = nodeId.

The compiler calls the splitter once, in canonical plan order. It holds the answer to its own numbers and refuses, never repairs, when any of these hold:

• The unit set is not exactly the plan's.
• gross/fee/net differ from floor(g·feeBps/10000) and n = g − f.
• A unit has fewer than 1 or more than 16 legs.
• A leg goes to the zero address, or has an amount that is not a positive integer base-unit string.
• A unit's legs don't conserve exactly. Every such unit is reported, not just the first.

Both terms hashes are sealed in acceptedDealDigest, and so is economics' agreementHash (see the next section). All three are null without an agreement. Without a splitter, nothing changes: one leg, and the payout address receives n.

agreementHash is sealed (2de38d7, economics #2755)

Economics asked, after an adversarial review of #360 (@bad29552), that acceptance bind agreementHash, not only the two terms hashes. The terms hashes do not cover the agreement's envelope (asOf, version, deadline), so sealing only them would leave asOf mutable after acceptance.

• NetSplitResult ok requires agreementHash. It is now structurally identical to economics' PlanSplitResult.
• snapshotSplit reads it exactly once, with the other scalars.
• A missing, malformed or non-string value is economics-malformed "agreement-hash"; a throwing getter is "result". It is never a throw.
• CompiledAcceptedPlan.agreementHash is lowercased, or null without an agreement. It is in the digest preimage.
• The domain moves to PCC:accepted-deal:v2, because the preimage schema changed. Nothing is persisted under v1: the R13 store is not built, and VCR carries the digest as opaque bytes.
• 3 new tests: sealed alone, required, and read once. Six mutation checks are all killed: the hash left out of the preimage, not digest-checked, re-read from the answer, not lowercased, dropped by compile, and swapped for the economic hash.
• This changes the PR after its round-5 SHIP, so round 6 goes back to cross-family review, queued with coord-watch.

8 new tests. 8 mutation checks, each caught by a failing test.

Hardening from cross-family review of the split hook (4479b79, ce18cf4)

Round 1: DO-NOT-SHIP. A recipient getter could grow the payouts array past the 16-leg cap. A hash getter could return one value to the check and another to the use. Throwing getters and proxies threw out of the compiler.

• Fix: the economics answer is copied into plain data, reading every property and every length once, inside one catch boundary. A throwing splitter still propagates as a server fault.

Round 2 closed all six findings. astra withdrew its "$ admits \n" claim, which is correct for JavaScript. It found one new escape: an answer getter, or the program gate, could mutate the caller's input through a shared reference after validation.

• Fix: the whole input is snapshotted into frozen, compiler-owned data before anything runs. Validation, the gate, the splitter, unit construction and the digest see only that copy.
• Bounds: 1024 nodes, 4096 edges, 64 evidence requirements per node.

Round 3: DO-NOT-SHIP. The general guarantee was still open:

• callable objects and non-array containers kept caller references

• the catch could throw on a hostile thrown value

• the gate's answer was read unprotected

• Fix (0571c00): every structurally invalid value becomes a frozen compiler-owned sentinel (NOT_DATA), so no caller reference survives. A bound is recognized by the identity of a token the compiler owns. The gate's answer is read once, defensively.

• New test: a deep read-counting proxy proves every input property is read at most once, and that the result equals the plain compile.

Round 4: the round-3 findings are CLOSED. It blocked on the deps callbacks being read twice: a callback could swap a dependency between reads.

• Fix (2c6324d): both callbacks are read once, before any input. A present-but-non-function slot fails closed. The answer's scalars are normalized.

Round 5: SHIP. No validation/use mismatch, retained caller reference or escaping exception remains beyond the stated server faults (the gate or splitter function throwing), and there are no material test gaps. Its one nonblocking suggestion is applied in 69012b4.

N25: the deal seals each node's execution contract (6060331)

VCR recomputes planHash = sha256(canonicalize(canonicalPlan)) from the plan bytes it receives, and requires it to equal the node's planHash sealed in acceptedDealDigest (VCR #2300 and #2332). Before this, the deal sealed money and assurance but not WHICH document gets printed.

• plan-json.ts. A node's inputs and constraints are the caller's plain-JSON CONTENT: WHAT runs, never who is paid. The copy is exactly JSON and bounded (depth, keys, lengths, values, 8 KiB canonical) and reads every property once. Bad JSON is refused as invalid-execution-json for every bad field, independent of node order.

• canonical-plan.ts. VCR's per-node contract:

  • schema, plan and node id, capability (type, id, CSD, digest);
  • operator, payTo;
  • the exact amount in base units;
  • job and unit;
  • assurance (tier, program, evidence);
  • inputs and constraints.

  planHash is byte-exact against VCR's crossrepo-accepted-bundle-v1, including its one-byte mutation.

• Sealing. Each NodeUnitBinding carries canonicalPlan + planHash. The preimage (domain PCC:accepted-deal:v2) seals the carried planHash AND a hash recomputed from the carried content, so the consumer's recompute-and-compare catches tampering of either.

• Golden vector for VCR: execution-contract.vectors.json (the deal, canonicalPlans, planHashes, digest and 3 mutations). A copy is at /mnt/sparkbulk/pcc-reconciliation/vectors/composition-accepted-deal-v2.json.

• 13 tests; 25 mutation checks, all killed.

Economics option (b), royalties on top (9be1e8b, economics #3025)

With an agreement, a unit's gross is the agreement's, and the operator's live quote is at most that gross. An optional per-node quoteBaseUnits is read once and must be at most the gross; absent means quote = gross. It is passed to the splitter as quote, so economics can hold the operator's legs to at least quote - floor(quote*feeBps/1e4). Nothing new is sealed: the live quote is committed through matchedCapabilityDigest, and the grossed-up price through g/f/n and the legs. The golden vector is unchanged. 3 tests; 4 mutation checks, all killed.

Cross-family status: round 6 (agreementHash + N25 + quote, now including the 9d7686a self-review fixes below) goes through the operator's ChatGPT review as pack B-composition-351-r6c-9d7686af.md.

Self-review fixes (9d7686a)

An adversarial self-review of 9be1e8b (same model family, so it does not replace the cross-family round; its verdict was SHIP-WITH-FIXES) found one HIGH and several LOW gaps. Each fix has a test that fails without it.

• D5 (HIGH), plan-json number policy. An integer outside ±(2^53−1) is refused as unsafe-integer — VCR, the oracle and fix(spec): canonicalize refuses values that have no JSON form #359 refuse to hash one (the shared vector's policyD5), so sealing one sealed a planHash nobody could recompute. A larger value must be sent as a decimal string.
• plan-json. Keys are visited in sorted order, so which refusal an input gets no longer depends on key insertion order (finding 8). The canonical-size bound is checked AS the copy grows, on a sound lower bound (string and key lengths), so an oversized input is refused before the rest is read (finding 7). The header now says symbol-keyed and non-enumerable properties are ignored, as JSON.stringify ignores them (finding 10).
• Compiler, evidence requirements (findings 2, 5). Each requirement must be an object with printable-ASCII ids and an integer tier 0..3. A number, boolean, bigint or symbol id is refused and never throws. They are sealed sorted by (evidenceTypeId, tier, requirementId), so the order they are listed in cannot change the planHash or the deal.
• Compiler, quotes and the operator floor (finding 4). A quote that differs from the gross is refused without an agreement (quote-without-agreement). With an agreement, the legs to the node's payout address must carry at least the quote's net (operator-below-quote). Addresses are compared case-insensitively.
• Compiler, diagnostics and the preimage (findings 3b, 6). The too-many-payout-legs count is clamped, so a lying length cannot put an unsafe integer into the diagnostics. The preimage seals the carried planHash verbatim — it was case-folded, and VCR compares planHash byte-exactly.
• A test-file type error from 9be1e8b is fixed: a SplitUnitInput literal lacked quote.
• execution-contract.vectors.json gains two sections; every existing value is unchanged: refusals (the D5 case) and edgeCases/F7 (Unicode keys in UTF-16 code-unit order, JavaScript's shortest number forms, and -0).

Findings 9 (cross-language string hazards) and 11 (planHash is unique only through planId) are INFO and are noted in the PR, not changed here.

Also in this head (79b6c1d, amendment #3231): acceptedDealPreimage is now exported — the canonical bytes acceptedDealDigest hashes. R13 stores the sealed deal as the digest's own preimage, so sha256(stored bytes) == consumed_deal_digest holds literally (steward condition (a), #3235). acceptedDealDigest is now sha256 of acceptedDealPreimage(plan). Behaviour and digest are unchanged; the golden vector still matches.

Consumer contract (R13 / R14 must honor this; flagged by review)

• The reservation consume must recompute and compare. It must recompute acceptedDealDigest from the compiled plan it is about to encode, compare it to the digest it seals, and do both in the same atomic step that consumes the reservation. Carrying the digest along, or authorizing by compositionRoot alone, would reopen the "different deals, same root" hole.
• The encoder must encode exactly the sealed units. On-chain, each job's prePolicyRoot then binds those units.
• The ReservationRef must come from the durable store. The route (R9) loads it from the store by id (R13). It is never taken from a receipt the caller presents.

Not in this PR (by design)

• ABI encoding (escrow R14)
• reservation issue and consume (the R13 store)
• provider re-read (R10)
• the HTTP route (R9, which needs R28 scopes)
• a VCR canonicalPlan emitter. Its shape is still to be pinned with VCR. This PR emits the node→unit binding, including the stepId string and keccak256(utf8(stepId)).

Cross-family review

1. sol + astra on 44fd8d1: DO-NOT-SHIP. Findings:

   • the plan root didn't bind tier, fee or signing operator
   • caller-controlled decimals
   • a null program on a non-zero tier got past a permissive gate
   • input-ordered diagnostics

   Fixed in fb68b1d.

2. astra's confirmation of fb68b1d: SHIP-WITH-FIXES. Findings 1–3 are CLOSED. Finding 4 was still open: when two nodes shared an id, which violations got reported depended on which copy came first. Astra also found a robustness gap: a non-string operator threw a TypeError before the rejection was returned. Both are fixed in e2100a3.

3. Coverage. The reviewer found no settlement-significant compiled field that can change without changing the digest.

4. Rounds 3-5 (astra), on the read-once input snapshot and dependency capture. Round 5 on 2c6324d returned SHIP; 69012b4 added its one nonblocking suggestion.

5. Round 6, at 9d7686a (agreementHash, N25, the quote, the preimage export and the self-review fixes): goes through the operator's ChatGPT review as pack B-composition-351-r6c-9d7686af.md.

Tests

• 76 tests in packages/spec/src/csd/accepted-plan-compiler.test.ts, plus 13 in execution-contract.test.ts. They include the required negatives:

  • obligation over the reservation
  • a reservation for another request or currency
  • an unapproved program; a missing gate; a program on tier 0; mixed programs; a null program on a non-zero tier
  • a duplicate node (no double obligation, order-independent diagnostics)
  • a cycle, self-loop, unknown edge or duplicate edge
  • more than 16 units per operator
  • operator == payer
  • fee rules; gross bounds
  • malformed and coerced input
  • permutation and idempotence determinism
  • each settlement term (tier in isolation, fee, operator, decimals) changes the sealed digest

• Full @pcc/spec: 898/898 at 9d7686a (887/887 after 79b6c1d's preimage export; 886/886 before it). tsc --noEmit is clean, for the package and for the test files.

• Mutation checks. Each of these mutations turns a test red:

  • removing the reservation cap
  • skipping the missing-gate refusal
  • reversing the tie-break
  • rounding the fee up
  • dropping the tier from the deal digest

  The four tests added for astra's confirmation each fail against fb68b1d.

• 9d7686a self-review: 21 mutation checks, all killed, each by a failing test. Three first-pass gaps got tests before the run: the key-size floor, the tier tie-break, and case-insensitive payout-address matching. A test-file type error from 9be1e8b — a SplitUnitInput literal missing quote — is fixed in this commit.

Reconciliation note: /mnt/sparkbulk/pcc-reconciliation/returns/pcc-composition-reconciliation-note.md (findings A–D).

🤖 Generated with Claude Code

https://claude.ai/code/session_0171FftEAfqjwbJHowVTqAbz