@sabaiway/agent-workflow-kit 10.5.0 → 11.0.0

package/tools/core-evidence.mjs

@@ -24,7 +24,7 @@
 // re-derived): safe repo-relative path resolution, no-follow real-path containment, shell-free
 // argv, per-run timeout, N/N reruns, the quarantine lane (reruns 3, timeout 120s).
 // Import posture: this module is the DAG BOTTOM — it imports only node built-ins + atomic-write +
-// changed-surface + the pure leaves (repo-lex, fs-read-nofollow, coverage-state), and OWNS the
+// changed-surface + the pure leaves (repo-lex, fs-read-nofollow, coverage-state, git-env), and OWNS the
 // canonical review-domain primitives (tree fingerprint, receipt read
 // path, attesting predicate, verdict vocabulary, testId format, base resolution). review-state
 // RE-EXPORTS its historical public API from here, so its consumers (and the bash-twin parity
@@ -43,6 +43,7 @@ import { parsePositiveIntKnob, probeVerdict } from './changed-surface.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { lexicalRepoRelative } from './repo-lex.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, withGitPath } from './git-env.mjs';
 // The coverage vocabulary leaf: run-gates RECORDS the token this validator checks, and run-gates
 // imports THIS module (the sole-writer boundary), so their shared home sits below both.
 import { COVERAGE, FINAL_COVERAGE_STATES } from './coverage-state.mjs';
@@ -52,7 +53,6 @@ const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${messag
 const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
 
 const isoNow = () => new Date().toISOString();
-const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff / TAP stream can be large; never truncate
 
 const gitRaw = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 
@@ -114,15 +114,32 @@ export const isNeverCommittableStat = (stat) =>
   stat != null &&
   (stat.isCharacterDevice() || stat.isBlockDevice() || stat.isFIFO() || stat.isSocket());
 
+// The git runner seam the tree computations share — (args, dir, input, env) — and its guard: a
+// runner that THROWS answers as a failed spawn (measured: a raw stack out of a fingerprint).
+const defaultRunGit = (args, dir, input, env) => spawnSync('git', args, { cwd: dir, input, env: withGitPath(env ?? process.env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+const guardedRunner = (runGit, env) => (args, dir, input, override) => {
+  try { return runGit(args, dir, input, override ?? env); } catch (err) { return { error: err, status: null, signal: null, stdout: Buffer.alloc(0), stderr: '' }; }
+};
+const stdoutOf = (r) => (r.error || r.status !== 0 ? null : r.stdout);
+// Only a work-tree location is computed over (git-env's table under the runner's own env) — a redirecting GIT_DIR never hashes another repository in silence.
+const locateWorkTree = (cwd, run, env) => {
+  const location = resolveGitLocation(cwd, { spawn: (cmd, args, opts) => run(args, opts.cwd, undefined, opts.env), env });
+  return location.state === 'work-tree' ? location.top : null;
+};
+
 // The canonical payload bytes: staged diff + unstaged diff + the untracked-not-ignored section —
-// byte-identical to the wrappers' emit_fingerprint_payload, emitted from the work-tree ROOT. Null
-// outside a git work tree. The lstat is injectable ONLY for the never-committable filter tests.
-export const computeFingerprintPayload = (cwd, { lstat = lstatSync } = {}) => {
-  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+// byte-identical to the wrappers' emit_fingerprint_payload, emitted from the work-tree ROOT. Null on
+// every location but a work tree. lstat is injectable ONLY for the never-committable filter tests.
+export const FINGERPRINT_CACHED_DIFF_ARGV = Object.freeze(['diff', '--cached', '--no-ext-diff', '--no-textconv', '--ignore-submodules=none']);
+export const FINGERPRINT_UNSTAGED_DIFF_ARGV = Object.freeze(['diff', '--no-ext-diff', '--no-textconv', '--ignore-submodules=none']);
+export const computeFingerprintPayload = (cwd, { lstat = lstatSync, runGit = null, env = process.env } = {}) => {
+  const run = guardedRunner(runGit ?? defaultRunGit, env);
+  const top = locateWorkTree(cwd, run, env);
   if (top == null) return null;
-  const staged = gitBuf(['diff', '--cached', '--no-ext-diff'], top);
-  const unstaged = gitBuf(['diff', '--no-ext-diff'], top);
-  const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top);
+  const buf = (args) => stdoutOf(run(args, top));
+  const staged = buf(FINGERPRINT_CACHED_DIFF_ARGV);
+  const unstaged = buf(FINGERPRINT_UNSTAGED_DIFF_ARGV);
+  const untrackedZ = buf(['ls-files', '--others', '--exclude-standard', '-z']);
   if (staged == null || unstaged == null || untrackedZ == null) return null;
   const chunks = [staged, unstaged];
   for (const rel of untrackedZ.toString('utf8').split('\0').filter(Boolean)) {
@@ -348,21 +365,17 @@ const flaggedIndexLag = (top, runGit, lstat, readlink) => {
   return { paths: lagging, submodules: laggingSubmodules, flagged: laggingFlags };
 };
 
-export const computeWorkingState = (cwd, { lstat = lstatSync, readlink = readlinkSync, runGit = null } = {}) => {
-  const run = runGit ?? ((args, dir, input, env) => spawnSync('git', args, { cwd: dir, input, env: env ?? process.env, maxBuffer: GIT_MAX_BUFFER, windowsHide: true }));
-  const topRun = run(['rev-parse', '--show-toplevel'], cwd);
-  if (topRun.error || topRun.status !== 0) return null;
-  const top = topRun.stdout.toString('utf8').replace(/\r?\n$/, '');
+export const computeWorkingState = (cwd, { lstat = lstatSync, readlink = readlinkSync, runGit = null, env = process.env } = {}) => {
+  const run = guardedRunner(runGit ?? defaultRunGit, env);
+  const top = locateWorkTree(cwd, run, env);
+  if (top == null) return null;
   // `--ignore-submodules=none` on the staged probe too: a config-hidden STAGED gitlink would
   // otherwise make stagedDirty false, and isTreeClean would call such a tree clean.
   const staged = run(['diff', '--cached', '--quiet', '--ignore-submodules=none'], top);
   // ONLY 0 or 1 is a usable answer: a signal-killed probe reports status null, which the old
   // `> 1` guard let through as "nothing staged" — a fail-OPEN the whole arm cannot afford.
   if (staged.error || (staged.status !== 0 && staged.status !== 1)) return null;
-  const buf = (args) => {
-    const r = run(args, top);
-    return r.error || r.status !== 0 ? null : r.stdout;
-  };
+  const buf = (args) => stdoutOf(run(args, top));
   // The FULL probe forces submodules back in: diff.ignoreSubmodules / submodule.<n>.ignore would
   // otherwise erase a dirty submodule from the comparison entirely.
   const changedZ = buf(['diff', '--name-only', '-z', '--ignore-submodules=none']);
@@ -370,7 +383,7 @@ export const computeWorkingState = (cwd, { lstat = lstatSync, readlink = readlin
   const untrackedZ = buf(['ls-files', '--others', '--exclude-standard', '-z']);
   if (changedZ == null || plainZ == null || untrackedZ == null) return null;
   const split = (b) => b.toString('utf8').split('\0').filter(Boolean);
-  const changed = split(changedZ);
+  const changed = [...new Set(split(changedZ))]; // an unmerged path is listed once per conflict side
   const plain = new Set(split(plainZ));
   const flagged = flaggedIndexLag(top, run, lstat, readlink);
   if (flagged == null) return null;
@@ -950,6 +963,7 @@ export const runRedProof = ({ cwd = process.cwd(), env = process.env, testId } =
   // captured BEFORE the runs and re-checked after them; any drift refuses below.
   const base = resolveBase(cwd);
   const fingerprint = computeTreeFingerprint(cwd);
+  if (fingerprint == null) throw stop('cannot compute the tree fingerprint — the git location is not a work tree; nothing was observed, no runs were spent');
   const { entry, file, resolveReason } = probeBound({ testId, rootTop, env, reruns, timeoutS });
   const verdict = probeVerdict(entry);
   const counts = `${entry.greens} green / ${entry.reds} red / ${entry.timeouts} timed out / ${entry.runs - entry.greens - entry.reds - entry.timeouts} unresolved of ${entry.runs} run(s)`;
@@ -974,7 +988,6 @@ export const runRedProof = ({ cwd = process.cwd(), env = process.env, testId } =
         `${entry.timeouts > 0 ? 'raise the timeout or make the test faster' : 'replace the flaky test'}, then re-observe. Nothing was recorded.`,
     );
   }
-  if (fingerprint == null) throw stop('cannot compute the tree fingerprint — not a git work tree');
   // Post-run drift recheck: fingerprint, base, and the test-file bytes must all equal the
   // pre-run capture — a mutating test / parallel edit / commit would otherwise mint a record
   // whose fields attest different trees.

package/tools/coverage-check.mjs

@@ -24,6 +24,7 @@ import { lstatSync, readFileSync, realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 import { computeChangedSurface } from './changed-surface.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { lcovCoveredMap, uncoveredChangedFromLcov } from './lcov.mjs';
@@ -47,7 +48,6 @@ const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${m
 
 export const LCOV_BASENAME = 'agent-workflow-lcov.info';
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const gitLine = (args, cwd) => {
   const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;

package/tools/dispatch-store-read.mjs

@@ -0,0 +1,269 @@
+import { join, isAbsolute, normalize, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import {
+  validateDelegationRecord, canonicalDelegationDigest, allowedSuccessorKinds,
+  isThreadTerminalRecord,
+} from './dispatch-record.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
+
+export const DELEGATION_STORE_STOP = 'DELEGATION_STORE_STOP';
+export const delegationStoreStop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'DelegationStoreStop', code: DELEGATION_STORE_STOP });
+const stop = delegationStoreStop;
+
+export const DELEGATION_STORE_BASENAME = 'agent-workflow-delegation.jsonl';
+const runGit = (args, cwd, spawn = spawnSync) => spawn('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+const readGitLine = (args, cwd, spawn) => {
+  const result = runGit(args, cwd, spawn);
+  return result.error || result.status !== 0 ? null : result.stdout.toString('utf8').replace(/\r?\n$/, '');
+};
+
+export const resolveDelegationStorePath = (cwd, env = process.env) => {
+  if (env.AW_DELEGATION_STORE) {
+    if (!isAbsolute(env.AW_DELEGATION_STORE)) {
+      throw stop(`AW_DELEGATION_STORE must be an ABSOLUTE path (got "${env.AW_DELEGATION_STORE}") — a relative override resolves a different ledger from each worktree/cwd (fail closed)`);
+    }
+    const normalized = normalize(env.AW_DELEGATION_STORE);
+    if (normalized.endsWith(sep) || normalized.endsWith('/')) {
+      throw stop(`AW_DELEGATION_STORE must not end with a path separator (got "${env.AW_DELEGATION_STORE}") — a store is a file, not a directory (fail closed)`);
+    }
+    return normalized;
+  }
+  if (readGitLine(['rev-parse', '--is-inside-work-tree'], cwd) !== 'true') return null;
+  const commonDir = readGitLine(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+  return commonDir == null ? null : join(commonDir, DELEGATION_STORE_BASENAME);
+};
+
+const parseDelegationLine = (line, index) => {
+  if (line.trim() === '') return { empty: true };
+  try {
+    const record = JSON.parse(line);
+    const verdict = validateDelegationRecord(record);
+    return verdict.ok
+      ? { record, recordLine: index + 1 }
+      : { reason: `line ${index + 1}: ${verdict.reason}` };
+  } catch {
+    return { reason: `line ${index + 1}: invalid JSON` };
+  }
+};
+
+export const parseDelegationStoreText = (raw) => {
+  const parsed = String(raw).split('\n').map(parseDelegationLine);
+  const records = parsed.filter((item) => item.record !== undefined).map((item) => item.record);
+  const recordLines = parsed.filter((item) => item.recordLine !== undefined).map((item) => item.recordLine);
+  const malformedReasons = parsed.filter((item) => item.reason !== undefined).map((item) => item.reason);
+  return { records, recordLines, malformed: malformedReasons.length, malformedReasons };
+};
+
+const emptyRead = (outcome) => ({ outcome, records: [], recordLines: [], malformed: 0, malformedReasons: [] });
+
+export const readDelegationStore = (path, io = {}) => {
+  const read = readRegularFileNoFollow(path, io);
+  if (read.outcome === 'absent') return emptyRead('absent');
+  if (read.outcome === 'foreign') {
+    const reason = `the store is a ${read.className}, not a regular file — refusing to read it (fail closed)`;
+    return { ...emptyRead('error'), reason, readError: reason };
+  }
+  if (read.outcome === 'error') return { ...emptyRead('error'), reason: read.code, readError: read.code };
+  const parsed = parseDelegationStoreText(read.content);
+  return parsed.malformed > 0
+    ? { outcome: 'error', reason: parsed.malformedReasons[0], ...parsed }
+    : { outcome: 'ok', ...parsed };
+};
+
+const describeGitFailure = (result) => {
+  if (result.error) return result.error.code ?? result.error.message;
+  const stderr = result.stderr?.toString('utf8').trim() ?? '';
+  if (stderr !== '') return stderr;
+  if (result.signal) return `signal ${result.signal}`;
+  return `exit ${result.status}`;
+};
+
+export const readHeadInstant = (cwd, spawn = spawnSync) => {
+  const inside = runGit(['rev-parse', '--is-inside-work-tree'], cwd, spawn);
+  if (inside.error || inside.status !== 0 || inside.stdout.toString('utf8').trim() !== 'true') {
+    return { state: 'error', reason: `cannot resolve the git work tree (${describeGitFailure(inside)})` };
+  }
+  const head = runGit(['log', '-1', '--format=%ct'], cwd, spawn);
+  const raw = head.error || head.status !== 0 ? null : head.stdout.toString('utf8').trim();
+  if (raw !== null && /^\d+$/.test(raw)) return { state: 'ok', seconds: Number(raw) };
+  const status = runGit(['status', '--porcelain=v2', '--branch', '--untracked-files=no'], cwd, spawn);
+  if (!status.error && status.status === 0 && status.stdout.toString('utf8').split(/\r?\n/u).includes('# branch.oid (initial)')) {
+    return { state: 'unborn' };
+  }
+  return { state: 'error', reason: `cannot read HEAD committer time (${describeGitFailure(head)})` };
+};
+
+const THREAD_KINDS = ['dispatch', 'return', 'fold', 'degrade'];
+
+export const delegationThreadState = (records, nonce) => {
+  const thread = records.filter((record) => THREAD_KINDS.includes(record.kind) && record.nonce === nonce);
+  const last = thread.at(-1) ?? null;
+  const dispatch = thread.find((record) => record.kind === 'dispatch') ?? null;
+  const terminal = last !== null && isThreadTerminalRecord(last);
+  return {
+    records: thread,
+    dispatch,
+    return: thread.find((record) => record.kind === 'return') ?? null,
+    closure: thread.find((record) => record.kind === 'fold' || record.kind === 'degrade') ?? null,
+    last,
+    terminal,
+    open: dispatch !== null && !terminal,
+  };
+};
+
+const findRetryChainOrigin = (records, current, seen = new Set([current.nonce])) => {
+  if (current.retryOf === null) return current;
+  const prior = records.find((record) => record.kind === 'dispatch' && record.nonce === current.retryOf);
+  if (prior === undefined || seen.has(prior.nonce)) return current;
+  return findRetryChainOrigin(records, prior, new Set([...seen, prior.nonce]));
+};
+
+const describeClosure = (last) =>
+  last.kind === 'fold' ? 'its fold'
+    : last.kind === 'degrade' ? 'its recorded degrade'
+      : `a terminal return (outcome "${last.outcome}")`;
+
+const WAVE_SCOPED_KINDS = ['dispatch', 'observation', 'degrade'];
+
+export const delegationSemanticPreflight = ({ records, snapshot, storePath }) => {
+  const digest = canonicalDelegationDigest(snapshot);
+  if (records.some((record) => canonicalDelegationDigest(record) === digest)) {
+    throw stop(`refusing a canonical duplicate: ${storePath} already carries this exact record (${digest.slice(0, 12)}…), however its keys are ordered — a genuine new record carries new content or a new timestamp; nothing was written`);
+  }
+  const registration = records.find((record) => record.kind === 'pre-registration' && record.waveId === snapshot.waveId);
+  if (snapshot.kind === 'pre-registration' && registration !== undefined) {
+    throw stop(`refusing a second pre-registration: the wave "${snapshot.waveId}" is already registered and a registration is IMMUTABLE per wave — thresholds a wave was registered under can never move under its own observations; nothing was written`);
+  }
+  if (WAVE_SCOPED_KINDS.includes(snapshot.kind)) {
+    if (registration === undefined) {
+      throw stop(`refusing a ${snapshot.kind} that names the UNREGISTERED wave "${snapshot.waveId}" — acceptance is PRE-REGISTERED before the first observation it will count, so the thresholds can never be chosen after the fact; register the wave first; nothing was written`);
+    }
+    if (!registration.stepClasses.includes(snapshot.stepClass)) {
+      throw stop(`refusing a ${snapshot.kind}: step class "${snapshot.stepClass}" is not among the classes wave "${snapshot.waveId}" registered (${registration.stepClasses.join(' | ')}) — the registered set IS the acceptance set; nothing was written`);
+    }
+  }
+  const nonce = typeof snapshot.nonce === 'string' ? snapshot.nonce : null;
+  if (nonce === null) return;
+  const state = delegationThreadState(records, nonce);
+  if (snapshot.kind === 'dispatch') {
+    if (state.dispatch !== null) {
+      throw stop(`refusing a duplicate dispatch: nonce "${nonce}" already carries a dispatch — a nonce IS the thread identity and is minted once; nothing was written`);
+    }
+    if (snapshot.retryOf !== null) {
+      const prior = delegationThreadState(records, snapshot.retryOf);
+      if (prior.dispatch === null) {
+        throw stop(`refusing a retry: no dispatch for nonce "${snapshot.retryOf}" is in the store — a retry names the thread it retries; nothing was written`);
+      }
+      const successor = records.find((record) => record.kind === 'dispatch' && record.retryOf === snapshot.retryOf);
+      if (successor !== undefined) {
+        throw stop(`refusing a retry: thread "${snapshot.retryOf}" already has the retry successor "${successor.nonce}" — a thread is retried at most ONCE, or the recorded cap would bound only the chain's depth while its branching stayed free; nothing was written`);
+      }
+      if (!prior.terminal) {
+        throw stop(`refusing a retry: thread "${snapshot.retryOf}" is still OPEN — a thread is retried only after it closed (a success or acceptance-failure return stays live until its fold or degrade); nothing was written`);
+      }
+      if (prior.last.kind === 'fold') {
+        throw stop(`refusing a retry: thread "${snapshot.retryOf}" was closed by its fold — folding accepts the attempt into the tree, so a folded thread is never a retry origin whatever its return's outcome was; open a NEW thread instead; nothing was written`);
+      }
+      if (snapshot.retryIndex !== prior.dispatch.retryIndex + 1) {
+        throw stop(`refusing a retry: retryIndex ${snapshot.retryIndex} must be ${prior.dispatch.retryIndex + 1} — a retry increments its origin's index by exactly one, so the chain length is the index; nothing was written`);
+      }
+      if (snapshot.waveId !== prior.dispatch.waveId) {
+        throw stop(`refusing a retry: it names wave "${snapshot.waveId}" but its retry origin "${snapshot.retryOf}" was dispatched in wave "${prior.dispatch.waveId}" — a retry stays in its origin's wave, or one thread would count in two acceptance sets; nothing was written`);
+      }
+      if (snapshot.stepClass !== prior.dispatch.stepClass) {
+        throw stop(`refusing a retry: it declares step class "${snapshot.stepClass}" but its retry origin "${snapshot.retryOf}" was dispatched as "${prior.dispatch.stepClass}" — the pairing key is the step class, so a chain that changes it mid-way would split one attempt's accounting across two classes; nothing was written`);
+      }
+      const origin = findRetryChainOrigin(records, prior.dispatch);
+      if (snapshot.retryIndex > origin.retryCap) {
+        throw stop(`refusing a retry: retryIndex ${snapshot.retryIndex} exceeds the retryCap ${origin.retryCap} recorded on the thread's ORIGIN dispatch ("${origin.nonce}") — a fresh contract never manufactures a fresh retry budget; nothing was written`);
+      }
+      if (prior.return !== null && prior.return.outcome === 'contract-refusal' && snapshot.contractDigest === prior.dispatch.contractDigest) {
+        throw stop(`refusing a retry: it retries a contract-refusal thread and must carry a DIFFERENT contractDigest — an unchanged contract would only be refused again, and a retry loop on one contract is exactly what the cap exists to prevent; nothing was written`);
+      }
+    }
+    return;
+  }
+  if (state.dispatch === null) {
+    throw stop(`refusing a ${snapshot.kind}: no dispatch for nonce "${nonce}" is in the store — a thread opens with its dispatch, and a record that binds to nothing is never absorbed; nothing was written`);
+  }
+  if (snapshot.kind === 'return' && state.return !== null) {
+    throw stop(`refusing a second return: nonce "${nonce}" already carries a return (outcome "${state.return.outcome}") — one dispatch answers exactly once, so a stale return never lands; nothing was written`);
+  }
+  const allowed = allowedSuccessorKinds(state.last);
+  if (!allowed.includes(snapshot.kind)) {
+    throw stop(state.terminal
+      ? `refusing a ${snapshot.kind}: thread "${nonce}" is already closed by ${describeClosure(state.last)} — a closed thread never absorbs another record; nothing was written`
+      : `refusing a ${snapshot.kind}: nonce "${nonce}" carries no return to fold — the thread's last record is a ${state.last.kind}, whose only legal successors are ${allowed.join(' | ')}; nothing was written`);
+  }
+  if (snapshot.kind === 'return') {
+    for (const field of ['backend', 'contractDigest', 'preTreeDigest']) {
+      if (snapshot[field] !== state.dispatch[field]) {
+        throw stop(`refusing a return: ${field} "${snapshot[field]}" does not equal its dispatch's "${state.dispatch[field]}" — a return is bound to the dispatch it answers by nonce AND by identity; nothing was written`);
+      }
+    }
+    if (state.dispatch.baselineClean === false && snapshot.metric.eligible) {
+      throw stop(`refusing a return: its dispatch recorded baselineClean:false, so the metric is INELIGIBLE — the uncommitted-state fingerprint is blind to the index↔worktree split, so a dirty baseline cannot attribute bytes to this dispatch (D5); record eligible:false with ineligibleReason "dirty-baseline" (or the stricter reason this return's own fields substantiate); nothing was written`);
+    }
+    if (state.dispatch.baselineClean !== false && snapshot.metric.ineligibleReason === 'dirty-baseline') {
+      throw stop(`refusing a return: it claims ineligibleReason "dirty-baseline" while its dispatch recorded baselineClean:true — the override is unsubstantiated, and only the dispatch decides that fact; nothing was written`);
+    }
+  }
+  if (snapshot.kind === 'degrade') {
+    for (const field of ['waveId', 'stepClass']) {
+      if (snapshot[field] !== state.dispatch[field]) {
+        throw stop(`refusing a degrade: ${field} "${snapshot[field]}" does not equal its dispatch's "${state.dispatch[field]}" — a thread is closed inside the wave and step class it was dispatched in; nothing was written`);
+      }
+    }
+  }
+  if (snapshot.kind === 'fold') {
+    const target = records.find((record) => canonicalDelegationDigest(record) === snapshot.returnDigest);
+    if (target === undefined) {
+      throw stop(`refusing a fold: returnDigest ${snapshot.returnDigest.slice(0, 12)}… matches no record in the store — a fold binds an EXISTING return by its canonical digest; nothing was written`);
+    }
+    if (target.kind !== 'return') {
+      throw stop(`refusing a fold: returnDigest resolves to a ${target.kind} record, not a return — a fold folds a return; nothing was written`);
+    }
+    if (target.nonce !== nonce) {
+      throw stop(`refusing a fold: returnDigest resolves to the return of nonce "${target.nonce}", not this fold's "${nonce}" — a fold never reaches across threads; nothing was written`);
+    }
+    if (snapshot.treeDigestAtFold !== target.postTreeDigest) {
+      throw stop(`refusing a fold: treeDigestAtFold ${snapshot.treeDigestAtFold.slice(0, 12)}… does not equal the folded return's postTreeDigest ${target.postTreeDigest.slice(0, 12)}… — the tree moved between the return and the fold, so what was folded is not what was returned; nothing was written`);
+    }
+  }
+};
+
+export const auditDelegationStoreSemantics = ({ records = [], recordLines = [], storePath = '(store)' } = {}) =>
+  records.reduce((verdict, record, index) => {
+    if (!verdict.ok) return verdict;
+    try {
+      delegationSemanticPreflight({ records: records.slice(0, index), snapshot: record, storePath });
+      return verdict;
+    } catch (error) {
+      return { ok: false, line: recordLines[index] ?? index + 1, reason: error.message };
+    }
+  }, { ok: true });
+
+export const readDelegationLedger = (cwd, env, deps = {}) => {
+  try {
+    const {
+      resolveStore = resolveDelegationStorePath,
+      readStore = readDelegationStore,
+      audit = auditDelegationStoreSemantics,
+      readHead = readHeadInstant,
+    } = deps;
+    const storePath = resolveStore(cwd, env);
+    if (storePath === null) return { state: 'error', reason: 'the delegation ledger path is unresolvable (fail closed)' };
+    const read = readStore(storePath);
+    if (read.outcome === 'absent') return { state: 'absent' };
+    if (read.outcome === 'error' || read.readError != null || read.malformed > 0) {
+      return { state: 'error', reason: read.reason ?? read.readError ?? read.malformedReasons[0] };
+    }
+    const audited = audit({ records: read.records, recordLines: read.recordLines, storePath });
+    if (!audited.ok) return { state: 'error', reason: `line ${audited.line}: ${audited.reason}` };
+    return { state: 'ok', records: read.records, head: readHead(cwd) };
+  } catch (error) {
+    return { state: 'error', reason: error.message };
+  }
+};