@sabaiway/agent-workflow-kit 5.10.0 → 5.11.1

package/tools/flow-adoption-mint.mjs

@@ -0,0 +1,70 @@
+// flow-adoption-mint.mjs — the adoption mint (#58): the frontmatter planId reader and mintAdoption,
+// which binds a plan's chain identity to {frontmatter planId, plan content digest} and lands the
+// chain's FIRST record. Split out of flow-store.mjs unchanged (baseline-practices tranche 2); the
+// facade re-exports both names.
+//
+// The plan file is READ, never written. 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 below is a deliberate copy rather than a sideways import.
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { FLOW_SCHEMA_VERSION, CHAIN_KIND, canonicalFlowDigest } from './flow-record.mjs';
+import { resolveBase, computeTreeFingerprint } from './core-evidence.mjs';
+import { flowStoreStop, resolveFlowStorePath, readFlowStore, deriveFlowOwner } from './flow-store-read.mjs';
+import { appendFlowRecord } from './flow-append.mjs';
+
+const stop = flowStoreStop;
+const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+const PLAN_ID_FRONTMATTER_HINT = 'planId: <your-stable-plan-id>';
+
+// Identity binds only a CLOSED leading frontmatter block — an unterminated block never yields an
+// id; CRLF is normalized per line so line endings never fork chain identity.
+export const readPlanFrontmatterId = (text) => {
+  const lines = text.split('\n').map((line) => line.replace(/\r$/, ''));
+  if (lines[0]?.trim() !== '---') return null;
+  const close = lines.findIndex((line, i) => i > 0 && line.trim() === '---');
+  if (close === -1) return null;
+  for (const line of lines.slice(1, close)) {
+    const m = /^planId:[ \t]*(\S+)[ \t]*$/.exec(line);
+    if (m) return m[1];
+  }
+  return null;
+};
+
+export const mintAdoption = ({ cwd = process.cwd(), env = process.env, deps = {}, planPath, planLabel, cycle = 1, commitEpoch = 0, timestamp = new Date().toISOString() } = {}) => {
+  const owner = deriveFlowOwner(cwd);
+  if (owner == null) throw stop('not inside a git work tree — the adoption mint derives the owning worktree and the tree fingerprint from git (fail closed)');
+  let planBytes;
+  try {
+    planBytes = readFileSync(resolve(cwd, planPath));
+  } catch (err) {
+    throw stop(`cannot read the plan file ${planPath} (${(err && err.code) || (err && err.message) || err}) — the adoption mint READS an existing plan file (fail closed)`);
+  }
+  const planId = readPlanFrontmatterId(planBytes.toString('utf8'));
+  if (planId == null) {
+    throw stop(`the plan file ${planPath} carries no frontmatter planId — plan filenames are never chain identity. Add this line inside a leading "---" frontmatter block:\n${PLAN_ID_FRONTMATTER_HINT}\nand re-run; the plan file is never written by this mint (fail closed)`);
+  }
+  const planDigest = sha256Hex(planBytes);
+  // A pre-append read purely for the NAMED refusal: the locked append would refuse a second
+  // adoption anyway, but only this comparison can surface whether the plan content still matches.
+  const resolved = resolveFlowStorePath(cwd, env);
+  const adopted = resolved == null ? undefined : readFlowStore(resolved).records
+    .find((r) => r.kind === CHAIN_KIND && r.purpose === 'adoption' && r.planId === planId);
+  if (adopted !== undefined) {
+    throw stop(adopted.planDigest === planDigest
+      ? `plan "${planId}" is already adopted (content digest unchanged — a rename never resets chain identity); adoption is only ever the chain's first record`
+      : `plan "${planId}" is already adopted and the plan file content no longer matches its adoption record (recorded ${adopted.planDigest.slice(0, 12)}…, current ${planDigest.slice(0, 12)}…) — re-adopting edited plan content is refused; the digest mismatch is surfaced, never silent`);
+  }
+  const fingerprint = computeTreeFingerprint(cwd);
+  if (fingerprint == null) throw stop('cannot compute the tree fingerprint — the adoption record binds {base, fingerprint} (fail closed)');
+  const record = {
+    schema: FLOW_SCHEMA_VERSION, kind: CHAIN_KIND, purpose: 'adoption', planId, cycle, round: 0,
+    commitEpoch, owner, base: resolveBase(cwd), timestamp, stepId: null, fingerprint,
+    planLabel: planLabel ?? planId, createdAt: timestamp, planDigest,
+  };
+  const { writtenPath } = appendFlowRecord({ cwd, record, env, deps });
+  return { writtenPath, record, digest: canonicalFlowDigest(record) };
+};

package/tools/flow-append.mjs

@@ -0,0 +1,309 @@
+// flow-append.mjs — the flow store's ONE write door (flow-orchestration Phase 2, extracted from
+// flow-store.mjs unchanged by baseline-practices tranche 2): the flow lane over the parameterized
+// createStoreAppendLane, the SEMANTIC append preflight, the two generic append entries, the
+// subset-run serializer + the pre-gate lock probe, and the Decision-7 locked subset-attempt factory.
+//
+// The lock/CAS discipline itself lives one module further down in store-append.mjs (delegation
+// Plan 1 D12); this leaf injects the flow store's nouns, env seams, knob names, validator, parser
+// and the per-kind legality the lane runs inside the critical section.
+//
+// Imports run ONE way: this module composes the two PURE leaves (flow-chain-state.mjs,
+// flow-subset-budget.mjs) and the read half; the two mint leaves compose THIS one. Nothing here
+// reaches back up to the flow-store.mjs facade — that edge would be the cycle
+// test/read-graph-purity.test.mjs reds.
+//
+// flowSemanticPreflight, deepFreezeClone and the lane's own captureRecordSnapshot/
+// appendResolvedRecord stay PRIVATE: the factory-only rule for subset-attempt records is kept by
+// NOT publishing them, so a hand-built record can never forge a fresh counting context.
+
+import {
+  FLOW_SCHEMA_VERSION, CHAIN_KIND, validateFlowRecord, validateChainSequence, validateSupersessions,
+  canonicalFlowDigest, subsetFoldBatchDigest, subsetGateIdsDigest, SUBSET_ATTEMPT_DIAGNOSIS_FROM,
+} from './flow-record.mjs';
+import { derivePregateSubsetIds, GATES_REL } from './gates-declaration.mjs';
+import { CONFIG_REL } from './orchestration-config.mjs';
+import { createStoreAppendLane } from './store-append.mjs';
+import {
+  flowStoreStop, resolveFlowStorePath, resolveFlowLockPath, parseFlowStoreText, deriveFlowOwner,
+} from './flow-store-read.mjs';
+import {
+  walkChainState, resolveRecordReference, isAuthoritativeReferenceTarget, validateOpenerReference,
+} from './flow-chain-state.mjs';
+import {
+  SUBSET_ATTEMPT_MAX_REDS, SUBSET_ATTEMPT_DIAGNOSIS_REDS, subsetAttemptState, subsetAttemptGate,
+} from './flow-subset-budget.mjs';
+
+const stop = flowStoreStop;
+
+// Wait bound + poll cadence; the env knobs keep hermetic tests off wall-clock.
+export const FLOW_LOCK_WAIT_MS = 10_000;
+export const FLOW_LOCK_POLL_MS = 100;
+
+// ── the shared append lane (D12) ──────────────────────────────────────────────────────────────────
+
+// The lock/CAS discipline, the fd-custody rules and the serialized append are the EXTRACTION of
+// exactly this module's former code into store-append.mjs, so behavior is unchanged by
+// construction: this store injects its nouns (every refusal still names the flow store), its env
+// seam and knob names, its typed-STOP factory, its record validator, its store-text parser, and
+// the SEMANTIC preflight below. The flow suites are the characterization bar for that claim.
+const flowAppendLane = createStoreAppendLane({
+  nouns: { store: 'flow store', adj: 'flow-store', record: 'flow record' },
+  envNames: { store: 'AW_FLOW_STORE', waitKnob: 'AW_FLOW_LOCK_WAIT_MS', pollKnob: 'AW_FLOW_LOCK_POLL_MS' },
+  stop,
+  resolveStorePath: resolveFlowStorePath,
+  resolveLockPath: resolveFlowLockPath,
+  validateRecord: validateFlowRecord,
+  parseStoreText: parseFlowStoreText,
+  lockWaitMs: FLOW_LOCK_WAIT_MS,
+  lockPollMs: FLOW_LOCK_POLL_MS,
+});
+
+const captureRecordSnapshot = flowAppendLane.captureRecordSnapshot;
+
+// ── the ONE append (validated, semantic-preflighted, lock-serialized, atomic) ─────────────────────
+
+// The store path is always RESOLVED (cwd/env), never caller-supplied — a raw path param would
+// bypass the absolute-normalization door the AW_FLOW_STORE seam enforces. Read, write, and unlock
+// all use the CANONICAL pair acquire returned — nothing is re-derived mid-append.
+export const appendFlowRecord = ({ cwd = process.cwd(), record, env = process.env, deps = {} } = {}) => {
+  const { line, snapshot } = captureRecordSnapshot(record);
+  // Round-9 fold: subset-attempt records are minted ONLY by the locked factory — foldBatch,
+  // subsetDigest, and attemptIndex are DERIVED inside its critical section, and a hand-built
+  // record could forge a fresh counting context and bypass the hard-stop budget.
+  if (snapshot.kind === 'subset-attempt') {
+    throw stop('subset-attempt records are minted ONLY by the locked append factory (appendSubsetAttempt) — a hand-built record could forge a fresh counting context and bypass the hard-stop budget (fail closed)');
+  }
+  return flowAppendLane.appendResolvedRecord({ cwd, env, deps, preflight: flowSemanticPreflight, makeRecord: () => ({ line, snapshot }) });
+};
+
+// appendFlowRecordWithPreflight — the generic lane plus a caller `preflight(records)` hook that
+// runs INSIDE the critical section on the locked store snapshot (Plan 4 Phase 3 / round-1 fold
+// F6): a writer's lock-free cap/completeness walk is advisory — the locked snapshot decides, so
+// a concurrent append can never slip a stale terminal (or a stranding round) through. The hook
+// receives a DEEP-FROZEN CLONE (round-1 fold M5): a buggy preflight throws on any mutation
+// attempt and can never skew the bytes the semantic validation and the write see. A throwing
+// preflight refuses the append with nothing written. The subset-attempt factory-only rule holds
+// on this lane too.
+export const appendFlowRecordWithPreflight = ({ cwd = process.cwd(), record, env = process.env, deps = {}, preflight = null } = {}) => {
+  const { line, snapshot } = captureRecordSnapshot(record);
+  if (snapshot.kind === 'subset-attempt') {
+    throw stop('subset-attempt records are minted ONLY by the locked append factory (appendSubsetAttempt) — a hand-built record could forge a fresh counting context and bypass the hard-stop budget (fail closed)');
+  }
+  return flowAppendLane.appendResolvedRecord({ cwd, env, deps, preflight: flowSemanticPreflight, makeRecord: (records) => {
+    if (preflight != null) preflight(deepFreezeClone(records));
+    return { line, snapshot };
+  } });
+};
+
+const deepFreezeClone = (value) => {
+  const freeze = (v) => {
+    if (v !== null && typeof v === 'object') {
+      Object.values(v).forEach(freeze);
+      Object.freeze(v);
+    }
+    return v;
+  };
+  return freeze(structuredClone(value));
+};
+
+// The SEMANTIC half of the append, handed to the shared lane and run by it INSIDE the critical
+// section on the LOCKED store snapshot (a writer's lock-free walk is advisory — only the locked
+// snapshot decides): per-kind chain legality, reference resolution, the closure rules, the
+// counting-context gate, and supersession legality. An illegal record never lands. Throws a typed
+// STOP; the lane releases the lock and re-throws.
+const flowSemanticPreflight = ({ records, snapshot, storePath }) => {
+  if (snapshot.kind === CHAIN_KIND) {
+    const chain = records.filter((r) => r.kind === CHAIN_KIND && r.planId === snapshot.planId);
+    const existingSeq = validateChainSequence(chain);
+    if (!existingSeq.ok) {
+      throw stop(`refusing to append to a flow store whose existing chain for plan "${snapshot.planId}" is already illegal (${existingSeq.reason}) — inspect ${storePath}; nothing was written (fail closed)`);
+    }
+    const candidateSeq = validateChainSequence([...chain, snapshot]);
+    if (!candidateSeq.ok) {
+      throw stop(`refusing an illegal chain record: ${candidateSeq.reason} — the append-only store never absorbs a record that permanently reddens the checker; nothing was written`);
+    }
+    // Reference RESOLUTION (#63) on top of the structural half above: a step-OPENING round must
+    // digest-reference the chain's prior terminal; a round REVISION re-states its reference
+    // byte-bound (validateRoundRevision), so it is never re-classified against a moved terminal.
+    if (snapshot.purpose === 'round' && snapshot.opensFrom !== null && walkChainState(chain).mode === 'boundary') {
+      const ref = validateOpenerReference(records, snapshot);
+      if (!ref.ok) throw stop(`refusing a step-opening round: ${ref.reason} — nothing was written`);
+    }
+    if (snapshot.purpose === 'refresh') {
+      if (resolveRecordReference(records, snapshot.refreshedRecord) === undefined) {
+        throw stop(`refusing a refresh whose refreshedRecord does not match the store (no record digests to ${snapshot.refreshedRecord.slice(0, 12)}…) — a re-attestation binds an existing record; nothing was written`);
+      }
+      if (!isAuthoritativeReferenceTarget(records, snapshot.refreshedRecord)) {
+        throw stop('refusing a refresh whose refreshedRecord targets a superseded record — a re-attestation binds the authoritative latest record of its key; nothing was written');
+      }
+    }
+  }
+  // The closure rule runs UNDER the lock on the captured snapshot — a writer's lock-free
+  // usability pre-check can race a concurrent up/clear, and a justification minted after its
+  // mark closed can never satisfy the decide layer (#25), so the store refuses to strand it.
+  if (snapshot.kind === 'degrade-justification') {
+    const closed = records.some((r) => (r.kind === 'down-mark-up' || r.kind === 'down-mark-clear') && r.target === snapshot.downMark);
+    if (closed) {
+      throw stop('refusing a degrade-justification whose down-mark is already closed by up/clear — minted-after-close can never satisfy (#25); nothing was written');
+    }
+  }
+  // The same P3-26 discipline for the consult-attestation (Phase-4): the writer derives
+  // {cycle, stepId, round} lock-free, so a concurrent converged/park/complete can close or move
+  // the step first — under the lock the named plan's chain must be LEGAL and hold an OPEN step
+  // (in-step, not parked, not completed) whose {cycle, stepId, round} EQUALS the record's; a
+  // stale consult context can never satisfy the decide layer, so the store refuses to strand it.
+  if (snapshot.kind === 'consult-attestation') {
+    const chain = records.filter((r) => r.kind === CHAIN_KIND && r.planId === snapshot.planId);
+    const seq = chain.length === 0 ? { ok: false, reason: 'no chain exists for that plan' } : validateChainSequence(chain);
+    if (!seq.ok) {
+      throw stop(`refusing a consult-attestation: the plan "${snapshot.planId}" chain is not a legal open carrier under the lock (${seq.reason}); nothing was written`);
+    }
+    const state = walkChainState(chain);
+    const open = state.mode === 'in-step' && !state.parked && !state.completed;
+    if (!open || state.stepId !== snapshot.stepId || state.cycle !== snapshot.cycle || state.round !== snapshot.round) {
+      const shown = !open
+        ? (state.completed ? 'the plan is completed' : state.parked ? 'the plan is parked' : 'no step is open')
+        : `the open step is "${state.stepId}" (cycle ${state.cycle}, round ${state.round})`;
+      throw stop(`refusing a consult-attestation whose {cycle, stepId, round} does not match the OPEN step under the lock — ${shown}; a consult binds the open step's round, and a stale context can never satisfy; nothing was written`);
+    }
+  }
+  // The Decision-7/8 counting-context gate runs UNDER the lock for BOTH append lanes (the
+  // factory computes a passing record; a hand-built one must satisfy the same rules).
+  if (snapshot.kind === 'subset-attempt') {
+    const gate = subsetAttemptGate(records, snapshot);
+    if (!gate.ok) throw stop(`refusing a subset-attempt: ${gate.reason} — nothing was written`);
+  }
+  const existingSup = validateSupersessions(records);
+  if (!existingSup.ok) {
+    throw stop(`refusing to append to a flow store whose existing records already violate supersession legality (${existingSup.reason}) — inspect ${storePath}; nothing was written (fail closed)`);
+  }
+  const candidateSup = validateSupersessions([...records, snapshot]);
+  if (!candidateSup.ok) {
+    throw stop(`refusing an illegal supersession: ${candidateSup.reason} — the append-only store never absorbs a record that permanently reddens the checker; nothing was written`);
+  }
+};
+
+// ── the Decision-7 subset-run serializer (round-6 fold) ──────────────────────────────────────────
+
+// --pre-review's WHOLE armed cycle (budget preflight → gates → append) holds this lock: without
+// it a parallel run executes gates whose red can no longer be recorded once the winner lands,
+// and an unrecorded red undercounts the budget ("EVERY subset-run red counts"). A SEPARATE lock
+// file beside the store — never the store lock itself, so appends from other lanes never block
+// behind a minutes-long gate run — riding the same CAS/fd-custody/holder-liveness discipline: a
+// crashed holder surfaces as the named DEAD refusal with its rm recovery; a live holder is a
+// bounded loud wait (the queued run then re-reads the budget and re-decides).
+export const SUBSET_RUN_LOCK_INFIX = '.subset-run';
+
+export const acquireSubsetRunLock = ({ cwd = process.cwd(), env = process.env, deps = {} } = {}) => {
+  const resolved = flowAppendLane.resolveOrStop(cwd, env, 'serialize a subset run against');
+  const { lockPath, lockFd, lockIdentity } = flowAppendLane.acquireLock(`${resolved}${SUBSET_RUN_LOCK_INFIX}`, env, deps);
+  return { lockPath, release: () => flowAppendLane.releaseLock(lockPath, lockFd, lockIdentity, deps) };
+};
+
+// The pre-gate append-lock readiness probe (round-8 fold): acquire and immediately release the
+// ORDINARY append lock through the full acquire discipline — a DEAD/foreign/malformed lock or
+// an unwritable parent surfaces BEFORE any gate spends, with the acquire's own named refusal.
+// Stated residual: a lock landing between this probe and the post-run append still refuses at
+// append time — closing that would mean holding the append lock across the whole gate run.
+export const probeFlowAppendLock = ({ cwd = process.cwd(), env = process.env, deps = {} } = {}) => {
+  const resolved = flowAppendLane.resolveOrStop(cwd, env, 'probe');
+  const { lockPath, lockFd, lockIdentity } = flowAppendLane.acquireLock(resolved, env, deps);
+  const issue = flowAppendLane.releaseLock(lockPath, lockFd, lockIdentity, deps);
+  if (issue != null) throw issue;
+};
+
+// appendSubsetAttempt — the Decision-7 locked append factory: the chain identity is captured
+// BEFORE the gates run (the caller's `expected` {planId, cycle, stepId, round}) and re-checked
+// under the append lock against the OPEN owning chain; attemptIndex, foldBatch/subsetDigest
+// derivation, and the hard-stop state are computed from the captured store snapshot INSIDE the
+// critical section — a concurrent appender never duplicates an index, and a round/park/complete
+// landing mid-run refuses the append (never a silent misfile). subsetGateIds states what the
+// caller RAN — only the caller knows that — but it never DECIDES the counting context: the
+// factory re-derives the subset from the declaration + config itself (the R10 rider, via the
+// gates-declaration leaf) and refuses a mismatch, so a caller-chosen id list can never forge a
+// fresh subsetDigest and bypass the hard-stop budget.
+export const appendSubsetAttempt = ({ cwd = process.cwd(), env = process.env, deps = {}, expected, subsetGateIds, status, diagnosis = null, base, fingerprint, timestamp = new Date().toISOString() } = {}) => {
+  const owner = deriveFlowOwner(cwd);
+  if (owner == null) throw stop('not inside a git work tree — the subset-attempt mint derives the owning worktree from git (fail closed)');
+  if (expected == null || typeof expected.planId !== 'string' || expected.planId.length === 0
+    || !Number.isInteger(expected.cycle) || !Number.isInteger(expected.round)
+    || (expected.stepId !== null && typeof expected.stepId !== 'string')) {
+    throw stop('the captured chain identity must be {planId, cycle, stepId|null, round} — the factory re-checks exactly this projection under the lock (fail closed)');
+  }
+  if (!Array.isArray(subsetGateIds)) throw stop("subsetGateIds must be the derived subset's ordered gate-id array (fail closed)");
+  if (status !== 'green' && status !== 'red') throw stop(`status must be green | red (got ${JSON.stringify(status)}) — an unrunnable subset refuses with NO attempt record (fail closed)`);
+  if (diagnosis !== null && (typeof diagnosis !== 'string' || diagnosis.length === 0)) {
+    throw stop(`diagnosis must be null or a non-empty string (got ${JSON.stringify(diagnosis)}) — a mistyped input would otherwise record diagnosis-less silently (round-11 fold; fail closed)`);
+  }
+  let derived;
+  try {
+    derived = derivePregateSubsetIds(cwd);
+  } catch (err) {
+    throw stop(`the pregate subset cannot be re-derived (${(err && err.message) || err}) — an attempt records only a subset the declaration derives (R10; fail closed)`);
+  }
+  if (derived.length !== subsetGateIds.length || derived.some((id, i) => id !== subsetGateIds[i])) {
+    throw stop(`subsetGateIds [${subsetGateIds.join(', ')}] does not match the subset derived from ${GATES_REL} + ${CONFIG_REL} flow.pregateExclude [${derived.join(', ')}] — the factory re-derives the subset itself (R10), so a caller-chosen id list never binds a counting context (fail closed)`);
+  }
+  // Everything downstream binds the factory-owned DERIVED ids — the caller array stays mutable in
+  // the caller's hands (a deps lock-hook could rewrite it after the check above) and must never
+  // reach the digest domain.
+  const subsetIds = Object.freeze([...derived]);
+  let minted = null;
+  const value = flowAppendLane.appendResolvedRecord({ cwd, env, deps, preflight: flowSemanticPreflight, makeRecord: (records) => {
+    const chain = records.filter((r) => r.kind === CHAIN_KIND && r.planId === expected.planId);
+    if (chain.length === 0) throw stop(`no chain exists for plan "${expected.planId}" under the lock — the captured identity is stale; re-run the subset under the current context (fail closed)`);
+    const seq = validateChainSequence(chain);
+    if (!seq.ok) throw stop(`the plan "${expected.planId}" chain is illegal under the lock (${seq.reason}) — refusing to bind an attempt to it (fail closed)`);
+    if (chain[0].owner !== owner) throw stop(`the plan "${expected.planId}" chain is owned by "${chain[0].owner}", not this worktree ("${owner}") — a foreign chain never records this tree's attempts (fail closed)`);
+    const state = walkChainState(chain);
+    const open = !state.completed && !state.parked;
+    const held = open && state.cycle === expected.cycle && state.stepId === expected.stepId && (state.round ?? 0) === expected.round;
+    if (!held) {
+      const shown = state.completed ? 'the plan completed' : state.parked ? 'the plan parked' : `the open context is {cycle ${state.cycle}, step ${JSON.stringify(state.stepId)}, round ${state.round ?? 0}}`;
+      throw stop(`the chain identity moved under the run — captured {cycle ${expected.cycle}, step ${JSON.stringify(expected.stepId)}, round ${expected.round}}, but ${shown} under the lock (a round/park/complete landed mid-run); re-run the subset under the current context (fail closed)`);
+    }
+    if (expected.stepId === null && state.openers.length > 0) {
+      throw stop(`the plan "${expected.planId}" chain sits at a post-convergence boundary — the stepId-null context is legal only before the FIRST round (the adoption context, round-6 fold); open the next step round first (fail closed)`);
+    }
+    // Round-9 fold: the EXACTLY-ONE-open-owning-chain rule is re-derived UNDER the lock — an
+    // adoption/resume landing after the caller's preflight would otherwise record the attempt
+    // into an already-ambiguous context. (After the specific refusals above, so a parked or
+    // moved TARGET chain keeps its own named diagnosis.)
+    const openOwn = [...new Set(records.filter((r) => r.kind === CHAIN_KIND && r.owner === owner).map((r) => r.planId))].filter((planId) => {
+      const c = records.filter((r) => r.kind === CHAIN_KIND && r.planId === planId);
+      if (c[0].purpose !== 'adoption' || c[0].owner !== owner || !validateChainSequence(c).ok) return false;
+      const s = walkChainState(c);
+      return !s.completed && !s.parked;
+    });
+    if (openOwn.length !== 1 || openOwn[0] !== expected.planId) {
+      throw stop(`this worktree ("${owner}") owns ${openOwn.length} open chains under the lock (${openOwn.join(', ') || 'none'}) — an attempt records only when exactly ONE open owning chain exists and it is the captured one ("${expected.planId}"); a chain landed mid-run — re-run the subset under the current context (fail closed)`);
+    }
+    const probe = { planId: expected.planId, cycle: expected.cycle, stepId: expected.stepId, foldBatch: subsetFoldBatchDigest(expected), subsetDigest: subsetGateIdsDigest(subsetIds) };
+    const budget = subsetAttemptState(records, probe);
+    const attemptIndex = budget.nextIndex;
+    if (budget.reds >= SUBSET_ATTEMPT_DIAGNOSIS_REDS && (typeof diagnosis !== 'string' || diagnosis.length === 0)) {
+      throw stop(`attempt ${attemptIndex} follows ${budget.reds} reds at this counting context and requires a recorded diagnosis (Decision 8 — the blind budget is spent): investigate, then re-run with a non-empty diagnosis byte-distinct from the prior attempt's; never a wait-for-maintainer`);
+    }
+    if (attemptIndex < SUBSET_ATTEMPT_DIAGNOSIS_FROM && diagnosis != null) {
+      throw stop(`attempt ${attemptIndex} is inside the blind budget (attempts 1-2) — a diagnosis rides only attempt ${SUBSET_ATTEMPT_DIAGNOSIS_FROM} and later (Decision 8); drop the diagnosis input (the captured context may be stale — fail closed, never silently dropped)`);
+    }
+    const { line, snapshot } = captureRecordSnapshot({
+      schema: FLOW_SCHEMA_VERSION, kind: 'subset-attempt', planId: expected.planId, cycle: expected.cycle,
+      stepId: expected.stepId, foldBatch: probe.foldBatch, subsetDigest: probe.subsetDigest, attemptIndex,
+      ...(typeof diagnosis === 'string' ? { diagnosis } : {}), status, base, fingerprint, timestamp,
+    });
+    // Computed UNDER the lock from the captured snapshot — a lock-free preflight state could
+    // pick the wrong message under a concurrent append.
+    const consumedPermit = budget.reds >= SUBSET_ATTEMPT_MAX_REDS;
+    const redsAfter = budget.reds + (status === 'red' ? 1 : 0);
+    const creditsAfter = budget.credits - (consumedPermit ? 1 : 0);
+    minted = {
+      attemptIndex,
+      redsAtKey: redsAfter,
+      reopened: consumedPermit,
+      exhaustedAfter: redsAfter >= SUBSET_ATTEMPT_MAX_REDS && creditsAfter <= 0,
+    };
+    return { line, snapshot };
+  } });
+  return { ...value, ...minted, digest: canonicalFlowDigest(value.record) };
+};

package/tools/flow-chain-state.mjs

@@ -0,0 +1,91 @@
+// flow-chain-state.mjs — the chain-state walk and the generic prior-terminal reference validator
+// (#63): priorChainTerminal, walkChainState, resolveRecordReference, isAuthoritativeReferenceTarget
+// and validateOpenerReference. Split out of flow-store.mjs unchanged (baseline-practices tranche 2),
+// which now re-exports every name here.
+//
+// PURE over read results and the LOWEST of the store's five leaves: no store IO, no git, no fs, and
+// the record vocabulary is its only tools sibling. Imports run ONE way — flow-append.mjs composes
+// this module; nothing here reaches back up to the facade.
+
+import { CHAIN_KIND, canonicalFlowDigest, authoritativeFlowRecords } from './flow-record.mjs';
+
+const TERMINAL_PURPOSES = ['adoption', 'converged', 'complete'];
+
+// The record a step-opening round must reference: the latest converged/complete, else the adoption
+// record itself (the plan's first step — the exemption is explicit, never inferred).
+export const priorChainTerminal = (chain) => {
+  let terminal = null;
+  for (const r of chain) {
+    if (r.purpose === 'adoption' && terminal === null) terminal = r;
+    else if (r.purpose === 'converged' || r.purpose === 'complete') terminal = r;
+  }
+  return terminal;
+};
+
+// walkChainState(chain) → { mode, parked, completed, cycle, round, stepId, openers, lastTerminal }
+// over ONE plan's raw-order chain. Legality lives in validateChainSequence — callers run it first;
+// this walk only derives state, including each opener with its at-that-point prior terminal.
+export const walkChainState = (chain) => {
+  const state = {
+    mode: 'boundary', parked: false, completed: false,
+    cycle: chain[0]?.cycle ?? null, round: chain[0]?.round ?? null, stepId: null,
+    openers: [], lastTerminal: null,
+  };
+  for (const r of chain) {
+    state.cycle = r.cycle;
+    if (r.purpose === 'adoption') { state.lastTerminal = r; state.round = r.round; continue; }
+    if (r.purpose === 'park') { state.parked = true; continue; }
+    if (r.purpose === 'resume') { state.parked = false; continue; }
+    if (r.purpose === 'complete') { state.completed = true; state.lastTerminal = r; continue; }
+    if (r.purpose === 'converged') { state.mode = 'boundary'; state.lastTerminal = r; state.stepId = null; continue; }
+    if (r.purpose === 'unfreeze' && state.mode === 'boundary') { state.mode = 'in-step'; state.stepId = r.stepId; state.round = r.round; continue; }
+    if (r.purpose === 'round') {
+      if (state.mode === 'boundary') {
+        state.openers.push({ record: r, priorTerminal: state.lastTerminal });
+        state.mode = 'in-step';
+        state.stepId = r.stepId;
+        state.round = r.round;
+      } else if (r.round > state.round) state.round = r.round;
+    }
+  }
+  return state;
+};
+
+// Reference checks live ENTIRELY in the digest domain — two byte-different records with one
+// canonical serialization are ONE identity, so object identity never decides resolution or
+// authority. resolveRecordReference returns the LAST matching record (consistent with the
+// latest-per-key authoritative selection); the prefix (records BEFORE the referencing one) is the
+// resolution domain, so an out-of-order reference never resolves.
+export const resolveRecordReference = (prefixRecords, digest) =>
+  prefixRecords.findLast((r) => canonicalFlowDigest(r) === digest);
+
+export const isAuthoritativeReferenceTarget = (scopeRecords, digest) =>
+  authoritativeFlowRecords(scopeRecords).some((r) => canonicalFlowDigest(r) === digest);
+
+// validateOpenerReference(prefixRecords, candidate) → { ok } | { ok: false, reason }. The named
+// classification of a step-opening round's prior-terminal reference: unresolved · non-chain ·
+// another plan · non-terminal · superseded · not-the-prior-terminal.
+export const validateOpenerReference = (prefixRecords, candidate) => {
+  const target = resolveRecordReference(prefixRecords, candidate.opensFrom);
+  if (target === undefined) {
+    return { ok: false, reason: `the prior-terminal reference does not match the store — no record digests to ${candidate.opensFrom.slice(0, 12)}…` };
+  }
+  if (target.kind !== CHAIN_KIND) {
+    return { ok: false, reason: `the prior-terminal reference targets a ${target.kind} record, not a chain terminal` };
+  }
+  if (target.planId !== candidate.planId) {
+    return { ok: false, reason: `the prior-terminal reference targets another plan's record ("${target.planId}") — a step never opens from a foreign chain` };
+  }
+  if (!TERMINAL_PURPOSES.includes(target.purpose)) {
+    return { ok: false, reason: `the prior-terminal reference targets a non-terminal record (purpose "${target.purpose}") — an opener references adoption, converged, or complete only` };
+  }
+  const chain = prefixRecords.filter((r) => r.kind === CHAIN_KIND && r.planId === candidate.planId);
+  if (!isAuthoritativeReferenceTarget(chain, candidate.opensFrom)) {
+    return { ok: false, reason: 'the prior-terminal reference targets a superseded record — reference the latest record of that key' };
+  }
+  const prior = priorChainTerminal(chain);
+  if (prior == null || canonicalFlowDigest(prior) !== candidate.opensFrom) {
+    return { ok: false, reason: `the prior-terminal reference must target the chain's PRIOR terminal (${prior == null ? 'none' : `${canonicalFlowDigest(prior).slice(0, 12)}…`}), not another step's or an earlier terminal — step minting cannot manufacture fresh budgets` };
+  }
+  return { ok: true };
+};

package/tools/flow-check-cores.mjs

@@ -20,6 +20,7 @@ import {
   short, shellQuote, writerCommand,
   collectUnansweredRedRefusals, collectDegradeCoverageRefusals, collectReceiptCoverageRefusals,
 } from './flow-check-rungs.mjs';
+import { CONTENT_FREE_FINGERPRINT } from './core-evidence.mjs';
 
 // The checker only refuses — park/resume/complete are explicit writer actions (#59). Printed
 // operand shapes: flag values ride the inline --flag='value' form and positionals follow a
@@ -128,10 +129,21 @@ const deltaRefusals = (records, owner) => {
 // degrade after a final-start at the same fingerprint refuses unless a LATER final-start at that
 // fingerprint completed (its `final` record landed after it). The checker reads raw records,
 // never the authoritative selection (#65).
-const degradeOrderingRefusals = (coreRecords) => {
+const degradeOrderingRefusals = (coreRecords, advisories) => {
   const refusals = [];
+  let contentFree = 0;
   coreRecords.forEach((r, i) => {
     if (r.kind !== 'degrade') return;
+    // A degrade carries no base and no attempt, so on the content-free fingerprint two records
+    // from unrelated clean moments pair up and this rung refuses EVERY commit, whatever tree is
+    // being judged. Their order is not a fact about any tree, so it decides nothing here. Stated
+    // residual: #64 is therefore unenforceable for a degrade minted on a clean tree until the
+    // record carries a base — the queued store migration owns that, and a clean tree gates nothing
+    // meanwhile.
+    if (r.fingerprint === CONTENT_FREE_FINGERPRINT) {
+      contentFree += 1;
+      return;
+    }
     const startedBefore = coreRecords.some((s, j) => j < i && s.kind === 'final-start' && s.fingerprint === r.fingerprint);
     if (!startedBefore) return;
     const cured = coreRecords.some((s, j) => j > i && s.kind === 'final-start' && s.fingerprint === r.fingerprint
@@ -140,6 +152,9 @@ const degradeOrderingRefusals = (coreRecords) => {
       refusals.push(`a core degrade (backend "${r.backend}") landed AFTER a final-start at its fingerprint (${short(r.fingerprint)}) with no later completed re-run at it — degrades mint strictly BEFORE the final run (#64); re-run run-gates.mjs --final on this tree`);
     }
   });
+  if (contentFree > 0) {
+    advisories.push(`${contentFree} core degrade(s) minted on a CONTENT-FREE tree are outside the ordering rung (#64): the record carries no base, so two clean moments cannot be shown to be one and their order states nothing about any tree`);
+  }
   return refusals;
 };
 
@@ -225,7 +240,7 @@ const baseMotionRefusals = (chain, planId, owner, motion) => {
 // Phase-1 rungs (#65/#25/#42 — each self-gates on an OWN adoption). Absent inputs keep the decision
 // byte-identical to the Plan-2 checker. `consumer` rides through to the #65 lane split and defaults
 // to the STRICT lane, so a caller that forgets to thread it inherits strictness.
-export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flow store', corePath = 'the core evidence store', motion = null, evidence = null, consumer = 'commit-guard' }) => {
+export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flow store', corePath = 'the core evidence store', motion = null, evidence = null, consumer = 'commit-guard', treeCarriesBytes = true }) => {
   const refusals = [];
   const advisories = [];
   if (flowRead.readError) refusals.push(`the flow store is unreadable (${flowRead.readError}) — the checker consumes the FULL read-result; inspect ${flowPath} (fail closed)`);
@@ -243,11 +258,25 @@ export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flo
     if (motion != null && plan.integrityClean) refusals.push(...baseMotionRefusals(chain, planId, owner, motion));
   }
   refusals.push(...deltaRefusals(records, owner));
-  refusals.push(...degradeOrderingRefusals(coreRead.records));
+  refusals.push(...degradeOrderingRefusals(coreRead.records, advisories));
   if (evidence != null) {
-    refusals.push(...collectUnansweredRedRefusals({ flowRecords: records, coreRecords: coreRead.records, currentBase: evidence.tree.base, owner, consumer, currentFingerprint: evidence.tree.fingerprint }));
-    refusals.push(...collectDegradeCoverageRefusals({ flowRecords: records, coreRecords: coreRead.records, tree: evidence.tree, owner, backends: evidence.degradeBackends }));
-    refusals.push(...collectReceiptCoverageRefusals({ flowRecords: records, receipts: evidence.receipts, tree: evidence.tree, owner, backends: evidence.receiptBackends, declaredPaths: evidence.declaredPaths, refreshCap: evidence.refreshCap }));
+    // The base-keyed rung always runs — it asks about this BASE's gate history, which a tree with
+    // no content does not change. The two FINGERPRINT-keyed rungs do not, when the CALLER states
+    // that the tree carries no bytes: their coverage would then be demanded of the one fingerprint
+    // every clean moment shares, so whatever they found there was minted by another moment and
+    // possibly another base (the symmetry the #65 content-free arm and commit-guard's content-free
+    // lanes state — such evidence must decide nothing, in either direction). The fact is DECLARED
+    // by the caller rather than derived here: only the caller knows whether it is judging a commit
+    // at all, and a checker that keyed it off the fingerprint alone would also silence the rungs
+    // for every routine clean-tree check, where they are exactly what the operator asked for. The
+    // skip is RECORDED, never silent.
+    refusals.push(...collectUnansweredRedRefusals({ flowRecords: records, coreRecords: coreRead.records, currentBase: evidence.tree.base, owner, consumer, currentFingerprint: evidence.tree.fingerprint, advisories }));
+    if (!treeCarriesBytes) {
+      advisories.push('the caller states this tree carries NO bytes, so the fingerprint-keyed correlations are skipped: degrade coverage (#25) and receipt coverage (#42) here, and the D10 flow-to-final binding at the guard — evidence at a content-free fingerprint belongs to some other clean moment');
+    } else {
+      refusals.push(...collectDegradeCoverageRefusals({ flowRecords: records, coreRecords: coreRead.records, tree: evidence.tree, owner, backends: evidence.degradeBackends }));
+      refusals.push(...collectReceiptCoverageRefusals({ flowRecords: records, receipts: evidence.receipts, tree: evidence.tree, owner, backends: evidence.receiptBackends, declaredPaths: evidence.declaredPaths, refreshCap: evidence.refreshCap }));
+    }
   }
   return { refusals, advisories };
 };

package/tools/flow-check-rungs.mjs

@@ -13,7 +13,7 @@ import {
   CHAIN_KIND, canonicalFlowDigest, authoritativeFlowRecords, flowTreeIdentity,
 } from './flow-record.mjs';
 import { resolveRecordReference } from './flow-store.mjs';
-import { authoritativeOfKind, summarizeReviewReceiptsForTree } from './core-evidence.mjs';
+import { authoritativeOfKind, summarizeReviewReceiptsForTree, CONTENT_FREE_FINGERPRINT } from './core-evidence.mjs';
 import { FALLBACK_LENS_ADDITIONAL_ONLY } from './cheap-agents.mjs';
 
 export const short = (digest) => `${digest.slice(0, 12)}…`;
@@ -161,7 +161,21 @@ export const evaluateVetoOverride = ({ records, vetoReceipt, tree }) => {
 // runner-attested capability (a one-time unpublished nonce over stdin or an inherited FD, verified
 // against a one-way commitment recorded in the final-start); it needs its own IPC contract and is
 // QUEUED, never pretended here.
-export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, currentBase, owner, consumer = 'commit-guard', currentFingerprint = null }) => {
+//
+// The CONTENT-FREE arm (FINGERPRINT-BASE-BINDING, second face): a red final minted while the work
+// tree was CLEAN hashes an empty payload, and that one value is shared by every clean moment of
+// every repository — so the base correlation resolves to as many bases as the store has clean
+// moments and refuses fail-closed forever, on a record that describes no working state at all.
+// The arm is keyed on the FINGERPRINT, not on how many bases happen to correlate: resolving to
+// exactly one base is an accident of store history, never a statement about the tree. It is one
+// half of a symmetry, and it is only sound WITH the other: content-free evidence must decide
+// nothing in either direction, so commit-guard equally refuses to ATTEST from a content-free
+// receipt (commit-guard.mjs, the two content-free lanes) — without that half, stepping over a red
+// here would leave a stale green free to acquit. The skip is RECORDED in the `advisories` sink —
+// a rung that steps over evidence says so. That sink is the ONLY place the skip is observable:
+// decideFlowCheck always passes one, and a caller that omits it (a test, a future consumer) gets
+// the same refusals and no record of the step.
+export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, currentBase, owner, consumer = 'commit-guard', currentFingerprint = null, advisories = [] }) => {
   if (!hasOwnAdoption(flowRecords, owner)) return [];
   const adoptionInstants = flowRecords
     .filter((r) => r.kind === CHAIN_KIND && r.purpose === 'adoption' && r.owner === owner)
@@ -192,6 +206,10 @@ export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, current
   for (const { r, i } of finals) {
     if (r.status !== 'red') continue;
     if (armingInstant !== null && isCanonicalInstant(r.timestamp) && Date.parse(r.timestamp) < armingInstant) continue;
+    if (r.fingerprintBefore === CONTENT_FREE_FINGERPRINT) {
+      advisories.push(`a red final (attempt "${r.attempt}") is OUTSIDE the rung: its tree fingerprint ${short(r.fingerprintBefore)} is CONTENT-FREE — a clean work tree emits an empty payload, so the value identifies no working state, correlates to no base, and gates no commit (#65 content-free arm)`);
+      continue;
+    }
     const bases = basesAt(r.fingerprintBefore);
     if (bases.length === 0) {
       refusals.push(`a red final (attempt "${r.attempt}") cannot be base-correlated: no flow record carries its tree fingerprint ${short(r.fingerprintBefore)} — the zero-base lane is a fail-closed ambiguity (#65); the rung demands exactly ONE base through the flow store`);