@tachikomagundam/abathur 0.1.0

package/dist/core/evolve/self-overlay.js

@@ -0,0 +1,213 @@
+// Low-level pieces of the snapshot-overlay self-bench (plan 157-164): clone a
+// frozen incumbent snapshot into a mutable build dir, decide + write the
+// candidate overlay, and run the three pinned-toolchain steps (build / suite /
+// replay) as argv children via runChild. NO promote authority, NO dynamic
+// imports — the candidate's code is only ever executed by CHILD processes inside
+// the snapshot; trusted files (sealed globs, src/test/**, selfbench/**) always
+// come from the incumbent snapshot, never from the candidate tree.
+import { cpSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { runChild } from "../../bench/adapter.js";
+import { cannotAnswer } from "../../exit.js";
+import { thawTree } from "../../util/freeze.js";
+import { snapshotCommit } from "../worktree.js";
+import { compileGlob } from "../glob.js";
+const OVERLAY_PREFIX = "src/";
+const TRUSTED_TEST_PREFIX = "src/test/";
+/** Relative posix paths of a tree (regular files only, symlinks skipped), sorted. */
+export function treePaths(root) {
+    const out = [];
+    const walk = (dir, rel) => {
+        for (const entry of readdirSync(dir).sort()) {
+            const abs = path.join(dir, entry);
+            const relPath = rel === "" ? entry : `${rel}/${entry}`;
+            const stat = lstatSync(abs);
+            if (stat.isDirectory())
+                walk(abs, relPath);
+            else if (stat.isFile())
+                out.push(relPath);
+        }
+    };
+    walk(root, "");
+    return out;
+}
+/**
+ * Overlay law (plan 11c): ONLY candidate src/** files matching no immutableGlob
+ * and not under src/test/** are copied over the snapshot. Candidate edits to
+ * src/test/** are DROPPED (the trusted suite scores every candidate); deletions
+ * are unrepresentable in a copy-only overlay (matching udiff v1's
+ * modify/create-only contract). Everything outside src/** is ignored.
+ */
+export function planOverlay(baseFiles, candidateFiles, spec) {
+    const globs = spec.kernel.immutableGlobs.map((glob) => compileGlob(glob));
+    const overlay = [];
+    const dropped = [];
+    for (const [relPath, content] of candidateFiles) {
+        if (!relPath.startsWith(OVERLAY_PREFIX))
+            continue;
+        if (baseFiles.get(relPath) === content)
+            continue; // unchanged bytes ride in the base clone
+        if (relPath.startsWith(TRUSTED_TEST_PREFIX)) {
+            dropped.push({ path: relPath, reason: "trusted-tests" });
+            continue;
+        }
+        if (globs.some((re) => re.test(relPath))) {
+            dropped.push({ path: relPath, reason: "sealed" });
+            continue;
+        }
+        overlay.push({ path: relPath, content });
+    }
+    for (const relPath of baseFiles.keys()) {
+        if (!relPath.startsWith(OVERLAY_PREFIX) || candidateFiles.has(relPath))
+            continue;
+        // The candidate DELETED a base file: trusted paths must survive (report the
+        // drop); unsealed deletions are unrepresentable in a copy-only v1 overlay.
+        if (relPath.startsWith(TRUSTED_TEST_PREFIX))
+            dropped.push({ path: relPath, reason: "trusted-tests" });
+        else if (globs.some((re) => re.test(relPath)))
+            dropped.push({ path: relPath, reason: "sealed" });
+    }
+    return { overlay, dropped };
+}
+/**
+ * Mutable clone of a frozen snapshot (minus .git): cpSync preserves the 0444/
+ * 0555 freeze modes, so the clone is thawed before anything overlays onto it;
+ * the harness's own node_modules is SYMLINKED (pinned toolchain — never copied,
+ * never npm ci, never candidate-supplied build scripts).
+ */
+export async function cloneSnapshot(snapshotPath, buildDir, nodeModules) {
+    mkdirSync(path.dirname(buildDir), { recursive: true });
+    cpSync(snapshotPath, buildDir, {
+        recursive: true,
+        filter: (src) => {
+            const rel = path.relative(snapshotPath, src);
+            return rel !== ".git" && !rel.startsWith(`.git${path.sep}`);
+        },
+    });
+    await thawTree(buildDir);
+    symlinkSync(nodeModules, path.join(buildDir, "node_modules"), "dir");
+}
+export function writeOverlay(buildDir, decision) {
+    for (const file of decision.overlay) {
+        const abs = path.join(buildDir, file.path);
+        mkdirSync(path.dirname(abs), { recursive: true });
+        writeFileSync(abs, file.content, "utf8");
+    }
+}
+/**
+ * The repo's OWN build recipe under the HARNESS-PINNED toolchain reached
+ * through the node_modules symlink: `tsc -p tsconfig.json` then
+ * `node scripts/copy-assets.mjs` (the two steps npm run build runs — never
+ * npm, never candidate-supplied scripts; copy-assets is itself sealed).
+ * timeoutS bounds BOTH steps together.
+ */
+export async function runBuild(buildDir, timeoutS, onChild) {
+    const started = Date.now();
+    const remaining = () => Math.max(5, timeoutS - Math.round((Date.now() - started) / 1000));
+    const steps = [
+        { label: "tsc", argv: [process.execPath, path.join(buildDir, "node_modules", "typescript", "bin", "tsc"), "-p", "tsconfig.json"] },
+        { label: "copy-assets", argv: [process.execPath, "scripts/copy-assets.mjs"] },
+    ];
+    for (const stepDef of steps) {
+        const outcome = await step({ argv: stepDef.argv, cwd: buildDir, timeoutS: remaining() }, onChild);
+        if (outcome.kind === "timeout")
+            return { status: "timeout", exit: null, note: `${stepDef.label}: ${outcome.reason}` };
+        if (outcome.kind === "spawn_failed")
+            return { status: "failed", exit: null, note: `${stepDef.label}: ${outcome.reason}` };
+        if (outcome.exitCode !== 0) {
+            const first = outcome.stdout.trim().split("\n").find((l) => l.length > 0) ?? outcome.stderr.trim().split("\n")[0] ?? "no output";
+            return { status: "failed", exit: outcome.exitCode, note: `${stepDef.label}: ${first}` };
+        }
+    }
+    return { status: "ok", exit: 0, note: "" };
+}
+/** node --test over the compiled suite (the plan's scoring surface). */
+export async function runSuite(buildDir, timeoutS, onChild) {
+    return step({ argv: [process.execPath, "--test", "dist/test/**/*.test.js"], cwd: buildDir, timeoutS, env: { NODE_TEST_CONTEXT: undefined } }, onChild);
+}
+export async function runReplay(buildDir, timeoutS, onChild) {
+    return step({ argv: [process.execPath, "selfbench/replay.mjs"], cwd: buildDir, timeoutS }, onChild);
+}
+function step(opts, onChild) {
+    return runChild(onChild === undefined ? opts : { ...opts, onChild });
+}
+/** Parse the node:test TAP summary lines ('# tests N' / '# pass N' / '# fail N'). */
+export function parseTapSummary(stdout) {
+    let tests = null;
+    let pass = null;
+    let fail = null;
+    for (const line of stdout.split("\n")) {
+        const m = /^# (tests|pass|fail) (\d+)$/.exec(line);
+        if (m === null)
+            continue;
+        const value = Number(m[2]);
+        if (m[1] === "tests")
+            tests = value;
+        else if (m[1] === "pass")
+            pass = value;
+        else
+            fail = value;
+    }
+    if (tests === null || pass === null || fail === null)
+        return null;
+    return { tests, pass, fail };
+}
+export function parseReplayDigest(stdout) {
+    const lines = stdout.trim().split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = lines[i] ?? "";
+        if (!line.startsWith("{"))
+            continue;
+        try {
+            const value = JSON.parse(line);
+            if (typeof value === "object" && value !== null && "digest" in value) {
+                const d = value.digest;
+                if (typeof d === "string" && /^[0-9a-f]{64}$/.test(d))
+                    return d;
+            }
+        }
+        catch {
+            // not the digest line — keep scanning upward.
+        }
+    }
+    return null;
+}
+export async function incumbentSnapshot(genomeRepo, genomeFp, commitSha, env) {
+    const handle = await snapshotCommit({ repoPath: genomeRepo, genomeFp }, commitSha, { env });
+    return handle.snapshotPath;
+}
+/** src/** candidate files (rel path -> text) from a candidate snapshot. */
+export function candidateSrcFiles(snapshotPath) {
+    const out = new Map();
+    for (const rel of treePaths(snapshotPath)) {
+        if (rel.startsWith(OVERLAY_PREFIX))
+            out.set(rel, readFileSync(path.join(snapshotPath, rel), "utf8"));
+    }
+    return out;
+}
+export function removeBuildDir(buildDir) {
+    rmSync(buildDir, { recursive: true, force: true });
+}
+/** The TRUSTED replay expectation — a corrupt goalpost file is cannot-answer, never a pass. */
+export function readExpectedDigest(snapshotPath) {
+    let raw;
+    try {
+        raw = readFileSync(path.join(snapshotPath, "selfbench", "expected.json"), "utf8");
+    }
+    catch {
+        return cannotAnswer(`self-snapshot: trusted selfbench/expected.json missing from snapshot ${snapshotPath}`);
+    }
+    let digest;
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value === "object" && value !== null && "digest" in value)
+            digest = value.digest;
+    }
+    catch {
+        return cannotAnswer(`self-snapshot: selfbench/expected.json in ${snapshotPath} is not valid JSON`);
+    }
+    if (typeof digest !== "string" || !/^[0-9a-f]{64}$/.test(digest)) {
+        return cannotAnswer(`self-snapshot: selfbench/expected.json in ${snapshotPath} carries no 64-hex digest`);
+    }
+    return digest;
+}

package/dist/core/evolve/self-snapshot.js

@@ -0,0 +1,170 @@
+// Snapshot-overlay self-bench (plan todo 11c): score = candidate src UNDER the
+// incumbent-pinned test suite + golden toy-replay, both executed inside a
+// private clone of the frozen incumbent snapshot. Pure incumbent-vs-incumbent
+// is the forbidden degenerate case, so the incumbent bench doubles as the
+// baseline for exactly that suite; every candidate bench re-runs it against the
+// overlaid build. Nothing here loads candidate code into this process, touches
+// the operator's real repo worktree (snapshots come from COMMITS only), or
+// references promote — `self-eval` reports fitness; humans merge.
+//
+// Timeout caps (documented): build 180s (a candidate that makes tsc hang is
+// killed => inconclusive), suite 900s (spec.bench.timeoutS semantics), replay
+// 120s. All steps are argv runChild children tracked by the caller's
+// ChildTracker, so a killed run leaves no orphans.
+import { mkdtempSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { cannotAnswer } from "../../exit.js";
+import { runId } from "../ids.js";
+import { genomeDir } from "../genome-paths.js";
+import { round3, unitMatrixRowSchema } from "./run-rows.js";
+import { candidateSrcFiles, cloneSnapshot, incumbentSnapshot, parseReplayDigest, parseTapSummary, planOverlay, readExpectedDigest, removeBuildDir, runBuild, runReplay, runSuite, writeOverlay, } from "./self-overlay.js";
+export const DEFAULT_BUILD_TIMEOUT_S = 180;
+export const DEFAULT_TEST_TIMEOUT_S = 900;
+export const DEFAULT_REPLAY_TIMEOUT_S = 120;
+export const SELF_OVERLAY_EMPTY = "self-bench: overlay empty";
+export const SELF_BUILD_TIMEOUT = "self-bench: build timeout";
+const HARNESS_ROOT = path.resolve(fileURLToPath(new URL("../../..", import.meta.url)));
+function specUnits(spec) {
+    const train = spec.bench.units.find((u) => u.split === "train");
+    const val = spec.bench.units.find((u) => u.split === "val");
+    if (train === undefined || val === undefined) {
+        cannotAnswer("self-snapshot: the self genome spec needs one train (suite) and one val (replay) unit");
+    }
+    return { trainId: train.id, valId: val.id };
+}
+function tscVersion(nodeModules) {
+    try {
+        const parsed = JSON.parse(readFileSync(path.join(nodeModules, "typescript", "package.json"), "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export async function selfBench(req) {
+    const started = Date.now();
+    const { trainId, valId } = specUnits(req.spec);
+    const baseSnapshot = await incumbentSnapshot(req.genomeRepo, req.genomeFp, req.incumbentCommit, req.env);
+    const replayExpected = readExpectedDigest(baseSnapshot);
+    const decision = req.candidateCommit === null
+        ? { overlay: [], dropped: [] }
+        : planOverlay(candidateSrcFiles(baseSnapshot), candidateSrcFiles(await incumbentSnapshot(req.genomeRepo, req.genomeFp, req.candidateCommit, req.env)), req.spec);
+    const buildDir = mkdtempSync(path.join(genomeDir(req.env, { repoPath: req.genomeRepo, genomeFp: req.genomeFp }), `selfbench-${req.genId}-`));
+    const suiteRow = { unitId: trainId, split: "train", scores: [], runIds: [], failures: [] };
+    const replayRow = { unitId: valId, split: "val", scores: [], runIds: [], failures: [] };
+    let buildStatus = "ok";
+    let buildNote = "";
+    let complete = true;
+    const suiteRuns = [];
+    let replayDigest = null;
+    const nodeModules = path.join(HARNESS_ROOT, "node_modules");
+    try {
+        await cloneSnapshot(baseSnapshot, buildDir, nodeModules);
+        writeOverlay(buildDir, decision);
+        const buildTimeoutS = req.buildTimeoutS ?? DEFAULT_BUILD_TIMEOUT_S;
+        const build = await runBuild(buildDir, buildTimeoutS, req.onChild);
+        buildStatus = build.status;
+        buildNote = build.note;
+        if (build.status === "timeout") {
+            complete = false;
+            suiteRow.failures.push(`${SELF_BUILD_TIMEOUT}: tsc killed after ${String(buildTimeoutS)}s (hung build is cannot-answer, never a zero)`);
+        }
+        else if (build.status === "failed") {
+            for (let rep = 0; rep < req.reps; rep += 1) {
+                suiteRow.scores.push(0);
+                suiteRow.runIds.push(runId(req.genId, trainId, rep));
+                suiteRow.failures.push(`${trainId} rep ${String(rep)}: run build_failed: tsc exit ${String(build.exit ?? "spawn")}`);
+                replayRow.scores.push(0);
+                replayRow.runIds.push(runId(req.genId, valId, rep));
+                replayRow.failures.push(`${valId} rep ${String(rep)}: run build_failed: replay skipped (build broken)`);
+            }
+        }
+        else {
+            const testTimeoutS = req.testTimeoutS ?? DEFAULT_TEST_TIMEOUT_S;
+            const replayTimeoutS = req.replayTimeoutS ?? DEFAULT_REPLAY_TIMEOUT_S;
+            for (let rep = 0; rep < req.reps; rep += 1) {
+                const suite = await runSuite(buildDir, testTimeoutS, req.onChild);
+                if (suite.kind !== "exited") {
+                    complete = false;
+                    suiteRow.failures.push(`${trainId} rep ${String(rep)}: run ${suite.kind === "timeout" ? "timeout" : "infra_failed"}: ${suite.reason}`);
+                }
+                else {
+                    const summary = parseTapSummary(suite.stdout);
+                    if (summary === null || summary.tests === 0) {
+                        suiteRow.failures.push(`${trainId} rep ${String(rep)}: grader inconclusive: no usable TAP summary from node --test`);
+                    }
+                    else {
+                        suiteRuns.push(summary);
+                        suiteRow.scores.push(summary.fail === 0 ? 1 : summary.pass / summary.tests);
+                        suiteRow.runIds.push(runId(req.genId, trainId, rep));
+                        if (summary.fail > 0)
+                            suiteRow.failures.push(`${trainId} rep ${String(rep)}: scored ${(summary.pass / summary.tests).toFixed(4)} (${String(summary.fail)} failing trusted tests, not passing)`);
+                    }
+                }
+                const replay = await runReplay(buildDir, replayTimeoutS, req.onChild);
+                if (replay.kind !== "exited") {
+                    complete = false;
+                    replayRow.failures.push(`${valId} rep ${String(rep)}: run ${replay.kind === "timeout" ? "timeout" : "infra_failed"}: ${replay.reason}`);
+                }
+                else {
+                    const digest = parseReplayDigest(replay.stdout);
+                    if (digest === null) {
+                        replayRow.failures.push(`${valId} rep ${String(rep)}: grader inconclusive: replay printed no 64-hex digest (exit ${String(replay.exitCode)})`);
+                    }
+                    else {
+                        replayDigest ??= digest;
+                        replayRow.scores.push(digest === replayExpected ? 1 : 0);
+                        replayRow.runIds.push(runId(req.genId, valId, rep));
+                        if (digest !== replayExpected)
+                            replayRow.failures.push(`${valId} rep ${String(rep)}: scored 0 (golden-replay digest mismatch — behavior moved)`);
+                    }
+                }
+            }
+            if (req.candidateCommit !== null && decision.overlay.length === 0 && decision.dropped.length > 0) {
+                suiteRow.failures.push(`${SELF_OVERLAY_EMPTY}: every candidate src change matched a seal or the trusted-test rule — score equals the incumbent by construction, no nomination without scored change`);
+            }
+        }
+    }
+    finally {
+        removeBuildDir(buildDir);
+    }
+    const failures = [...suiteRow.failures, ...replayRow.failures];
+    return {
+        units: [unitMatrixRowSchema.parse(suiteRow), unitMatrixRowSchema.parse(replayRow)],
+        spent: { candidates: req.candidateCommit === null ? 0 : 1, modelCalls: 0, tokens: 0, wallS: round3((Date.now() - started) / 1000) },
+        provenance: {
+            benchType: req.spec.bench.type,
+            versions: [
+                { bin: "node", version: process.version },
+                { bin: "tsc", version: tscVersion(nodeModules) },
+            ],
+        },
+        complete,
+        failures,
+        overlaid: decision.overlay.map((f) => f.path),
+        dropped: decision.dropped,
+        buildStatus,
+        buildNote,
+        suiteRuns,
+        replayDigest,
+        replayExpected,
+        snapshotPath: baseSnapshot,
+        buildDir,
+    };
+}
+/**
+ * Self-bench verdict guards (plan AC-4 / hung_commands): a killed step (build
+ * timeout, hung/crashed suite or replay child) can never answer — inconclusive;
+ * a candidate whose entire overlay was dropped never changed scored bytes, so a
+ * (degenerate) nomination downgrades to indeterminate. Everything else passes
+ * through to evaluate's verdict.
+ */
+export function selfGuardVerdict(failures, base) {
+    if (failures.some((f) => f.startsWith(SELF_BUILD_TIMEOUT) || f.includes(": run timeout") || f.includes(": run infra_failed"))) {
+        return "inconclusive";
+    }
+    if (failures.some((f) => f.startsWith(SELF_OVERLAY_EMPTY)) && base === "nominated")
+        return "indeterminate";
+    return base;
+}

package/dist/core/evolve/stub-mutators.mjs

@@ -0,0 +1,105 @@
+// Deterministic scripted-patch mutator STUB (plan todo 5). Model-free candidate
+// generator for the toy substrate: a fixed table of textual patches, seedable
+// selection (mulberry32 + Fisher-Yates — same seed, same order, always), and an
+// all-or-nothing single-occurrence apply. todo 8/9 consume this via the mutator
+// interface; real LLM-driven mutators replace the table later, the selection
+// contract stays.
+//
+// Patch semantics: `from` must occur EXACTLY ONCE in <repoDir>/<file> or applyPatch
+// refuses (returns false, writes nothing) — ambiguous rewrites are how silent
+// corruption starts.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** @type {ReadonlyArray<{id: string, description: string, file: string, from: string, to: string}>} */
+const SCRIPTED_PATCHES = [
+  {
+    id: "fix-add",
+    description: "seeded-bug fix: add() must sum, not subtract",
+    file: "units/add.mjs",
+    from: "return a - b; // seeded bug: must be `return a + b;`",
+    to: "return a + b;",
+  },
+  {
+    id: "break-mul",
+    description: "harmful mutation: mul gains a spurious +a term",
+    file: "units/mul.mjs",
+    from: "return a * b;",
+    to: "return a * b + a;",
+  },
+  {
+    id: "break-sub",
+    description: "harmful mutation: sub() flips sign",
+    file: "units/sub.mjs",
+    from: "return a - b;",
+    to: "return a + b;",
+  },
+  {
+    id: "annotate-add",
+    description: "benign mutation: cosmetic marker inside add()'s signature",
+    file: "units/add.mjs",
+    from: "export function add(",
+    to: "export function add /* patched */(",
+  },
+];
+
+/** Every scripted patch, in stable declaration order (a copy — callers may sort). */
+export function scriptedPatches() {
+  return SCRIPTED_PATCHES.slice();
+}
+
+/**
+ * Deterministically select up to `count` patches for `seed`: seeded shuffle of the
+ * table, then slice. Same (seed, count) => element-wise identical arrays.
+ * @param {number} seed non-negative integer
+ * @param {number} count desired patch count, clamped into [0, table length]
+ */
+export function selectPatches(seed, count) {
+  if (!Number.isInteger(seed) || seed < 0) {
+    throw new TypeError(`selectPatches: seed must be an integer >= 0, got ${String(seed)}`);
+  }
+  if (!Number.isInteger(count) || count < 0) {
+    throw new TypeError(`selectPatches: count must be an integer >= 0, got ${String(count)}`);
+  }
+  const items = SCRIPTED_PATCHES.slice();
+  const rand = mulberry32(seed >>> 0);
+  for (let i = items.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(rand() * (i + 1));
+    const swap = /** @type {const} */ ([items[i], items[j]]);
+    items[j] = swap[0];
+    items[i] = swap[1];
+  }
+  return items.slice(0, Math.min(count, items.length));
+}
+
+/**
+ * Apply one patch under repoDir (accepts a patch from scriptedPatches/selectPatches
+ * or any same-shaped object). Returns true on success; false — with NOTHING written —
+ * when the file is missing, `from` is absent, or it occurs more than once.
+ * @param {string} repoDir
+ * @param {{file: string, from: string, to: string}} patch
+ * @returns {boolean}
+ */
+export function applyPatch(repoDir, patch) {
+  if (typeof patch.from !== "string" || patch.from.length === 0) return false;
+  const file = path.join(repoDir, patch.file);
+  if (!existsSync(file)) return false;
+  const text = readFileSync(file, "utf8");
+  const first = text.indexOf(patch.from);
+  if (first === -1) return false;
+  if (text.indexOf(patch.from, first + 1) !== -1) return false; // ambiguous
+  writeFileSync(file, `${text.slice(0, first)}${patch.to}${text.slice(first + patch.from.length)}`, "utf8");
+  return true;
+}
+
+/** Classic mulberry32 PRNG — 32-bit state, tiny, stable across engines. */
+function mulberry32(a) {
+  return function next() {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}

package/dist/core/evolve/udiff.js

@@ -0,0 +1,189 @@
+// Minimal unified-diff parser + atomic in-memory applier for mutator candidates
+// (todo 8, plan lines 133-140). Git style sections: `--- a/f`, `+++ b/f`,
+// `@@ -oldStart[,oldCount] +newStart[,newCount] @@` with ' '/'-'/'+' body lines.
+//
+// v1 candidate ops, DOCUMENTED SCOPE:
+//   allowed:  modify existing text file, create new text file (`--- /dev/null`).
+//   refused:  delete (`+++ /dev/null`), rename/copy (a/ != b/ or rename lines),
+//             binary (`Binary files … differ`, `GIT binary patch`), and
+//             `` markers.
+// Nothing touches disk here: parseUnifiedDiff + applyChanges are pure, so a
+// candidate with ANY violating file is rejected before ANY file is mutated
+// (whole-candidate rejection is enforceable, not best-effort).
+const HUNK_RE = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+const DIFF_GIT_RE = /^diff --git a\/(\S+) b\/(\S+)$/;
+const fail = (error) => ({ ok: false, error });
+function isBinaryMarker(line) {
+    return line.startsWith("Binary files") || line.startsWith("GIT binary patch") || line.startsWith("literal ") || line.startsWith("delta ");
+}
+/** Skip metadata lines between a `diff --git` header and its `---` line. */
+function metadata(line) {
+    return (line.startsWith("index ") ||
+        line.startsWith("new file mode") ||
+        line.startsWith("old mode") ||
+        line.startsWith("new mode") ||
+        line.startsWith("similarity index"));
+}
+export function parseUnifiedDiff(text) {
+    if (text.includes("\r"))
+        return fail("CRLF line endings are not supported in v1");
+    // control bytes outside tab/LF = binary payload smuggled into a text hunk
+    if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(text))
+        return fail("control characters (binary content) are not supported as candidate ops");
+    const lines = text.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    const changes = [];
+    let pendingGit = null;
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.length === 0 || metadata(line)) {
+            i += 1;
+            continue;
+        }
+        if (line.startsWith("diff --git ")) {
+            const m = DIFF_GIT_RE.exec(line);
+            if (m === null)
+                return fail(`diff --git header not parsable (spaces in paths unsupported in v1): ${line}`);
+            if (m[1] !== m[2])
+                return fail(`renames are not supported as candidate ops: ${String(m[1])} -> ${String(m[2])}`);
+            pendingGit = String(m[1]);
+            i += 1;
+            continue;
+        }
+        if (line.startsWith("rename ") || line.startsWith("copy "))
+            return fail("renames/copies are not supported as candidate ops");
+        if (line.startsWith("deleted file mode"))
+            return fail("deletes are not supported as candidate ops");
+        if (isBinaryMarker(line))
+            return fail("binary patches are not supported as candidate ops");
+        if (!line.startsWith("--- "))
+            return fail(`unrecognized diff line: ${line}`);
+        const oldRaw = line.slice(4).split("\t")[0].trim();
+        const next = lines[i + 1];
+        if (next === undefined || !next.startsWith("+++ "))
+            return fail(`expected '+++ b/<path>' after '---' at line ${String(i + 1)}`);
+        const newRaw = next.slice(4).split("\t")[0].trim();
+        if (newRaw === "/dev/null")
+            return fail("deletes (+++ /dev/null) are not supported as candidate ops");
+        if (!newRaw.startsWith("b/"))
+            return fail(`+++ header must name a b/<path>: ${newRaw}`);
+        const newPath = newRaw.slice(2);
+        let kind;
+        if (oldRaw === "/dev/null") {
+            kind = "create";
+        }
+        else {
+            if (!oldRaw.startsWith("a/"))
+                return fail(`--- header must name an a/<path> or /dev/null: ${oldRaw}`);
+            if (oldRaw.slice(2) !== newPath)
+                return fail(`renames are not supported as candidate ops: ${oldRaw.slice(2)} -> ${newPath}`);
+            kind = "modify";
+        }
+        if (pendingGit !== null && pendingGit !== newPath) {
+            return fail(`diff --git header path '${pendingGit}' disagrees with section path '${newPath}'`);
+        }
+        i += 2;
+        const hunks = [];
+        while (i < lines.length && !isBinaryMarker(lines[i]) && !metadata(lines[i])) {
+            const hm = HUNK_RE.exec(lines[i]);
+            if (hm === null)
+                break; // section ends where a new one begins
+            const oldStart = Number(hm[1]);
+            const oldCount = hm[2] === undefined ? 1 : Number(hm[2]);
+            const newStart = Number(hm[3]);
+            const newCount = hm[4] === undefined ? 1 : Number(hm[4]);
+            i += 1;
+            const body = [];
+            let oldSeen = 0;
+            let newSeen = 0;
+            while (i < lines.length) {
+                const bl = lines[i];
+                if (bl.startsWith("@@") || bl.startsWith("--- ") || bl.startsWith("diff --git "))
+                    break;
+                if (isBinaryMarker(bl))
+                    break;
+                if (bl.startsWith("\\"))
+                    return fail('"No newline at end of file" markers are not supported in v1');
+                const op = bl.length === 0 ? " " : bl[0] === " " || bl[0] === "-" || bl[0] === "+" ? bl[0] : null;
+                if (op === null)
+                    return fail(`unrecognized hunk line: ${bl}`);
+                if (op !== "+")
+                    oldSeen += 1;
+                if (op !== "-")
+                    newSeen += 1;
+                body.push({ op, text: bl.slice(1) });
+                i += 1;
+            }
+            if (oldSeen !== oldCount || newSeen !== newCount) {
+                return fail(`hunk @@ -${oldStart},${oldCount} +${newStart},${newCount} @@ declares ${oldCount}/${newCount} lines, body has ${oldSeen}/${newSeen}`);
+            }
+            if (oldCount + newCount === 0)
+                return fail(`empty hunk at ${newPath}:${String(oldStart)}`);
+            hunks.push({ oldStart, oldCount, newStart, newCount, lines: body });
+        }
+        if (i < lines.length && isBinaryMarker(lines[i]))
+            return fail("binary patches are not supported as candidate ops");
+        if (hunks.length === 0)
+            return fail(`no valid @@ hunk for file section ${newPath}`);
+        changes.push({ path: newPath, kind, hunks });
+        pendingGit = null;
+    }
+    if (changes.length === 0)
+        return fail("no file sections found in diff");
+    return { ok: true, changes };
+}
+/**
+ * Apply parsed changes fully in memory. `readBase(relPath)` returns the current
+ * file text or null when absent. Hunks are POSITIONAL: the drifted worktree case
+ * (file shifted or edited around the anchor) refuses with a mismatch reason and
+ * the caller — having written nothing yet — discards the whole candidate.
+ * Precondition enforced here: paths unique across `changes`.
+ */
+export function applyChanges(changes, readBase) {
+    const files = new Map();
+    const touched = [];
+    for (const change of changes) {
+        if (files.has(change.path))
+            return failApply(`duplicate file section for ${change.path}`);
+        const base = readBase(change.path);
+        if (change.kind === "create") {
+            if (base !== null)
+                return failApply(`create refused: ${change.path} already exists`);
+            const added = change.hunks.flatMap((h) => h.lines.filter((l) => l.op !== "-").map((l) => l.text));
+            files.set(change.path, `${added.join("\n")}\n`);
+            touched.push(change.path);
+            continue;
+        }
+        if (base === null)
+            return failApply(`target file missing in worktree: ${change.path}`);
+        const hadFinalNewline = base.endsWith("\n");
+        const src = base.split("\n");
+        if (hadFinalNewline)
+            src.pop();
+        const out = [...src];
+        let offset = 0;
+        for (const h of change.hunks) {
+            const olds = h.lines.filter((l) => l.op !== "+").map((l) => l.text);
+            const news = h.lines.filter((l) => l.op !== "-").map((l) => l.text);
+            const start = h.oldStart - 1 + offset;
+            if (start < 0 || start + olds.length > src.length) {
+                return failApply(`hunk at ${change.path}:${String(h.oldStart)} out of range — worktree drifted`);
+            }
+            for (let j = 0; j < olds.length; j += 1) {
+                if (out[start + j] !== olds[j]) {
+                    return failApply(`hunk context mismatch at ${change.path}:${String(h.oldStart + j)} — worktree drifted, refusing without force`);
+                }
+            }
+            out.splice(start, olds.length, ...news);
+            offset += news.length - olds.length;
+        }
+        files.set(change.path, out.join("\n") + (hadFinalNewline ? "\n" : ""));
+        touched.push(change.path);
+    }
+    return { ok: true, files, touched };
+}
+function failApply(reason) {
+    return { ok: false, reason };
+}