assertledger 1.1.1 → 1.2.0

package/docs/developer-experience.md

@@ -37,11 +37,13 @@ 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.
+`testforge_doctor` alias) with `{ "root": "..." }`, plus optional `"exclude"` entry names that follow
+the `--exclude` rules; an empty array replaces the configured list (see
+[repository initialization](repository-init.md)). 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

package/docs/distribution.md

@@ -10,8 +10,8 @@ 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 checks the advertised schemas, conformance bundle, integration skill, Bun assertion
+helper, callback preload and driver, 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.
@@ -26,7 +26,12 @@ 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`.
+CI runs this smoke on Windows, Linux and macOS with Node 22.15.0 and 24 plus pinned Bun 1.4.2,
+alongside `pnpm check`.
+The verification matrix installs Bun 1.4.2 on Windows, Linux, and macOS and executes the
+real Bun campaign and its negative witnesses. The package smoke also runs a Bun v3 campaign
+and replay through the freshly installed CLI and checks the installed `assertledger/bun` export
+and types.
 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

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/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

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;

package/integrations/bun/assertions.mjs

@@ -0,0 +1,25 @@
+const ASSERTION_ERROR_NAME = "AssertLedgerBunAssertionError";
+const ASSERTION_ERROR_MESSAGE = "AssertLedger assertSame failed";
+const issuedErrors = new WeakSet();
+const addIssuedError = WeakSet.prototype.add.bind(issuedErrors);
+const hasIssuedError = WeakSet.prototype.has.bind(issuedErrors);
+
+class AssertLedgerBunAssertionError extends Error {
+  constructor() {
+    super(ASSERTION_ERROR_MESSAGE);
+    this.name = ASSERTION_ERROR_NAME;
+  }
+}
+
+export function assertSame(actual, expected) {
+  if (!Object.is(actual, expected)) {
+    const error = new AssertLedgerBunAssertionError();
+    addIssuedError(error);
+    throw error;
+  }
+}
+
+/** @internal Identifies an error instance issued by this helper. */
+export function isAssertSameFailure(error) {
+  return typeof error === "object" && error !== null && hasIssuedError(error);
+}

package/integrations/bun/driver.d.mts

@@ -0,0 +1,27 @@
+export interface BunInstrumentedResult {
+  protocolVersion: "1.0.0";
+  outcome:
+    | "PASS"
+    | "ASSERTION_FAILURE"
+    | "PROCESS_CRASH"
+    | "TIMEOUT"
+    | "INFRA_ERROR"
+    | "NO_TEST_DISCOVERED";
+  testsDiscovered: number;
+  candidateTestsDiscovered: number;
+  attributed: boolean;
+}
+
+export type BunTestEvent =
+  | { kind: "found"; id: string; file: string }
+  | { kind: "end"; id: string; status: "pass" | "fail"; owned: boolean }
+  | { kind: "hook-error" };
+
+export function classifyBunInstrumentedEvidence(
+  events: readonly BunTestEvent[] | undefined,
+  junit: { tests: number; failures: number; skipped: number } | undefined,
+  baseFiles: ReadonlySet<string>,
+  candidateFiles: ReadonlySet<string>,
+  exitCode: number | null,
+  operationalError?: boolean,
+): BunInstrumentedResult;