assertledger 1.0.0

package/docs/agentic-test-profile.md

@@ -0,0 +1,274 @@
+# Agentic Test Profile
+
+Status: implemented public contract for `testforge-agentic-profile/1.0.0`.
+
+## Purpose
+
+The Agentic Test Profile describes how much declared fault-detection evidence a test candidate
+delivers within an observed execution budget. It is a derived, auditable report for developers,
+agents, and CI systems. It does not change the meaning of an evidence manifest or its `VERIFIED`
+decision.
+
+The profile answers a bounded question:
+
+> Among candidates that already produced valid AssertLedger evidence, which ones delivered the most
+> declared fault-detection value within the repository's stated feedback budget?
+
+It does not answer whether the program is correct, whether the supplied worlds are complete, or
+whether a test will remain non-flaky in every future environment.
+
+## Testing mode
+
+Version 1 profiles **hardening tests** only. A hardening test:
+
+- passes on the operator-declared reference implementation;
+- passes on required behaviour-preserving neutral worlds;
+- produces attributed assertion failures on operator-declared target worlds; and
+- is intended to remain in the repository to detect future regressions.
+
+This is different from a **catching test**, which passes on a parent revision and intentionally
+fails on a proposed revision to report a possible bug in that change. Catching tests have a
+different reference direction, false-positive workflow, and lifecycle. They require a separate
+future policy and must not be assigned a hardening profile.
+
+## Two independent layers
+
+The evidence decision and efficiency profile remain separate:
+
+```text
+deterministic evidence: VERIFIED | REJECTED | INCONCLUSIVE | ENGINE_ERROR
+empirical profile:      QUALIFIED | BUDGET_MISSED | INSUFFICIENT_TIMING_EVIDENCE | NOT_QUALIFIED
+```
+
+An efficiency profile may be positive only when:
+
+1. the source manifest strictly validates;
+2. replay validates the schema, decision digest, artifact digest, and decision semantics;
+3. the campaign decision is `VERIFIED`; and
+4. every profiled candidate is selected and `ELIGIBLE`.
+
+Latency never compensates for weak target strength, an invalid reference or neutral observation,
+missing evidence, instability, or an unattributed failure.
+
+## Versioned profile policy
+
+Thresholds are repository policy, not universal constants. A policy declares named feedback lanes:
+
+```json
+{
+  "profileVersion": "1.0.0",
+  "profileId": "example-project/default",
+  "mode": "HARDENING",
+  "minimumTimingSamples": 5,
+  "lanes": [
+    { "id": "instant", "maximumReferenceP95Ms": 2000 },
+    { "id": "loop", "maximumReferenceP95Ms": 10000 },
+    { "id": "gate", "maximumReferenceP95Ms": 60000 }
+  ]
+}
+```
+
+Lane identifiers are descriptive labels scoped to the policy. AssertLedger does not claim that two
+repositories using an `instant` lane are directly comparable. Lane thresholds must be positive,
+strictly increasing, and use unique portable identifiers.
+
+## Report binding
+
+The derived report binds:
+
+- the complete, strictly validated source manifest, preserved in the report so profile replay does
+  not depend on a mutable side file;
+- the source manifest's `artifactDigest`, which includes operational durations;
+- the profile policy and its digest;
+- the profile implementation version;
+- candidate metrics and classifications; and
+- a canonical report digest.
+
+The evidence manifest v1 remains byte-for-byte and semantically unchanged. Adding the profile to
+the manifest would break its strict schema and digest projections, so the profile is a separate
+public artifact.
+
+## Metrics
+
+### Declared target strength
+
+For a candidate `c`:
+
+```text
+targetWeightPermille(c) =
+  1000 * weight of target worlds killed by c / total target-world weight
+```
+
+The profile metrics preserve required targets killed/total and all killed target identifiers. The
+embedded source manifest remains the authoritative location for reference and neutral gate results,
+evidence run identifiers, and candidate reason codes; the derived candidate rows do not duplicate
+them. Code coverage may be reported by external tools as diagnostic context, but it is not a
+qualification gate.
+
+### Observed consistency
+
+The report uses `OBSERVED_CONSISTENT` or `OBSERVED_INCONSISTENT` plus the exact attempt count. It
+never calls a test universally stable. Repeating a test three times records three consistent
+observations; it does not establish a useful probabilistic upper bound on future failure. Any
+contradictory attempt is preserved as observed inconsistency even though the candidate is already
+ineligible for a positive profile.
+
+### Latency
+
+Version 1 derives timing from candidate observations already recorded in the source manifest.
+Candidate feedback latency is summarized from `REFERENCE` observations because those represent the
+normal passing developer loop. The report includes:
+
+- sample count;
+- minimum and maximum;
+- integer-arithmetic p50 and p95 using the nearest-rank method; and
+- total recorded candidate execution time across all worlds and attempts.
+
+Nearest rank sorts non-negative finite durations and selects index `ceil(p * n) - 1`. Fractional
+adapter durations are preserved. Empty input has no quantile. The report is
+`INSUFFICIENT_TIMING_EVIDENCE` when reference sample count is below the policy minimum.
+
+These durations include the adapter process boundary measured by the current engine. They do not
+distinguish cold start, warm execution, compilation, collection, or test-body time. Therefore v1
+calls them `RECORDED_REFERENCE_WALL_TIME` and makes no cold/warm claim.
+
+### Marginal evidence
+
+For selected candidates in deterministic selection order, the report includes the target weight
+first covered by that candidate. A candidate that only repeats already-covered targets has zero
+marginal weight even if its individual target score is high.
+
+### Pareto status
+
+Pareto comparison is performed only among selected `ELIGIBLE` candidates with sufficient timing
+evidence, including candidates that miss every declared lane. Candidate A dominates B when A is no
+worse on all of these dimensions and strictly better on at least one:
+
+- declared target weight killed: greater is better;
+- required targets killed: greater is better;
+- reference p95 wall time: lower is better;
+- total recorded candidate wall time: lower is better; and
+- candidate size in bytes: lower is better.
+
+Candidates without sufficient timing evidence are not placed on the timed frontier. The report
+publishes the frontier; it does not collapse the dimensions into a single opaque score.
+
+## Classification
+
+Classification is applied in this order:
+
+Invalid schema or replay evidence is rejected before a report is produced. For a valid source,
+classification is applied in this order:
+
+1. `NOT_QUALIFIED` when the campaign is not `VERIFIED`, or a candidate is not both selected and
+   `ELIGIBLE`.
+2. `INSUFFICIENT_TIMING_EVIDENCE` when the evidence gates pass but the declared minimum number of
+   reference timing samples is not present.
+3. `BUDGET_MISSED` when evidence is valid but the candidate satisfies no declared latency lane.
+4. `QUALIFIED` when evidence is valid, timing evidence is sufficient, and at least one lane is
+   satisfied.
+
+The report lists every satisfied lane and a `bestLaneId`, defined as the smallest declared budget
+the candidate satisfies. `QUALIFIED` is always scoped to declared worlds, attempts, environment,
+and profile policy.
+
+## Portfolio selection under a budget
+
+Each lane also yields a deterministic weighted-coverage portfolio under that lane's wall-time
+budget. Selection operates only after evidence qualification:
+
+1. compute uncovered target weight contributed by each remaining eligible candidate;
+2. discard candidates whose recorded p95 exceeds the remaining budget;
+3. select the greatest marginal target weight per unit of p95 cost;
+4. break ties by greater absolute marginal weight, lower p95, lower candidate size, digest, then id;
+5. stop when no candidate adds target weight within the remaining budget.
+
+The report records selected identifiers, summed reference p95 cost, covered target weight, required
+targets, and coverage permille for every lane. The greedy portfolio is an explainable baseline, not
+a proof of a globally optimal subset. The full Pareto frontier remains available so callers can make
+another policy choice without falsifying the recorded evidence.
+
+APFDc may be emitted as a diagnostic for a declared sequential order with declared target severity.
+It is not the primary score because parallel execution and partial portfolios violate the simple
+sequential interpretation.
+
+## Calibration and anti-gaming
+
+A public profile is no stronger than its world portfolio. A mature evaluation corpus should combine:
+
+- historical real faults with independently verified fixes;
+- operator-reviewed synthetic mutants;
+- behaviour-preserving neutral rewrites;
+- boundary and metamorphic properties; and
+- explicit dispositions for equivalent, redundant, disputed, or out-of-scope mutants.
+
+Local development may use fully visible worlds. Competitive or certification-like evaluation needs
+an independently governed holdout. A commit-reveal workflow can publish the corpus digest before a
+campaign and reveal the worlds afterward. Even then, the report claims only performance on that
+corpus.
+
+The initial product hypotheses are falsifiable:
+
+- H1: at equal declared target strength, Pareto selection reduces reference-loop p95 versus the full
+  eligible suite.
+- H2: candidates required to pass neutral worlds survive behaviour-preserving rewrites more often
+  than reference-only candidates.
+- H3: under equal time budgets, the qualified portfolio detects no fewer held-out historical faults
+  than a coverage-guided baseline.
+- H4: a reviewed reduced mutant portfolio retains non-inferior historical-fault recall at lower
+  execution cost than the exhaustive mutant set.
+
+If H3 or H4 fails, the project must describe the output as an audited declared-world profile, not as
+an empirically established testing sweet spot.
+
+The executable corpus gate lives under `benchmarks/agentic-profile`. It requires at least 20 strict
+cases from three immutable sources, a non-empty private holdout, and evaluable evidence for H1-H4.
+Until those gates pass, the scorer returns `NOT_READY` and no optimization loop is authorized.
+Public evaluation exposes exact reason codes; holdout evaluation exposes aggregate outcomes only.
+
+## Provenance maturity
+
+The source manifest does not fingerprint the complete host, effective environment, or dependency
+graph, and structured-command adapters remain part of the trusted computing base. The separate
+Agentic Benchmark Artifact now binds these declarations and a strict comparison scope. It does not
+authenticate them, and the built-in `node:test` reporter cannot yet acquire the four phase markers.
+Exact scoped timing therefore requires a trustworthy producer containing at least:
+
+- operating-system and architecture identity;
+- CPU and resource-limit identity;
+- runtime, adapter, dependency, and executable digests;
+- cold/warm preparation protocol;
+- raw per-phase samples; and
+- drift checks against a calibrated workload.
+
+Until that artifact exists, v1 profile timing is local observed evidence, not a portable benchmark.
+
+## Research basis
+
+- [Just et al., mutants and real faults, FSE 2014](https://homes.cs.washington.edu/~mernst/pubs/mutation-effectiveness-fse2014-abstract.html)
+  found mutation detection correlated with real-fault detection independently of code coverage,
+  while documenting important limitations.
+- [Elbaum, Rothermel, and Penix, regression testing in CI, FSE 2014](https://research.google/pubs/techniques-for-improving-regression-testing-in-continuous-integration-development-environments/)
+  treats fast feedback and test cost as first-class CI objectives.
+- [Meta predictive test selection](https://engineering.fb.com/2018/11/21/developer-tools/predictive-test-selection/)
+  demonstrates large-scale cost reduction while explicitly calibrating missed-regression and flaky
+  test risk.
+- [Kaufman et al., TCAP mutant prioritization, ICSE 2022](https://doi.org/10.1145/3510003.3510187)
+  argues that a mutant is useful insofar as it elicits a test that advances test completeness.
+- [Meta Mutation-Guided LLM-based Test Generation](https://arxiv.org/abs/2501.12862) uses a small,
+  concern-specific mutant portfolio to guide production test generation.
+- [Meta Just-in-Time Catching Test Generation](https://arxiv.org/abs/2601.22832) distinguishes
+  hardening tests from change-specific catching tests and shows why false-positive drag must be
+  measured independently from raw catch generation.
+
+## Explicit non-claims
+
+An Agentic Test Profile does not prove:
+
+- program correctness or complete fault detection;
+- semantic correctness or completeness of operator-supplied worlds;
+- permanent absence of flakiness;
+- portability of recorded timing to another machine;
+- resistance to a candidate designed with knowledge of visible worlds;
+- provenance authenticity without an external attestation; or
+- that a greedy portfolio is globally optimal.

package/docs/architecture.md

@@ -0,0 +1,157 @@
+# Architecture
+
+AssertLedger separates proposal, integration, orchestration, and decision authority. The separation
+keeps model-specific behavior out of the evidence policy and process I/O out of the deterministic
+core.
+
+## Four layers
+
+| Layer | Responsibilities | Must not do |
+| --- | --- | --- |
+| Agent or harness | Analyze context, propose candidate test files, submit requests | Decide that its own tests are valid |
+| Integration facade | Translate Skill, MCP, JSON CLI, or SDK calls into shared use cases | Reimplement gates or selection |
+| AssertLedger orchestrator | Snapshot repositories, enforce budgets, create workspaces, run adapters, normalize observations | Grant target credit outside the core |
+| Deterministic core | Canonicalize evidence, evaluate gates, select candidates, seal manifests | Read files, spawn processes, use the network, clock, randomness, or a model |
+
+Dependencies point downward:
+
+```text
+agent or harness
+       │
+       ▼
+facade: skill / MCP / CLI / SDK
+       │
+       ▼
+orchestrator: repository / execution / adapters / budgets
+       │
+       ▼
+core: contracts / gates / selection / digests
+```
+
+The concrete source boundaries are `src/contracts`, `src/core`, `src/engine`, and the thin
+`src/sdk`, `src/cli.ts`, and `src/mcp` facades. `src/contracts` and `src/core` form the deterministic
+core layer: contracts own the versioned wire request, and core owns decision authority.
+
+## Campaign data flow
+
+```text
+versioned request
+  ├─ repository root and exclusions
+  ├─ operator-owned worlds and provenance
+  ├─ candidate test overlays
+  ├─ adapter configuration
+  ├─ trusted-local authorization and environment allowlist
+  └─ policy and budgets
+          │
+          ▼
+single repository snapshot and repository digest
+          │
+          ├─ control × world × attempt
+          └─ candidate × world × attempt
+                    │
+                    ▼
+fresh workspace per execution
+world overlay → candidate overlay → adapter process
+                    │
+                    ▼
+normalized observations
+                    │
+                    ▼
+pure gate evaluation → deterministic selection → sealed manifest
+```
+
+The engine copies the source repository once into a campaign snapshot. Every execution receives a
+fresh copy of that snapshot. World overlays apply first; candidate overlays apply second. Candidate
+files must remain under a configured `candidateRoots` path.
+
+After request parsing and repository-root resolution, the engine validates source file and byte
+budgets before any runtime probe or preflight. It validates the copied snapshot again before
+campaign execution. See [validation error precedence](migration-repository-validation-order.md).
+
+The request separates budget scopes:
+
+- campaign-wide: `maximumCandidates`, `maximumWorlds`, `maximumExecutions`,
+  `maximumRepositoryFiles`, `maximumRepositoryBytes`, `maximumWorldOverlayBytes`, and
+  `maximumTotalCandidateBytes`;
+- per candidate: `maximumCandidateBytes`;
+- per execution: `timeoutMsPerExecution` and `maximumOutputBytes`, applied separately to captured
+  stdout and stderr.
+
+Local timeout enforcement and process-tree termination are best effort host operations, not
+containment.
+
+## Worlds and controls
+
+- `REFERENCE`: code the operator expects to be correct; an eligible candidate must pass it.
+- `TARGET`: code containing an operator-declared fault; a strong candidate must produce an attributed
+  assertion failure according to policy.
+- `NEUTRAL`: an operator-declared irrelevant or equivalent variation; an eligible candidate must
+  continue to pass it.
+
+The engine runs every world without a candidate. All controls must complete, remain stable, report
+`PASS`, discover no candidate tests, and claim no candidate attribution. Invalid controls make the
+campaign `INCONCLUSIVE`; a candidate cannot receive credit for a world that was already broken.
+
+AssertLedger does not generate mutants in v0.1. Mutant generators may produce operator-reviewed target
+worlds, but they never gain decision authority.
+
+## Determinism boundary
+
+Process execution is not deterministic by construction. Scheduling, timing, caches, filesystem
+behavior, dependencies, and the host can change observed runs. AssertLedger guarantees a narrower
+invariant:
+
+```text
+same versioned policy + same normalized evidence = same decision
+```
+
+The core sorts decision inputs before evaluation and excludes declared host-volatile observation
+fields from the decision digest. It does not make nondeterministic executions deterministic. Repeat
+attempts reveal only instability observed within the configured attempt budget.
+
+## Selection
+
+The core removes ineligible candidates, then selects candidates by deterministic marginal target
+coverage. Ties use candidate size, content digest, and identifier, in that order. Runtime is not a
+tie-breaker because it depends on the host.
+
+## Provenance and integrity
+
+The evidence context binds the engine identity, adapter configuration, achieved isolation level,
+environment allowlist names, budgets, candidate roots, and each world's provenance and overlay
+digest to the decision. It does not record effective environment values. For `node:test`, the engine
+probes the requested executable, resolves its real path, probes the resolved file again, and records
+the matching Node.js version plus the executable's SHA-256 digest. The structured-command adapter
+records its configured command but does not resolve or hash it.
+
+The repository digest covers regular files visited by the analyzer. The analyzer omits `.git`,
+`.testforge`, `node_modules`, and operator-excluded path segments. It rejects any encountered
+symbolic link instead of silently excluding it. Candidate contents and world overlays have separate
+digests. Preserve the snapshot and resolved dependency identities for stronger provenance.
+
+`detectedTestFrameworks` remains a sorted string array in repository-analysis v1 so this correction
+does not change the schema or existing wire consumers. Detection is deliberately conservative:
+JavaScript frameworks require a dependency declaration or dedicated config file, pytest requires a
+Python dependency/config declaration, and `node:test` requires an import in a file below a recognized
+test directory or in a colocated `*.test.*`/`*.spec.*` file. A lightweight lexer ignores comments,
+quoted examples, and template literals; config filenames must use a supported JavaScript,
+TypeScript, or JSON extension. These rules favor precision over recall, so an unrecognized manifest
+layout or naming convention can yield a false negative. The field does not expose per-framework
+provenance in v1; when evidence is absent, an empty list is more truthful than an inference. A future
+provenance-bearing shape requires an additive schema version.
+
+The decision digest covers decision-relevant evidence. The artifact digest covers the emitted
+manifest, including operational fields and disclosure metadata. Both are integrity checks, not
+signatures; neither authenticates the producer. See [proof-model.md](proof-model.md).
+
+The emitted manifest contains normalized observations and stdout/stderr digests, not raw process
+output, candidate or world file bodies, or a repository archive. A self-contained audit bundle must
+preserve those inputs and logs beside the manifest.
+
+## Extension points
+
+- Built-in adapters translate framework behavior into normalized observations.
+- The structured-command protocol supports external test-framework reporters.
+- A future isolation backend may replace `trusted-local` without changing gate ownership.
+- A future native orchestrator may replace the Node.js engine only after passing shared schema,
+  canonicalization, decision, and digest conformance fixtures.

package/docs/ci.md

@@ -0,0 +1,37 @@
+# CI and trusted-local execution
+
+The repository workflow runs the full checks on Windows/Linux with Node 22/24, then tests
+the packed distribution on Windows/Linux with Node 22.15/24. The package job retains
+manifests, summaries, replay results, command logs and the tarball for 14 days. Artifact names
+contain the tested GitHub SHA and matrix values.
+
+Both jobs execute repository code. They run on disposable GitHub-hosted runners with
+`contents: read`, no deployment secrets, and checkout credential persistence disabled.
+Never move trusted-local verification onto a privileged or self-hosted runner handling
+untrusted contributions. AssertLedger does not contain hostile code.
+
+The workflow permits pushes to `main` and same-repository pull requests from an owner,
+member or collaborator. Fork pull requests are skipped. A skipped job does not establish
+compatibility or release readiness: a maintainer must inspect the exact contribution and
+bring the reviewed changes onto a trusted repository branch before executing them.
+
+This is the project's contribution policy, not a sandbox or an immutable security boundary:
+workflow definitions themselves must be reviewed, and GitHub's repository permission and
+workflow-approval settings remain operator-owned controls. Do not use `pull_request_target`
+to execute a contributor's checkout with elevated authority.
+
+## Reuse the result
+
+Open the package job's `package-evidence-*` artifact. Start with `historical-strong-summary.md`,
+then inspect the corresponding manifest and `historical-provenance.json`. Run:
+
+```sh
+assertledger replay historical-strong-manifest.json --json
+```
+
+`historical-checkout-preserved.json` records the unchanged source files, index hash and HEAD.
+The weak and generic-crash cases must be rejected, with valid replay. These results prove
+the observed supported case; they do not authenticate an arbitrary evidence producer.
+
+Keep release evidence outside the temporary CI retention window when publishing a version.
+Never upload private proof-policy copies, credentials or unrelated workspace artifacts.

package/docs/client-connections.md

@@ -0,0 +1,61 @@
+# Project-local client connections
+
+AssertLedger can prepare a read-only MCP connection and install its packaged skill inside one
+repository. Run these commands from the installed package after `dist/cli.js` has been built.
+
+## Preview first
+
+`connect` and `disconnect` are previews unless `--write` is present. A connection preview lists
+every managed path and prints the complete planned contents between explicit delimiters. A removal
+preview lists the paths that would be checked. Neither preview changes the repository.
+
+```console
+assertledger connect . --client codex
+assertledger connect . --client claude-code
+assertledger disconnect . --client codex
+```
+
+Use `--write` only after reviewing the paths:
+
+```console
+assertledger connect . --client codex --write
+assertledger disconnect . --client codex --write
+```
+
+The operation is idempotent. Reinstalling identical artifacts reports `UNCHANGED`; removing an
+already absent installation reports `ABSENT`.
+
+## Managed artifacts
+
+| Client | MCP configuration | Packaged skill |
+| --- | --- | --- |
+| Codex | `.codex/config.toml` | `.agents/skills/assertledger/SKILL.md` |
+| Claude Code | `.mcp.json` | `.claude/skills/assertledger/SKILL.md` |
+
+The skill is copied byte-for-byte from the versioned `integrations/skill/SKILL.md` included in the
+installed AssertLedger package, including its frontmatter.
+
+Both configurations start `assertledger mcp --root <canonical-repository-root>`. The default server
+is read-only. Installing a connection does not authorize candidate execution, trust the repository,
+or reload the client; those remain explicit operator actions.
+
+AssertLedger creates a managed file only when it is absent. If any target already contains different
+content, the complete operation reports `CONFLICT` before writing anything. Linked paths,
+directories in place of files, and other non-regular targets are refused.
+
+`disconnect --write` removes only files that still match the exact bytes shipped or generated by the
+current AssertLedger installation. If a person or another tool changed either file, the complete
+removal reports `CONFLICT` and leaves every artifact in place. Directories are never removed.
+
+## Generic MCP descriptor
+
+Other MCP clients can request a transport descriptor:
+
+```console
+assertledger connect . --client mcp
+```
+
+The command prints a JSON object with `transport`, `command`, `args`, and `cwd`. AssertLedger does not
+write this descriptor because MCP clients do not share a universal project configuration path or
+file format. Copy the fields into the client-specific configuration after checking that client's
+documentation.

package/docs/conformance-v1.md

@@ -0,0 +1,72 @@
+# AssertLedger conformance bundle v1
+
+`conformance/v1/` is a checked-in compatibility oracle. It contains autonomous JSON inputs and
+complete expected JSON outputs for canonicalization, evidence decisions and replay, Profile v1,
+and Benchmark v1. The bundle includes positive behavior and negative security witnesses.
+
+The published npm package includes this static bundle for inspection and interoperability. The
+maintainer commands below require a source checkout with development dependencies; package scripts
+are repository-maintenance metadata, not an installed-package verification API.
+
+`pnpm run check:conformance` never generates fixtures. It first verifies the exact file set, every
+raw file SHA-256, and this root digest construction over ordinally sorted portable paths:
+
+```text
+SHA256(path + NUL + "sha256:" + raw-hex-digest + newline)
+```
+
+It then verifies the raw SHA-256 and `$id` of all 34 published schemas directly from `schemas/`,
+strictly parses `bundle.json`, dispatches an explicit operation allowlist to public AssertLedger APIs,
+and deep-compares every complete expected output. Additional assertions ensure compilation,
+collection, timeout, process-crash, infrastructure-error, and no-test-discovered outcomes never
+become target kills, and that re-sealed semantic forgeries remain invalid even when their public
+digest rails are true.
+
+## Negative witness runner
+
+`pnpm run witness:conformance` exercises the checker against seven mutations in an OS-temporary copy,
+never against the checked-in candidate. It first proves the copied oracle green, then verifies that:
+
+1. changing one fixture byte fails the raw-file lock; and
+2. replacing each of COMPILE_FAILURE, COLLECTION_FAILURE, TIMEOUT, PROCESS_CRASH, INFRA_ERROR, and
+   NO_TEST_DISCOVERED, together with its expected output, with VERIFIED semantics still fails the
+   manually written non-kill assertion, even after the temporary raw locks and root are resealed.
+
+The runner recreates the temporary copy between mutants, verifies a final green run, removes the
+temporary directory, and emits one JSON receipt containing the before/after raw digests, red and
+green exit codes, and output digests. It rejects any mutation target inside the repository. Because
+the runner is deliberately mutating and more expensive, it is an explicit audit command and is not
+part of `pnpm check`.
+
+## Maintainer regeneration
+
+The generator requires an explicit output directory and normally writes only to a temporary or
+review directory:
+
+```sh
+pnpm exec tsx scripts/generate-conformance-v1.ts --output-dir ./tmp/conformance-candidate
+```
+
+It refuses `conformance/v1` unless `--maintainer-allow-canonical` is present and never writes
+`scripts/conformance-v1-lock.ts`. Updating the public oracle therefore requires an intentional
+sequence:
+
+1. generate into a temporary directory and review the semantic delta;
+2. obtain a fresh proof-integrity review of changed operations and witnesses;
+3. explicitly regenerate the canonical directory with the maintainer flag;
+4. format the final JSON bytes;
+5. independently calculate and manually update raw file hashes, the root digest, and locked public
+   decision/artifact/profile/benchmark digests;
+6. run `pnpm check` and review the final aggregate diff.
+
+Any fixture or lock change is a public compatibility migration and must be documented. Do not
+accept a regenerated lock merely because the new checker is green: the checked-in oracle is an
+initial assumption, not an independent source of truth.
+
+## Scope and non-claims
+
+The bundle establishes deterministic compatibility with these checked-in examples and preserves
+named negative witnesses. It does not prove that the initial expected outputs are correct, that all
+semantic branches are covered, that execution evidence is truthful, or that a self-modifying
+change deserves acceptance. A fresh human or independent proof audit remains required whenever
+the fixtures, lock, checker, schemas, digest projections, or decision semantics change.

package/docs/decisions/0001-typescript-runtime.md

@@ -0,0 +1,24 @@
+# ADR 0001: TypeScript runtime for the first vertical release
+
+Status: accepted for v0.1
+
+## Decision
+
+Implement the first complete AssertLedger release in strict TypeScript on maintained Node.js releases.
+
+## Rationale
+
+The first release must deliver a pure decision core, JSON schemas, process orchestration, SDK, CLI,
+and current MCP integration together. TypeScript makes those integration surfaces directly usable by
+agent harnesses while preserving a strict protocol boundary.
+
+Rust would improve native distribution and OS process control. The schema and CLI protocols are
+therefore versioned so a native orchestrator can replace the Node implementation without moving gate
+authority or changing consumers.
+
+## Consequences
+
+- Node.js 22.15 or newer is a runtime dependency.
+- `trusted-local` process-tree termination is best effort, especially on Windows.
+- The core remains I/O-free and portable at the algorithmic level.
+- A future Rust backend must prove byte-compatible canonical decisions with shared fixtures.