assertledger 1.0.0

package/docs/developer-experience.md

@@ -0,0 +1,55 @@
+# Developer entry points
+
+AssertLedger can inspect repository readiness without running candidate code:
+
+```text
+assertledger doctor .
+assertledger doctor . --json
+```
+
+The JSON form is the existing repository initialization result. `WOULD_CREATE` means the static
+configuration can be planned; it does not mean worlds, candidates, campaign evidence, or an MCP
+client connection are ready. `BLOCKED` exits with code 3 and `CONFLICT` with code 4.
+
+After installing and building AssertLedger, generate a project-local Codex MCP descriptor:
+
+```text
+assertledger connect . --client codex
+assertledger connect . --client codex --write
+```
+
+The first command previews `.codex/config.toml` and the packaged project skill. `--write` creates
+absent files, accepts byte-identical content as unchanged, and refuses to overwrite different
+operator-owned content. It never changes global configuration, authentication, hooks, or trust.
+Codex project trust and client restart or reload remain explicit user actions.
+
+Use `--write` in a trusted local repository whose directory tree stays stable during the operation.
+Existing symlinks and junctions at the configuration path are refused. This check does not provide
+filesystem isolation against another process swapping directories concurrently; the default
+print-only command creates no files.
+
+The [client guide](client-connections.md) also covers Claude Code, a generic MCP descriptor and
+`disconnect`. Removal affects only byte-identical managed files; modified files cause a conflict.
+
+The generated server command uses the current Node executable, the installed compiled CLI entry,
+and `mcp --root` with the repository's real path. The server is read-only by default. Candidate
+execution remains unavailable unless an operator separately starts it with
+`--allow-unsafe-execution`; that mode is explicitly UNSANDBOXED trusted-local.
+
+On a connected read-only server, agents may call `assertledger_doctor` (or the legacy
+`testforge_doctor` alias) with `{ "root": "..." }`. It returns the same static repository
+initialization result as `assertledger doctor . --json`, after enforcing the server's allowed-root
+boundary. The tool writes no configuration and does not execute repository code. It reports
+configuration readiness only; dynamic dependency, reporter, permission and liveness diagnostics
+remain outside this static check.
+
+Use the separate [runtime doctor](runtime-doctor.md) after initialization to run controlled probes
+with explicit authorization. [Reason-code explanations](diagnostics.md) remain available without
+execution permission through the CLI, SDK and MCP.
+
+`init` and every static doctor entry point require `assertledger.config.json` and
+`assertledger.lock.json` to be regular files when they already exist. A symlink, dangling symlink,
+directory or other file type returns `CONFLICT` with `INIT_MANAGED_PATH_UNSAFE` before its content is
+read. Repositories that previously linked either managed file must replace the link with an
+operator-owned regular file. This check assumes the trusted repository tree remains stable during
+the operation; it is not a defense against a hostile concurrent path swap.

package/docs/diagnostics.md

@@ -0,0 +1,35 @@
+# Understand a refusal and choose the next action
+
+Run `assertledger explain TARGET_STRENGTH_INSUFFICIENT` for an explanation. Add `--json` for
+the strict `catalogueVersion: "1.0.0"` report. Several codes can be passed together; duplicates
+are removed and results are sorted by code.
+
+The same report is available through `new AssertLedger().explain(codes)` and the read-only
+MCP tool `assertledger_explain` with `{ "codes": ["TARGET_STRENGTH_INSUFFICIENT"] }`.
+`DiagnosticReportSchema` and `explainReasonCodes` are public package exports. Git qualification
+includes this guidance in the terminal and its saved summary.
+
+| Symptom | Meaning | Next step |
+| --- | --- | --- |
+| `TARGET_STRENGTH_INSUFFICIENT` | The test did not detect enough declared bugs by assertion. | Assert the corrected behavior and rerun against the same worlds. |
+| `REFERENCE_NOT_GREEN` | The test fails on corrected code. | Fix the test or the reference before interpreting bug detection. |
+| `OBSERVATIONS_DIVERGE` | Repeated runs disagree. | Remove nondeterministic inputs and repeat all attempts. |
+| `CANDIDATE_DISCOVERY_INVALID` | The candidate was not identified as expected. | Check the committed path and runner selection. |
+| `TIMEOUT` / `PROCESS_CRASH` | Execution did not yield acceptable assertion evidence. | Resolve the operational failure; it cannot count as a detected bug. |
+| `GIT_REGRESSION_OUTPUT_EXISTS` | The chosen directory already contains something. | Choose a new evidence directory. |
+| `MCP_REPOSITORY_ROOT_FORBIDDEN` | The server does not permit the requested repository. | Use the intended project root or a server configured by its operator. |
+
+Guidance is derived presentation data. It does not change the verdict, evidence manifest,
+decision digest, artifact digest or existing JSON outputs. Unknown codes remain unknown and
+advise consulting the matching package version. Inputs accept only bounded uppercase reason
+codes; arbitrary exception messages, source code, environment values and logs are not inputs.
+
+## Français
+
+La commande `assertledger explain CODE --json` rend les mêmes explications que le SDK et MCP.
+Les explications du catalogue sont en anglais pour conserver un vocabulaire commun aux outils.
+Un code inconnu reste signalé comme inconnu ; il ne devient jamais un résultat favorable.
+
+Commencez par le premier contrôle en échec. Corrigez les erreurs d’exécution avant d’évaluer la
+force du test. Un délai dépassé, une compilation impossible ou une exception générique ne
+prouvent pas que le test détecte le défaut déclaré.

package/docs/distribution.md

@@ -0,0 +1,40 @@
+# Verify the installed package
+
+Run `pnpm run smoke:package` from a checkout with its locked dependencies installed.
+The command builds once, checks the schemas and conformance bundle, packs the distribution and
+installs that tarball into a fresh temporary npm consumer whose path contains spaces.
+Consumer dependencies are fetched from the public npm registry; lifecycle scripts
+and the operator's npm configuration are disabled.
+
+The smoke exercises both installed command aliases (`assertledger`, `testforge`),
+both SDK class aliases, the public root and core exports, static init and audit,
+and the bundled trusted `node:test` example. The strong test must be selected,
+the weak test must be rejected as `WEAK_ORACLE`, and every replay rail must pass.
+It also checks the advertised schemas, conformance bundle, integration skill and
+runtime files in the tarball and installed package.
+It also compiles a TypeScript consumer against the installed root/core exports
+using the checkout's pinned compiler and Node type definitions. Consumer imports
+resolve from the temporary project; no source-package alias is configured.
+Runtime module resolution is confined to that consumer, so a dependency installed
+elsewhere on the developer's machine cannot hide an incomplete package manifest.
+The existing pinned TypeScript scanner is a production dependency of static repository analysis.
+
+Three fault witnesses remove a runtime file and break runtime and TypeScript
+exports. Each must fail for the expected module or type error, then pass after byte-exact
+restoration in a fresh process. Raw command results, witnesses, manifest, replay,
+the tarball and its SHA-256 are retained under `.testforge/package-smoke/<run-id>`.
+Temporary consumers are removed after the run. The retained manifest is replayable;
+its original execution paths refer to the removed consumer.
+
+CI runs this smoke on Windows and Linux with Node 22.15.0 and 24 alongside `pnpm check`.
+A successful local smoke proves that local tarball on the reported Node version
+and operating system. It does not establish npm publication, cross-platform CI
+success, hostile-code isolation, or adoption by external users. The example uses
+explicitly unsandboxed trusted-local execution.
+
+The installed `check` journey also evaluates a
+[real historical correction projected into a node:test fixture](../examples/git-history/README.md).
+It requires `VERIFIED` for the strong candidate, `REJECTED` for weak and generic-crash candidates,
+two correct target observations each, valid replay, and unchanged source bytes, index and HEAD.
+Each case retains its request, manifest and human summary. The upstream source snapshots,
+license, commit IDs, Git blob IDs and SHA-256 hashes are bundled and checked before use.

package/docs/git-regression.md

@@ -0,0 +1,39 @@
+# Qualifier un test de régression entre des révisions Git
+
+La commande `check` vérifie qu’un test JavaScript `node:test` commité détecte une correction précise. Elle exécute le même test sur trois projections déclarées : la révision corrigée, la révision qui contient le bug et une révision neutre choisie par l’opérateur.
+
+Remplacez `BEFORE`, `AFTER` et `NEUTRAL` par vos révisions. Cette commande s’utilise sur une ligne
+sous PowerShell comme dans un shell POSIX :
+
+```sh
+assertledger check . --before BEFORE --after AFTER --neutral NEUTRAL --neutral-reason "raison explicite du contrôle" --test tests/regression.test.js --base-test tests/base.test.js --out .assertledger/evidence --allow-unsafe-execution
+```
+
+`--after` utilise `HEAD` par défaut. `--base-test` peut être répété. Le dossier donné à `--out` doit être un nouveau chemin relatif au dépôt. AssertLedger le réserve de manière exclusive, écrit `executed-request.json` et `summary.md`, puis publie `manifest.json` en dernier par renommage atomique. La présence de `manifest.json` est le marqueur de complétion ; un lecteur doit ignorer un dossier qui ne le contient pas.
+
+L’exécution `trusted-local` est volontairement **UNSANDBOXED**. Le drapeau `--allow-unsafe-execution` constitue l’autorisation distincte de l’opérateur. L’API équivalente est `new AssertLedger().checkGitRegression(options)` et exige `allowUnsafeExecution: true`.
+
+MCP expose le même parcours avec `assertledger_check` (alias `testforge_check`) seulement si
+l’opérateur a démarré le serveur avec `--allow-unsafe-execution`. L’entrée reprend les options
+du SDK, sans le champ de permission : `repository`, `before`, `after` facultatif, `neutral`,
+`neutralReason`, `test`, `baseTests` et `out`. La racine est confinée aux dépôts autorisés ; le
+dossier de sortie suit les mêmes contrôles que la CLI. Un client ne peut pas s’accorder cette
+permission dans son message.
+
+## Limites de cette première tranche
+
+- seules les révisions commitées sont lues ; les changements locaux sont ignorés ;
+- le test candidat doit être un fichier `.js`, `.mjs` ou `.cjs` utilisant les modules Node intégrés et des imports relatifs ;
+- les dépendances d’exécution déclarées ne sont pas transportées ;
+- le test de base doit être explicitement indiqué et identique dans les trois révisions ; les contrôles doivent découvrir au moins un vrai test ;
+- les ensembles de chemins doivent rester identiques après retrait du test candidat ; les ajouts, suppressions, renommages, liens, sous-modules et modes exécutables sont refusés ;
+- une révision neutre identique à la révision corrigée est acceptée comme contrôle répété, sans preuve indépendante de robustesse ;
+- le rejeu vérifie l’intégrité du manifeste, mais ne réauthentifie pas les objets Git ni l’exécution passée.
+
+Le verdict porte uniquement sur la faute déclarée. Un résultat `REJECTED` ne démontre pas que le test est inutile dans un autre contexte.
+
+La sortie humaine et `summary.md` indiquent les SHA résolus, les observations sur le défaut,
+les motifs du verdict et du candidat, les limites et une commande de rejeu adaptée au shell de
+la machine. Le dossier de sortie ne peut pas se trouver dans les métadonnées Git. Les lectures
+Git sont bornées ; le contenu est vérifié puis conservé en mémoire, dans la limite de 107 003 904
+octets de données brutes, auxquels s’ajoutent des en-têtes bornés.

package/docs/migration-repository-validation-order.md

@@ -0,0 +1,35 @@
+# Repository validation precedes runtime probing
+
+The engine now checks the source repository's file and byte budgets before probing an adapter
+runtime, running the `node:test` preflight, or creating the campaign directory. It still checks
+the copied snapshot against the same budgets before executing a campaign.
+
+Previously, an over-budget repository could return a runtime error first. A slow runtime preflight
+could therefore mask `REPOSITORY_BYTES_BUDGET_EXCEEDED` with an engine error. The CLI now reliably
+returns the existing repository-budget reason code and validation exit code `4` when that source
+budget fails, including when the configured Node executable is unavailable.
+
+For callers that submit several invalid inputs, error precedence changes: after request parsing
+and repository-root resolution, source inventory and repository-budget errors precede runtime
+probe errors. Callers should correct the reported repository problem before retrying runtime
+qualification. With valid repository budgets, the existing runtime checks still apply.
+
+No schema versions, error codes, manifest fields, gate semantics, digest projections, or unsafe
+execution permissions change. Existing manifests retain their replay contract.
+
+Compatibility witnesses in `tests/integration.test.ts` combine each invalid repository budget with
+an unavailable Node executable. Both fail against the old ordering and pass with repository
+validation first. The ordinary runtime and campaign tests cover valid-budget execution.
+
+## Qualification output budgets
+
+Both executable identity probes and both runtime preflight probes now propagate the caller's
+`maximumOutputBytes`, capped by the existing internal 64 KiB ceiling. Previously these processes
+always used 64 KiB, even when the caller requested less. Controlled reporter files retain their
+independent fixed bound; this correction concerns captured stdout and stderr.
+
+A runtime installed at a long path can exceed a small capture budget when reporting its identity.
+That case now returns the existing `NODE_TEST_EXECUTABLE_PROBE_FAILED` validation error instead of
+continuing with output captured beyond the requested limit. Increase the request budget explicitly
+when needed. No schema, digest, or decision semantics change. Runtime tests include a real copied
+Node executable at a long path and a runner witness for both the lower caller cap and upper safety cap.

package/docs/migration-testforge-to-assertledger.md

@@ -0,0 +1,64 @@
+# Migrating from TestForge to AssertLedger
+
+AssertLedger is a rename, not a protocol break. The evidence model, gates, decision semantics, and
+every wire-level identifier described in [proof-model.md](proof-model.md) and
+[conformance-v1.md](conformance-v1.md) are unchanged. Existing integrations continue to work without
+modification during the compatibility window; there is no forced migration date.
+
+## What changed
+
+- The preferred public name is **AssertLedger**; the npm package is `assertledger`.
+- The preferred SDK entry point is the `AssertLedger` class.
+- The preferred CLI binary is `assertledger`.
+- The preferred MCP server name and tool prefix is `assertledger`.
+
+## What did not change
+
+Nothing at the wire level. The following identifiers are frozen for replay and interoperability
+compatibility and are **not** renamed by this migration:
+
+| Identifier | Value | Where |
+| --- | --- | --- |
+| Schema `$id` domain | `https://testforge.dev/schemas/...` | every published JSON Schema |
+| H3 payload schema domain | `https://testforge.dev/payloads/...` | `src/contracts/index.ts` |
+| Structured-command adapter kind | `"testforge-command"` | verification request/manifest `adapter.kind` |
+| Reserved environment prefix | `TESTFORGE_*` | `RESERVED_ENVIRONMENT_VARIABLE` allowlist rejection |
+| Corpus allocation canonicalization domain | `"TESTFORGE_AGENTIC_CORPUS_CASE_V1"` | `src/contracts/index.ts` |
+| Observation taxonomy domain | `"TESTFORGE_OBSERVATION_V1"` | `src/contracts/index.ts` |
+| H3 structured-result protocol | `"TESTFORGE_H3_STRUCTURED_RESULT_V1"` | `src/contracts/index.ts` |
+| Evidence context engine name | `"testforge"` | `evidenceContext.engine.name` in every manifest |
+| Repository-digest exclusion directory | `.testforge` | repository analyzer default excludes |
+| All published schema bytes and conformance bundle digests | unchanged | `schemas/`, `conformance/v1/` |
+
+Changing any of these would be a public contract change requiring a major version and a documented
+compatibility break under [AGENTS.md](../AGENTS.md). This migration deliberately does not do that.
+
+## Compatibility surface
+
+| Surface | Preferred | Legacy (still supported) |
+| --- | --- | --- |
+| npm package | `assertledger` | — (package was renamed; `testforge` was never published) |
+| CLI binary | `assertledger` | `testforge` — installed alongside, identical `dist/cli.js` entrypoint |
+| SDK class | `AssertLedger` | `TestForge` — a `class TestForge extends AssertLedger {}` subclass with an identical surface |
+| MCP server name | `assertledger` | reported server name; no separate legacy server identity |
+| MCP tool names | `assertledger_*` | `testforge_*` — every tool is registered twice with the exact same handler and tool configuration; every pair except the variable schema-document lookup also shares one output-schema object |
+| MCP factory function | `createAssertLedgerServer` | `createTestForgeServer` — a direct alias (`export const createTestForgeServer = createAssertLedgerServer`), not a reimplementation |
+
+Every alias pair calls the identical underlying function. None of the facades (`src/sdk`, `src/cli.ts`,
+`src/mcp`) reimplement a gate, a schema, or a digest computation for either name.
+
+## What operators and integrators should do
+
+- New integrations: use the `assertledger` package/binary, the `AssertLedger` SDK class, and the
+  `assertledger_*` MCP tool names.
+- Existing integrations: no action is required. `testforge`, `TestForge`, and `testforge_*` continue
+  to resolve to the same code.
+- Do not expect a new schema version, a new adapter kind, or a new reserved environment prefix. None
+  was introduced by this rename.
+
+## What is deliberately not covered by this migration
+
+- No npm publish, GitHub repository rename, domain change, or release under the new name — those are
+  external delivery actions outside this compatibility slice.
+- No change to the `conformance/v1/` bundle or `schemas/*.json` bytes.
+- No removal date for the `testforge`/`TestForge`/`testforge_*` aliases has been set.

package/docs/project-intent.md

@@ -0,0 +1,173 @@
+# Intention et cap d’AssertLedger
+
+État des lieux et cap ratifié le 8 septembre 2026. Le propriétaire a demandé d’aligner Linear et
+les issues sur la qualification de tests de correction, puis de poursuivre jusqu’à une release
+1.0 avec une prise en main soignée. Les contrats de preuve existants restent applicables.
+
+## Cap 1.0 décidé
+
+**Vérifiez que le test détecte réellement le bug corrigé, avant de l’accepter.** La cible initiale
+est une équipe SaaS Node.js/TypeScript qui utilise des agents. Le développeur désigne le test et
+la correction ; le tech lead obtient un verdict, les raisons, les révisions et les limites.
+
+Le premier parcours s’appuie sur `node:test`, une version fautive, une référence corrigée et un
+contrôle neutre justifié. Les interfaces préparent les entrées du vérificateur sans redéfinir ses
+gates. La première exécution reste réservée au code de confiance avec opt-in explicite
+`UNSANDBOXED`. L’ouverture aux contributions hostiles exige une isolation qualifiée.
+
+Le projet Linear est désormais [AssertLedger 1.0 — Tests de régression vérifiés](https://linear.app/hoklims/project/assertledger-10-tests-de-regression-verifies-acf768519152).
+Le dépôt public dédié est [hoklims/assertledger](https://github.com/hoklims/assertledger).
+Le [contrat de livraison 1.0](release-1.0.md) décrit le parcours, les critères et les travaux différés.
+Les sections ci-dessous conservent les constats de départ ; leur séquencement est précisé par ce cap.
+
+## Le résultat recherché
+
+Donner au développeur qui travaille avec des agents une réponse exploitable à cette question :
+**quels tests ajoutent une protection démontrée contre les fautes visées, et combien coûte leur
+exécution ?**
+
+L’agent propose des tests. AssertLedger les exécute sur une référence, des variantes fautives et
+des variantes censées préserver le comportement. Il explique ensuite ce que les observations
+permettent de conclure. Le développeur conserve l’autorité sur le comportement attendu, les
+variantes pertinentes et l’acceptation du changement.
+
+L’usage initial proposé est le durcissement de dépôts de confiance utilisés par Guillaume et ses
+agents. Un premier parcours doit aboutir à une preuve utile sur un dépôt consommateur, puis être
+reproduit depuis un autre harness. L’ouverture à du code non fiable exige une isolation distincte.
+
+## Trois résultats à distinguer
+
+| Résultat | Question posée | Limite |
+| --- | --- | --- |
+| Qualification d’un candidat | Ce test passe-t-il sur la référence et les neutres, et détecte-t-il les fautes exigées ? | La conclusion porte sur les mondes et essais déclarés. |
+| Choix d’un ensemble de tests | Quelle protection supplémentaire apporte chaque test, pour quel coût mesuré ? | La sélection actuelle porte sur les candidats déjà éligibles et sélectionnés par la source. |
+| Validation empirique du produit | Cette méthode conserve-t-elle la détection de vrais défauts hors calibration ? | Il faut des expériences pré-engagées et un holdout indépendant. |
+
+La rapidité intervient après les exigences de preuve. Elle ne compense jamais un échec de
+référence, un monde neutre rouge, une observation instable ou une attribution douteuse.
+
+## Ce qui existe réellement
+
+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 34 schémas JSON, tous présents dans le verrou de conformance. 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 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` :
+ses événements ne suffisent pas à mesurer fidèlement les quatre phases demandées.
+
+La documentation rapporte huit cas TestExplora admis pour calibration curatée. Elle ne fournit
+pas de holdout réel qualifié. Cette reprise ne réexécute pas ces campagnes historiques et n’accède
+pas aux données privées du holdout.
+
+Le dépôt est sur `feat/testforge-core`, HEAD `cb1dde2c2fe0f66e46652e7223086dd04b460c67`.
+À la reprise, 29 fichiers suivis sont modifiés, de nombreux nouveaux fichiers restent non suivis
+et aucun remote Git n’est configuré. Du code local, même testé, ne constitue donc pas une release
+publiée. La qualification `node:test` HOK-570 reste `In Progress` dans Linear.
+
+## Les écarts qui empêchent l’usage visé
+
+Le parcours Linear annoncé est `install → init → connect → doctor → check --changed → land → replay CI`.
+`connect` est maintenant utilisable en CLI, et le diagnostic statique `doctor` en CLI, SDK et MCP ;
+`check --changed` et `land` restent des travaux de backlog. `init` produit une configuration et un
+lock ; il laisse explicitement les mondes et les candidats à fournir par l’opérateur ou le harness.
+
+Le premier obstacle d’adoption est donc le passage entre « dépôt initialisé » et « campagne
+pertinente ». Ajouter des adaptateurs aide à exécuter les tests, mais ne décide pas quelles fautes
+et quels comportements les tests doivent représenter.
+
+Un résultat historique illustre une seconde difficulté : la campagne sur les 36 tests du noyau
+exigeait que chaque candidat tue les quatre cibles obligatoires. Tous ont été rejetés, alors que
+six détectaient une cible. C’est le résultat attendu de la politique choisie. Il ne permet pas
+de conclure que ces tests n’ont aucune valeur sur leurs responsabilités respectives.
+
+Pour le pilote, les mondes obligatoires doivent donc correspondre à la responsabilité du candidat.
+Si l’on veut accepter un ensemble dont les membres se complètent sans être individuellement
+éligibles, il faudra un contrat distinct, des contre-exemples et une décision explicite. Cette
+proposition ne modifie pas les gates v1 pour obtenir un résultat plus flatteur.
+
+Enfin, l’intégrité d’un manifeste et l’authenticité de ses observations sont deux propriétés
+différentes. Un replay valide ne prouve ni que les octets ont été exécutés, ni que le producteur est
+indépendant. La politique externe de preuve et ses reçus restent une responsabilité séparée.
+
+## Ordre de reprise proposé
+
+### 1. Fiabiliser et conserver le socle existant
+
+Terminer la vérification de la qualification `node:test`, corriger les échecs reproductibles,
+conserver les preuves exactes et inventorier le diff hérité avant tout checkpoint Git.
+
+Critère de sortie : `pnpm check` vert, témoins adversariaux pertinents observés, campagne minimale
+rejouable et limites d’acceptation explicites. La revue du système de preuve porte sur l’agrégat
+qui sera réellement accepté. Le durcissement global HOK-406 n’autorise pas implicitement une
+modification de la politique active et ne remplace pas le reçu attendu.
+
+### 2. Démontrer un usage complet dans un dépôt consommateur
+
+Choisir une responsabilité métier bornée, une référence, une faute connue et un monde neutre
+justifié. Comparer au moins un test utile à un test qui passe sans détecter la faute. Présenter le
+verdict, ses raisons, les limites et les octets concernés depuis un harness, puis rejouer le même
+artefact depuis un second point d’entrée.
+
+Critères de sortie proposés : installation et parcours documentés exécutés depuis un consommateur
+neuf ; premier résultat compréhensible ; échec générique et timeout refusés comme preuves ; mêmes
+décisions au replay ; durée jusqu’à la première preuve mesurée. L’objectif historique de cinq
+minutes reste un objectif à mesurer, pas une performance acquise.
+
+L’adaptateur suivant dépend du dépôt choisi. HOK-571 prépare Vitest ; HOK-574 prépare pytest.
+Les cinq adaptateurs de HOK-422 restent prévus, mais ne doivent pas tous précéder le premier
+apprentissage d’usage. Le branchement au harness et les diagnostics se construisent à partir des
+obstacles observés dans ce parcours.
+
+### 3. Mesurer le gain, puis élargir
+
+Mesurer d’abord le coût complet de la qualification, le temps de feedback et la protection
+supplémentaire apportée dans un contexte fixé. Une somme de p95 individuels ne constitue pas une
+mesure du p95 du portefeuille réellement exécuté.
+
+Reprendre ensuite le corpus et les expériences H1–H4 avec les autorités, sources et engagements
+prévus. La calibration peut produire un résultat nul ou défavorable : ce résultat doit rester
+publiable. Étendre les adaptateurs, le cache et l’isolation selon les usages vérifiés.
+
+Critère de sortie pour une affirmation empirique : hypothèses et seuils pré-engagés, provenance
+complète, holdout sous garde indépendante et critères satisfaits. Un corpus mécaniquement `READY`
+ne signifie pas que les hypothèses sont confirmées.
+
+## Mesurer la valeur sans inventer un score universel
+
+| Mesure proposée | Ce qu’elle aide à décider |
+| --- | --- |
+| Temps jusqu’à la première campagne comprise et rejouée | Le parcours est-il réellement accessible ? |
+| Fautes pertinentes détectées et contrôles conservés verts | Le test protège-t-il la responsabilité visée ? |
+| Faux positifs sur les erreurs opérationnelles | Le verdict accorde-t-il indûment de la confiance ? |
+| Coût total de qualification et coût du feedback courant | Le bénéfice justifie-t-il la dépense ? |
+| Protection marginale d’un test ou d’un ensemble | L’ajout apporte-t-il quelque chose de démontrable ? |
+
+Ces mesures nécessitent un contexte et un protocole. Aucun gain, taux d’adoption ou classement
+entre machines n’est établi par ce document.
+
+## Frontières conservées
+
+- Le noyau décide sans I/O, horloge, réseau, hasard ou jugement de modèle.
+- Seul un échec d’assertion attribué peut compter comme détection d’une cible en v1.
+- `trusted-local` reste explicitement non isolé ; ses ressources bornées ne forment pas une sandbox.
+- Les mondes, politiques et pins de confiance ne deviennent pas valides parce qu’un agent les fournit.
+- Les catching tests, qui doivent échouer sur une révision proposée, restent hors du mode hardening v1.
+- Une évolution de schéma, de digest, d’éligibilité ou de permission exige son contrat et ses preuves.
+- La publication, l’acceptation externe et la validation scientifique conservent leurs critères propres.
+
+## Sources de reprise
+
+- [Contrat de preuve](proof-model.md), [architecture](architecture.md),
+  [initialisation](repository-init.md) et [adaptateurs](adapter-protocol.md).
+- [Profil v1](agentic-test-profile.md), [profil v2](agentic-test-profile-v2.md),
+  [plan de corpus](agentic-corpus-plan.md) et [résultat historique sur les tests du noyau](../benchmarks/self-hosted-core/RESULT-existing-tests-v1.md).
+- [Projet Linear](https://linear.app/hoklims/project/assertledger-agentic-test-profile-acf768519152),
+  [parcours HOK-419](https://linear.app/hoklims/issue/HOK-419),
+  [qualification HOK-570](https://linear.app/hoklims/issue/HOK-570),
+  [politique externe HOK-406](https://linear.app/hoklims/issue/HOK-406).

package/docs/proof-model.md

@@ -0,0 +1,116 @@
+# Evidence and decision model
+
+AssertLedger uses “proof” to mean recorded operational evidence, not mathematical verification of a
+program.
+
+## What `VERIFIED` means
+
+For the repository digest scope, worlds, adapter configuration, policy, attempts, and execution
+metadata recorded in the manifest, every selected candidate:
+
+1. stayed within configured candidate roots and size budgets;
+2. ran from the campaign snapshot in a fresh execution workspace;
+3. produced complete, stable, attributed candidate observations;
+4. passed every reference and neutral world;
+5. produced attributed assertion failures for every required target and met the weighted threshold;
+6. was selected by the published deterministic ordering.
+
+This statement applies only to the recorded attempts and worlds. It does not generalize to
+unexecuted states, future environments, or faults outside the supplied targets.
+
+## Outcome taxonomy
+
+| Outcome | Meaning | Can kill a target in v1? |
+| --- | --- | --- |
+| `PASS` | Runner completed successfully | No |
+| `ASSERTION_FAILURE` | Adapter attributed an assertion failure to the candidate | Yes |
+| `COLLECTION_FAILURE` | Runner could not collect tests | No |
+| `COMPILE_FAILURE` | Code could not compile or load | No |
+| `PROCESS_CRASH` | Runner failed without an admitted assertion | No |
+| `TIMEOUT` | Execution exceeded its time budget | No |
+| `INFRA_ERROR` | Runner, adapter, report, or host failed | No |
+| `NO_TEST_DISCOVERED` | Adapter found no candidate test | No |
+
+Only an attributed `ASSERTION_FAILURE` kills a target in policy v1. A caller cannot configure
+timeouts, crashes, compilation failures, or collection failures as accepted target outcomes.
+
+## Candidate gates
+
+The core evaluates gates in this order and records a status, evidence run IDs, and reason codes for
+each gate:
+
+| Gate | Condition |
+| --- | --- |
+| `COMPLETENESS` | Every world has exactly the required attempts |
+| `STABILITY` | Normalized outcomes agree across attempts |
+| `DISCOVERY` | Every candidate run reports at least one attributed candidate test |
+| `REFERENCE` | All reference observations pass |
+| `NEUTRAL` | All neutral observations pass |
+| `TARGET_STRENGTH` | Required targets are killed and the weighted threshold is met |
+
+A failed prerequisite leaves later dependent gates as `NOT_RUN`. Repetition measures observed
+stability; a successful retry never erases a contradictory attempt.
+
+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;
+- `UNSTABLE`: complete attempts produced different normalized outcomes;
+- `INCONCLUSIVE`: required observations were missing or execution produced `TIMEOUT` or
+  `INFRA_ERROR`.
+
+## Campaign statuses
+
+- `VERIFIED`: at least one eligible candidate was selected.
+- `REJECTED`: evidence was complete and conclusive, but no candidate was eligible.
+- `INCONCLUSIVE`: controls were invalid, or at least one candidate was unstable or inconclusive.
+- `ENGINE_ERROR`: the core could not normalize the supplied evidence safely.
+
+## Controls and attribution
+
+Every world runs without a candidate before candidate runs. A valid control is complete, stable,
+`PASS`, reports zero candidate tests, and reports no candidate attribution. One invalid control makes
+the campaign `INCONCLUSIVE`.
+
+Attribution comes from the adapter and remains part of the trusted computing base. The built-in
+`node:test` adapter consumes runner events and associates them with resolved candidate file paths;
+the structured-command adapter trusts its strict runtime report. See
+[adapter-protocol.md](adapter-protocol.md).
+
+## Decision and artifact digests
+
+The manifest carries two SHA-256 integrity values with different scopes:
+
+- `decisionDigest` binds decision-relevant normalized evidence: schema and policy versions,
+  repository digest, evidence context and world provenance, candidate assessments, gates,
+  decision-relevant observations, and the final selection. It excludes observation duration, process
+  exit code, and stdout/stderr digests.
+- `artifactDigest` binds the complete emitted manifest except `artifactDigest` itself. It therefore
+  detects changes to operational observation fields and disclosure metadata that do not alter the
+  decision digest.
+
+`AssertLedger.replay()` validates the manifest contract, recomputes both digests, and recomputes
+candidate assessments and the final decision from the recorded normalized evidence. Its result
+includes `schemaValid`, `decisionDigestValid`, `artifactDigestValid`, and
+`decisionSemanticsValid`; `valid` requires all four rails. Replay does not rerun tests, prove that
+observations were truthful, authenticate the producer, or replace a signed external attestation.
+
+The manifest alone is not a self-contained reproduction bundle. It stores candidate and world
+digests rather than their file bodies, stdout/stderr digests rather than raw logs, and environment
+allowlist names rather than effective values. The built-in `node:test` adapter records its resolved
+executable real path, version, and SHA-256 digest; the structured-command adapter records only its
+configured command. Preserve the original request, repository snapshot, dependencies, missing
+executable identities, and raw logs separately when independent audit matters.
+
+## Explicit non-claims
+
+AssertLedger does not prove:
+
+- absence of bugs or complete fault detection;
+- universal oracle quality;
+- absence of flakiness beyond observed attempts;
+- semantic relevance or correctness of operator-supplied worlds;
+- resistance to a candidate designed to recognize the worlds;
+- containment of hostile code under `trusted-local`;
+- provenance authenticity without a separate signed attestation.