forgedock 1.29.1 → 1.31.0

package/bin/lean/apishape.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Public-API-shape change detector (forge#4449, light lane #4442). Deterministic, no LLM: for every file changed in
+ * <base>...<head> it indexes the base and head blobs with scripts/symbol-index.py / symbol-index.mjs `--shape` (the
+ * target repo's own Python `ast` / `typescript`) and compares the public symbols:
+ *   signature | sync-async | generator-function | removed | renamed
+ * renamed = a vanished public symbol paired with a new public symbol of the same kind and shape in the same file;
+ * public→private counts as removed; additions never report. Code in a language without an indexer (go, rust, ...)
+ * or a blob the indexer refuses (parse error, no parser) is `unknown`, which the light lane treats as an upgrade.
+ * Docs/config/data files, test files and .d.ts are skipped.
+ *
+ * CLI: node bin/lean/apishape.mjs <base>...<head> | <base> <head>   (run from the repo root)
+ *   stdout {"status":"none|changed|unknown","changes":[{file,symbol,change,before,after}],"unknown":[{file,lang,reason}]}
+ *   exit 0 none/changed/unknown | 2 usage or bad ref
+ */
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPTS = fileURLToPath(new URL("../../scripts/", import.meta.url));
+export const SYMBOL_INDEX_PY = join(SCRIPTS, "symbol-index.py");
+export const SYMBOL_INDEX_MJS = join(SCRIPTS, "symbol-index.mjs");
+
+const INDEXED = { ".py": "python", ".ts": "ts", ".tsx": "ts", ".mts": "ts", ".cts": "ts", ".js": "js", ".jsx": "js", ".mjs": "js", ".cjs": "js" };
+const UNINDEXED = {
+  ".go": "go", ".rs": "rust", ".rb": "ruby", ".java": "java", ".kt": "kotlin", ".c": "c", ".h": "c", ".cc": "cpp",
+  ".cpp": "cpp", ".hpp": "cpp", ".cs": "csharp", ".php": "php", ".swift": "swift", ".sh": "shell",
+};
+const TEST_FILE = /(^|\/)(test_[^/]*\.py|[^/]*_test\.py|conftest\.py|[^/]*\.(test|spec)\.[^/]+)$|(^|\/)(tests?|__tests__)\//;
+
+/** argv runner without a shell; never throws for a non-zero exit. */
+export function defaultRun(cmd, args, { cwd } = {}) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { cwd, maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+      const code = err ? (Number.isInteger(err.code) ? err.code : 127) : 0;
+      resolve({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? (err && !Number.isInteger(err.code) ? err.message : "")) });
+    });
+  });
+}
+
+/** "python" | "ts" | "js" for an indexed file, { unknown: lang } for code without an indexer, null when skipped. */
+export function classifyPath(path) {
+  const p = String(path);
+  if (TEST_FILE.test(p) || /\.d\.[cm]?ts$/.test(p)) return null;
+  const ext = extname(p).toLowerCase();
+  if (INDEXED[ext]) return INDEXED[ext];
+  return UNINDEXED[ext] ? { unknown: UNINDEXED[ext] } : null;
+}
+
+/** `git diff -z --name-status -M` → [{ status, before, after }] (before/after null for added/deleted). */
+export function parseNameStatus(out) {
+  const f = String(out).split("\0");
+  const rows = [];
+  for (let i = 0; i < f.length && f[i];) {
+    const st = f[i][0];
+    if (st === "R" || st === "C") { rows.push({ status: st, before: st === "R" ? f[i + 1] : null, after: f[i + 2] }); i += 3; continue; }
+    const p = f[i + 1];
+    rows.push({ status: st, before: st === "A" ? null : p, after: st === "D" ? null : p });
+    i += 2;
+  }
+  return rows;
+}
+
+const shapeOf = (s) => ({ async: !!s.async, generator: !!s.generator, sig: s.sig ?? null });
+const shapeKey = (s) => JSON.stringify([s.kind, shapeOf(s)]);
+
+/** Public-symbol shape changes between two `--shape` indexes of one file. */
+export function compareIndexes(file, base, head) {
+  const pub = (idx) => new Map((idx?.symbols ?? []).filter((s) => s.public).map((s) => [s.name, s]));
+  const b = pub(base), h = pub(head), changes = [];
+  for (const [name, bs] of b) {
+    const hs = h.get(name);
+    if (!hs) continue;
+    const x = shapeOf(bs), y = shapeOf(hs);
+    if (x.async !== y.async) changes.push({ file, symbol: name, change: "sync-async", before: x.async ? "async" : "sync", after: y.async ? "async" : "sync" });
+    if (x.generator !== y.generator) changes.push({ file, symbol: name, change: "generator-function", before: x.generator ? "generator" : "function", after: y.generator ? "generator" : "function" });
+    if (x.sig !== y.sig) changes.push({ file, symbol: name, change: "signature", before: x.sig, after: y.sig });
+    else if (x.async === y.async && x.generator === y.generator && bs.kind !== hs.kind) {
+      changes.push({ file, symbol: name, change: "signature", before: bs.kind, after: hs.kind });
+    }
+  }
+  const added = [...h.keys()].filter((n) => !b.has(n)).sort();
+  for (const name of [...b.keys()].filter((n) => !h.has(n)).sort()) {
+    const key = shapeKey(b.get(name));
+    const i = added.findIndex((n) => shapeKey(h.get(n)) === key);
+    if (i >= 0) changes.push({ file, symbol: name, change: "renamed", before: name, after: added.splice(i, 1)[0] });
+    else changes.push({ file, symbol: name, change: "removed", before: name, after: null });
+  }
+  return changes;
+}
+
+async function indexBlob({ cwd, run, dir, ref, path, lang }) {
+  const show = await run("git", ["show", `${ref}:${path}`], { cwd });
+  if (show.code !== 0) return { unknown: { lang, reason: `git-show-failed: ${ref}:${path}` } };
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, basename(path));
+  writeFileSync(file, show.stdout);
+  const r = lang === "python"
+    ? await run("python3", [SYMBOL_INDEX_PY, "--shape", file], { cwd })
+    : await run(process.execPath, [SYMBOL_INDEX_MJS, "--shape", file], { cwd });
+  let out = null;
+  try { out = JSON.parse(r.stdout); } catch { /* reported below */ }
+  if (r.code !== 0 || !out) return { unknown: { lang, reason: r.code === 127 ? "no-indexer-runtime" : `index-failed: exit ${r.code}` } };
+  if (out.unsupported) return { unknown: { lang: out.unsupported, reason: out.reason ?? "unsupported" } };
+  return { index: out };
+}
+
+/**
+ * Compare base vs head for the changed files. Throws only for a bad ref or a failed `git diff` (CLI exit 2).
+ * @returns {Promise<{status:"none"|"changed"|"unknown", changes:object[], unknown:object[]}>}
+ */
+export async function detectApiShape({ cwd = process.cwd(), base, head, run = defaultRun } = {}) {
+  for (const ref of [base, head]) {
+    if (!ref || (await run("git", ["rev-parse", "--verify", "-q", `${ref}^{commit}`], { cwd })).code !== 0) throw new Error(`bad ref: ${ref}`);
+  }
+  const diff = await run("git", ["diff", "-z", "--name-status", "-M", `${base}...${head}`], { cwd });
+  if (diff.code !== 0) throw new Error(`git diff failed: ${diff.stderr.trim()}`);
+  const changes = [], unknown = [];
+  const tmp = mkdtempSync(join(tmpdir(), "apishape-"));
+  try {
+    let n = 0;
+    for (const row of parseNameStatus(diff.stdout)) {
+      if (!row.before) continue; // added (or copied) file: additions are not shape changes
+      const file = row.after ?? row.before;
+      const kind = classifyPath(row.before);
+      if (kind === null) continue;
+      if (typeof kind === "object") { unknown.push({ file, lang: kind.unknown, reason: "unsupported-language" }); continue; }
+      const dir = join(tmp, String(n++));
+      const b = await indexBlob({ cwd, run, dir: join(dir, "base"), ref: base, path: row.before, lang: kind });
+      if (b.unknown) { unknown.push({ file, ...b.unknown }); continue; }
+      let h = { index: { symbols: [] } };
+      if (row.after) {
+        const headKind = classifyPath(row.after);
+        if (headKind !== kind) { unknown.push({ file, lang: typeof headKind === "object" && headKind ? headKind.unknown : String(headKind), reason: "language-changed" }); continue; }
+        h = await indexBlob({ cwd, run, dir: join(dir, "head"), ref: head, path: row.after, lang: kind });
+        if (h.unknown) { unknown.push({ file, ...h.unknown }); continue; }
+      }
+      changes.push(...compareIndexes(file, b.index, h.index));
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+  const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+  changes.sort((a, b) => cmp(a.file, b.file) || cmp(a.symbol, b.symbol) || cmp(a.change, b.change));
+  unknown.sort((a, b) => cmp(a.file, b.file));
+  return { status: unknown.length ? "unknown" : changes.length ? "changed" : "none", changes, unknown };
+}
+
+async function main(argv) {
+  let base, head;
+  if (argv.length === 1 && argv[0].includes("...")) [base, head] = argv[0].split("...");
+  else if (argv.length === 2) [base, head] = argv;
+  if (!base || !head || argv.includes("-h") || argv.includes("--help")) {
+    process.stderr.write("usage: apishape.mjs <base>...<head> | <base> <head>\n");
+    return 2;
+  }
+  try {
+    process.stdout.write(JSON.stringify(await detectApiShape({ base, head })) + "\n");
+    return 0;
+  } catch (err) {
+    process.stderr.write(`apishape: ${err.message}\n`);
+    return 2;
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) process.exitCode = await main(process.argv.slice(2));

package/bin/lean/apishape.test.mjs

@@ -0,0 +1,187 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Public-API-shape detector (forge#4449): bin/lean/apishape.mjs against throwaway git repos built from
+// scripts/fixtures/apishape/<lang>/<case>/{base,head}/ and the real symbol indexers.
+// The JS/TS cases need the `typescript` (or `ts-morph`) package: APISHAPE_TS_NODE_MODULES=<node_modules holding it> is
+// symlinked into each repo; without it they skip, and APISHAPE_REQUIRE_TS=1 turns the skip into a failure (CI).
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { classifyPath, compareIndexes, detectApiShape, parseNameStatus } from "./apishape.mjs";
+
+const FIX = fileURLToPath(new URL("../../scripts/fixtures/apishape/", import.meta.url));
+const CLI = fileURLToPath(new URL("./apishape.mjs", import.meta.url));
+const TS_MODULES = process.env.APISHAPE_TS_NODE_MODULES || "";
+const HAS_TS = !!TS_MODULES && (existsSync(join(TS_MODULES, "typescript")) || existsSync(join(TS_MODULES, "ts-morph")));
+const tsSkip = HAS_TS ? false : "TS-parser cases skipped (set APISHAPE_TS_NODE_MODULES)";
+if (!HAS_TS && process.env.APISHAPE_REQUIRE_TS === "1") {
+  throw new Error("APISHAPE_REQUIRE_TS=1 but APISHAPE_TS_NODE_MODULES holds neither typescript nor ts-morph");
+}
+
+const git = (cwd, ...args) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+
+function clearTracked(dir) {
+  for (const ent of readdirSync(dir)) if (ent !== ".git" && ent !== "node_modules") rmSync(join(dir, ent), { recursive: true, force: true });
+}
+
+/** A repo with commit `base` (fixture base/) and commit `head` (fixture head/), or explicit file maps. */
+function repo({ fixture, base, head, ts = false }) {
+  const dir = tmpDir("apishape-");
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "t@example.com");
+  git(dir, "config", "user.name", "t");
+  if (ts) symlinkSync(TS_MODULES, join(dir, "node_modules"));
+  writeFileSync(join(dir, ".gitignore"), "node_modules\n");
+  const put = (side, files) => {
+    clearTracked(dir);
+    writeFileSync(join(dir, ".gitignore"), "node_modules\n");
+    if (fixture) cpSync(join(FIX, fixture, side), dir, { recursive: true });
+    for (const [p, body] of Object.entries(files ?? {})) { mkdirSync(join(dir, p, ".."), { recursive: true }); writeFileSync(join(dir, p), body); }
+    git(dir, "add", "-A");
+    git(dir, "commit", "-q", "--allow-empty", "-m", side);
+    git(dir, "tag", side);
+  };
+  put("base", base);
+  put("head", head);
+  return dir;
+}
+
+const detect = (cwd) => detectApiShape({ cwd, base: "base", head: "head" });
+const brief = (r) => r.changes.map((c) => `${c.change}:${c.symbol}:${c.before}>${c.after}`);
+
+describe("apishape: Python fixtures", () => {
+  it("signature: a new keyword-only parameter", async () => {
+    const r = await detect(repo({ fixture: "python/signature" }));
+    assert.equal(r.status, "changed");
+    assert.deepEqual(brief(r), ["signature:area:(width, height)>(width, height, *, scale=)"]);
+    assert.equal(r.changes[0].file, "shapes.py");
+  });
+
+  it("sync-async: a top-level function and a method", async () => {
+    const r = await detect(repo({ fixture: "python/sync-async" }));
+    assert.deepEqual(brief(r), ["sync-async:Client.get:sync>async", "sync-async:fetch:sync>async"]);
+  });
+
+  it("generator-function: a generator def becomes a list-returning def", async () => {
+    const r = await detect(repo({ fixture: "python/generator-function" }));
+    assert.deepEqual(brief(r), ["generator-function:pairs:generator>function"]);
+  });
+
+  it("removed public symbol", async () => {
+    const r = await detect(repo({ fixture: "python/removed" }));
+    assert.deepEqual(brief(r), ["removed:sub:sub>null"]);
+  });
+
+  it("renamed public symbol (same kind and shape)", async () => {
+    const r = await detect(repo({ fixture: "python/renamed" }));
+    assert.deepEqual(brief(r), ["renamed:slugify:slugify>to_slug"]);
+  });
+
+  it("private/internal edit reports nothing", async () => {
+    const r = await detect(repo({ fixture: "python/private-edit" }));
+    assert.deepEqual(r, { status: "none", changes: [], unknown: [] });
+  });
+
+  it("regression #4442: more-itertools ichunked generator → plain function is flagged", async () => {
+    const r = await detect(repo({ fixture: "python/ichunked" }));
+    assert.equal(r.status, "changed");
+    assert.deepEqual(brief(r), ["generator-function:ichunked:generator>function"]);
+  });
+});
+
+describe("apishape: JS/TS fixtures", () => {
+  const ts = (fixture) => detect(repo({ fixture, ts: true }));
+  it("signature: a new defaulted parameter (.ts)", { skip: tsSkip }, async () => {
+    const r = await ts("ts/signature");
+    assert.deepEqual(brief(r), ["signature:area:(width: number, height: number) -> number>(width: number, height: number, scale=) -> number"]);
+  });
+
+  it("sync-async: a function and an arrow const (.mjs)", { skip: tsSkip }, async () => {
+    const r = await ts("ts/sync-async");
+    assert.deepEqual(brief(r), ["sync-async:fetchUrl:sync>async", "sync-async:load:sync>async"]);
+  });
+
+  it("generator-function: function* becomes a plain function (.js)", { skip: tsSkip }, async () => {
+    const r = await ts("ts/generator-function");
+    assert.deepEqual(brief(r), ["generator-function:pairs:generator>function"]);
+  });
+
+  it("removed exported symbol", { skip: tsSkip }, async () => {
+    const r = await ts("ts/removed");
+    assert.deepEqual(brief(r), ["removed:sub:sub>null"]);
+  });
+
+  it("renamed exported symbol", { skip: tsSkip }, async () => {
+    const r = await ts("ts/renamed");
+    assert.deepEqual(brief(r), ["renamed:slugify:slugify>toSlug"]);
+  });
+
+  it("non-exported edit reports nothing", { skip: tsSkip }, async () => {
+    const r = await ts("ts/private-edit");
+    assert.deepEqual(r, { status: "none", changes: [], unknown: [] });
+  });
+});
+
+describe("apishape: scope and unknown", () => {
+  it("a language without an indexer reports unknown", async () => {
+    const r = await detect(repo({ fixture: "other/go-change" }));
+    assert.equal(r.status, "unknown");
+    assert.deepEqual(r.unknown, [{ file: "x.go", lang: "go", reason: "unsupported-language" }]);
+  });
+
+  it("docs-only change, an added public file and a test-file signature change report nothing", async () => {
+    const r = await detect(repo({
+      base: { "README.md": "a\n", "tests/test_x.py": "def test_a(x):\n    pass\n" },
+      head: { "README.md": "b\n", "tests/test_x.py": "def test_a(x, y):\n    pass\n", "new.py": "def f():\n    pass\n" },
+    }));
+    assert.deepEqual(r, { status: "none", changes: [], unknown: [] });
+  });
+
+  it("a deleted file reports each public symbol as removed; a renamed file compares old vs new path", async () => {
+    const r = await detect(repo({
+      base: { "a.py": "def keep(x):\n    pass\n\n\ndef _p():\n    pass\n", "b.py": "def gone():\n    pass\n" },
+      head: { "pkg/a.py": "def keep(x):\n    pass\n\n\ndef _p():\n    pass\n" },
+    }));
+    assert.deepEqual(r.changes.map((c) => `${c.file}:${c.change}:${c.symbol}`), ["b.py:removed:gone"]);
+  });
+
+  it("a head that does not parse reports unknown, public→private counts as removed", async () => {
+    const r = await detect(repo({ base: { "a.py": "def f():\n    pass\n" }, head: { "a.py": "def f(:\n" } }));
+    assert.equal(r.status, "unknown");
+    assert.match(r.unknown[0].reason, /^parse-error/);
+    const p = compareIndexes("a.py", { symbols: [{ name: "f", kind: "function", public: true, sig: "()" }] },
+      { symbols: [{ name: "f", kind: "function", public: false, sig: "()" }] });
+    assert.deepEqual(p.map((c) => c.change), ["removed"]);
+  });
+
+  it("classifyPath and parseNameStatus", () => {
+    assert.equal(classifyPath("src/a.py"), "python");
+    assert.equal(classifyPath("src/a.tsx"), "ts");
+    assert.equal(classifyPath("src/a.cjs"), "js");
+    assert.deepEqual(classifyPath("cmd/main.rs"), { unknown: "rust" });
+    for (const p of ["README.md", "x.json", "src/a.test.ts", "__tests__/b.js", "pkg/test_a.py", "a_test.py", "conftest.py", "types.d.ts"]) {
+      assert.equal(classifyPath(p), null, p);
+    }
+    assert.deepEqual(parseNameStatus("M\0a.py\0R100\0b.py\0c.py\0A\0d.py\0D\0e.py\0"), [
+      { status: "M", before: "a.py", after: "a.py" },
+      { status: "R", before: "b.py", after: "c.py" },
+      { status: "A", before: null, after: "d.py" },
+      { status: "D", before: "e.py", after: null },
+    ]);
+  });
+
+  it("CLI: exit 2 on a bad ref, JSON status none on an empty diff", () => {
+    const dir = repo({ base: { "a.py": "def f():\n    pass\n" }, head: { "a.py": "def f():\n    pass\n" } });
+    const bad = spawnSync(process.execPath, [CLI, "nope...head"], { cwd: dir, encoding: "utf8" });
+    assert.equal(bad.status, 2);
+    assert.match(bad.stderr, /bad ref: nope/);
+    assert.equal(spawnSync(process.execPath, [CLI], { cwd: dir }).status, 2);
+    const ok = spawnSync(process.execPath, [CLI, "base", "head"], { cwd: dir, encoding: "utf8" });
+    assert.equal(ok.status, 0);
+    assert.deepEqual(JSON.parse(ok.stdout), { status: "none", changes: [], unknown: [] });
+  });
+});

package/bin/lean/batch.mjs

@@ -5,6 +5,8 @@
  *
  * A batch lives in `~/.forge/batches/<id>/` (or `FORGEDOCK_BATCH_DIR`): `plan.json` (the command), `state.json` (the
  * scheduler state, rewritten after every transition), `log.jsonl` (one line per lane update), `parallel` (live K),
+ * `add` (issues added to the batch by `--add`, #4408: a cumulative JSON set the runner re-reads every pass),
+ * `cancel` (`{at, reason}` written by `--cancel`, #4376: the runner stops admitting and stops its local lanes; a resume clears it),
  * `lanes/<issue>.{json,log}` (each lane's result and output) and `report.json` (the final rows and printed report, written
  * when the scheduler loop returns; `forgedock orchestrate --resume` on a finished batch replays it, #4192). Every write is tmp + fsync + rename, and the root must be
  * on disk, never tmpfs. A lane is its own session (`setsid` through `detached`), so killing the dispatcher leaves it
@@ -61,6 +63,11 @@ export function writeAtomic(file, data) {
 
 const readJson = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
 
+const readAdded = (file) => {
+  const v = readJson(file);
+  return Array.isArray(v) ? [...new Set(v.filter((n) => Number.isSafeInteger(n) && n > 0))].sort((a, b) => a - b) : [];
+};
+
 export function newBatchId(now = Date.now(), pid = process.pid) {
   return `b${new Date(now).toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15)}-${pid}`;
 }
@@ -93,6 +100,31 @@ export function openBatch(root, id) {
       if (!Number.isInteger(k) || k < 1) throw new Error("parallel must be a positive integer");
       writeAtomic(f("parallel"), `${k}\n`);
     },
+    /** Issues added by `--add` (#4408): the `add` file, sorted unique positive integers; [] when missing or invalid. */
+    readAdded: () => readAdded(f("add")),
+    /**
+     * Merge `list` into the `add` file. Not a plain positive integer: skipped `not an integer`; already in state.json
+     * `order`, in the file or earlier in `list`: skipped `already in batch`. @returns {{added:number[], skipped:Array<{issue, reason}>}}
+     */
+    addIssues: (list) => {
+      const have = new Set([...(readJson(f("state.json"))?.order ?? []), ...readAdded(f("add"))]);
+      const added = [], skipped = [];
+      for (const x of Array.isArray(list) ? list : []) {
+        const n = typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN;
+        if (!Number.isSafeInteger(n) || n < 1) { skipped.push({ issue: x, reason: "not an integer" }); continue; }
+        if (have.has(n)) { skipped.push({ issue: n, reason: "already in batch" }); continue; }
+        have.add(n); added.push(n);
+      }
+      if (added.length) writeAtomic(f("add"), JSON.stringify([...new Set([...readAdded(f("add")), ...added])].sort((a, b) => a - b)) + "\n");
+      return { added, skipped };
+    },
+    /** `--cancel` (#4376): `{at, reason}` in the `cancel` file; the runner re-reads it every pass. */
+    requestCancel: ({ reason = "operator" } = {}) => writeAtomic(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason) }) + "\n"),
+    /** The cancel record, or null when missing or invalid. */
+    readCancel: () => { const v = readJson(f("cancel")); return v && typeof v === "object" && !Array.isArray(v) && typeof v.at === "string" ? v : null; },
+    clearCancel: () => rmSync(f("cancel"), { force: true }),
+    /** Added issues the batch never took into its `order` (a finished or unhosted batch with pending adds). */
+    unrunAdds: () => { const order = new Set(readJson(f("state.json"))?.order ?? []); return readAdded(f("add")).filter((n) => !order.has(n)); },
     /** The lane updates in `log.jsonl`, in order (unparsable lines skipped). */
     readLog: () => {
       let text = "";