feat(spec): planProvenance, the deterministic provenance planner (ADK D2)

[LamaSu]

What

ADK D2: the deterministic provenance planner, planProvenance() in @pcc/spec/evidence. Evidence agreed that it lives here, under their review (#2752).

For one capability contract (CSD) and one operator setup (adapter types, device roles, operator adjustments), it answers three questions:

• which assurance tier the setup can reach;
• why it stops there;
• what would unlock the next tier, meaning which primitive is missing and which default emitter (an adapter or a device role) supplies it.

The gateway can expose it, and the ADK runs the same function locally. That makes it the onboarding half of N56: "your machine supports this assurance; add a camera to unlock these jobs".

How

No new evidence logic. It composes the engine that exists but nothing calls:

• Contract side: computeCsdEligibility, with the rule unchanged and the same options, including requireImplementedVerifier for the oracle-enforcing mode.
• Supply side: ADAPTER_DEFAULT_MANIFESTS and DEVICE_ROLE_DEFAULT_MANIFESTS, plus explicit operator add and remove.
• Hints: defaultEmitterIndex() maps each primitive to the default emitters that supply it, and never suggests mock.
• Identity: provenancePlanDigest(plan) = sha256(canonicalize(plan)), using spec's single canonicalizer.

Rules (each has a test)

Rule	How it is enforced
Never reads a self-declared tier	Only csd.url and csd.evidence are read. maxAssuranceTier and assuranceTiers leave the digest unchanged.
mock never exceeds tier 0	It caps even when the operator declares every primitive.
Achievable = contract-eligible and fully supplied	Per tier, then cumulative. An unachievable tier 0 blocks every higher tier, matching the lint.
Human approval and payment are settlement steps	attest and pay primitives are listed, never counted as hardware gaps. The tier≥2 human floor still comes from the lint.
Unknown adapter, role or primitive	The adapter or role supplies nothing and gets an advisory. An unknown primitive in the contract blocks its tier; one added by the operator is ignored, with an advisory.
Operator-declared emitters are claims	Flagged: nothing is demonstrated until a real test job produces it.
Deterministic	Inputs are de-duplicated and sorted, and the contract's refs are put in canonical order before the lint, because the lint's reasons follow ref order. Every output list is sorted. Any permutation gives the same digest.

It never mints assurance and does not decide fundability. Fundability is #349's pre-funding gate (assertAcceptedProgramForTier: the committed program hash, plus tiers 0..T eligible with implemented verifiers); a fundable flag can compose with it once #349 merges. Evidence reviewed and APPROVED this PR (#3174); the doc fix is df9f0efd.

What it says about today's built-in contracts

These match what the evidence lane found independently (#383):

• 2d-print is legacy free-text, so it is capped at tier 0 for any hardware.
• document-print-and-mail:
  • the contract caps itself at 0, because tier 1 lists receipt.kernel_signed and machine.execution_log without their dependency ident.registered_key;
  • separately, no default emitter supplies machine.execution_log, so a kit or a custom adapter must.
• opentrons, hamilton and pylabrobot have no default manifests, so the lab vertical supplies nothing today. The manifest entries are data for evidence to add, as proposed in my note.

Tests

• 19 new tests:
  • a golden plan for an IPP printer with a camera, reaching tier 2, with its digest pinned;
  • the built-in CSDs;
  • permutation invariance, including the contract's ref order;
  • the self-declared tier being ignored;
  • the mock cap;
  • an unknown adapter;
  • operator add and remove;
  • the human floor;
  • an unknown primitive;
  • the tier-0 block;
  • the oracle-enforcing mode.
• Spec: 816 passed, 0 failed (797 before). tsc --noEmit is clean.
• Mutation check: 10 mutants, all caught. One equivalent survivor, a redundant dedupe, was simplified away.

Review

Evidence reviews the semantics; it is their area (#2752). By board rule it touches assurance, so coord-watch cross-family review is also requested. It is report-only and changes no gate.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PkeiQMnVePeBGU9svhREFy