@sabaiway/agent-workflow-kit 5.11.0 → 5.11.2

package/tools/flow-delta-proof.mjs

@@ -0,0 +1,307 @@
+// flow-delta-proof.mjs — the bookkeeping-delta custody proof (#60): the masked revert-and-recompute
+// at mint time, its strict -z index/HEAD parsers, the diff-section mask, the ONE captured read set,
+// computeMaskedFingerprintPayload and mintBookkeepingDelta. Split out of flow-store.mjs unchanged
+// (baseline-practices tranche 2); the facade re-exports both public names.
+//
+// The computation only READS: the working tree is never mutated, and an unconfined delta never
+// lands. Imports run ONE way: this leaf mints through the store's ONE append door
+// (flow-append.mjs) and never reaches the flow-store.mjs facade or its sibling mint leaf — the
+// one-line sha256Hex, HEX64_RE and the git buffer helper below are deliberate copies rather than
+// sideways imports.
+
+import { createHash } from 'node:crypto';
+import { readFileSync, lstatSync, readlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { lstatNoFollow } from './atomic-write.mjs';
+import { FLOW_SCHEMA_VERSION, canonicalFlowDigest } from './flow-record.mjs';
+import { isNeverCommittableStat, isBinaryFile, lexicalRepoRelative, resolveBase } from './core-evidence.mjs';
+import { flowStoreStop, gitLine, describeNonRegular } from './flow-store-read.mjs';
+import { appendFlowRecord } from './flow-append.mjs';
+
+const stop = flowStoreStop;
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+const gitBuf = (args, cwd) => {
+  const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  return r.stdout;
+};
+const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+const HEX64_RE = /^[0-9a-f]{64}$/;
+
+// The supported pre-state model; everything else refuses BY NAME (fail closed): the delta lives in
+// the WORKTREE layer of one plain-ASCII, non-binary, non-executable regular path. A tracked path
+// must be CLEAN at the path before the delta (pre-change worktree bytes = its index entry), so the
+// pre-state contributes NO unstaged diff section and the mask is pure section REMOVAL plus
+// untracked-entry splicing — the recompute never regenerates git diff bytes, whose exact form this
+// module cannot promise. Supported transitions: present→present, present→absent, absent→present.
+
+const GIT_PLAIN_PATH_RE = /^[\x20-\x7e]+$/;
+const pathNeedsGitQuoting = (rel) => !GIT_PLAIN_PATH_RE.test(rel) || rel.includes('"') || rel.includes('\\');
+const bufferLooksBinary = (buf) => buf.subarray(0, 8192).includes(0);
+const REGULAR_FILE_MODE = '100644';
+
+const defaultRunGit = (args, dir) => spawnSync('git', args, { cwd: dir, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+
+// The declared path enters git as a LITERAL pathspec and comes back through a strict -z parse:
+// exactly one NUL-terminated record whose path field EQUALS the declared rel, full-octal mode,
+// an OID of exactly 40 or 64 hex — a glob-capable name ([]*?) or a prefix-valid truncated answer
+// can then never bind the proof to another file (fail closed on every mismatch).
+const OID_PART = '(?:[0-9a-f]{40}|[0-9a-f]{64})';
+const INDEX_META_RE = new RegExp(`^([0-7]{6}) (${OID_PART}) (\\d)$`);
+const TREE_META_RE = new RegExp(`^([0-7]{6}) (\\w+) (${OID_PART})$`);
+
+const parseZRecords = (stdout) => {
+  const text = stdout.toString('utf8');
+  if (text === '') return [];
+  if (!text.endsWith('\0')) return null;
+  return text.slice(0, -1).split('\0');
+};
+
+const splitZEntry = (entry, metaRe) => {
+  const at = entry.indexOf('\t');
+  if (at === -1) return null;
+  const meta = metaRe.exec(entry.slice(0, at));
+  return meta == null ? null : { meta, path: entry.slice(at + 1) };
+};
+
+const readIndexEntry = (top, rel, runGit) => {
+  const out = runGit(['ls-files', '-s', '-z', '--', `:(literal)${rel}`], top);
+  if (out.error || out.status !== 0) throw stop(`cannot read the index entry of ${rel} (git ls-files failed) — refusing to mint (fail closed)`);
+  const recordsZ = parseZRecords(out.stdout);
+  if (recordsZ == null) throw stop(`cannot parse the index entry of ${rel} (unterminated git ls-files output) — refusing to mint (fail closed)`);
+  if (recordsZ.length === 0) return null;
+  const entry = splitZEntry(recordsZ[0], INDEX_META_RE);
+  if (recordsZ.length > 1 || entry == null || entry.meta[3] !== '0' || entry.path !== rel) {
+    throw stop(`the declared path ${rel} carries an unmerged or unparseable index entry — an unsupported pre-state class (fail closed)`);
+  }
+  return { mode: entry.meta[1], sha: entry.meta[2] };
+};
+
+// An absent HEAD layer is PROVEN unborn, never assumed: rev-parse must answer with EXACTLY the
+// clean verify-miss status (1) AND HEAD must still resolve as a symbolic ref; any operational
+// fault fails closed. "No entry" is ONLY an empty ls-tree stdout — a non-empty answer must parse
+// as exactly one entry line, else the repository is at fault (a false custody proof otherwise).
+const GIT_VERIFY_MISS_STATUS = 1;
+const readHeadEntry = (top, rel, runGit) => {
+  const probe = runGit(['rev-parse', '--verify', '--quiet', 'HEAD'], top);
+  if (probe.error || probe.status !== 0) {
+    const verifyMiss = !probe.error && probe.status === GIT_VERIFY_MISS_STATUS;
+    const sym = verifyMiss ? runGit(['symbolic-ref', '--quiet', 'HEAD'], top) : null;
+    if (sym == null || sym.error || sym.status !== 0) {
+      throw stop('cannot decide the HEAD state (git rev-parse --verify HEAD did not answer with a clean verify miss, or symbolic-ref HEAD failed) — refusing to mint (fail closed)');
+    }
+    return null;
+  }
+  const out = runGit(['ls-tree', '-z', 'HEAD', '--', `:(literal)${rel}`], top);
+  if (out.error || out.status !== 0) throw stop(`cannot read the HEAD entry of ${rel} (git ls-tree failed with an existing HEAD) — refusing to mint (fail closed)`);
+  const recordsZ = parseZRecords(out.stdout);
+  if (recordsZ == null) throw stop(`cannot parse the HEAD entry of ${rel} (unterminated git ls-tree output) — refusing to mint (fail closed)`);
+  if (recordsZ.length === 0) return null;
+  const entry = splitZEntry(recordsZ[0], TREE_META_RE);
+  if (recordsZ.length > 1 || entry == null || entry.path !== rel) {
+    throw stop(`cannot parse the HEAD entry of ${rel} (unexpected git ls-tree output) — refusing to mint (fail closed)`);
+  }
+  if (entry.meta[2] !== 'blob') {
+    throw stop(`the HEAD entry of ${rel} is a ${entry.meta[2]}, not a blob — an unsupported pre-state class (fail closed)`);
+  }
+  return { mode: entry.meta[1], sha: entry.meta[3] };
+};
+
+const readBlob = (top, sha, runGit) => {
+  const out = runGit(['cat-file', 'blob', sha], top);
+  if (out.error || out.status !== 0) throw stop(`cannot read blob ${sha} from the object store — refusing to mint (fail closed)`);
+  return out.stdout;
+};
+
+// Byte-level removal of ONE file's section from a git diff buffer. Hunk lines start with
+// [ +\-\\@], so a line starting "diff --git " is always a section header; the declared path is
+// plain-ASCII by refusal, so its header is these exact bytes. No section = a no-op mask.
+const DIFF_SECTION_START = Buffer.from('\ndiff --git ');
+const removeDiffSection = (buf, rel) => {
+  const header = Buffer.from(`diff --git a/${rel} b/${rel}\n`);
+  let at = -1;
+  if (buf.subarray(0, header.length).equals(header)) at = 0;
+  else {
+    const i = buf.indexOf(Buffer.concat([Buffer.from('\n'), header]));
+    if (i !== -1) at = i + 1;
+  }
+  if (at === -1) return buf;
+  const next = buf.indexOf(DIFF_SECTION_START, at + header.length - 1);
+  const end = next === -1 ? buf.length : next + 1;
+  return Buffer.concat([buf.subarray(0, at), buf.subarray(end)]);
+};
+
+// One untracked entry's payload chunks, branch-for-branch the frozen core's discipline
+// (computeFingerprintPayload) — the NULL-mask parity test pins the byte equality.
+const untrackedEntryChunks = (top, rel, lstat) => {
+  const full = join(top, rel);
+  let stat = null;
+  try {
+    stat = lstat(full);
+  } catch {
+    stat = null;
+  }
+  if (isNeverCommittableStat(stat)) return [];
+  if (stat?.isSymbolicLink()) {
+    let target = '?';
+    try {
+      target = readlinkSync(full);
+    } catch {
+      target = '?';
+    }
+    return [Buffer.from(`untracked-symlink:${rel} -> ${target}\n`)];
+  }
+  if (!stat?.isFile()) return [Buffer.from(`untracked-nonregular:${rel}\n`)];
+  if (isBinaryFile(full)) return [Buffer.from(`untracked-binary:${rel}\n`)];
+  return [Buffer.from(`untracked:${rel}\n`), readFileSync(full)];
+};
+
+// ONE captured read set — every assembly over it (masked and unmasked) binds the SAME tree
+// snapshot, so a tree move between two independent snapshots can never be certified. The three
+// git reads themselves are separate processes; that window is the frozen core's own inherent
+// residual and stays declared, not closed.
+const captureFingerprintPieces = (cwd, { lstat = lstatSync } = {}) => {
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  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);
+  if (staged == null || unstaged == null || untrackedZ == null) return null;
+  const entries = untrackedZ.toString('utf8').split('\0').filter(Boolean)
+    .map((rel) => ({ rel, chunks: untrackedEntryChunks(top, rel, lstat) }));
+  return { staged, unstaged, entries };
+};
+
+// mask: null = the exact frozen-core payload; { layer: 'diff', rel } removes the path's unstaged
+// section (its pre-state section is EMPTY by the clean-at-path rule); { layer: 'untracked', rel,
+// insert, preBytes } splices the untracked entry (git emits ls-files sorted by path bytes).
+const assembleMaskedPayload = (pieces, mask) => {
+  const unstaged = mask?.layer === 'diff' ? removeDiffSection(pieces.unstaged, mask.rel) : pieces.unstaged;
+  let entries = pieces.entries;
+  if (mask?.layer === 'untracked') {
+    entries = entries.filter((e) => e.rel !== mask.rel);
+    if (mask.insert) {
+      const at = entries.findIndex((e) => e.rel > mask.rel);
+      entries = [...entries];
+      entries.splice(at === -1 ? entries.length : at, 0, { rel: mask.rel, chunks: [Buffer.from(`untracked:${mask.rel}\n`), mask.preBytes] });
+    }
+  }
+  return Buffer.concat([pieces.staged, unstaged, ...entries.flatMap((e) => e.chunks)]);
+};
+
+export const computeMaskedFingerprintPayload = (cwd, mask = null, fsx) => {
+  const pieces = captureFingerprintPieces(cwd, fsx);
+  return pieces == null ? null : assembleMaskedPayload(pieces, mask);
+};
+
+// mintBookkeepingDelta: the FULL pre-state arrives as EXPLICIT inputs (pre-change worktree bytes +
+// the presence class; tracked-ness derives from the window-constant HEAD/index layers) — never
+// reconstructed from ambient git state. The computation only READS: the working tree is never
+// mutated. The mint refuses unless the masked recompute reproduces fingerprintBefore — an
+// unconfined delta never lands; the proof payload persists so the checker can verify a PROVEN
+// mint against a bare declaration.
+export const mintBookkeepingDelta = ({ cwd = process.cwd(), env = process.env, deps = {}, path: rel, fingerprintBefore, preContent = null, timestamp = new Date().toISOString() } = {}) => {
+  if (typeof fingerprintBefore !== 'string' || !HEX64_RE.test(fingerprintBefore)) {
+    throw stop('fingerprintBefore must be the 64-hex PRE-DELTA tree fingerprint — the proof compares the masked recompute against it (fail closed)');
+  }
+  const lex = lexicalRepoRelative(rel);
+  if (!lex.ok) throw stop(`the declared path must be lexically repo-relative — ${lex.reason} (fail closed)`);
+  if (pathNeedsGitQuoting(rel)) {
+    throw stop(`the declared path "${rel}" needs git diff-header quoting — an unsupported pre-state class (the masked recompute matches plain header bytes only; fail closed)`);
+  }
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  if (top == null) throw stop('not inside a git work tree — the custody proof has no meaning outside the fingerprint domain; refusing to mint');
+  const preBytes = preContent == null ? null : Buffer.from(preContent);
+  if (preBytes !== null && bufferLooksBinary(preBytes)) {
+    throw stop(`the pre-change bytes of ${rel} carry binary content — an unsupported pre-state class (fail closed)`);
+  }
+  const full = join(top, rel);
+  const st = lstatNoFollow(full, deps.lstat ?? lstatSync);
+  if (st?.isSymbolicLink()) throw stop(`the declared path ${rel} is a symlink — an unsupported pre-state class (fail closed)`);
+  if (st && !st.isFile()) throw stop(`the declared path ${rel} is a ${describeNonRegular(st)} — an unsupported pre-state class (fail closed)`);
+  if (st && (st.mode & 0o111) !== 0) throw stop(`the declared path ${rel} carries an executable mode — an unsupported pre-state class (mode motion cannot be expressed; fail closed)`);
+  const nowBytes = st ? readFileSync(full) : null;
+  if (nowBytes !== null && bufferLooksBinary(nowBytes)) {
+    throw stop(`the declared path ${rel} carries binary content — an unsupported pre-state class (fail closed)`);
+  }
+  const preClass = preBytes === null ? 'absent' : 'present';
+  if (preClass === 'absent' && nowBytes === null) {
+    throw stop('the absent→absent transition is unsupported — supported: present→present, present→absent, absent→present (fail closed)');
+  }
+  const runGit = deps.runGit ?? defaultRunGit;
+  const index = readIndexEntry(top, rel, runGit);
+  const head = readHeadEntry(top, rel, runGit);
+  for (const [layer, entry] of [['index', index], ['HEAD', head]]) {
+    if (entry && entry.mode !== REGULAR_FILE_MODE) {
+      throw stop(`the ${layer} entry of ${rel} carries mode ${entry.mode} — an unsupported pre-state class (only plain ${REGULAR_FILE_MODE} regular files are expressible; fail closed)`);
+    }
+  }
+  if (index == null && head != null) {
+    throw stop(`the declared path ${rel} has a HEAD entry but no index entry (a staged deletion) — an unsupported pre-state class (fail closed)`);
+  }
+  const tracked = index != null || head != null;
+  const headBytes = head == null ? null : readBlob(top, head.sha, runGit);
+  const indexBytes = index == null ? null : readBlob(top, index.sha, runGit);
+  let mask;
+  if (tracked) {
+    if (preClass === 'absent') {
+      throw stop(`the declared path ${rel} is tracked while its pre-change worktree state is absent — a dirty pre-state at the declared path is an unsupported pre-state class (the masked proof covers a clean-at-path pre-state only; fail closed)`);
+    }
+    if (!preBytes.equals(indexBytes)) {
+      throw stop(`the declared path ${rel} has a dirty pre-state (the pre-change worktree bytes do not equal the index entry) — an unsupported pre-state class (the masked proof covers a clean-at-path pre-state only; fail closed)`);
+    }
+    mask = { layer: 'diff', rel };
+  } else {
+    // --no-index: the ignore ANSWER must come from the rules alone — with the index consulted, a
+    // tracked glob neighbor (feature-a.md vs the literal feature-[a].md) flips the answer and a
+    // genuinely ignored path would spuriously refuse to mint.
+    const ig = runGit(['check-ignore', '-q', '--no-index', '--', rel], top);
+    if (ig.error || (ig.status !== 0 && ig.status !== 1)) {
+      throw stop(`cannot decide the ignore state of ${rel} (git check-ignore failed) — refusing to mint (fail closed)`);
+    }
+    // An ignored path is outside the fingerprint domain in BOTH states — the mask is a no-op there.
+    // Honest limit: an untracked path's MODE is likewise invisible to the frozen payload in both
+    // states (an entry is name + bytes only) — untracked mode motion is neither expressible nor
+    // claimed; only the CURRENT tree's non-plain modes refuse by name above.
+    mask = { layer: 'untracked', rel, insert: preClass === 'present' && ig.status !== 0, preBytes };
+  }
+  const pieces = captureFingerprintPieces(cwd, deps);
+  if (pieces == null) throw stop('cannot capture the fingerprint read set (a git probe failed) — refusing to mint (fail closed)');
+  // Bracket: the declared path must still be EXACTLY what the class checks and contentDigest
+  // observed — the no-follow class checks repeat first, then presence + bytes must match, so the
+  // digest and the captured payload can never bind two different post-states.
+  const stAfter = lstatNoFollow(full, deps.lstat ?? lstatSync);
+  if (stAfter?.isSymbolicLink()) throw stop(`the declared path ${rel} is a symlink — an unsupported pre-state class (fail closed)`);
+  if (stAfter && !stAfter.isFile()) throw stop(`the declared path ${rel} is a ${describeNonRegular(stAfter)} — an unsupported pre-state class (fail closed)`);
+  if (stAfter && (stAfter.mode & 0o111) !== 0) throw stop(`the declared path ${rel} carries an executable mode — an unsupported pre-state class (mode motion cannot be expressed; fail closed)`);
+  const bytesAfter = stAfter ? readFileSync(full) : null;
+  const declaredMoved = (stAfter == null) !== (nowBytes === null)
+    || (nowBytes !== null && bytesAfter !== null && !bytesAfter.equals(nowBytes));
+  if (declaredMoved) {
+    throw stop(`the declared path ${rel} moved under the mint (its bytes or presence changed during the capture) — contentDigest and the captured payload must bind ONE post-state; retry on a quiescent tree (fail closed)`);
+  }
+  const maskedFingerprint = sha256Hex(assembleMaskedPayload(pieces, mask));
+  if (maskedFingerprint !== fingerprintBefore) {
+    throw stop(`the delta is NOT confined to the declared path ${rel} — the masked revert-and-recompute (${maskedFingerprint.slice(0, 12)}…) does not reproduce fingerprintBefore (${fingerprintBefore.slice(0, 12)}…); something else moved in the window (fail closed)`);
+  }
+  // Both fingerprints derive from the ONE captured read set — a tree move between two independent
+  // snapshots can never be certified as a confined delta.
+  const fingerprintAfter = sha256Hex(assembleMaskedPayload(pieces, null));
+  const record = {
+    schema: FLOW_SCHEMA_VERSION, kind: 'bookkeeping-delta', fingerprintBefore, fingerprintAfter,
+    path: rel, contentDigest: nowBytes === null ? null : sha256Hex(nowBytes),
+    custodyProof: {
+      preClass, tracked,
+      headDigest: headBytes === null ? null : sha256Hex(headBytes),
+      indexDigest: indexBytes === null ? null : sha256Hex(indexBytes),
+      worktreeDigest: preBytes === null ? null : sha256Hex(preBytes),
+      maskedFingerprint,
+    },
+    base: resolveBase(cwd), timestamp,
+  };
+  const { writtenPath } = appendFlowRecord({ cwd, record, env, deps });
+  return { writtenPath, record, digest: canonicalFlowDigest(record) };
+};

package/tools/flow-finding-manifest.mjs

@@ -0,0 +1,70 @@
+// flow-finding-manifest.mjs — the wrapper finding manifest (Phase 4.2, Decision 2 / P5 / P24): the
+// SAFE nonce grammar, the manifest filename prefix and the basename derived from the dispatch
+// identity, the closed manifest shape, and the ONE fatal-UTF-8 decoder both kit consumers share.
+// Split out of flow-record.mjs unchanged (baseline-practices tranche 3), which now re-exports every
+// name here.
+//
+// Pure form: no filesystem, no git, no CLI, no side effects on import — it validates and DERIVES a
+// name, it never opens the file the name denotes. Imports run ONE way: the vocabulary leaf owns the
+// schema version and the shared form bindings, and nothing here reaches back up to the facade.
+
+import { FLOW_SCHEMA_VERSION, isHex64, isNonEmptyString, isPlainObject, refuse } from './flow-vocabulary.mjs';
+
+// ── the wrapper finding manifest (Phase 4.2, Decision 2 / P5 / P24) — pure form ──────────────────
+
+// The SAFE nonce grammar (containment-checked): the nonce enters a DERIVED FILENAME in the git
+// dir, so only this closed byte set is accepted — anything else refuses before a name composes.
+export const SAFE_NONCE_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+export const FINDING_MANIFEST_PREFIX = 'agent-workflow-finding-manifest-';
+
+// The manifest filename derives from the DISPATCH IDENTITY {backend, nonce} — two backends can
+// never collide on one nonce (P24). Both halves are containment-checked; null on any violation.
+export const findingManifestBasename = (backend, nonce) => {
+  if (typeof backend !== 'string' || !SAFE_NONCE_RE.test(backend)) return null;
+  if (typeof nonce !== 'string' || !SAFE_NONCE_RE.test(nonce)) return null;
+  return `${FINDING_MANIFEST_PREFIX}${backend}-${nonce}.json`;
+};
+
+// The closed manifest shape {schema, backend, nonce, fingerprint, findings} (P24) — findings is
+// the wrapper-captured findings payload VERBATIM (form-provable; semantics stay an honest limit).
+const FINDING_MANIFEST_KEYS = ['schema', 'backend', 'nonce', 'fingerprint', 'findings'];
+
+export const validateFindingManifest = (manifest) => {
+  if (!isPlainObject(manifest)) return refuse('finding manifest: not an object');
+  const stray = Object.keys(manifest).find((k) => !FINDING_MANIFEST_KEYS.includes(k));
+  if (stray !== undefined) return refuse(`finding manifest: unknown field "${stray}" — the key set is closed (fail closed)`);
+  const missing = FINDING_MANIFEST_KEYS.find((k) => !(k in manifest));
+  if (missing !== undefined) return refuse(`finding manifest: missing field "${missing}"`);
+  if (manifest.schema !== FLOW_SCHEMA_VERSION) {
+    return refuse(`finding manifest: unknown schema ${JSON.stringify(manifest.schema)} — this reader accepts schema ${FLOW_SCHEMA_VERSION} only (fail closed)`);
+  }
+  if (typeof manifest.backend !== 'string' || !SAFE_NONCE_RE.test(manifest.backend)) return refuse('finding manifest: backend must satisfy the safe name grammar ([A-Za-z0-9._-]{1,64})');
+  if (typeof manifest.nonce !== 'string' || !SAFE_NONCE_RE.test(manifest.nonce)) return refuse('finding manifest: nonce must satisfy the safe nonce grammar ([A-Za-z0-9._-]{1,64})');
+  if (manifest.fingerprint !== null && !isHex64(manifest.fingerprint)) return refuse('finding manifest: fingerprint must be a 64-hex tree fingerprint, or null when the wrapper could not compute one');
+  if (!isNonEmptyString(manifest.findings)) return refuse('finding manifest: findings must be the non-empty captured findings payload (one string)');
+  if (!manifest.findings.isWellFormed()) return refuse('finding manifest: findings must be a well-formed Unicode string — utf8-hashing a lone surrogate would substitute U+FFFD and corrupt the findingDigest domain (fail closed)');
+  return { ok: true };
+};
+
+// The ONE manifest reader both kit consumers share (flow-writer's consult arm, the
+// receipt-deadline runner): FATAL UTF-8 decode — a lossy toString would substitute U+FFFD and
+// silently mutate the digest domain — with ignoreBOM, so a BOM-prefixed file keeps refusing at
+// JSON.parse exactly as the pre-helper path did (no behavior widening).
+export const decodeFindingManifest = (bytes) => {
+  let text;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return refuse('finding manifest: not valid UTF-8 — a lossy decode would silently mutate the findings digest domain (fail closed)');
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch {
+    return refuse('finding manifest: not valid JSON (fail closed)');
+  }
+  const valid = validateFindingManifest(manifest);
+  if (!valid.ok) return valid;
+  return { ok: true, manifest };
+};

package/tools/flow-legality.mjs

@@ -0,0 +1,248 @@
+// flow-legality.mjs — the two raw-order legality walks over an in-memory record list: chain
+// sequence legality (validateChainSequence, with the private round-revision rule it enforces) and
+// stateful-kind supersession legality (validateSupersessions). Split out of flow-record.mjs
+// unchanged (baseline-practices tranche 3), which now re-exports both names here.
+//
+// Pure form: no filesystem, no git, no CLI, no side effects on import. RAW order is the input — the
+// authoritative latest-per-key view deliberately never reaches these walks. Reference RESOLUTION
+// against a real store lands with flow-store/flow-check; this module resolves references only
+// inside the list it is handed. The HIGHEST leaf of the family: it composes the vocabulary, the
+// shape validator and the identity digests, and nothing here reaches back up to the facade.
+
+import { ALLOWED_TRANSITIONS, CHAIN_KIND, PLAN_LANE_PURPOSES, refuse } from './flow-vocabulary.mjs';
+import { validateFlowRecord } from './flow-record-shape.mjs';
+import { canonicalFlowDigest, flowCanonicalSerialization } from './flow-record-identity.mjs';
+
+// A same-index round REVISION re-states its round: opensFrom/base/fingerprint/commitEpoch are
+// byte-equal to the previous version (the receipt attests the DISPATCHED tree, even when the live
+// tree has moved on), existing ledger entries keep their order (a pending dispatch may land IN
+// PLACE — both digests arrive together; a landed entry stays byte-identical), and new entries
+// append only at the tail. Entry equality is canonical, never insertion-order-sensitive.
+const validateRoundRevision = (prev, r) => {
+  for (const field of ['opensFrom', 'base', 'fingerprint', 'commitEpoch']) {
+    if (r[field] !== prev[field]) {
+      return refuse(`chain sequence: a round revision re-states its round — ${field} stays unchanged (the receipt attests the DISPATCHED tree)`);
+    }
+  }
+  if (r.dispatches.length < prev.dispatches.length) {
+    return refuse('chain sequence: a round revision never regresses its dispatch ledger (an entry disappeared)');
+  }
+  for (let i = 0; i < prev.dispatches.length; i += 1) {
+    const before = prev.dispatches[i];
+    const after = r.dispatches[i];
+    if (flowCanonicalSerialization(before) === flowCanonicalSerialization(after)) continue;
+    const landedInPlace = before.receiptDigest === null && after.receiptDigest !== null
+      && flowCanonicalSerialization({ ...after, receiptDigest: null, findingManifestDigest: null }) === flowCanonicalSerialization(before);
+    if (!landedInPlace) {
+      return refuse(`chain sequence: a round revision never regresses or mutates its dispatch ledger (entry ${i} — only pending → landed enriches, in place)`);
+    }
+  }
+  if (r.dispositions.length < prev.dispositions.length) {
+    return refuse('chain sequence: a round revision never regresses its disposition ledger (an entry disappeared)');
+  }
+  for (let i = 0; i < prev.dispositions.length; i += 1) {
+    if (flowCanonicalSerialization(prev.dispositions[i]) !== flowCanonicalSerialization(r.dispositions[i])) {
+      return refuse(`chain sequence: a round revision never regresses its disposition ledger (entry ${i} — existing dispositions stay byte-identical, new ones append at the tail)`);
+    }
+  }
+  return { ok: true };
+};
+
+// ── chain sequence legality (raw order, one chain) ────────────────────────────────────────────────
+
+// validateChainSequence(records) → { ok } | { ok: false, reason }. Input: the RAW-order chain
+// records of ONE plan's chain. Enforces: starts at adoption and adoption never recurs (#44/#58);
+// serial-monotonic step grouping with closure scoped per {cycle, stepId} (a stepId reopens in a
+// LATER cycle through an ordinary opener — the redesign valve); the within-step successor table;
+// a step opens with "round" carrying the prior-terminal reference (structural half — digest
+// resolution against the store lands with flow-check); a boundary re-baseline records disjoint
+// base motion anchored to the prior terminal without reopening anything; park admits only resume
+// and both preserve the pre-park {cycle, round}; complete admits no successor. Park/resume/complete
+// are explicit writer actions — this validator only refuses (#59).
+export const validateChainSequence = (records) => {
+  if (!Array.isArray(records)) return refuse('chain sequence: records must be an array');
+  if (records.length === 0) return { ok: true };
+  for (const r of records) {
+    if (r?.kind !== CHAIN_KIND) return refuse(`chain sequence: the validator accepts chain records only (got kind ${JSON.stringify(r?.kind)})`);
+    const v = validateFlowRecord(r);
+    if (!v.ok) return refuse(`chain sequence: malformed member — ${v.reason}`);
+    if (r.planId !== records[0].planId) return refuse(`chain sequence: one validator run covers one plan's chain (got "${records[0].planId}" and "${r.planId}")`);
+    if (r.owner !== records[0].owner) return refuse(`chain sequence: chain records never migrate owners — every record carries the adoption owner ("${records[0].owner}", got "${r.owner}"); an ownership transfer needs an explicit protocol, never a silent field change`);
+  }
+  if (records[0].purpose !== 'adoption') {
+    return refuse(`chain sequence: the chain starts at adoption — first record is "${records[0].purpose}"`);
+  }
+  const closureKey = (cycle, stepId) => JSON.stringify([cycle, stepId]);
+  const state = {
+    mode: 'boundary',
+    parked: null,
+    completed: false,
+    currentStep: null,
+    stepCycle: null,
+    currentRound: null,
+    lastPurpose: null,
+    lastTerminated: null,
+    boundaryRound: records[0].round,
+    closedSteps: new Set(),
+    lastCycle: records[0].cycle,
+    lastEpoch: records[0].commitEpoch,
+    roundLedgers: new Map(),
+  };
+  const contextCycle = () => (state.mode === 'in-step' ? state.stepCycle : state.lastCycle);
+  const contextRound = () => (state.mode === 'in-step' ? state.currentRound : state.boundaryRound);
+  const ledgerKey = (r) => JSON.stringify([r.cycle, r.stepId, r.round]);
+  for (const r of records.slice(1)) {
+    const p = r.purpose;
+    if (state.completed) return refuse('chain sequence: complete admits no successor');
+    if (r.cycle < state.lastCycle) return refuse(`chain sequence: the cycle index is monotonic (${state.lastCycle} → ${r.cycle})`);
+    // A same-index round record is a LEDGER REVISION — a non-lifecycle enrichment that repeats the
+    // DISPATCHED tree's epoch and never enters the lifecycle epoch cursor.
+    const isRevision = p === 'round' && state.mode === 'in-step' && state.parked === null
+      && r.stepId === state.currentStep && r.round === state.currentRound;
+    if (!isRevision) {
+      if (r.commitEpoch < state.lastEpoch) return refuse(`chain sequence: commitEpoch never regresses (${state.lastEpoch} → ${r.commitEpoch})`);
+      state.lastEpoch = r.commitEpoch;
+    }
+    if (state.parked !== null) {
+      if (p !== 'resume') return refuse(`chain sequence: park admits only resume (got "${p}")`);
+      if (r.cycle !== state.parked.cycle || r.round !== state.parked.round) {
+        return refuse(`chain sequence: resume must carry the pre-park cycle and round (${state.parked.cycle}/${state.parked.round}, got ${r.cycle}/${r.round}) — a new cycle starts by an explicit transition after resume`);
+      }
+      state.parked = null;
+      continue;
+    }
+    if (p === 'adoption') return refuse("chain sequence: adoption is only ever the chain's first record");
+    if (PLAN_LANE_PURPOSES.includes(p)) {
+      if (p === 'park') {
+        if (r.cycle !== contextCycle() || r.round !== contextRound()) {
+          return refuse(`chain sequence: park must carry the pre-park cycle and round (${contextCycle()}/${contextRound()}, got ${r.cycle}/${r.round})`);
+        }
+        state.parked = { cycle: r.cycle, round: r.round };
+      } else if (p === 'resume') {
+        return refuse('chain sequence: resume without a preceding park');
+      } else {
+        if (state.mode === 'in-step') return refuse('chain sequence: complete may not interrupt an open step — the step ends at converged');
+        state.completed = true;
+        state.lastCycle = r.cycle;
+      }
+      continue;
+    }
+    if (state.mode === 'in-step') {
+      if (r.stepId !== state.currentStep) {
+        return refuse(`chain sequence: step sequences are serial — a record of step "${r.stepId}" interleaves open step "${state.currentStep}"`);
+      }
+      if (r.cycle !== state.stepCycle) return refuse('chain sequence: the cycle changes only at a step boundary');
+      if (!ALLOWED_TRANSITIONS.withinStep[state.lastPurpose].includes(p)) {
+        return refuse(`chain sequence: illegal within-step transition ${state.lastPurpose} → ${p} (allowed: ${ALLOWED_TRANSITIONS.withinStep[state.lastPurpose].join(', ')})`);
+      }
+      if (p === 'round') {
+        if (r.round === state.currentRound) {
+          const revised = validateRoundRevision(state.roundLedgers.get(ledgerKey(r)), r);
+          if (!revised.ok) return revised;
+          state.roundLedgers.set(ledgerKey(r), r);
+          continue;
+        }
+        if (r.round < state.currentRound) return refuse(`chain sequence: the round index must increase within a step (${state.currentRound} → ${r.round})`);
+        if (r.opensFrom !== null) return refuse('chain sequence: only a step-opening round carries a prior-terminal reference');
+        state.currentRound = r.round;
+        state.roundLedgers.set(ledgerKey(r), r);
+      } else if (r.round !== state.currentRound) {
+        return refuse(`chain sequence: a non-round record carries its step's current round index (${state.currentRound}, got ${r.round})`);
+      }
+      state.lastPurpose = p;
+      if (p === 'converged') {
+        state.mode = 'boundary';
+        state.closedSteps.add(closureKey(state.stepCycle, state.currentStep));
+        state.lastTerminated = { step: state.currentStep, round: state.currentRound, cycle: state.stepCycle };
+        state.boundaryRound = state.currentRound;
+      }
+    } else if (p === 'unfreeze') {
+      if (state.lastTerminated === null) return refuse('chain sequence: unfreeze requires a prior converged terminal');
+      if (r.stepId !== state.lastTerminated.step) {
+        return refuse(`chain sequence: unfreeze reopens only the step that just converged ("${state.lastTerminated.step}", got "${r.stepId}")`);
+      }
+      if (r.round !== state.lastTerminated.round) return refuse('chain sequence: unfreeze carries the converged round index');
+      if (r.cycle !== state.lastTerminated.cycle) {
+        return refuse("chain sequence: unfreeze reopens only in its terminal's cycle — a later cycle reopens the stepId through an ordinary opening round");
+      }
+      state.mode = 'in-step';
+      state.currentStep = r.stepId;
+      state.stepCycle = r.cycle;
+      state.currentRound = r.round;
+      state.lastPurpose = 'unfreeze';
+      state.closedSteps.delete(closureKey(r.cycle, r.stepId));
+    } else if (p === 're-baseline') {
+      const anchorStep = state.lastTerminated === null ? null : state.lastTerminated.step;
+      if (r.stepId !== anchorStep) {
+        return refuse(`chain sequence: a boundary re-baseline anchors to the prior terminal's stepId (${JSON.stringify(anchorStep)}, got ${JSON.stringify(r.stepId)}) — it reopens nothing`);
+      }
+      if (r.round !== state.boundaryRound) return refuse(`chain sequence: a boundary re-baseline carries the boundary round index (${state.boundaryRound}, got ${r.round})`);
+      if (r.cycle !== state.lastCycle) return refuse('chain sequence: a re-baseline never moves the cycle — base motion is not a redesign');
+    } else if (p === ALLOWED_TRANSITIONS.stepOpening) {
+      if (state.closedSteps.has(closureKey(r.cycle, r.stepId))) {
+        return refuse(`chain sequence: step "${r.stepId}" already converged in cycle ${r.cycle} — a converged step reopens only through the unfreeze lane`);
+      }
+      if (r.opensFrom === null) {
+        return refuse("chain sequence: a step-opening round must carry the prior-terminal reference (opensFrom) — the plan's first step references the adoption record itself");
+      }
+      if (r.round < 1) return refuse('chain sequence: a step opens at round 1 or later');
+      state.mode = 'in-step';
+      state.currentStep = r.stepId;
+      state.stepCycle = r.cycle;
+      state.currentRound = r.round;
+      state.lastPurpose = 'round';
+      state.roundLedgers.set(ledgerKey(r), r);
+    } else {
+      return refuse(`chain sequence: a step sequence opens with "${ALLOWED_TRANSITIONS.stepOpening}" (got "${p}")`);
+    }
+    state.lastCycle = r.cycle;
+  }
+  return { ok: true };
+};
+
+// ── stateful-kind supersession legality (raw order, in-memory list) ───────────────────────────────
+
+// validateSupersessions(records) → { ok } | { ok: false, reason }. Walks RAW order and resolves
+// supersession targets among EARLIER records by per-record canonical digest: down-mark-up/clear
+// must target an earlier down-mark of the SAME backend; a maintainer-override chain is linear per
+// veto instance — the first override carries supersedes: null, every later one must supersede the
+// CURRENT head (a stale target would fork the chain and let latest-per-key bury a live override
+// without explicit supersession, #56). Out-of-order and mis-targeted supersessions refuse by name.
+export const validateSupersessions = (records, digestOf = canonicalFlowDigest) => {
+  const seen = new Map();
+  const overrideHeads = new Map();
+  const activeMarks = new Map();
+  for (const r of records) {
+    if (r.kind === 'down-mark') {
+      if (activeMarks.has(r.backend)) {
+        return refuse(`down-mark: backend "${r.backend}" already carries an ACTIVE down-mark — it must be explicitly closed by up/clear before a new mark lands (supersession is explicit, never silent)`);
+      }
+      activeMarks.set(r.backend, digestOf(r));
+    }
+    if (r.kind === 'down-mark-up' || r.kind === 'down-mark-clear') {
+      const target = seen.get(r.target);
+      if (target === undefined) return refuse(`${r.kind}: the supersession target does not resolve to an EARLIER record (out-of-order or unknown) — a supersession lands only after its down-mark`);
+      if (target.kind !== 'down-mark') return refuse(`${r.kind}: the supersession target is a ${target.kind}, not a down-mark (mis-targeted)`);
+      if (target.backend !== r.backend) return refuse(`${r.kind}: the supersession target belongs to backend "${target.backend}", not "${r.backend}" (mis-targeted)`);
+      const active = activeMarks.get(r.backend);
+      if (active === undefined) return refuse(`${r.kind}: no active down-mark for backend "${r.backend}" — the family is closed (or never opened); a new down-mark opens a new instance`);
+      if (r.target !== active) return refuse(`${r.kind}: the supersession targets a stale down-mark — up/clear must target the backend's ACTIVE mark`);
+      activeMarks.delete(r.backend);
+    }
+    if (r.kind === 'maintainer-override') {
+      const head = overrideHeads.get(r.vetoReceiptDigest);
+      if (r.supersedes === null) {
+        if (head !== undefined) return refuse('maintainer-override: only the first override of a veto instance carries supersedes: null — a later override must supersede the CURRENT head');
+      } else {
+        const target = seen.get(r.supersedes);
+        if (target === undefined) return refuse('maintainer-override: supersedes does not resolve to an EARLIER record (out-of-order or unknown)');
+        if (target.kind !== 'maintainer-override') return refuse(`maintainer-override: supersedes must target a maintainer-override record, not a ${target.kind} (mis-targeted)`);
+        if (target.vetoReceiptDigest !== r.vetoReceiptDigest) return refuse('maintainer-override: the supersession crosses veto instances — one override binds exactly one veto instance (mis-targeted)');
+        if (r.supersedes !== head) return refuse('maintainer-override: supersedes targets a STALE override — a later override must supersede the CURRENT head of its veto instance');
+      }
+      overrideHeads.set(r.vetoReceiptDigest, digestOf(r));
+    }
+    seen.set(digestOf(r), r);
+  }
+  return { ok: true };
+};