feat(gateway): live provider re-read for externally authored plans (R10)

[LamaSu]

Round 3 (2026-09-29): astra's findings on d9a2185 (pack 44, DO-NOT-SHIP) fixed at 478dd7c

• D, the argument edit: both requested-id sets are now built BEFORE their loaders run, and each loader gets a copy of the ids. astra's attack (a loader emptying its argument) is a test.
• The tenant regression round 2 introduced: duplicates are judged PER ID.
  • A duplicated id with no copy visible to the caller looks exactly like an absent row: the same verdict, and no kernel lookup.
  • A contradiction the caller can see (public or own, plus foreign) is still refused, in either order.
• K, T, C and the decimal bound were confirmed closed by astra.
• Evidence: gateway 2984 passed; mutations 6 of 7 killed, plus one equivalent.
• Round-3 pack: 69-composition-r10-355-r3-478dd7c0.md.

---

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

The operator's ChatGPT review of c48af89 was DO-NOT-SHIP with four blocking findings. All four are fixed in d9a2185, each with a test that fails without it:

• Kernel status was not an allowlist. judge accepted any string except "suspended", so "offline", "retired" or an unrecognized value still reached current. Fixed: kernel status is now an ALLOWLIST, and only "online" is available. offline, maintenance and expired are unavailable/kernel-not-online; suspended stays operator-suspended; any other string ("retired", "", "ONLINE") is malformed-live-row.
• tenantId: "" was treated as a real tenant. Fixed: the tenant option must be a well-formed id, or the caller sees public rows only — an empty string is never a tenant — and a row whose tenant is not a well-formed id is visible to nobody.
• Duplicate live rows could silently pick a winner. Fixed: a REQUESTED id that appears twice in either loader answer makes that answer malformed, in either order, exactly like any other malformed answer. A broken second copy counts too — its id is reported even when the rest of the row cannot be read. Unrequested rows are still ignored.
• One call could resolve two ways for one type. Fixed: csdForType is called at most once per capability type, so two nodes of one type cannot resolve against two CSDs.
• Decimal cap. The verdict's resource note: a decimal string over 100 characters is now malformed before any BigInt work.

Tests: 6 new, R10 53/53, and tsc is clean for the service and its tests. 12 mutation checks: 10 killed. T1 and T2 SURVIVE, and they are an equivalent pair — validating the tenant option and validating the row tenant each close the tenant finding alone, because a visible scoped row must equal a validated option; removing both is killed. Both are kept as defense in depth.

Out of scope for this PR, and tracked: the verdict's section B/C5 asks that acceptance bind to row versions within one snapshot. That is the accept path (#356/#391), so it follows their first-round verdicts.

Round-2 pack: 44-composition-r10-355-r2-d9a2185c.md.

---

Reconciliation row R10 (goal pcc-reconciliation; MUST-CLOSE 3 and 4 of the composition charter): the gateway re-reads live provider rows for a plan an external agent wrote.

Stacked on #351. It uses #351's SETTLEMENT_TOKEN_DECIMALS, tierFromKey and MAX_GROSS_BASE_UNITS. The base retargets to master when #351 lands.

What it does

revalidatePlanSnapshots(claims, deps, { tenantId }) takes, for each node, what the caller claims: capability, price, currency, tier, the kernel it was quoted and the operator it expects to pay (both required: the digest does not cover the operator), and optional cross-checks (type, CSD, deal-snapshot digest). None of it is authoritative. The service then:

1. re-reads every capability and its kernel live, with one batched load per table;
2. recomputes the deal-snapshot digest with the decomposer's own inputs. A test pins that it equals the createMatcher digest for the same row;
3. returns one typed verdict per node, sorted by node id.

verdict	meaning
current	The claim matches the live row. resolved holds the server's terms: operator, gross in base units, digest, CSD. These are the only values the R12 compiler may take.
stale	The live row differs from the claim. diffs lists each field, and live is the re-quote. Never silently accepted: the caller re-submits against live.
missing	No such capability (or it is scoped to another tenant; the two look identical), or its kernel is gone.
unavailable	The operator is suspended, the settlement address is invalid or zero, or the row's tiers are malformed.
unpriceable	There is no exact flat price in a settleable currency.
incompatible	The capability type maps to no CSD, so there is no evidence contract to settle against.
invalid-claim	The claim itself is malformed, or a node id is duplicated.

Exact money:

• Price compare. Prices are compared as canonical decimal strings, so equal strings mean equal amounts.
• Gross. The gross is computed from the live decimal string in base units.
• What it never uses. It never goes through the digest's toFixed(2), which cannot see 6.504 vs 6.50; a test shows the digest collides there while the verdict is still stale. Nor through capPrice's fallback to 0 for an unpriced row.
• What it refuses rather than guesses:
  • an unpriced row
  • a missing currency (never defaulted to USDC) or an unknown one
  • variable pricing (it needs a parameterized quote)
  • sub-base-unit precision
  • a price out of range
  • baseCost < minimum, where the real charge would differ from what the digest commits

Payout wallet. payoutAddress is the kernel's operatorAddress. No payout-wallet store exists yet (#1690), and a caller-supplied payout address is never used.

Charter negatives

• Forged cheaper snapshot, including a digest computed over the forgery: stale, and the server's gross comes back.
• Provider price change between quote and accept: stale. Re-submitting against the re-quote gives current at the new price.
• A tier the provider no longer offers: stale.

Not in this PR

• the HTTP route (R9; it needs R28 money scopes)
• program resolution (R11, via evidence's feat(spec): committed programs per CSD tier and the pre-funding assurance gate (must-close 6) #349 gate)
• evidence requirements (read from the resolved CSD tier by the route)
• wiring the loaders to repos.capabilities.findByIds / repos.kernels.findByIds and csdForType to CsdRegistry.findUrlByType + csdSlugFromUrl. The row types are structurally compatible, so the route passes them directly.

Known limit, raised with gateway (#2241). The deal-snapshot digest preimage does not cover the settlement wallet, the measurement profile or a CSD version. R10 compares the operator and the CSD directly instead. Extending the preimage changes every digest, so it needs a versioned digest and is not done here.

Cross-family review (astra)

1. e20cd89: DO-NOT-SHIP. Findings:

   • (A) Tier default. The decomposer's assuranceTiers ?? [0,1] was mirrored for digest compatibility, so a row with no tiers sold tier 1 as current.
   • (C1) Side channel. Kernels were looked up for foreign-tenant capabilities.
   • (C2) Operator rotation. The operator cross-check was optional and the digest omits the operator, so an operator change since the quote passed as current.
   • (D) Throws. A loader returning [null] threw.
   • (E) Test gaps.

   Fixed in 8472b46:

   • tiers are never defaulted
   • kernelId and operator are required claim fields
   • visibility is applied before any kernel lookup
   • malformed rows get typed verdicts

2. astra's confirmation of 8472b46: SHIP-WITH-FIXES. All five findings are CLOSED. One gap remained: sparse-array holes passed every, and a shadowed every threw. Fixed in 27a23c6: tiers are read by index into a plain copy.

Review rounds 3 and 4 (astra) — fixed in 9a6da15 and c48af89

• Round 3: DO-NOT-SHIP. The same getter/proxy/callback class closed in feat(spec): accepted-plan compiler — composition half of MS-01 (R12) #351. Claims and live rows were re-read after validation: a tierKey getter, a loader re-pointing node ids, a csdForType callback mutating the row, a pricing getter splitting gross from digest, and a baseCost getter bypassing the minimum. Throwing getters escaped.

  • Fix: every claim, row (with a pricing snapshot and a fixed-length tier copy), kernel and loader answer is read once into owned data.
  • Failure handling: a failure to read data is a typed verdict; a loader or csdForType call that throws still propagates.

• Round 4: DO-NOT-SHIP. Four holes remained:

  • the tenant sentinel compared equal
  • wiring reads were unguarded
  • duplicates were counted over valid claims only
  • detached calls dropped this

  Fix:

  • visibility matches strings only
  • an unreadable dependency is a defined TypeError
  • duplicates are counted over every claim whose id was read
  • dependencies are called with their receiver
  • an over-cap list is too-many-claims

• Round 5 is queued for the codex reset at 14:42.

Tests

• 33 in packages/gateway/src/__tests__/plan-snapshot-revalidation.test.ts. Each review-driven test fails against the commit before its fix.
• The existing digest and decomposer-digest tests still pass.
• A scoped tsc over the new files and the spec sources is clean.
• 13 mutation checks, each caught by a failing test:
  • drop the exact price compare
  • drop the tier-offered check
  • drop tenant scoping
  • restore the tier default
  • make the operator optional again
  • remove the malformed-row guard
  • default the currency to USDC
  • drop the minimum-charge check
  • case-sensitive operator compare
  • unsorted verdicts
  • swallowed loader errors
  • first duplicate wins
  • allow a suspended operator
• Additive only: no existing file changes.
• Consumed by feat(gateway): accept seam for externally authored plans + end-to-end trace (R9 pure part) #356, the accept seam and end-to-end trace, stacked on this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_0171FftEAfqjwbJHowVTqAbz