assertledger 1.0.0 → 1.1.1

package/docs/proof-planner.md

@@ -0,0 +1,368 @@
+# Proof planner (internal module)
+
+The proof planner answers one question: **given a change, the claims it reaches, their criticality
+and an explicit assurance policy, which evidence is proportionate?** It lives in
+`src/proof-planner/`, is pure and deterministic, and is not exported from the package entry points.
+
+```text
+impact provider (e.g. a semantic context tool)   describes what MAY be affected
+        │ ChangeImpact (provider-neutral)
+        ▼
+proof planner                                     decides what MUST be proved
+        │ AssurancePlan
+        ▼
+AssertLedger                                      decides whether required evidence exists and is
+                                                  valid: sufficiency, provenance, freshness, identity
+```
+
+The planner never claims that evidence exists. AssertLedger never decides what is proportionate.
+V1 implements the planner only; the AssertLedger-side satisfaction check is future work.
+
+## 1. Audit of the existing model
+
+| Concept | Present | Where | What exists / what is missing |
+| --- | --- | --- | --- |
+| Claims | No | `src/contracts/index.ts` (profile `consistency.claim`) | The only `claim` field is a stability label. No claim id, criticality or claim-to-evidence link. The implicit claim of a campaign is "this candidate test detects the declared fault". |
+| Evidence | Yes | `EvidenceObservation`, gates, `EvidenceManifest` v1/v2, evidence export | One kind only: repeated test executions across REFERENCE/TARGET/NEUTRAL worlds plus candidate-free controls, scoped to one campaign. Typecheck, CI jobs, reviews or corpora are not AssertLedger evidence. |
+| Provenance | Partial | world `provenance` string, `assertledger-git-regression/1`, provider `sourceRevision` | Declared, unauthenticated (`authenticity: UNAUTHENTICATED`). Git commit/tree only inside a world provenance string. |
+| Freshness | No | export `cost.execution.freshness: "UNKNOWN"`, capability `EXECUTION_FRESHNESS: UNSUPPORTED` | No timestamp, expiry or validity window; the core forbids the clock. The only usable proxy is digest identity. |
+| Candidate identity | Partial | `repositoryDigest` (content digest of the snapshot), git-regression revisions | "Candidate" means a candidate **test**, not a candidate change. No first-class commit or tree of the change under proof. |
+| Invalidation | No | replay checks integrity only | Nothing marks evidence stale when the repository changes. Outputs are append-only. |
+| Confidence | Partial | export `confidence.level: "REPLAY_CONSISTENT_UNAUTHENTICATED"` | Constant, qualitative; `established` / `notEstablished` token lists are a good residual-uncertainty vocabulary. |
+| Verdicts | Yes | `VERIFIED/REJECTED/INCONCLUSIVE/ENGINE_ERROR`, candidate statuses, gate `PASSED/FAILED/NOT_RUN` | All verdicts are about test-evidence quality for one campaign; none says "this change is sufficiently proved". |
+| Infra vs product | Partial | outcome taxonomy; `TIMEOUT`/`INFRA_ERROR` are inconclusive | Observation-level only. Nothing distinguishes a change to the proof infrastructure from a change to the product. |
+
+### Where sufficiency is implicit or global
+
+These rules are correct for their own purpose and are **not** weakened by the planner:
+
+- `pnpm check` is the single completion gate for every change, and CI runs it on the full matrix
+  without path filters.
+- One invalid control makes a whole campaign `INCONCLUSIVE`; one timeout attempt among passes makes a
+  candidate `UNSTABLE`; every required target must be killed.
+- Consumer `obligations` are `COVERED` only when all are `EXECUTED`, and `EXECUTED` means "observed at
+  least once", not "satisfied".
+- The init lock digests every test, lockfile and CI file; one changed byte makes the runtime doctor
+  report `RUNTIME_CONFIGURATION_STALE`, whatever the change touches.
+- The decision digest folds product identity (repository, worlds) and proof-infrastructure identity
+  (engine, adapter, budgets, backend) into one value: a budget change re-identifies the evidence.
+
+What was missing is upstream of these gates: a planner that decides **whether** a given gate is
+proportionate for a change, and **which** earlier evidence stays admissible after a follow-up commit.
+
+## 2. Model
+
+### Inputs
+
+- `ChangeImpact`: the revision (git object id or `sha256:` digest), its merge-base `baseline`, an
+  optional `runtimeTreeDigest`, and the surfaces changed since the baseline (cumulative). Each
+  surface has a role (`product`, `execution-context`, `evaluation`, `test`, `proof-infrastructure`,
+  `documentation`), a reach (`direct`, `transitive`), a runtime (`none`, `build`,
+  `offline-analysis`, `live`), boundaries (protocol, persistence, replay, analysis, decision,
+  admission, security, public-api, benchmark, holdout), a declared behavior change (`none`,
+  `suspected`, `fix`, `feature`), coverage, environment sensitivity, an optional typed content
+  digest, and for test and proof-infrastructure surfaces the surfaces they exercise. The analysis
+  states its method (`static-graph` or `declared`), completeness, uncertainty, localized unknowns
+  and omitted surfaces.
+- `AssuranceClaim[]`: the project's claim registry or the claims a change makes. Pass the registry,
+  not a hand-picked subset: untouched claims are filtered by the planner, not by the caller.
+- `ProofSignal[]`: what proof runs revealed, for one revision each. A signal may also name the
+  baseline and runtime tree it was observed on: an unresolved signal (a product signal, or a failure
+  that may exercise the change) then still counts on a later revision whose product is
+  byte-identical, so a proof-only commit cannot erase a regression.
+- `AssurancePolicy`: versioned data, digested into the plan (default `DEFAULT_ASSURANCE_POLICY`).
+
+### Facts, not a level table
+
+Code derives a closed vocabulary of **facts** (`product:fix`, `boundary:replay:behavior`,
+`runtime:live:behavior`, `claim:critical:direct`, `impact:unbounded`, `observed:regression`, …).
+The policy is data that maps facts to:
+
+- **floors**: the minimal level a fact implies;
+- **raises**: one step up, once per subject, capped at P4 (a raise never creates P5);
+- **triggers**: evidence a fact requires or recommends;
+- **status**: facts that put the plan on `HOLD` or `BLOCKED`.
+
+Levels are computed **per subject** (product, evaluation, proof infrastructure, documentation) and
+the plan level is their maximum. A fact may concern several subjects. A level baseline (P1 static
+checks and affected tests, P2 targeted regression and revision identity, P3 targeted integration and
+production-path test, P4 independent review, P5 preregistration and provenance) only applies to the
+subjects that reached that level, and only to the impact surfaces of that subject: a holdout change
+at P5 does not drag product ceremony in, and criticality deepens proof without widening it. Breadth
+(full suite, full corpus, multi-environment) comes only from impact facts.
+
+Subjects follow what the evidence is about, not only the role of the surface:
+
+- benchmark and holdout boundaries always concern the evaluation subject, whatever role carries them;
+- security, admission and decision boundaries keep their weight on a changed gate or oracle
+  (proof-infrastructure surfaces, and test surfaces whose oracle changed), under the
+  proof-infrastructure subject;
+- within the impact, a claim is reached through the product only by product, execution-context or
+  evaluation surfaces (outside an unbounded impact, its surfaces are treated as reached product).
+  A high or critical claim whose test or gate changed (the test lists a claim surface in
+  `exercises`, or the claim lists the test) gets `claim:<criticality>:oracle` under the
+  proof-infrastructure subject: an `ORACLE_WITNESS` (the changed oracle still fails where the
+  violation is present) and, for a critical claim, an independent review, but no product
+  requalification;
+- a documentation claim whose documented surfaces change behavior requires the documentation check;
+  otherwise it is unaffected.
+
+| Level | Typical source facts |
+| --- | --- |
+| P0 | documentation only |
+| P1 | refactor; changed tests that no product evidence runs; proof infrastructure; evaluation touched |
+| P2 | product behavior change, new behavior, execution context, compatibility boundary touched; oracle of a high claim changed |
+| P3 | behavior across protocol, persistence, replay, analysis or public API; live surface touched; security boundary touched; high claim reached directly; oracle of a critical claim changed; unbounded impact; costly reversal |
+| P4 | live behavior; decision, admission or security behavior; critical claim reached directly; system-scope claim; irreversible change; observed corpus divergence or live runtime |
+| P5 | empirical claim; benchmark or holdout behavior |
+
+### Impact bound and exemptions
+
+| Bound | When | Effect on heavy evidence |
+| --- | --- | --- |
+| `no-product-runtime` | a complete, static, low-uncertainty analysis finds no product, execution-context or evaluation surface | may be `NOT REQUIRED` |
+| `bounded-confident` | the same analysis, with runtime surfaces | may be `NOT REQUIRED`; untouched claims are unaffected |
+| `bounded-uncertain` | declared analysis, partial with named unknowns, non-low uncertainty or localized unknowns | computed against the **worst case** of the enumerated surfaces; what the worst case needs becomes `RECOMMENDED`, the rest `NOT REQUIRED`; a high or critical claim outside the impact earns a recommended invariant check, never a floor |
+| `unbounded` | unknown completeness, unnamed unknowns, omitted surfaces, execution context changed, unknowns touching live or high-critical surfaces, observed unknown dependency or unplanned impact, whatever the enumerated surfaces are | full test suite `REQUIRED`; claims outside the impact are treated as reached transitively; everything not selected is `UNDETERMINED`, never `NOT REQUIRED` |
+
+The bound is checked before the roles: an incomplete analysis of what looks like a proof-only change
+is unbounded, because the omitted part may be product. An unbounded impact is treated as reaching
+the product. The worst case keeps the declared analysis, so it is never more trusting than the plan;
+if the worst case is itself unbounded, nothing can be exempted.
+
+Size is not uncertainty: a large, enumerated transitive set bounds the targeted evidence's scope,
+it does not trigger a global suite. A declared impact recommends the full suite, because surfaces
+it omits are not bounded.
+
+Every evidence kind of the catalog ends in exactly one status: required, recommended, not required
+or undetermined. Each `NOT REQUIRED` entry carries its activation condition (the triggers and level
+baselines that would require it, with current values) and states whether it was evaluated against
+the actual change or the worst case.
+
+### Product evidence versus proof-infrastructure evidence
+
+Product signals (`UNEXPECTED_BEHAVIOR`, `UNPLANNED_IMPACT`, `UNKNOWN_DEPENDENCY`,
+`LIVE_RUNTIME_TOUCHED`, `CORPUS_DIVERGENCE`, `WITNESS_NOT_CAUSAL`, `REGRESSION`) become facts.
+A regression blocks; unexpected behavior and missing causality hold the plan and raise it. A
+regression, an unexpected behavior or a corpus divergence that reproduces on the baseline is a
+pre-existing defect: it does not block or escalate, but the reproduction becomes required evidence
+(`FAILURE_ATTRIBUTION`). An unplanned impact reopens the bound unless the impact already names the
+observed surfaces; a live-runtime observation escalates unless every observed surface is already
+declared live.
+
+Infrastructure signals (`TIMEOUT`, `ENVIRONMENT_FAILURE`, `TOOLING_FAILURE`) are attributed in a
+fixed order, after the bound is known:
+
+1. `exercises` is recomputed: if the failing job's surfaces are changed runtime surfaces, or changed
+   proof surfaces that exercise one, it is `yes`, whatever was declared. A changed test that
+   exercises nothing changed stays proof evidence, so a repaired ceiling can still be attributed
+   when it flakes. A declared `no` is only trusted under a confident bound and when the failure
+   names its surfaces.
+2. A job that does not exercise the change is attributed to the proof infrastructure by any
+   admissible basis (baseline reproduction, pass on the same revision, outside impact, reported
+   infrastructure error, declared environment factor).
+3. A job that may exercise the change is attributed only by `REPRODUCES_ON_BASELINE`. A retry that
+   passes proves nondeterminism, not innocence: a slower code path can time out once and pass once.
+   An attribution that rests on the reproduction alone requires `FAILURE_ATTRIBUTION`.
+4. Otherwise the failure is unattributed: the plan holds and requires `FAILURE_ATTRIBUTION`, but the
+   level does **not** rise automatically.
+
+An attributed infrastructure failure never changes the level, the status or the evidence required
+on the changed surfaces; it adds `AFFECTED_JOB_RERUN` on the failing job, and `FAILURE_ATTRIBUTION`
+there too when a reproduction on the baseline is its only basis. An unattributed one adds
+`FAILURE_ATTRIBUTION` on the failing job; it widens the product evidence only to a failing job that
+is itself a product surface of the impact, never to a test, a harness or a job outside the impact.
+A proof-infrastructure surface without an `exercises` list is taken not to exercise the change when
+its failure is classified, so an outside-impact attribution declared for it stands under a
+confident bound.
+
+### Evidence bindings and carry-over
+
+Each kind declares what it stays valid for:
+
+- `exact-revision`: static checks and revision identity (cheap, re-run on every revision);
+- `surface-content`: valid per scoped surface while that surface, the proof surfaces that exercise
+  it (a test without an `exercises` list exercises everything; a proof-infrastructure surface
+  counts where it names the surface, and a directly changed one whose behavior change is not
+  declared `none` and that names nothing is reported as `proof.exercises-unknown`), the baseline and the runtime tree
+  keep their digests. Only documentation-only evidence about a surface both plans call
+  documentation ignores the runtime tree: a gate delta
+  review is redone when the code its budget measures changes, and a documentation claim scoped to a
+  runtime surface is checked again when the behavior it describes may have changed. Without a
+  scope, it is revision-wide;
+- `runtime-tree`: full suite, full corpus, multi-environment, live shadow, system requalification,
+  benchmark and holdout runs: valid while the baseline and runtime tree digest are unchanged.
+
+`carryOverEvidence(previous, next)` lists what may be reused and what must be produced again. Reuse
+is keyed on the kind's semantic digest (id, weight, binding, subjects, verification,
+`semanticsVersion`), never on its wording and never on the whole policy digest. Missing digests, a
+changed baseline (rebase) or a changed runtime tree force re-production of every kind that depends
+on them, and evidence never crosses to another revision on the surfaces that a signal unresolved in
+either plan may concern, read in both plans: the surfaces it names and what a named test or proof
+surface lists as exercised, or everything when it names no surface, a surface either impact does not
+know, an execution context, or a proof surface that does not list what it exercises. A signal the
+next plan observes counts too, because it contradicts evidence produced before it. Within one
+revision, only an observation the previous plan did not already have counts, compared by what was
+observed (id, revision, signal, classification, exercises, attribution basis and surfaces), not by
+id: evidence produced beside an observation answers it. Evidence that answers observations, such as
+a failure attribution or a job rerun, is reused only for the observations it was produced for, each
+scoped by the surfaces it names; exact-revision evidence is reused within its revision whatever was
+observed. Otherwise, a fact that names a signal its plan does not list, which only a stored or
+foreign plan can carry, blocks the reuse of the evidence behind it. A block lifts when the previous
+plan is planned again; the next plan does not revise its classification. A failure attributed to the
+proof infrastructure, or unattributed on a job that a confidently bounded impact places outside the
+change, concerns no product evidence. AssertLedger must still verify that reused evidence exists and
+carries the listed digests.
+
+### Escalations
+
+Each plan precomputes, by replanning with a canonical hypothetical signal, what every product
+signal and an attributed or unattributed infrastructure failure would do to its level, status and
+required evidence. The tests pin every row of the bounded replay fix with values derived from the
+policy by hand, and check the product rows for consistency with a replan through the public API
+(the same planner, so that check alone would not catch a planner error).
+
+## 3. Examples
+
+Produced by the V1 default policy; the tests in `tests/proof-planner.test.ts` assert these
+decisions.
+
+| Scenario | Level | Required | Heavy evidence |
+| --- | --- | --- | --- |
+| A documentation only | P0 | documentation check | all 11 broad or ceremonial kinds not required |
+| B local refactor | P1 | static checks, affected tests (+ characterization tests if untested) | all not required |
+| C local bugfix | P2 | causal witness, affected tests, targeted regression, static checks, revision identity | all not required |
+| D bounded replay fix | P3 | C + targeted integration, production-path test, targeted corpus, documentation check | all not required, including full corpus and system requalification |
+| D, declared impact | P3 | D | full test suite, characterization tests and an invariant check for the untouched critical claim recommended; the rest not required against the worst case |
+| D, partial analysis | P3 | D + full test suite, invariant check (the untouched critical claim is treated as reached) | full corpus and independent review recommended; everything else undetermined |
+| E live decoder fix | P4 | C + boundary compatibility, targeted integration, production-path test, live shadow, rollback plan, full corpus, independent review | benchmark, holdout, full suite, multi-environment, system requalification not required |
+| E tactical decision | P4 | acceptance test, affected tests, targeted regression and integration, production-path test, live shadow, rollback plan, full corpus, system requalification, independent review, static checks, revision identity | benchmark, holdout, full suite, multi-environment not required |
+| F holdout evaluator + empirical claim | P5 | preregistration, provenance, benchmark protocol, holdout evaluation, contamination check, independent review, affected tests, static checks, revision identity | live shadow, full suite, full corpus, system requalification not required |
+| G timeout ceiling repair | P1 | gate delta review, affected job rerun, static checks | all not required; no functional requalification |
+| G, the repaired test checks a critical claim | P3 (proof infrastructure) | G + oracle witness, independent review of the test, revision identity | no product requalification: every requirement is scoped to the changed test or revision-wide |
+
+Rendered plan for the bounded replay fix (abridged):
+
+```text
+AssurancePlan P3 PROVE - revision 1111… (baseline 0000…)
+policy assertledger.default-assurance@1.0.0; impact bounded-confident; product P3, documentation P0
+
+WHY
+  - impact: bounded-confident: static analysis, complete, low uncertainty
+  - claim: live-decoder-pins-unchanged: none of its runtime surfaces is in an impact bounded with confidence
+  - floor P3 boundary:replay:behavior: channel/replay-fold, channel/replay-safe-keys: replay behavior may change
+  - floor P2 product:behavior-change: channel/replay-safe-keys: product behavior may change
+
+REQUIRED
+  - CAUSAL_WITNESS (surface-content) [channel/replay-safe-keys] <- product:fix
+  - TARGETED_CORPUS (surface-content) [channel/replay-fold, channel/replay-safe-keys] <- boundary:analysis:behavior, boundary:replay:behavior
+  - PRODUCTION_PATH_TEST, TARGETED_INTEGRATION, TARGETED_REGRESSION, AFFECTED_TESTS, REVISION_IDENTITY, STATIC_CHECKS, DOCUMENTATION_CHECK
+
+NOT REQUIRED
+  - FULL_CORPUS: Not required: the policy asks for FULL_CORPUS when one of [boundary:decision:behavior,
+    impact:unbounded, observed:corpus-divergence, observed:live-runtime, runtime:live:behavior] holds;
+    none holds for this change, whose impact is bounded with confidence.
+  - SYSTEM_REQUALIFICATION, INDEPENDENT_REVIEW, FULL_TEST_SUITE, BENCHMARK_PROTOCOL, HOLDOUT_EVALUATION, …
+
+ESCALATE IF
+  - CORPUS_DIVERGENCE (product): Evidence about the product: level moves P3 -> P4, status PROVE, adds FAILURE_ATTRIBUTION, FULL_CORPUS, INDEPENDENT_REVIEW.
+  - REGRESSION (product): Evidence about the product: level stays P3, status BLOCKED, adds nothing.
+  - TIMEOUT (infrastructure-attributed): Evidence about the proof infrastructure: level stays P3, status PROVE, adds AFFECTED_JOB_RERUN, FAILURE_ATTRIBUTION.
+  - TIMEOUT (infrastructure-unattributed): Unattributed failure: level stays P3, status HOLD, adds FAILURE_ATTRIBUTION.
+  - …
+```
+
+## 4. Before and after: a localized fix with two peripheral timeouts
+
+Abstract reproduction of an observed consumer pull request: a three-line fix in a replay-only
+adapter, legitimate targeted proof, then two wall-clock ceilings in untouched packages that timed
+out one after the other (a property at 30.4 s for 30 s that had passed in 12.2 s on the same tree,
+then a performance guard at 2.78 s for 1.5 s whose literal ignored the declared CI latency factor).
+Observed cost before: 3 candidate commits, 5 CI runs, about 6 fresh audits; each ceiling repair
+created a new commit that invalidated the whole aggregate proof although the product claims never
+changed.
+
+The test suite replays the sequence with the default policy and with a modeled revision-bound
+global policy (every kind bound to the exact revision, full suite and independent audit at P3):
+
+| Step | Before (revision-bound global model) | After (default policy) |
+| --- | --- | --- |
+| r1, replay fix | P3, 12 required kinds | P3, 10 required kinds (full suite and audit not required) |
+| timeout 1 (outside impact, passed on the same tree) | proof infrastructure | proof infrastructure; level, status and product evidence unchanged |
+| r1 → r2, first ceiling routed | 13 kinds re-produced | 4 kinds: static checks, revision identity, gate delta review on the ceiling, job reruns on the ceiling and on the job of timeout 2 |
+| timeout 2 (outside impact, environment factor) | proof infrastructure | proof infrastructure |
+| r2 → r3, second ceiling routed | 13 kinds re-produced | 4 kinds, on the new ceiling only; the first ceiling's review is reused |
+
+The planner stays conservative on the same path: a corpus divergence moves the plan to P4 with the
+full corpus; a timeout on a job that exercises the replay surface holds the plan unless it
+reproduces on the baseline; a rebase, a changed runtime tree, a missing digest, a test without an
+`exercises` list, a harness that names the replay surface, or a product digest changed by a
+so-called infrastructure commit forces the product evidence to be produced again; and a regression
+left unresolved on r1 blocks the reuse of the evidence on its surfaces. Each of these is a test.
+
+## 5. Mapping to neighbours
+
+**Impact provider.** Any provider can fill `ChangeImpact`. From semctx, for example:
+`changedFiles`/`changedSymbols` give direct surfaces; `impactedConsumers` and `control_impact`
+paths give transitive ones; `impactedInvariants`/`impactedContracts` and change-contract
+`preserves` give claims (criticality from `criticalInvariantTags`); `unknowns` and the
+`analysis_scope_incomplete` / `index_binding_stale` findings give completeness and unknowns;
+`recommendedTests` only feed test surfaces, never required evidence. semctx reports neither a
+candidate commit nor content digests through MCP: the caller supplies `revision`, `baseline` and
+digests. Such an adapter belongs outside `src/` (a test forbids that name in source files).
+
+**AssertLedger.** Today AssertLedger can verify `CAUSAL_WITNESS` and `ACCEPTANCE_TEST` as a
+qualification campaign (TARGET = baseline, REFERENCE = revision, NEUTRAL = justified variation) with
+replay-valid manifests. Other kinds (static checks, CI jobs, reviews, corpora, preregistration) have
+no AssertLedger evidence type yet; kinds marked `attested` can only be recorded, not executed.
+
+## 6. Limits and risks
+
+- Inputs are trusted declarations. A caller can mislabel a live surface as offline or omit a surface;
+  the planner limits the damage (declared analysis never yields confident exemptions, contradicted
+  `exercises` values are overridden, incomplete analyses are unbounded whatever they enumerate,
+  untouched critical claims come back as recommendations under uncertainty and as requirements when
+  unbounded) but cannot detect a consistent lie. A policy-owned surface classifier is not in V1.
+- Claims come from the caller. Pass the full registry; V1 has no registry of its own. A changed proof
+  surface without an `exercises` list only reaches the claims that list it; the plan reports it as
+  residual uncertainty (`proof.exercises-unknown`).
+- The default policy is a first calibration, not a measured optimum. A caller-supplied policy must be
+  at least as strict as the default: every kind (verification, binding, subjects), baseline, floor,
+  trigger, raise and status rule of the default must still hold with at least the same strength, or
+  parsing fails with `PROOF_PLANNER_POLICY_BELOW_MINIMUM`. The tests pin the default by digest and
+  check its non-negotiable rules against an independent list. A project that wants a looser policy
+  must fork the default; that is deliberate in V1.
+- Signals carried across revisions need the caller to report the baseline and runtime tree they were
+  observed on. Without them, the carry-over still refuses reuse on the surfaces an unresolved signal
+  may concern, but the next plan does not hold or block by itself. An unattributed failure on a job
+  that a confidently bounded impact places outside the change holds its own revision only: it is
+  never carried and blocks no reuse, so the next revision must observe that job again.
+- Freshness is identity-based (digests, baseline, runtime tree), not time-based: the core forbids a
+  clock. Time-bound validity windows remain an AssertLedger-side concern.
+- The satisfaction check (does evidence exist for each requirement, bound to the listed digests) is
+  not implemented; the plan is advisory until it is.
+- Attribution bases are declared by whoever reports the signal. A pre-existing product defect, and
+  an infrastructure attribution that rests on `REPRODUCES_ON_BASELINE` alone, require
+  `FAILURE_ATTRIBUTION`, which AssertLedger should eventually verify; the other bases are trusted
+  as declared, within the limits above.
+- The module is compiled into `dist/proof-planner/` but not reachable through the package exports;
+  its types and digests are not a public contract yet.
+
+## 7. When should it become a separate tool?
+
+Not now. Extract it only when several of these hold, with evidence:
+
+1. **Used without AssertLedger**: at least one consumer plans assurance without producing or
+   verifying AssertLedger evidence (for example a CI router or a review bot).
+2. **Own policy and configuration lifecycle**: projects version their assurance policy independently
+   of AssertLedger releases, with their own compatibility promises.
+3. **Several consumers**: two or more independent harnesses or repositories call it, so its release
+   cadence conflicts with AssertLedger's.
+4. **Autonomous data model**: `ChangeImpact`, `AssurancePlan` and the policy need published JSON
+   schemas and conformance fixtures of their own.
+5. **Significant algorithms**: work beyond V1's fact derivation, such as learned calibration,
+   cross-revision planning or cost models, would bloat AssertLedger's evidence core.
+6. **Stable API**: the input and output shapes survive a few real projects without breaking changes.
+
+The module is built for that move: it imports only `zod`, its own files and `sha256Canonical` from
+the public `./core` API, and a test enforces that boundary.

package/docs/reference.md

@@ -18,7 +18,11 @@ assertledger audit . --json
 assertledger analyze . --json
 assertledger schema verification-request --json
 assertledger verify assertledger.request.json --allow-unsafe-execution --json
+assertledger verify assertledger.container-request.json --container-runtime '["docker"]' --json
 assertledger replay assertledger.manifest.json --json
+assertledger provider --json
+assertledger export assertledger.export-request.json --json
+assertledger export-replay assertledger.evidence-export.json --json
 assertledger profile assertledger.profile-request.json --json
 assertledger profile-replay assertledger.profile-report.json --json
 assertledger profile-v2 assertledger.profile-v2-request.json --json
@@ -45,15 +49,35 @@ directory or in a colocated `*.test.*`/`*.spec.*` source file. Comments, string
 documentation-like config filenames do not count; no evidence produces an empty list. Detection is
 intentionally incomplete: an unrecognized manifest layout or test-file convention yields no claim.
 
-`verify`, `replay`, `profile`, `profile-replay`, `profile-v2`, `profile-v2-replay`, `benchmark`, and
+`verify`, `replay`, `export`, `export-replay`, `profile`, `profile-replay`, `profile-v2`,
+`profile-v2-replay`, `benchmark`, and
 `benchmark-replay`, `benchmark-acquire`, and `benchmark-acquire-replay` also accept `-`
 or an omitted file argument and
 then read JSON from stdin. The CLI rejects file and stdin JSON inputs larger than 16 MiB. JSON
 results go to stdout. Diagnostics go to stderr. `assertledger mcp` reserves stdout for JSON-RPC.
 
 `--allow-unsafe-execution` is an external authorization signal. The CLI requires it for every
-campaign and sets the request's local acknowledgement before validation. The flag does not create a
-sandbox.
+trusted-local campaign and sets the request's local acknowledgement before validation. The flag does
+not create a sandbox.
+
+A v2 request with `container` isolation runs without that flag: each execution uses a fresh
+container from a digest-pinned local image through the operator's `--container-runtime` JSON argv,
+which defaults to `["docker"]`. `check` selects the same backend with `--container-image`. Combining
+the two modes fails with `ISOLATION_MODE_CONFLICT`. See [container isolation](container-isolation.md).
+
+`profile` exits with `0` for `QUALIFIED`, `2` for `NOT_QUALIFIED` or `BUDGET_MISSED`, and `3` for
+`INSUFFICIENT_TIMING_EVIDENCE`. A malformed request or a replay-invalid source manifest writes no
+report, prints its reason code such as `AGENTIC_PROFILE_SOURCE_INVALID` to stderr, and exits with
+`4`. `profile-replay` exits with `0` only when every replay rail is valid and with `4` otherwise.
+`profile-v2` has no `NOT_QUALIFIED` status; it uses the same codes for the statuses it shares with
+v1 and `4` for `OBSERVED_BENCHMARK_FAILURE` and `COMPARISON_SCOPE_MISMATCH`, and
+`profile-v2-replay` follows `profile-replay`. Unexpected engine errors exit with `5`.
+
+`provider` prints the evidence provider manifest and exits with `0`. `export` exits with `0` after
+writing an [evidence export](evidence-export.md), whatever its detection result; a malformed request
+or a replay-invalid source manifest writes no export, prints `EVIDENCE_EXPORT_REQUEST_INVALID` or
+`EVIDENCE_EXPORT_SOURCE_INVALID` to stderr, and exits with `4`. `export-replay` exits with `0` only
+when every replay rail is valid and with `4` otherwise.
 
 Versioned JSON Schemas are published for the
 [`verification request`](../schemas/verification-request.v1.json),
@@ -78,8 +102,12 @@ Versioned JSON Schemas are published for the
 [`corpus trust policy`](../schemas/agentic-corpus-trust-policy.v1.json) and paired
 [`corpus provenance`](../schemas/agentic-corpus-provenance.v1.json), six corpus allocation and
 two-party [`commitment/reveal`](../schemas/agentic-corpus-allocation-commitment.v1.json) contracts,
-plus six pre-declared [`H3 experiment`](../schemas/agentic-corpus-experiment-plan.v1.json) contracts.
-The main CLI `schema` command prints the thirty-one facade schemas by name; the corpus evaluator consumes
+plus six pre-declared [`H3 experiment`](../schemas/agentic-corpus-experiment-plan.v1.json) contracts,
+and the [`evidence provider manifest`](../schemas/evidence-provider-manifest.v1.json),
+[`evidence export request`](../schemas/evidence-export-request.v1.json),
+[`evidence export`](../schemas/evidence-export.v1.json), and
+[`evidence export replay result`](../schemas/evidence-export-replay-result.v1.json).
+The main CLI `schema` command prints the thirty-six facade schemas by name; the corpus evaluator consumes
 the two trust/provenance schemas directly.
 A complete runnable verification request
 is available at
@@ -96,8 +124,8 @@ campaign wall-time proxy with an exact scoped warm-total-wall p95 cost basis. It
 artifacts and commands remain supported.
 
 The checked-in [`conformance v1 bundle`](conformance-v1.md) locks autonomous inputs, complete
-expected outputs, negative replay witnesses, all published schema bytes, and selected public
-digests. `pnpm check` validates this static oracle without regenerating it.
+expected outputs, negative replay witnesses, the v1 schema bytes, and selected public digests; an
+additive lock covers the schemas published after v1. `pnpm check` validates this static oracle without regenerating it.
 
 ## TypeScript SDK
 
@@ -128,6 +156,14 @@ const profile = assertLedger.profile({
 });
 const profileIntegrity = assertLedger.replayProfile(profile);
 
+const provider = assertLedger.providerManifest();
+const evidenceExport = assertLedger.exportEvidence({
+  schemaVersion: "1.0.0",
+  manifest,
+  consumerRequest: null,
+});
+const exportIntegrity = assertLedger.replayEvidenceExport(evidenceExport);
+
 const benchmarkRequest = JSON.parse(await readFile("assertledger.benchmark-request.json", "utf8"));
 const benchmark = assertLedger.benchmark(benchmarkRequest);
 const benchmarkIntegrity = assertLedger.replayBenchmark(benchmark);
@@ -160,6 +196,10 @@ surface, for consumers migrating from the prior name.
 The SDK accepts plain JSON-compatible values and validates them against the same contracts as the
 CLI. Unlike the CLI and MCP tool, `AssertLedger.verify()` has no separate authorization parameter: the
 caller must set `isolation.acknowledgedUnsafeExecution` to `true` after applying its own policy.
+`verify()` and `checkGitRegression()` accept only v1 inputs and return v1 manifests.
+`verifyV2(request, { containerRuntime: { command } })` and `checkGitRegressionV2(options)` run
+[container isolation](container-isolation.md) and return v2 manifests; a container request needs no
+acknowledgement, and the runtime argv never comes from the request.
 
 `AssertLedger.replay()` reports schema validity, both digest checks, and deterministic
 decision-semantic validity. Its aggregate `valid` field is true only when all four checks pass. Replay
@@ -233,7 +273,7 @@ server name reported to clients is `assertledger`. Every tool is registered twic
 `assertledger_*` name and a legacy `testforge_*` name bound to the same handler and the same tool
 configuration. The schema lookup pair has no single fixed output schema because its selected JSON
 Schema document varies; every other pair shares the same output-schema object. The default server
-exposes twenty-eight read-only tools:
+exposes thirty-four read-only tools:
 
 | Preferred tool | Legacy alias | Purpose |
 | --- | --- | --- |
@@ -247,6 +287,9 @@ exposes twenty-eight read-only tools:
 | `assertledger_profile_v2` | `testforge_profile_v2` | Derive a benchmark-backed strength and warm-cost profile |
 | `assertledger_profile_v2_replay` | `testforge_profile_v2_replay` | Replay a self-contained Profile v2 report |
 | `assertledger_schema` | `testforge_schema` | Return any of the published JSON Schemas |
+| `assertledger_provider` | `testforge_provider` | Describe the evidence provider, its announced capabilities, cost model, and limits |
+| `assertledger_export` | `testforge_export` | Export replay-valid evidence for an external consumer |
+| `assertledger_export_replay` | `testforge_export_replay` | Replay a self-contained evidence export |
 | `assertledger_replay` | `testforge_replay` | Validate and replay a manifest's schema, digests, and decision semantics |
 | `assertledger_benchmark_acquire_replay` | `testforge_benchmark_acquire_replay` | Replay acquisition source, artifact, context, digest, and status bindings |
 | `assertledger_corpus_allocate` | `testforge_corpus_allocate` | Create a deterministic calibration/holdout allocation |
@@ -280,8 +323,9 @@ evidence manifest. The operator's capability is required for both tools.
 ## Continuous integration
 
 Run `pnpm check` on every change. The included GitHub Actions workflow runs this gate on Node.js 22
-and 24 on Ubuntu and Windows. A separate matrix installs and exercises the packed artifact on both
-operating systems with Node.js 22.15.0 and 24. A CI job that executes campaigns must
+and 24 on Ubuntu, Windows and macOS. A separate matrix installs and exercises the packed artifact
+on Ubuntu and Windows with Node.js 22.15.0 and 24. On Ubuntu, the gate also runs the real-daemon
+[container isolation](container-isolation.md) suite. A CI job that executes campaigns must
 also treat `trusted-local` as `UNSANDBOXED`: use an isolated runner without secrets or host
 credentials, and pass `--allow-unsafe-execution` only from reviewed CI configuration.
 
@@ -290,7 +334,9 @@ credentials, and pass `--allow-unsafe-execution` only from reviewed CI configura
 - `VERIFIED`: at least one candidate completed all required evidence and was selected.
 - `REJECTED`: the campaign completed, but no candidate satisfied the policy.
 - `INCONCLUSIVE`: controls or candidate evidence were incomplete, unstable, timed out, or affected
-  by infrastructure failure.
+  by infrastructure failure. Once its attempts are complete and agree, a completed candidate run
+  that reports no attributed candidate test still makes that candidate invalid, whatever else timed
+  out; see the [proof model](proof-model.md#candidate-gates).
 - `ENGINE_ERROR`: the deterministic core could not normalize the supplied evidence safely.
 
 Only an attributed `ASSERTION_FAILURE` can kill a target in protocol v1. Compilation errors,
@@ -328,7 +374,8 @@ deterministic core and protocols are framework-independent; `node:test` is the f
 framework adapter. Other frameworks integrate through the structured-command protocol described in
 [docs/adapter-protocol.md](adapter-protocol.md).
 
-Planned work is not shipped behavior. Priorities include a real sandbox backend, additional
+Planned work is not shipped behavior. Priorities include VM isolation, container evidence in
+derived reports, additional
 framework reporters with runtime attribution, signed provenance, cross-runtime conformance
 fixtures, and more built-in adapters. See [docs/roadmap.md](roadmap.md).
 

package/docs/roadmap.md

@@ -7,7 +7,9 @@ regression-test qualification workflow, acceptance criteria, and evidence bounda
 ## Implemented locally in v0.1
 
 - deterministic repository analysis;
-- thirty-four versioned public JSON Schemas, all frozen by conformance v1;
+- forty versioned public JSON Schemas: thirty-four frozen by conformance v1, and four
+  evidence-export schemas plus the v2 verification request and evidence manifest locked by the
+  additive schema-extension lock;
 - reference, target, and neutral overlay worlds;
 - one campaign snapshot and disposable execution workspaces;
 - built-in `node:test` runtime reporter and structured-command adapter;
@@ -28,11 +30,16 @@ regression-test qualification workflow, acceptance criteria, and evidence bounda
   planned-process and planned-timeout equality, content-addressed suites, per-source
   non-inferiority, and a shared frozen candidate universe;
 - a static conformance-v1 oracle locking canonicalization, decisions, replay witnesses, Profile v1,
-  Benchmark v1, and all 34 published schema bytes;
+  Benchmark v1, and all 34 v1 schema bytes, plus an additive lock for later schemas;
 - a pinned 24-case, three-source empirical corpus plan with signed admission and holdout rules,
   including eight receipt-linked TestExplora cases admitted only for curated calibration;
 - JSON CLI, TypeScript SDK, MCP v2 stdio server, and integration skill;
-- `trusted-local`, explicitly recorded as `UNSANDBOXED`.
+- an interoperable evidence export with a provider manifest, separate result, integrity,
+  authenticity, environment, confidence, control, and cost sections, and deterministic replay;
+- `trusted-local`, explicitly recorded as `UNSANDBOXED`;
+- a v2 [container isolation backend](container-isolation.md): a fresh digest-pinned Linux container
+  per execution, no network or host mounts, bounded resources, and backend facts bound to the
+  decision.
 
 ## Release 1.0 priority
 
@@ -55,7 +62,8 @@ scoped deterministic qualification workflow.
    tranche is curated calibration evidence and cannot satisfy the holdout requirement.
 2. Add faithful framework-specific phase adapters. The framework-neutral acquisition path is
    shipped, but the built-in `node:test` reporter cannot attribute all four phases.
-3. Add an isolation backend backed by an independently administered container or VM boundary.
+3. Extend container isolation to evidence export, profiles, benchmarks and MCP, and add a VM
+   boundary for threats that a shared kernel does not contain.
 4. Add framework reporters beyond `node:test` that derive discovery and attribution from runtime
    events.
 5. Publish cross-runtime conformance fixtures for canonicalization, decisions, and both digests.

package/examples/agentic-profile/profile-manifest.mjs

@@ -24,5 +24,9 @@ if (manifestPath === undefined) {
     },
   });
   process.stdout.write(`${JSON.stringify(report)}\n`);
-  process.exitCode = report.status === "QUALIFIED" ? 0 : 2;
+  // Same mapping as `assertledger profile`.
+  process.exitCode =
+    { QUALIFIED: 0, NOT_QUALIFIED: 2, BUDGET_MISSED: 2, INSUFFICIENT_TIMING_EVIDENCE: 3 }[
+      report.status
+    ] ?? 5;
 }

package/examples/evidence-export/consumer.mjs

@@ -0,0 +1,35 @@
+import { readFile } from "node:fs/promises";
+import { AssertLedger } from "assertledger";
+
+// A minimal external consumer. It applies its own obligations to an AssertLedger evidence export
+// and writes nothing back: AssertLedger results stay the same whatever it decides.
+const exportPath = process.argv[2];
+if (exportPath === undefined) {
+  console.error("Usage: node consumer.mjs <evidence-export.json>");
+  process.exitCode = 64;
+} else {
+  const evidence = JSON.parse(await readFile(exportPath, "utf8"));
+  const replay = new AssertLedger().replayEvidenceExport(evidence);
+  const reasons = [];
+  let decision;
+  if (!replay.valid) {
+    decision = "REJECT";
+    reasons.push("EXPORT_REPLAY_INVALID");
+  } else if (evidence.result.detection !== "OBSERVED") {
+    decision = "IGNORE";
+    reasons.push(`DETECTION_${evidence.result.detection}`);
+  } else {
+    const required = ["CONTROL_WITHOUT_CANDIDATE", "REFERENCE_PASS", "NEUTRAL_PASS"];
+    for (const control of required) {
+      const executed = evidence.controls.executed.find((item) => item.control === control);
+      if (executed?.status !== "EXECUTED") reasons.push(`CONTROL_NOT_EXECUTED_${control}`);
+    }
+    if (evidence.scope.gitRevisions !== "RECORDED") reasons.push("GIT_REVISIONS_NOT_RECORDED");
+    if (evidence.authenticity.status !== "ATTESTED") reasons.push("EVIDENCE_UNAUTHENTICATED");
+    // This consumer admits unauthenticated local evidence only as advisory.
+    decision = reasons.length === 0 ? "ACCEPT" : "DEGRADE";
+  }
+  process.stdout.write(
+    `${JSON.stringify({ decision, reasons, sourceArtifactDigest: evidence.sourceArtifactDigest ?? null })}\n`,
+  );
+}