assertledger 1.1.0 → 1.2.0

package/docs/migration-verification-v3.md

@@ -0,0 +1,33 @@
+# Verification v3 and Bun test migration
+
+Verification request and evidence manifest v3 add the built-in `bun-test` adapter. V1 and v2
+schema bytes, adapter unions, and historical manifests remain unchanged and replayable. V3 keeps
+the v2 execution-backend record and accepts `node-test` and `testforge-command` as before.
+`bun-test` requires `trusted-local`; a v3 Bun request with container isolation is refused before
+execution.
+
+`assertledger init` writes repository initialization config, lock, and result v2 for a detected
+`bun:test` repository with one or more base test files. Existing Node initialization remains v1.
+If a repository contains multiple test frameworks, select `--framework bun:test` explicitly.
+Local-only linked entries still need explicit `--exclude NAME` declarations. Static initialization
+does not execute tests or qualify the installed Bun binary. Run the unsafe runtime doctor, then
+a v3 campaign with operator-supplied worlds and candidates.
+
+New Bun candidate tests use `assertSame` from `assertledger/bun`. Existing `bun:test` tests can
+remain as base controls. Their native `expect` failures block a campaign as operational failures;
+they are not assertion evidence. The helper compares only with `Object.is`, so use an explicit
+scalar or boolean observation when structural equality is needed. Calculation errors occur before
+the helper and remain ordinary errors. The helper is installed from the package into each
+disposable workspace; no adapter implementation is required in the consumer repository.
+
+The Bun runtime profile pins version `1.4.2` and revision
+`744846f844374847c902b5e7fd59b4342a51ef99`. New manifests bind the resolved executable
+digest, Bun revision, driver digest, preload digest, helper digest, command shape,
+and fresh runtime preflight. They may have new decision and artifact digests because v3 evidence
+has a new schema identity. No old manifest is resealed. The v3 schemas are added to the
+post-conformance schema lock; the frozen v1 bundle and its root digest are unchanged.
+
+The v1 provider/export contracts still describe v1 manifests only. Consumers of v3 Bun evidence
+should parse and replay the v3 manifest directly; they must not project it through the v1 export
+contract. Windows, Linux, and macOS support is claimed only for the exact Bun version on which
+the corresponding CI campaign gate passes.

package/docs/project-intent.md

@@ -50,13 +50,15 @@ référence, un monde neutre rouge, une observation instable ou une attribution
 
 Le socle local comprend les contrats versionnés, le noyau déterministe, les digests, le replay
 sémantique, le moteur d’exécution, les façades CLI/SDK/MCP, l’audit statique et l’initialisation.
-Le registre contient 38 schémas JSON : les 34 figés par le verrou de conformance v1 et les 4
-schémas d’export d’évidence, verrouillés par une extension additive qui ne modifie pas le bundle v1.
+Le registre contient 45 schémas JSON : les 34 figés par le verrou de conformance v1 et 11
+extensions, verrouillées sans modifier le bundle v1.
 L’ancien décompte de 30 dans la roadmap était périmé.
 
-L’adaptateur officiel intégré est `node:test`. Le protocole `testforge-command` permet d’intégrer
-un autre framework avec un adaptateur fourni par l’opérateur. Détecter Vitest, Jest, Bun ou pytest
-pendant `init` ne fournit pas leur adaptateur officiel.
+Les adaptateurs officiels intégrés sont `node:test` et `bun:test`. Ce dernier est limité à Bun 1.4.2
+et aux assertions explicites du helper `assertSame` ; les échecs natifs de `expect` ne deviennent pas
+des preuves d’assertion. Le protocole `testforge-command` permet d’intégrer un autre framework avec
+un adaptateur fourni par l’opérateur. Détecter Vitest, Jest ou pytest pendant `init` ne fournit pas
+leur adaptateur officiel.
 
 Les profils v1 et v2, les artefacts de benchmark, les contrats de provenance et le protocole
 expérimental H3 sont présents. Le benchmark par phases refuse encore l’adaptateur `node:test` :

package/docs/proof-model.md

@@ -55,15 +55,33 @@ Candidate statuses are:
 
 - `ELIGIBLE`: every gate needed by policy passed;
 - `WEAK_ORACLE`: reference and neutral evidence passed, but target strength did not;
-- `INVALID`: discovery, reference, or neutral evidence failed;
+- `INVALID`: a completed run disproved discovery, or reference or neutral evidence failed;
 - `UNSTABLE`: complete attempts produced different normalized outcomes;
 - `INCONCLUSIVE`: required observations were missing or execution produced `TIMEOUT` or
   `INFRA_ERROR`.
 
+When several apply, the first gate that fails decides, and inconclusive execution takes precedence
+over later failures:
+
+1. missing observations make the candidate `INCONCLUSIVE` (`COMPLETENESS`);
+2. diverging attempts make it `UNSTABLE` (`STABILITY`);
+3. a completed run without an attributed candidate test makes it `INVALID`
+   (`CANDIDATE_DISCOVERY_INVALID`);
+4. when only `TIMEOUT` or `INFRA_ERROR` runs lack an attributed candidate test, `DISCOVERY` is
+   not established and the candidate is `INCONCLUSIVE` (`CANDIDATE_EXECUTION_INCONCLUSIVE`): such a
+   run never reached a verdict, so it can neither prove nor disprove discovery;
+5. after discovery, any `TIMEOUT` or `INFRA_ERROR` run makes the candidate `INCONCLUSIVE` before a
+   red reference or neutral world makes it `INVALID`.
+
+See [the migration note](migration-timeout-discovery-inconclusive.md) for the effect on existing
+manifests.
+
 ## Campaign statuses
 
 - `VERIFIED`: at least one eligible candidate was selected.
-- `REJECTED`: evidence was complete and conclusive, but no candidate was eligible.
+- `REJECTED`: evidence was complete and conclusive, but no candidate was eligible. Once attempts are
+  complete and agree, a completed run that disproves discovery is conclusive, even if other runs
+  timed out.
 - `INCONCLUSIVE`: controls were invalid, or at least one candidate was unstable or inconclusive.
 - `ENGINE_ERROR`: the core could not normalize the supplied evidence safely.
 

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

@@ -310,20 +310,21 @@ caller decide whether the capability exists. The server resolves repository root
 confines them to the server process's current working directory by default. Programmatic operators
 may supply a different `allowedRepositoryRoots` allowlist.
 
-The doctor pair accepts a strict `{ "root": "..." }` input and returns the existing
-`repository-init-result` contract. It is read-only in both the default and operator-enabled server;
+The doctor pair accepts a strict `{ "root": "...", "exclude": ["..."] }` input, where the optional
+`exclude` entry names follow the [repository initialization](repository-init.md) exclusion rules,
+and returns the existing `repository-init-result` contract. It is read-only in both the default and operator-enabled server;
 enabling unsafe execution does not change doctor behavior. Dynamic runtime and client diagnostics
 remain outside this static readiness result.
 
-`doctor_runtime` accepts the same strict root input and returns the separate
-[runtime diagnostic contract](runtime-doctor.md). `check` accepts the
+`doctor_runtime` accepts only the strict root input and returns the separate
+[runtime diagnostic contract](runtime-doctor.md), v2 for a generated Bun configuration. `check` accepts the
 [high-level Git options](git-regression.md), without a permission field, and returns the existing
 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, Windows and macOS. A separate matrix installs and exercises the packed artifact
+and 24 with Bun 1.4.2 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
@@ -334,7 +335,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,

package/docs/repository-init.md

@@ -22,13 +22,45 @@ plausible test frameworks, composite shell scripts, contradictory overrides, and
 adapter configurations return `CONFLICT`. Multiple CI providers are only sorted evidence and do not
 block initialization.
 
+The static inventory walks the filesystem, not the Git index, and never follows or copies a
+symbolic link: a link inside it returns `CONFLICT` with `UNSUPPORTED_REPOSITORY_SYMLINK` and writes
+nothing. It always skips entries named `.git`, `.testforge`, and `node_modules`, at any depth.
+When a local-only entry holds a link that no campaign needs, the operator can declare its name:
+
+```sh
+assertledger doctor . --exclude .claude --exclude .omx --json
+assertledger init . --exclude .claude --exclude .omx --json
+```
+
+Each `--exclude` value is one portable entry name without separators; every file or directory with
+that name is skipped at any depth. Anything else returns `CONFLICT` with
+`INVALID_REPOSITORY_EXCLUDE`. The declared names are written to `repository.exclude` beside the
+defaults. `init` and `doctor` without `--exclude`, `analyze` and runtime doctor's configuration check
+then reuse that list from a valid `assertledger.config.json`; an unreadable or invalid file leaves
+only the defaults, which widens the inventory. A configured entry that contains a separator matches
+nothing, as in a verification request. An explicit list, including an empty MCP `exclude` array,
+replaces the configured one, so a different declaration never silently widens or narrows the
+inventory: it fails closed, for example with `CONFIG_CONFLICT`, or with
+`UNSUPPORTED_REPOSITORY_SYMLINK` when a narrower list exposes a link again. Links outside the declared names stay fail-closed.
+
+The configured list governs only these static diagnostics and the evidence digests of
+`assertledger.lock.json`; it produces no campaign evidence. `audit`, a campaign's repository copy and
+its manifest `repositoryDigest` keep their own exclusions: the defaults, plus the verification
+request's `repository.exclude` for a campaign. `audit` therefore still refuses a linked local-only
+entry, and a request must declare the same names to leave it out of its copy; a committed
+configuration can never remove files from campaign evidence. Declaring a name is an operator decision
+recorded in a reviewable file, not a sandbox.
+
 Files at or below the managed `candidateRoots` are deliberately excluded from framework inference,
 evidence, built-in control tests, and repository-change comparison. Candidate generation therefore
 cannot silently redefine initialization facts or invalidate an otherwise unchanged lock.
 
-The built-in ready adapter is currently `node-test`. Bun, pytest, Vitest, and Jest can be detected,
-but initialization returns `BLOCKED` with `OFFICIAL_ADAPTER_UNAVAILABLE` unless the operator supplies
-an existing structured adapter configuration:
+The built-in ready adapters are `node-test` and `bun-test`. Bun initialization writes v2 config,
+lock, and result contracts; Node initialization stays v1. Bun's static plan does not qualify the
+installed runtime. Run runtime doctor and use a v3 verification request before claiming campaign
+evidence. Pytest, Vitest, and Jest can be detected, but initialization returns `BLOCKED` with
+`OFFICIAL_ADAPTER_UNAVAILABLE` unless the operator supplies an existing structured adapter
+configuration:
 
 ```sh
 assertledger init . --adapter-config integrations/my-adapter.json --json
@@ -37,8 +69,8 @@ assertledger init . --adapter-config integrations/my-adapter.json --json
 The adapter document is parsed through the public adapter contract and is operator-owned. Its
 executable is recorded as argv but is not resolved or executed by `init`. This is not an official
 adapter endorsement and does not reduce the later `trusted-local` execution boundary.
-`node-test` adapters are accepted only for the `node:test` framework; every other framework requires
-an operator-owned `testforge-command` adapter.
+`node-test` adapters are accepted only for `node:test`; `bun-test` adapters are accepted only for
+`bun:test`. Pytest, Vitest, and Jest require an operator-owned `testforge-command` adapter.
 
 All detections and evidence digests come from one byte snapshot. Immediately before returning or
 writing managed files, initialization rechecks the in-scope inventory and every evidence byte. A
@@ -54,7 +86,6 @@ Exit codes are `0` for `CREATED`, `UNCHANGED`, or `WOULD_CREATE`; `3` for `BLOCK
 ambiguity, invalid overrides, conflicts, or contract validation; `5` for unexpected I/O; and `64`
 for CLI usage errors.
 
-The public `repository-init-config.v1`, `repository-init-lock.v1`, and
-`repository-init-result.v1` contracts contain no timestamps, absolute repository roots, environment
+The public v1 and v2 initialization contracts contain no timestamps, absolute repository roots, environment
 values, worlds, or candidates. The lock binds normalized detections and sorted evidence digests; it
 does not authenticate the detector, repository, adapter, or later execution evidence.

package/docs/runtime-doctor.md

@@ -23,20 +23,23 @@ configuration inspection or executable probes. Unknown flags, repeated flags, an
 
 ## What it checks
 
-Version 1.0 supports the generated official `node:test` adapter. It fails closed for other
-frameworks and operator-supplied adapters. In order, it checks:
+Version 1.0 supports the generated official `node:test` adapter. Version 2.0 supports the
+generated official `bun:test` adapter on the qualified Bun 1.4.2 revision. Both fail closed for
+other frameworks and operator-supplied adapters. In order, they check:
 
 1. explicit trusted-local authorization;
 2. a current AssertLedger configuration and evidence lock;
-3. the supported generated `node:test` adapter;
-4. a stable Node.js executable at version 22.15 or newer;
-5. availability of Node's built-in `node:test` module;
+3. the supported generated adapter;
+4. a stable Node.js executable at version 22.15 or newer, or the exact Bun 1.4.2 revision;
+5. availability of the runner's built-in test module;
 6. permission to create, write, and clean up an operating-system temporary workspace;
 7. controlled reporter discovery, liveness, and attribution probes.
 
 The final probes use disposable synthetic tests. One assertion failure must be attributed to the
 candidate; a generic throw with a nested assertion cause must remain a process crash and must not
-be attributed. Malformed reporter output, missing discovery, cleanup failure, timeout, or process
+be attributed. The Bun probes also check its owned `assertSame` helper against a plain throw,
+a caught assertion, an operand error, and a native `expect` failure. Malformed reporter output,
+missing discovery, cleanup failure, timeout, or process
 failure blocks readiness. AssertLedger does not write to the repository during runtime doctor.
 
 ## Result contract
@@ -44,15 +47,15 @@ failure blocks readiness. AssertLedger does not write to the repository during r
 The SDK exposes the same strict additive contract:
 
 ```ts
-import { AssertLedger, parseRuntimeDoctorResult } from "assertledger";
+import { AssertLedger, parseVersionedRuntimeDoctorResult } from "assertledger";
 
 const result = await new AssertLedger().doctorRuntime(repositoryRoot, {
   allowUnsafeExecution: true,
 });
-parseRuntimeDoctorResult(result);
+parseVersionedRuntimeDoctorResult(result);
 ```
 
-`schemaVersion` is `1.0.0`. Each check has `PASS`, `BLOCKED`, or `LIMITATION`, a stable reason code
+`schemaVersion` is `1.0.0` for Node and `2.0.0` for Bun. Each check has `PASS`, `BLOCKED`, or `LIMITATION`, a stable reason code
 when relevant, a concise summary, and a safe next action. The top-level status is `READY` only when
 every supported runtime boundary passes. JSON results contain no subprocess output, environment
 values, credentials, or repository source.

package/integrations/bun/assertions.d.mts

@@ -0,0 +1,4 @@
+export declare function assertSame(actual: unknown, expected: unknown): void;
+
+/** @internal Identifies an error instance issued by this helper. */
+export declare function isAssertSameFailure(error: unknown): boolean;