@tachikomagundam/abathur 0.1.0

package/dist/test/worktree.test.js

@@ -0,0 +1,198 @@
+// src/core/worktree.ts acceptance pins (todo 3) — plan AC line 98 verbatim:
+// init → generation commit preserves the parent sha; two concurrent generations
+// coexist; after cleanup `git -C <repo> status --porcelain` shows no abathur
+// paths. Plus refusal/stale-state adversarial classes.
+import assert from "node:assert/strict";
+import { mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import * as os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { ExitSignal } from "../exit.js";
+import { cacheRoot, cleanupStale, fastForwardIncumbent, INCUMBENT_BRANCH, newGeneration, openGenome, sealGeneration, } from "../core/worktree.js";
+import { fixtureRepo, gitIn } from "./fixtures-wt.js";
+async function expectExit(code, pattern, action) {
+    try {
+        await action;
+    }
+    catch (e) {
+        assert.ok(e instanceof ExitSignal, `expected ExitSignal, got ${String(e)}`);
+        assert.equal(e.code, code);
+        assert.match(e.message, pattern);
+        return;
+    }
+    assert.fail(`expected rejection with exit ${code}`);
+}
+// ------------------------------------------------------------------ cacheRoot
+test("cacheRoot: XDG scheme, ~/.cache fallback, junk XDG ignored", () => {
+    assert.equal(cacheRoot({ XDG_CACHE_HOME: "/xdg" }), path.join("/xdg", "abathur", "worktrees"));
+    assert.equal(cacheRoot({ HOME: "/home/u" }), path.join("/home/u", ".cache", "abathur", "worktrees"));
+    assert.equal(cacheRoot({ XDG_CACHE_HOME: "relative/nope", HOME: "/home/u" }), path.join("/home/u", ".cache", "abathur", "worktrees"));
+    assert.equal(cacheRoot({}), path.join(os.homedir(), ".cache", "abathur", "worktrees"));
+});
+// ------------------------------------------------------------------ openGenome
+test("openGenome: clean base reports head + branch, no dirtiness notices", async (t) => {
+    const fx = await fixtureRepo(t);
+    const opened = await openGenome(fx.repo, [], { env: fx.env });
+    assert.equal(await realpath(opened.repoPath), await realpath(fx.repo));
+    assert.equal(opened.headCommit, fx.head);
+    assert.equal(opened.branch, "main");
+    assert.deepEqual(opened.dirtyWorktree, []);
+});
+test("openGenome: dirty TARGET path refuses with exit 1; unrelated dirt becomes notices", async (t) => {
+    const fx = await fixtureRepo(t);
+    await writeFile(path.join(fx.repo, "bench", "run.sh"), "# drifted\n");
+    await expectExit(1, /bench\/run\.sh/, openGenome(fx.repo, ["bench"], { env: fx.env }));
+    await expectExit(1, /bench\/run\.sh/, openGenome(fx.repo, [path.join(fx.repo, "bench")], { env: fx.env }));
+    // untracked file inside the target scope is dirty too
+    await rm(path.join(fx.repo, "bench", "run.sh"));
+    await gitIn(fx.repo, "checkout", "-q", "--", "bench/run.sh");
+    await writeFile(path.join(fx.repo, "bench", "scratch.tmp"), "u");
+    await expectExit(1, /bench\/scratch\.tmp/, openGenome(fx.repo, ["bench"], { env: fx.env }));
+    await rm(path.join(fx.repo, "bench", "scratch.tmp"));
+    // same dirtiness OUTSIDE the target scope: not a refusal, a ledger notice
+    await writeFile(path.join(fx.repo, "a.txt"), "dirty elsewhere\n");
+    const opened = await openGenome(fx.repo, ["bench"], { env: fx.env });
+    assert.equal(opened.dirtyWorktree.length, 1);
+    const notice = opened.dirtyWorktree[0];
+    assert.ok(notice !== undefined && notice.file === "a.txt" && notice.xy.length === 2);
+});
+test("openGenome: absent repo, non-git dir, empty repo and bare repo all block exit 1", async (t) => {
+    const fx = await fixtureRepo(t);
+    await expectExit(1, /not found/, openGenome(path.join(fx.root, "nope"), [], { env: fx.env }));
+    const plain = path.join(fx.root, "plain");
+    await mkdir(plain);
+    await expectExit(1, /not a git repository/, openGenome(plain, [], { env: fx.env }));
+    const empty = path.join(fx.root, "empty");
+    await mkdir(empty);
+    await gitIn(empty, "init", "-q", "-b", "main");
+    await expectExit(1, /no commits/, openGenome(empty, [], { env: fx.env }));
+    const bare = path.join(fx.root, "bare");
+    await gitIn(fx.root, "clone", "-q", "--bare", fx.repo, bare);
+    await expectExit(1, /bare/, openGenome(bare, [], { env: fx.env }));
+});
+// ------------------------------------------------- newGeneration + seal lifecycle
+test("lifecycle AC: generation commit preserves parent sha; genome branch untouched", async (t) => {
+    const fx = await fixtureRepo(t);
+    const genome = { repoPath: fx.repo, genomeFp: fx.fp };
+    const gen = await newGeneration(genome, fx.head, "g-100-alpha", { env: fx.env });
+    assert.ok(gen.worktreePath.startsWith(path.join(fx.env.XDG_CACHE_HOME, "abathur", "worktrees", fx.fp)));
+    assert.equal(gen.parentCommit, fx.head);
+    assert.equal(await gitIn(gen.worktreePath, "rev-parse", "HEAD"), fx.head);
+    assert.equal(await readFileStr(path.join(gen.worktreePath, "bench", "run.sh")), "echo bench\n");
+    await writeFile(path.join(gen.worktreePath, "mutant.txt"), "improved\n");
+    const sealed = await sealGeneration(genome, "g-100-alpha", "gen: tune bench mutant", {
+        env: fx.env,
+    });
+    assert.match(sealed.commitSha, /^[0-9a-f]{40}$/);
+    assert.match(sealed.treeSha, /^[0-9a-f]{40}$/);
+    // parent sha preserved through the seal
+    assert.equal(await gitIn(fx.repo, "rev-parse", `${sealed.commitSha}^`), fx.head);
+    assert.equal(await gitIn(fx.repo, "rev-parse", `${sealed.commitSha}^{tree}`), sealed.treeSha);
+    // the genome repo's checked-out branch was NEVER touched
+    assert.equal(await gitIn(fx.repo, "rev-parse", "HEAD"), fx.head);
+    assert.equal(await gitIn(fx.repo, "rev-parse", "--abbrev-ref", "HEAD"), "main");
+    assert.equal(await gitIn(fx.repo, "status", "--porcelain"), "");
+});
+test("AC: two concurrent generations' worktrees coexist; chain from sealed sha", async (t) => {
+    const fx = await fixtureRepo(t);
+    const genome = { repoPath: fx.repo, genomeFp: fx.fp };
+    const a = await newGeneration(genome, fx.head, "g-100-a", { env: fx.env });
+    const b = await newGeneration(genome, fx.head, "g-100-b", { env: fx.env });
+    assert.notEqual(a.worktreePath, b.worktreePath);
+    await writeFile(path.join(a.worktreePath, "x.txt"), "a");
+    const sealedA = await sealGeneration(genome, "g-100-a", "gen a", { env: fx.env });
+    // sealedA lives only in the shared object db via a detached worktree
+    assert.equal(await gitIn(b.worktreePath, "rev-parse", "HEAD"), fx.head); // untouched
+    const c = await newGeneration(genome, sealedA.commitSha, "g-101-c", { env: fx.env });
+    assert.equal(c.parentCommit, sealedA.commitSha);
+    assert.equal((await stat(path.join(c.worktreePath, "x.txt"))).isFile(), true);
+    const listed = await gitIn(fx.repo, "worktree", "list", "--porcelain");
+    // main + a + b + c — all four registry entries coexist
+    assert.equal(listed.split("\n").filter((l) => l.startsWith("worktree ")).length, 4);
+});
+test("sealGeneration: unknown generation and no-change seal both block exit 1", async (t) => {
+    const fx = await fixtureRepo(t);
+    const genome = { repoPath: fx.repo, genomeFp: fx.fp };
+    await expectExit(1, /not found/, sealGeneration(genome, "g-nope", "ghost", { env: fx.env }));
+    await newGeneration(genome, fx.head, "g-100-quiet", { env: fx.env });
+    await expectExit(1, /nothing/, sealGeneration(genome, "g-100-quiet", "no changes", { env: fx.env }));
+});
+// ------------------------------------------------------------------ cleanupStale
+test("cleanupStale AC: prunes generations+snapshots, survives double-run and dead registry entries", async (t) => {
+    const fx = await fixtureRepo(t);
+    const genome = { repoPath: fx.repo, genomeFp: fx.fp };
+    const gen = await newGeneration(genome, fx.head, "g-100-x", { env: fx.env });
+    await writeFile(path.join(gen.worktreePath, "x.txt"), "x");
+    await sealGeneration(genome, "g-100-x", "gen x", { env: fx.env });
+    const dead = await newGeneration(genome, fx.head, "g-100-dead", { env: fx.env });
+    await rm(dead.worktreePath, { recursive: true, force: true }); // crash simulation: dir gone, registry alive
+    const first = await cleanupStale(genome, 0, { env: fx.env });
+    assert.ok(first.removed.includes(gen.worktreePath));
+    assert.equal(first.kept.length, 0);
+    // idempotent second run (stale-state adversarial class)
+    const second = await cleanupStale(genome, 0, { env: fx.env });
+    assert.deepEqual(second.removed, []);
+    // dead registry entry pruned: only the main worktree remains, re-add with same id works
+    const listed = await gitIn(fx.repo, "worktree", "list", "--porcelain");
+    assert.equal(listed.split("\n").filter((l) => l.startsWith("worktree ")).length, 1);
+    const readd = await newGeneration(genome, fx.head, "g-100-dead", { env: fx.env });
+    assert.equal(await gitIn(readd.worktreePath, "rev-parse", "HEAD"), fx.head);
+    const report = await cleanupStale(genome, 0, { env: fx.env });
+    assert.ok(report.removed.length >= 1);
+    // AC verbatim: no abathur paths in the genome repo status, ever
+    assert.equal(await gitIn(fx.repo, "status", "--porcelain"), "");
+    await assert.rejects(stat(path.join(fx.env.XDG_CACHE_HOME, "abathur", "worktrees", fx.fp, "g-100-x")));
+});
+test("cleanupStale: fresh generations are KEPT when olderThanDays does not cover them", async (t) => {
+    const fx = await fixtureRepo(t);
+    const genome = { repoPath: fx.repo, genomeFp: fx.fp };
+    const gen = await newGeneration(genome, fx.head, "g-100-keep", { env: fx.env });
+    const r = await cleanupStale(genome, 7, { env: fx.env });
+    assert.deepEqual(r.removed, []);
+    assert.deepEqual(r.kept, [gen.worktreePath]);
+});
+test("cleanupStale: negative/NaN olderThanDays is a tool error (exit 2)", async (t) => {
+    const fx = await fixtureRepo(t);
+    const genome = { repoPath: fx.repo, genomeFp: fx.fp };
+    await expectExit(2, /olderThanDays/, cleanupStale(genome, Number.NaN, { env: fx.env }));
+    await expectExit(2, /olderThanDays/, cleanupStale(genome, -1, { env: fx.env }));
+});
+// ---------------------------------------------------------- incumbent discipline
+test("fastForwardIncumbent: creates, ff-forwards, refuses rewind and checked-out branch (never force)", async (t) => {
+    const fx = await fixtureRepo(t);
+    const genome = { repoPath: fx.repo, genomeFp: fx.fp };
+    const gen = await newGeneration(genome, fx.head, "g-100-p", { env: fx.env });
+    await writeFile(path.join(gen.worktreePath, "promote.txt"), "p");
+    const sealed = await sealGeneration(genome, "g-100-p", "gen p", { env: fx.env });
+    const made = await fastForwardIncumbent(genome, sealed.commitSha, { env: fx.env });
+    assert.equal(made.fromSha, null);
+    assert.equal(made.branch, INCUMBENT_BRANCH);
+    assert.equal(await gitIn(fx.repo, "rev-parse", INCUMBENT_BRANCH), sealed.commitSha);
+    // no-op when already there
+    const noop = await fastForwardIncumbent(genome, sealed.commitSha, { env: fx.env });
+    assert.equal(noop.fromSha, sealed.commitSha);
+    // rewind is a refusal, and the ref does not move
+    await expectExit(1, /ancestor/, fastForwardIncumbent(genome, fx.head, { env: fx.env }));
+    assert.equal(await gitIn(fx.repo, "rev-parse", INCUMBENT_BRANCH), sealed.commitSha);
+    // forward again works
+    const gen2 = await newGeneration(genome, sealed.commitSha, "g-101-q", { env: fx.env });
+    await writeFile(path.join(gen2.worktreePath, "more.txt"), "q");
+    const sealed2 = await sealGeneration(genome, "g-101-q", "gen q", { env: fx.env });
+    const moved = await fastForwardIncumbent(genome, sealed2.commitSha, { env: fx.env });
+    assert.equal(moved.fromSha, sealed.commitSha);
+    assert.equal(moved.toSha, sealed2.commitSha);
+    // checked-out incumbent must not be moved while in use
+    await gitIn(fx.repo, "checkout", "-q", INCUMBENT_BRANCH);
+    await expectExit(1, /checked out/, fastForwardIncumbent(genome, fx.head, { env: fx.env }));
+});
+// ---------------------------------------------------------------- unsafe inputs
+test("unsafe genomeFp/genId/parentCommit are tool errors (exit 2), never spawned to git", async (t) => {
+    const fx = await fixtureRepo(t);
+    await expectExit(2, /fingerprint/, newGeneration({ repoPath: fx.repo, genomeFp: "../evil" }, fx.head, "g-1", { env: fx.env }));
+    await expectExit(2, /generation id/, newGeneration({ repoPath: fx.repo, genomeFp: "ok" }, fx.head, "g 1;rm", { env: fx.env }));
+    await expectExit(2, /generation id/, newGeneration({ repoPath: fx.repo, genomeFp: "ok" }, fx.head, "-x", { env: fx.env }));
+    await expectExit(2, /revision/, newGeneration({ repoPath: fx.repo, genomeFp: "ok" }, "--help", "g-1", { env: fx.env }));
+});
+async function readFileStr(p) {
+    return readFile(p, "utf8");
+}

package/dist/util/freeze.js

@@ -0,0 +1,30 @@
+// Mode-bit walkers for read-only commit snapshots (todo 3). freezeTree strips
+// write bits recursively (files 0o444/0o555, dirs 0o555); thawTree restores
+// writability so rm -rf can collect a frozen tree. Linux cannot lchmod, so
+// symlinks are skipped — the enclosing dir's 0o555 already forbids unlink/create.
+import { chmod, lstat, readdir } from "node:fs/promises";
+import path from "node:path";
+async function walk(dir, dirMode, fileMode) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            continue;
+        const p = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walk(p, dirMode, fileMode);
+            await chmod(p, dirMode);
+        }
+        else {
+            const st = await lstat(p);
+            await chmod(p, fileMode(st.mode));
+        }
+    }
+    await chmod(dir, dirMode);
+}
+/** Strip all write bits under `root` (root itself included). */
+export async function freezeTree(root) {
+    await walk(root, 0o555, (mode) => 0o444 | (mode & 0o111));
+}
+/** Re-add owner write bits under `root` (root itself included). */
+export async function thawTree(root) {
+    await walk(root, 0o755, (mode) => 0o644 | (mode & 0o111));
+}

package/dist/util/git.js

@@ -0,0 +1,85 @@
+// Thin git wrapper (todo 3 contract): execFile('git', arrayArgs) ONLY — paths are
+// passed as argv elements and never reach a shell, so metacharacters in repo or
+// worktree paths cannot inject commands. No push, no ref-mutating shortcuts
+// live here; callers pass the exact argv they need.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+export class GitError extends Error {
+    kind;
+    args;
+    exitCode;
+    stderr;
+    constructor(kind, args, exitCode, stderr, message) {
+        super(message);
+        this.kind = kind;
+        this.args = args;
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = "GitError";
+    }
+}
+function isExecError(err) {
+    return err instanceof Error;
+}
+function firstLine(text) {
+    const line = text.split("\n", 1)[0] ?? "";
+    return line.trim();
+}
+function describe(args) {
+    return `git ${args.join(" ")}`;
+}
+function classify(args, cause) {
+    if (isExecError(cause)) {
+        const stderr = cause.stderr ?? "";
+        if (cause.killed === true) {
+            return new GitError("timeout", args, null, stderr, `${describe(args)} timed out and was killed (signal ${cause.signal ?? "SIGKILL"})`);
+        }
+        if (cause.code === "ENOENT") {
+            return new GitError("spawn", args, null, stderr, `${describe(args)}: cannot spawn git binary: ${firstLine(cause.message)}`);
+        }
+        if (typeof cause.code === "number") {
+            return new GitError("failed", args, cause.code, stderr, `${describe(args)} exited ${cause.code}: ${firstLine(stderr) || firstLine(cause.message)}`);
+        }
+    }
+    const why = cause instanceof Error ? firstLine(cause.message) : String(cause);
+    return new GitError("spawn", args, null, "", `${describe(args)} failed to run: ${why}`);
+}
+async function spawnGit(args, opts) {
+    try {
+        const { stdout, stderr } = await execFileAsync(opts.bin ?? "git", [...args], {
+            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+            timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+            maxBuffer: MAX_BUFFER_BYTES,
+            env: { ...process.env, LC_ALL: "C" },
+        });
+        return { stdout, stderr };
+    }
+    catch (cause) {
+        throw classify(args, cause);
+    }
+}
+/** Run git; reject with GitError on non-zero exit, timeout, or spawn failure. */
+export async function git(args, opts = {}) {
+    return spawnGit(args, opts);
+}
+/**
+ * Like git(), but a plain non-zero *exit* is a result (ok: false) instead of a
+ * rejection — for predicates like `merge-base --is-ancestor`. Timeouts and
+ * spawn failures still reject (they are not answers, only missing ones).
+ */
+export async function tryGit(args, opts = {}) {
+    try {
+        const result = await spawnGit(args, opts);
+        return { ok: true, ...result };
+    }
+    catch (cause) {
+        if (cause instanceof GitError && cause.kind === "failed") {
+            return { ok: false, error: cause };
+        }
+        throw cause;
+    }
+}

package/docs/federation.md

@@ -0,0 +1,184 @@
+# Federation — the bundle format and the graft contract
+
+v1 federation is a **file format plus local tools**. A bundle is a `.tgz` you
+carry by any means you like; `bundle export`, `bundle inspect`, and `graft`
+run entirely offline. There are no signatures, no trust, no discovery, no
+transport, no auto-merge, and no auto-promotion — the verification model
+replaces all of those with byte-equality. Schemas and gate behavior below are
+field-for-field from `src/core/bundle-manifest.ts`, `src/core/bundle-inspect.ts`,
+`src/core/graft.ts`, `src/core/graft-gates.ts`, `src/core/graft-rebench.ts`,
+and `src/core/graft-support.ts`.
+
+## Bundle v1 — container layout
+
+Tarball name: `abathur-<fp16>-<genId>.bundle.tgz` (`<fp16>` = first 16 hex of
+the genome fingerprint). Generation content is read from **git objects**
+(`git archive`) at export time, never from a working tree. Members:
+
+| Member | Content |
+|---|---|
+| `manifest.json` | the v1 manifest below — the only file that pins everything else |
+| `README.md` | human summary: fingerprint, gen list, primary commit/tree, verdict, rationale |
+| `lineage.json` | per-generation ledger-row summaries (`LineageEntry`: genId, parent, commitSha, treeSha, verdict, rationale) |
+| `patch.diff` | unified diff primary parent → primary commit |
+| `trees/<genId>/**` | full contained tree per generation — exempt from masking (byte truth) |
+| `evidence/<genId>/<runId>.jsonl` | bench transcripts — **train units only, structurally never val**, and mask-scanned |
+
+The export is **deterministic**: re-exporting an unchanged ledger produces a
+byte-identical tarball (proven in packaging evidence: identical sha256 across
+two exports). Nothing about a bundle is authoritative until re-verified —
+`bundle inspect` re-hashes every pinned member from the contained bytes.
+
+### Masking (leak gate)
+
+Evidence and manifest strings pass a fail-closed secret-scan before the
+tarball is written, and `inspect` re-runs it over the final bytes:
+
+- Always masked → placeholder: this machine's `HOME` → `<HOME>`, the genome's
+  `repoPath` → `<GENOME>`.
+- Extended per genome by `spec.bundle.maskLiterals` → `<MASKED-n>` (indexed by
+  list order).
+- `trees/**` members are exempt: they are the byte-truth content, and sealing
+  plus review keep machine literals out of genomes by construction.
+- A leak on export refuses the write (exit 1, nothing produced); a leak found
+  by `inspect` is a blocked verdict with `member:line` and snippet.
+
+## Bundle v1 — `manifest.json` schema (strict object; unknown keys are rejected)
+
+Key insertion order IS the serialized byte order (pins determinism).
+
+| Field | Type / shape | Meaning |
+|---|---|---|
+| `schema_version` | literal `1` | format version |
+| `digest_algo` | string | must be `sha256-canonical-v1`; any other value → inspect exit 2 (cannot answer — wrong tool for the format) |
+| `genome` | `{ label: string≥1, fingerprint: sha256-hex(64) }` | which genome this lineage belongs to; identity is the fingerprint, the label rides along for humans |
+| `parent` | git commit id (hex 7–64) | primary parent commit |
+| `benchDigest` | sha256-hex(64) | digest of the bench SURFACE for the primary tree under this spec (`benchDigestFor`) — what was measured, not the score |
+| `benchProvenance` | object, all fields nullable | scoring conditions, see below |
+| `budgetCounters` | `{ candidates, modelCalls, tokens, wallS }` | budget the peer spent producing this lineage |
+| `stats` | `{ matrix: unitMatrixRow[], verdict: "nominated"\|"culled"\|"indeterminate"\|"inconclusive"\|null }` | the peer's **claim** — per-unit rows + final verdict; never trusted, always re-benched |
+| `sealedGlobs` | string[] | copy of `kernel.immutableGlobs` at export |
+| `files` | `[{ path, sha256, len }]`, ≥1 | every other member, pinned by hash and length; `manifest.json` never pins itself |
+| `rationale` | string | primary generation's rationale |
+| `frictionDigests` | string[] | friction-digest ids that motivated this lineage, for cross-instance learning |
+
+`benchProvenance` fields (the scoring-provenance subset):
+
+| Field | Derivation (`deriveBenchProvenance`) | Toy genome value |
+|---|---|---|
+| `opencodeVersion` | from the bench row's version probes (`bin == "opencode"`) | `null` |
+| `agentModel` | `spec.bench.agentModel` | engine-driven only |
+| `adapterConfigDigest` | fingerprint of `{adapterIface: abathur-bench-adapter-v1, benchType, graderCommand, judgeCommand, resetCommand, runCommand, seedCommand, timeoutS}` | digest over the inert descriptor commands |
+| `fixtureSeedId` | `fingerprint({seedCommand})` | `null` when no seedCommand |
+| `judgeModel` | `spec.bench.judgeModel` | engine-driven only |
+| `mutatorModel` | constant `null` in v1 | `null` — honest absence, never a guess |
+| `nRepeats` | the peer row's reps | e.g. 2 |
+| `statsConfigDigest` | `fingerprint(bench.stats)` | digest of the stats gates |
+
+Fields a bench kind genuinely does not have are explicit `null`s — the manifest
+never fabricates provenance to look comparable.
+
+## `bundle inspect` — gate order and exit codes
+
+`inspect` answers "is this bundle internally honest", from contained bytes only:
+
+1. read/gunzip container — garbage → **exit 2**
+2. parse + schema-validate `manifest.json` — invalid → **exit 2**; unknown
+   `digest_algo` → **exit 2**
+3. re-hash every pinned member — missing member, sha or length mismatch, or
+   unexpected member → **exit 1**; a `path` escaping the bundle (absolute,
+   `..`, backslash, NUL) is rejected at tar-read → **exit 2**
+4. `patch.diff` present (it is schema-pinned content) — missing → **exit 1**
+5. genome check — no `trees/<genId>` members at all → **exit 2**; contained
+   spec's fingerprint or label disagreeing with `manifest.genome` → **exit 1**
+6. recompute `benchDigest` from the contained primary tree + contained spec —
+   mismatch → **exit 1**
+7. val exclusion — any `evidence/` row for a val-split unit → **exit 1**
+8. mask re-scan over manifest + evidence — leak → **exit 1**
+
+On success: exit 0 with a member count, re-hash count, and the primary verdict.
+
+## `graft` — four steps, six decisions
+
+The graft target is a bundle plus a locally registered `--genome label`. Every
+step happens **before** the next; the first three never create a worktree.
+
+1. **Full inspect** (above). Integrity failure is a decision, not a
+   negotiation: `quarantined` booked to the local ledger, exit 1.
+   Container garbage (exit-2 class) leaves no state — a refusal line only.
+2. **Registration + duplicate check**: genome not registered locally →
+   `pending-bench`: an entry under `<configDir>/graft-queue/<bundle-sha256>.json`,
+   exit 1, zero bench runs. Repair (register the genome), then re-run `graft` —
+   pending rows are explicitly non-terminal. On a registered genome the ledger
+   is then checked for a prior terminal decision on this exact bundle + genome:
+   any terminal row (`quarantined`/`nominated`/`culled`/`indeterminate`/
+   `inconclusive`) → refusal, exit 1 ("export a newer bundle; re-running never
+   re-benches").
+3. **Byte-exact gates**, in order; any miss → `quarantined` (exit 1, one
+   `graft_import` ledger row naming the failing gate, no worktree, no bench):
+   - gate 1 genome fingerprint: local spec must fingerprint **byte-equal** to
+     `manifest.genome.fingerprint`;
+   - gate 2 benchDigest: recomputed from the contained primary tree under the
+     LOCAL spec vs `manifest.benchDigest`;
+   - gate 3 scoring provenance: the five recomputable fields
+     (`agentModel, judgeModel, statsConfigDigest, adapterConfigDigest,
+     fixtureSeedId`) must agree **three ways** — manifest claim vs what the
+     bundle's own contained spec derives vs local — and `opencodeVersion` must
+     be semver-equal to the local incumbent bench row's version (both-null is
+     the honest equality for toy; unparsable is incomparable);
+   - gate 4 `requires[]` probes via the todo-6 machinery (argv spawn, 30 s cap,
+     fixture genomes additionally through the engine/minVersion probe).
+     Probe failure → `pending-bench` (exit 2 this time — repair setup, re-run).
+4. **Local re-bench** — only if all gates passed. A fresh worktree is created
+   from the LOCAL incumbent HEAD, the bundle's tree bytes are applied as
+   byte-truth (`applyBundleTree`: overwrite every member, remove tracked files
+   the bundle lacks), and the candidate is benched at **LOCAL** reps
+   (`clampReps` under the local stats config) and **LOCAL** thresholds, under
+   the machine-local genome lock, inside the normal budget machinery. The todo-7
+   statistics gate decides. The bundle's scores never enter the math — they are
+   booked as `peerClaim` metadata in the single `graft_import` row.
+
+Decision table — the complete outcome surface:
+
+| Outcome | Trigger | Exit | Ledger / state |
+|---|---|---|---|
+| `nominated` | local re-bench passes all gates' stats | 0 | `graft_import` + generation row; waits for human `promote` — graft itself never promotes (`promote.ts` is structurally not imported) |
+| `culled` | local stats say no (peer claim irrelevant either way) | 1 | `graft_import` + generation row |
+| `indeterminate` | local stats degenerate (e.g. zero-variance) | 1 | `graft_import` + generation row |
+| `inconclusive` | local bench truncated by budget/timeout | 2 | `graft_import` + generation row — cannot-answer, never a fake pass |
+| `quarantined` | any gate 0–3 integrity/fingerprint/digest/provenance mismatch | 1 | exactly one `graft_import` row; **no worktree, no bench** |
+| `pending-bench` | genome unregistered (exit 1) or probes unmet (exit 2) | 1 / 2 | queue file under `<configDir>/graft-queue/` (+ row if a ledger exists); non-terminal by design |
+
+`graftGenId = fingerprint({ graft: bundleSha256, sourceGenome, parent })` — a
+grafted generation has a deterministic id derived from the bundle content, and
+the sealed row carries `commitSha`/`treeSha` of what was actually benched.
+
+## Honest limitation: env-bound genomes re-derive identity per machine
+
+Byte-equality is literal. A genome whose spec contains **resolved absolute
+paths** — the historian case, where the operator materializes
+`config/genomes/historian.example.jsonc` into a machine-specific
+`*.local.jsonc` — fingerprints over those bytes. Its fingerprint
+(on the orchestrator's paths: `2b2456be6cddcb91…`) and every digest derived
+from its spec (`benchDigest`, `adapterConfigDigest`) are therefore stable **per
+resolved path set**, not across machines. Grafting a historian bundle onto a
+peer whose local spec resolved to different paths fails gate 1 — quarantined,
+correctly: "same genome" for v1 means "byte-identical spec", and different
+paths can genuinely mean different fixture services.
+
+The escape hatch is the one abathur-self uses: keep the spec bytes
+machine-independent (e.g. the `${ABATHUR_SELF_REPO}` unresolved-literal
+`repoPath` pattern, resolved only at filesystem seams, `effectiveRepoPath` in
+`src/core/spec.ts`) and machine-neutral commands. Then the same spec
+fingerprints identically everywhere (`1913fcec…`) and graft works across
+machines as designed. What v1 will not do is pretend two differently-resolved
+genomes are comparable.
+
+## Out of scope (v1, explicitly)
+
+Bundle signing or any trust chain; discovery, transport, or sync protocols;
+merge of two incumbent branches; auto-promotion or any bypass flag
+(`--force` does not exist in the binary); noise-tolerance bands on digest
+equality. Every one of these, if ever built, must fit the invariant the whole
+design rests on: **a verdict exists only if it was recomputed locally from
+bytes that hash the same on both sides.**

package/docs/immutable-kernel.md

@@ -0,0 +1,87 @@
+# The Immutable Kernel — what self-evolution may and may not touch
+
+This is the human-facing contract of the shipped seed `genomes/abathur-self.jsonc`
+and of `src/core/evolve/self-overlay.ts` / `self-snapshot.ts`. The seed's header
+comments restate the same contract in spec-adjacent form; where they are terse,
+this document is the expansion. Registration is fail-closed by design: every
+seal glob must cover at least one real file (the `graders/**` contract directory
+satisfies that since todo 14), and the seed stays byte-stable — its `repoPath` is
+the unresolved literal `${ABATHUR_SELF_REPO}`, so the spec fingerprint
+(`1913fcec…`) is identical on every machine and the checkout only resolves at
+filesystem seams. Point that variable at a git checkout with `npm ci` done; unset
+exits 2, naming the variable.
+
+## The sealed set
+
+`kernel.immutableGlobs` on the abathur-self genome seals:
+
+| Pattern | Why it is sealed |
+|---|---|
+| `src/core/stats.ts` | the selection gate itself — nomination math, Bonferroni, budget verdicts |
+| `src/core/ledger.ts` | append-only evidence: friction queue + generation rows |
+| `src/core/ids.ts` | canonical JSON + fingerprints — the identity of every genome/row/tree |
+| `src/core/genome.ts` | registry semantics: registration, superset rule, fail-closed coverage |
+| `src/core/promote.ts` | the human-only gate: second sealed-path pass, CAS ref move, manifest regen |
+| `src/bench/toy.*`, `src/bench/fixture.*` | the bench adapters — how every score is produced |
+| `graders/**` | grader contract schemas — what "correct" means per bench |
+| `genomes/**` | every genome spec, including this seed and the toy-smoke fixtures |
+| `scripts/copy-assets.mjs`, `package.json`, `tsconfig.json` | the toolchain itself |
+
+Self cannot unseal: a candidate diff touching any sealed file is rejected at the
+path stage (`validateCandidate`), the kernel audit refuses runs against a drifted
+working tree (exit 1, before any state exists), and only the human `promote`
+command ever reseals the manifest — from the promoted tree, never the worktree.
+The sealed hashes live in a per-genome manifest under `<configDir>/kernels/`
+(written at registration, re-checked at every bench and `self-eval` entry);
+`abathur kernel audit <label>` compares that manifest against the working tree.
+
+**Consequence (accepted):** v1 self-evolution cannot change dependencies or
+build configuration. `package.json` and `tsconfig.json` ride outside the
+overlaid `src/**` and would otherwise slip into a promoted generation
+score-neutrally and silently reseal on installer re-add (plan round-2 #2).
+Toolchain changes are a human PR, not an evolution candidate.
+
+## Why tests run from a snapshot, not from the candidate
+
+Fitness-hack class (plan 11c, oracle Critical #1): if the candidate's own tree
+supplies the test suite, a candidate can delete or weaken the tests it is graded
+by and score better while getting worse. The self-bench therefore composes:
+
+1. **Trusted tree** = `snapshotCommit(incumbent)` — sealed kernel files, the
+   test suite (`src/test/**`), the golden-replay fixtures + expected digests,
+   and toolchain config, all read-only from the incumbent commit.
+2. **Overlay** = candidate `src/**` files matching no seal and not under
+   `src/test/**` (candidate test edits are dropped by the allowlist; deletions
+   are unrepresentable in a copy-only overlay, matching udiff v1's
+   modify/create-only contract).
+3. **Build** with the harness-pinned toolchain: the repo's own `tsc` against the
+   harness install's `node_modules` — never candidate-supplied build scripts,
+   never `npm ci`. Caps: build 180 s, suite 900 s, replay 120 s; a build timeout
+   is inconclusive, a suite/replay timeout scores nothing.
+4. **Score** = `node --test dist/test/**/*.test.js` over the overlaid build plus
+   the golden toy-replay digest (`selfbench/replay.mjs`, expected from the
+   TRUSTED copy). Pure incumbent-vs-incumbent is degenerate and forbidden; the
+   incumbent build is the baseline, candidates are the overlaid builds.
+
+The seed's two bench units make the goalposts concrete: `suite` (train) is
+`node --test dist/test/**/*.test.js` built from the overlaid candidate sources;
+`golden-replay` (val) replays `selfbench/replay.mjs` and compares the digest
+against `selfbench/expected.json` — taken from the TRUSTED copy, so a candidate
+cannot move the val goalpost it is measured against. Both units score binary per
+rep, which is why the seed pins `stats.halfWidth 0.05, minEffect 0, nReps 2..4`:
+a nomination means "candidate src passes the incumbent-pinned suite AND the
+golden digest holds, non-degenerately, across reps". A pure incumbent-vs-incumbent
+comparison is degenerate and forbidden; an overlay with no effective change is
+downgraded to `indeterminate` by the overlay-empty guard, never nominated.
+
+The candidate worktree's own tests are never executed, and the scorer is invoked
+with snapshot paths only — structurally, nothing in `self-eval`/`self-snapshot`
+imports `promote.ts`; `self-eval` reports fitness, the operator promotes.
+
+## Friction digest
+
+Every `run` appends structured `friction_digest` records to the global queue
+`<configDir>/friction.jsonl` (stalls, repeated rejections by stage, inconclusive
+causes, CLI errors). Records are schema-validated, strings are echo-sanitized
+and bounded, and digests covering val-unit runs carry counts/timings/status
+codes only — scenario text and assertion diffs can never enter the queue.

package/graders/historian/grader-core.d.mts

@@ -0,0 +1,53 @@
+// Type declarations for grader-core.mjs — the plan-185 scoring engine.
+// Runtime lives in the .mjs; this file is the compile-time contract.
+
+export type DimKey = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H";
+export type Bit = 0 | 1;
+export type FullDims = Readonly<Record<DimKey, Bit>>;
+export type WorthDims = Readonly<{ G: Bit; H: Bit; J: Bit }>;
+
+export interface CreatedPage {
+  readonly path: string;
+  readonly locale: string;
+  readonly title: string;
+  readonly content: string;
+}
+
+export interface Observation {
+  readonly scenarioNo: number;
+  readonly created: readonly CreatedPage[];
+  readonly updated: readonly CreatedPage[];
+  readonly moved: readonly { readonly from: string; readonly to: string }[];
+  readonly deletedFixturePaths: readonly string[];
+  readonly outside: {
+    readonly created: readonly string[];
+    readonly updated: readonly string[];
+    readonly deleted: readonly string[];
+  };
+  readonly indexUpdated: boolean;
+  readonly indexContent: string;
+  readonly livePaths: readonly string[];
+  readonly allPaths: readonly string[];
+  readonly backlinkBodies: ReadonlyArray<{ readonly path: string; readonly locale: string; readonly content: string }>;
+  readonly finalMessage: string;
+  readonly urlChecks: readonly { readonly url: string; readonly status: number }[];
+}
+
+export interface UnitScore {
+  readonly score: number;
+  readonly pass: boolean;
+  readonly total: number;
+  readonly applicableWeight: number;
+}
+
+export type ScoredUnit = UnitScore & {
+  readonly dims: Readonly<Record<string, Bit>>;
+  readonly notes: readonly string[];
+};
+
+export const WEIGHTS: Readonly<Record<DimKey, number>>;
+
+export function computeDims(obs: Observation): FullDims;
+export function judgment(scenarioNo: number, created: readonly CreatedPage[], finalMessage: string): Bit;
+export function scoreFromDims(scenarioNo: number, dims: FullDims | WorthDims): UnitScore;
+export function scoreUnit(obs: Observation): ScoredUnit;