@sabaiway/agent-workflow-kit 5.4.0 → 5.6.0

package/tools/exec-receipt.mjs

@@ -0,0 +1,263 @@
+// exec-receipt.mjs — the wrapper-minted EXEC RECEIPT contract (delegation Plan 2, Phase 1). Pure
+// form: no filesystem, no git, no CLI, no side effects on import. The bridge wrapper MINTS these
+// bytes; `dispatch return` (Phase 2) reads them and absorbs the run into the delegation ledger.
+//
+// Why the artifact exists at all: the bridge is dependency-free bash with NO path to the kit
+// (codex-cli-bridge/capability.json detect.installed resolves the BRIDGE's own directory), so it
+// cannot append to the ledger — a bash-side append would re-implement the lock/CAS leaf and could not
+// run the store's cross-record preflight, a second and drifting legality door. The wrapper therefore
+// mints what it can PROVE about its own run, and the kit absorbs it through the one append door.
+//
+// TWO STATES, one path (D1). `reserved` is written atomically and no-clobber BEFORE the run is spent
+// — that write IS the nonce reservation, so a duplicate nonce refuses before any spend. `terminal`
+// replaces it at exit, written by the run that owns the reservation. The state split is what makes
+// the artifact a safe arrival signal: `terminal` means the report beside it is already complete.
+//
+// The reserved state carries everything knowable PRE-SPEND (wrapperVersion, posture, capS,
+// killGraceS, contractDigest) and NULL in every terminal-only field, so a `--no-receipt` absorb can
+// still source the fields a tree cannot supply. A reserved receipt filling a terminal-only field
+// refuses: the two states are distinguishable by their content, not only by their label.
+//
+// `contractDigest` is computed by the WRAPPER from the dispatch file it was actually handed — an
+// independently produced value, never a copy of what the ledger holds. Without it the store's
+// return↔dispatch correlation would compare the dispatch record against values derived from itself,
+// and a run that executed a DIFFERENT contract would correlate cleanly.
+//
+// The wrapper's outcome vocabulary is a SUBSET of the ledger's (D3): a run can prove only what it
+// observed about itself. `success` = exit 0 with a session id; `missing-identity` = exit 0 without
+// one; `transport-failure` = any nonzero exit, the timeout codes included. Every orchestrator
+// judgment (contract-refusal, partial-edit, acceptance-failure, stale-return, store-failure) is
+// recorded at absorb time, never claimed here.
+//
+// Named grammars are taken by reference, never re-stated: the safe token grammar SAFE_NONCE_RE and
+// the 64-hex digest. Descriptor discipline follows dispatch-record.mjs — own enumerable DATA
+// properties only, each read exactly once, so the bytes a validator approved are the bytes a reader
+// re-reads.
+//
+// Honest limit: a receipt is forgeable, exactly like every other record in this family. What it
+// defends against is a BUGGY or interrupted producer, not a hostile one.
+//
+// Second honest limit, stated where the name is built: the length prefix closes the SEPARATOR
+// ambiguity, not the CASE one. `Codex` and `codex` are both safe tokens and compose different names —
+// but the same FILE on a case-insensitive filesystem, where an atomic no-clobber mint could then
+// refuse a legitimately different dispatch. Closing it means narrowing a grammar the FAMILY owns
+// (SAFE_NONCE_RE lives in flow-record.mjs and is taken by reference here), and the review lane's
+// manifest names carry the identical axis — so it is one family decision, queued as
+// ARTIFACT-BASENAME-NOT-INJECTIVE, not a local fork.
+
+import { SAFE_NONCE_RE } from './flow-record.mjs';
+
+const refuse = (reason) => ({ ok: false, reason });
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+const isHex64 = (v) => typeof v === 'string' && /^[0-9a-f]{64}$/.test(v);
+const isSafeToken = (v) => typeof v === 'string' && SAFE_NONCE_RE.test(v);
+
+// The artifact name is LENGTH-PREFIXED, and that is what makes it injective. Both tokens share the
+// safe grammar, which admits `-`, so a plain `<backend>-<nonce>` join is ambiguous: {backend "a-b",
+// nonce "c"} and {backend "a", nonce "b-c"} compose the SAME file, and the no-clobber reservation
+// would then refuse a genuinely different dispatch. Restricting the backend instead was tried and
+// rejected — the ledger's own contract (dispatch-record.mjs) admits any safe token as a backend, so
+// a stricter rule here would record dispatches whose receipts could never be named. The length
+// prefix keeps every character inside the safe set, keeps the name greppable, and recovers the pair:
+// read digits to the first `-`, take that many characters as the backend, the remainder is the nonce.
+const lengthPrefixed = (prefix, backend, nonce, suffix) =>
+  (isSafeToken(backend) && isSafeToken(nonce) ? `${prefix}${backend.length}-${backend}-${nonce}${suffix}` : null);
+const isCanonicalInstant = (v) => typeof v === 'string' && Number.isFinite(Date.parse(v)) && new Date(v).toISOString() === v;
+const isByteCount = (v) => Number.isSafeInteger(v) && v >= 0;
+
+const isDataProperty = (obj, field) => {
+  const descriptor = Object.getOwnPropertyDescriptor(obj, field);
+  return descriptor !== undefined && Object.hasOwn(descriptor, 'value');
+};
+
+const ACCESSOR_REFUSAL = 'is an ACCESSOR — a receipt field must be a data property, or a re-read could answer differently than the validator did';
+
+const short = (v) => {
+  let s;
+  try {
+    s = JSON.stringify(v);
+  } catch {
+    return `<unserializable ${typeof v}>`;
+  }
+  if (s === undefined) s = `<${typeof v}>`;
+  return s.length > 80 ? `${s.slice(0, 79)}…` : s;
+};
+
+const deepFreeze = (value) => {
+  if (value !== null && typeof value === 'object') {
+    Object.values(value).forEach(deepFreeze);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+// ── the closed vocabulary ─────────────────────────────────────────────────────────────────────────
+
+export const EXEC_RECEIPT_SCHEMA_VERSION = 1;
+export const EXEC_RECEIPT_KIND = 'exec-receipt';
+
+export const EXEC_RECEIPT_STATES = deepFreeze(['reserved', 'terminal']);
+
+export const EXEC_RECEIPT_KEYS = deepFreeze([
+  'state', 'backend', 'nonce', 'owner', 'contractDigest', 'wrapperVersion', 'posture',
+  'capS', 'killGraceS', 'sessionId', 'exitStatus', 'outcome', 'reportDigest', 'reportLength', 'timestamp',
+]);
+
+// The fields only a finished run can fill; a reservation carries null in every one of them.
+export const TERMINAL_ONLY_FIELDS = deepFreeze(['sessionId', 'exitStatus', 'outcome', 'reportDigest', 'reportLength']);
+
+// D3 — the three outcomes a wrapper can prove about its own run.
+export const WRAPPER_OUTCOMES = deepFreeze(['success', 'transport-failure', 'missing-identity']);
+
+const POSTURE_KEYS = deepFreeze(['model', 'effort', 'tier']);
+
+const IDENTITY_FIELDS = ['schema', 'kind'];
+
+export const EXEC_RECEIPT_BASENAME_PREFIX = 'agent-workflow-exec-receipt-';
+export const EXEC_REPORT_BASENAME_PREFIX = 'agent-workflow-exec-report-';
+
+// The {backend, nonce}-derived artifact names. Null when either token leaves the safe grammar — an
+// unsafe token would compose a path, and a name that can escape its directory is never built.
+export const execReceiptBasename = (backend, nonce) =>
+  lengthPrefixed(EXEC_RECEIPT_BASENAME_PREFIX, backend, nonce, '.json');
+
+export const execReportBasename = (backend, nonce) =>
+  lengthPrefixed(EXEC_REPORT_BASENAME_PREFIX, backend, nonce, '.txt');
+
+// ── per-field shapes ──────────────────────────────────────────────────────────────────────────────
+
+const FIELD_CHECKS = {
+  state: { ok: (v) => EXEC_RECEIPT_STATES.includes(v), want: `one of ${EXEC_RECEIPT_STATES.join(' | ')}` },
+  backend: { ok: isSafeToken, want: 'a backend name in the safe token grammar ([A-Za-z0-9._-]{1,64})' },
+  nonce: { ok: isSafeToken, want: 'a dispatch nonce in the safe token grammar ([A-Za-z0-9._-]{1,64})' },
+  owner: { ok: isNonEmptyString, want: 'the non-empty opaque token identifying the run that holds the reservation' },
+  contractDigest: { ok: isHex64, want: 'the 64-hex digest the WRAPPER computed from the dispatch file it ran' },
+  wrapperVersion: { ok: isNonEmptyString, want: 'the non-empty minting wrapper version' },
+  posture: { ok: isPlainObject, want: 'the closed posture object {model, effort, tier}' },
+  capS: { ok: (v) => Number.isSafeInteger(v) && v >= 1, want: 'the positive integer wall-clock cap the run ACTUALLY applied' },
+  killGraceS: { ok: isByteCount, want: 'the non-negative integer kill grace the run ACTUALLY applied' },
+  sessionId: { ok: (v) => v === null || isNonEmptyString(v), want: 'a non-empty backend session id, or null where no session existed' },
+  exitStatus: { ok: (v) => v === null || isByteCount(v), want: 'a non-negative integer process exit status, or null on a reservation' },
+  outcome: { ok: (v) => v === null || WRAPPER_OUTCOMES.includes(v), want: `one of ${WRAPPER_OUTCOMES.join(' | ')}, or null on a reservation` },
+  reportDigest: { ok: (v) => v === null || isHex64(v), want: 'the 64-hex digest of the report artifact, or null when no report was written' },
+  reportLength: { ok: (v) => v === null || isByteCount(v), want: 'the non-negative byte length of the report artifact, or null on a reservation' },
+  timestamp: { ok: isCanonicalInstant, want: 'a canonical UTC ISO instant (toISOString round-trip)' },
+};
+
+const validatePosture = (posture) => {
+  if (!isPlainObject(posture)) return refuse('posture must be an object');
+  const own = Object.keys(posture);
+  const stray = own.find((k) => !POSTURE_KEYS.includes(k));
+  if (stray !== undefined) return refuse(`posture: unknown field "${stray}" — the posture key set is closed`);
+  const missing = POSTURE_KEYS.find((k) => !own.includes(k));
+  if (missing !== undefined) return refuse(`posture: missing field "${missing}"`);
+  const accessor = POSTURE_KEYS.find((k) => !isDataProperty(posture, k));
+  if (accessor !== undefined) return refuse(`posture: field "${accessor}" ${ACCESSOR_REFUSAL}`);
+  if (!isNonEmptyString(posture.model)) return refuse(`posture: model must be a non-empty model name (got ${short(posture.model)})`);
+  const bad = ['effort', 'tier'].find((k) => posture[k] !== null && !isNonEmptyString(posture[k]));
+  return bad === undefined ? { ok: true } : refuse(`posture: ${bad} must be a non-empty string or null (got ${short(posture[bad])})`);
+};
+
+// The state contract, both directions: a reservation proves nothing about a run that has not
+// finished, and a terminal receipt that left a terminal field null would be a reservation wearing the
+// wrong label.
+const validateStateFields = (receipt) => {
+  if (receipt.state === 'reserved') {
+    const filled = TERMINAL_ONLY_FIELDS.find((f) => receipt[f] !== null);
+    return filled === undefined
+      ? { ok: true }
+      : refuse(`a RESERVED receipt carries null in every terminal-only field — "${filled}" is ${short(receipt[filled])}; a reservation is minted before the run is spent and can prove nothing about its outcome`);
+  }
+  const empty = ['exitStatus', 'outcome', 'reportLength'].find((f) => receipt[f] === null);
+  if (empty !== undefined) {
+    return refuse(`a TERMINAL receipt requires "${empty}" — a null there is a reservation wearing the terminal label`);
+  }
+  return { ok: true };
+};
+
+// D3's mapping, enforced as a TOTAL relation so no run can record an outcome its own numbers deny.
+const validateOutcomeMapping = (receipt) => {
+  if (receipt.state !== 'terminal') return { ok: true };
+  if (receipt.outcome === 'success') {
+    if (receipt.exitStatus !== 0) return refuse(`outcome "success" requires exitStatus 0 (got ${receipt.exitStatus}) — a nonzero exit never reports success`);
+    if (receipt.sessionId === null) return refuse('outcome "success" requires a non-null sessionId — a run that identified no session is "missing-identity"');
+    return { ok: true };
+  }
+  if (receipt.outcome === 'missing-identity') {
+    if (receipt.exitStatus !== 0) return refuse(`outcome "missing-identity" requires exitStatus 0 (got ${receipt.exitStatus}) — a nonzero exit is "transport-failure"`);
+    if (receipt.sessionId !== null) return refuse(`outcome "missing-identity" requires sessionId null (got ${short(receipt.sessionId)})`);
+    return { ok: true };
+  }
+  return receipt.exitStatus === 0
+    ? refuse('outcome "transport-failure" requires a nonzero exitStatus — a run that exited 0 is "success" or "missing-identity"')
+    : { ok: true };
+};
+
+// A TERMINAL receipt always has a report behind it — that is the publication ORDER, not a courtesy:
+// the report is written atomically FIRST and the reservation is replaced by the terminal receipt
+// LAST, and a wrapper that cannot complete either write exits nonzero having published no terminal
+// receipt at all. So on `terminal` the digest is REQUIRED, and an empty report stays perfectly
+// expressible as the sha256 of no bytes with reportLength 0. The absent form belongs to the
+// reservation (both fields null), which is exactly what the `--no-receipt` absorb lane reads.
+const validateReportPair = (receipt) => {
+  if (receipt.state !== 'terminal') return { ok: true };
+  if (receipt.reportDigest !== null) return { ok: true };
+  return refuse(`a TERMINAL receipt requires a reportDigest (reportLength ${receipt.reportLength}) — the report is published BEFORE the terminal receipt replaces the reservation, so a terminal artifact with no report behind it is a state no completed run mints; an EMPTY report is the sha256 of no bytes with length 0`);
+};
+
+// validateExecReceipt(receipt) → { ok: true } | { ok: false, reason }. Fail closed on an unknown
+// schema/kind/state, a missing, accessor or malformed field, any key outside the closed set, and every
+// cross-field relation the state pins. Never throws on a DATA record.
+export const validateExecReceipt = (receipt) => {
+  if (!isPlainObject(receipt)) return refuse('exec receipt is not an object');
+  const own = Object.keys(receipt);
+  const missingIdentity = IDENTITY_FIELDS.find((f) => !own.includes(f));
+  if (missingIdentity !== undefined) return refuse(`missing field "${missingIdentity}" — the identifying fields are read before any value is`);
+  const accessorIdentity = IDENTITY_FIELDS.find((f) => !isDataProperty(receipt, f));
+  if (accessorIdentity !== undefined) return refuse(`field "${accessorIdentity}" ${ACCESSOR_REFUSAL}`);
+  if (receipt.schema !== EXEC_RECEIPT_SCHEMA_VERSION) {
+    return refuse(`unknown schema ${short(receipt.schema)} — this reader accepts exec-receipt schema ${EXEC_RECEIPT_SCHEMA_VERSION} only (fail closed)`);
+  }
+  if (receipt.kind !== EXEC_RECEIPT_KIND) {
+    return refuse(`unknown kind ${short(receipt.kind)} — this reader accepts "${EXEC_RECEIPT_KIND}" only (fail closed)`);
+  }
+  const allowed = [...IDENTITY_FIELDS, ...EXEC_RECEIPT_KEYS];
+  const stray = own.find((k) => !allowed.includes(k));
+  if (stray !== undefined) return refuse(`unknown field "${stray}" — the exec-receipt key set is closed`);
+  for (const field of EXEC_RECEIPT_KEYS) {
+    if (!own.includes(field)) return refuse(`missing field "${field}"`);
+    if (!isDataProperty(receipt, field)) return refuse(`field "${field}" ${ACCESSOR_REFUSAL}`);
+    if (!FIELD_CHECKS[field].ok(receipt[field])) {
+      return refuse(`${field} must be ${FIELD_CHECKS[field].want} (got ${short(receipt[field])})`);
+    }
+  }
+  const posture = validatePosture(receipt.posture);
+  if (!posture.ok) return posture;
+  const state = validateStateFields(receipt);
+  if (!state.ok) return state;
+  const mapping = validateOutcomeMapping(receipt);
+  if (!mapping.ok) return mapping;
+  return validateReportPair(receipt);
+};
+
+// parseExecReceipt(text) → { ok: true, receipt } | { ok: false, reason }.
+export const parseExecReceipt = (text) => {
+  if (typeof text !== 'string') return refuse('exec receipt: the artifact must be text');
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return refuse('exec receipt: the artifact is not valid JSON (fail closed)');
+  }
+  const valid = validateExecReceipt(parsed);
+  return valid.ok ? { ok: true, receipt: parsed } : valid;
+};
+
+// The wrapper's own mapping, exported so the bridge's minted bytes and the kit's expectation come from
+// ONE rule rather than two implementations that agree today (D3).
+export const wrapperOutcomeFor = (exitStatus, sessionId) => {
+  if (!isByteCount(exitStatus)) return null;
+  if (exitStatus !== 0) return 'transport-failure';
+  return isNonEmptyString(sessionId) ? 'success' : 'missing-identity';
+};

package/tools/flow-check-cores.mjs

@@ -0,0 +1,253 @@
+// flow-check-cores.mjs — the checker's decision cores over the FULL read-results of BOTH stores
+// (flow + core evidence) and the tree context: store health, chain adoption and transition
+// legality, prior-terminal references, worktree scoping, bookkeeping-delta custody and
+// re-attestation, degrade-before-final ordering, armed base motion — and `decideFlowCheck`, the
+// ONE composition every consumer reads. Split out of flow-check.mjs (baseline-practices tranche 1);
+// the CLI, the store reads and the report render stay there.
+//
+// Pure: no store IO and no git of its own — the base-motion inputs arrive as INJECTED resolvers,
+// so flow-check-git-lane.mjs is never imported here. The evidence rungs live one module down
+// (flow-check-rungs.mjs), which also owns the refusal vocabulary both halves share.
+
+import {
+  CHAIN_KIND, validateChainSequence, validateSupersessions, canonicalFlowDigest,
+  authoritativeFlowRecords,
+} from './flow-record.mjs';
+import {
+  walkChainState, validateOpenerReference, resolveRecordReference, isAuthoritativeReferenceTarget,
+} from './flow-store.mjs';
+import {
+  short, shellQuote, writerCommand,
+  collectUnansweredRedRefusals, collectDegradeCoverageRefusals, collectReceiptCoverageRefusals,
+} from './flow-check-rungs.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
+// literal ` -- ` — one shape for EVERY id, so a leading-dash operand stays recoverable.
+const parkRecovery = (planId) =>
+  `recovery (pasteable): ${writerCommand(`park -- ${shellQuote(planId)}`)}`;
+
+// Arms in dependency order; the first failing arm reports, and integrityClean gates the caller's
+// dependent arms (base motion) off a broken chain.
+const planRefusals = (records, chain, planId, owner, advisories) => {
+  if (chain[0].purpose !== 'adoption') {
+    return { integrityClean: false, refusals: [`plan "${planId}": the chain has no content-digest-bound adoption record — a chain starts at adoption binding the plan content digest (#58); the store is append-only, so inspect how this chain was written`] };
+  }
+  const seq = validateChainSequence(chain);
+  if (!seq.ok) return { integrityClean: false, refusals: [`plan "${planId}": illegal transition — ${seq.reason}`] };
+  const state = walkChainState(chain);
+  const referenceIssues = [];
+  for (const { record } of state.openers) {
+    const check = validateOpenerReference(records.slice(0, records.indexOf(record)), record);
+    if (!check.ok) referenceIssues.push(`plan "${planId}": step-opening round (step "${record.stepId}") — ${check.reason}`);
+  }
+  for (const r of chain) {
+    if (r.purpose !== 'refresh') continue;
+    const prefix = records.slice(0, records.indexOf(r));
+    if (resolveRecordReference(prefix, r.refreshedRecord) === undefined) {
+      referenceIssues.push(`plan "${planId}": a refresh's refreshedRecord does not match the store (no earlier record digests to ${short(r.refreshedRecord)}) — a re-attestation binds an existing record`);
+    } else if (!isAuthoritativeReferenceTarget(prefix, r.refreshedRecord)) {
+      referenceIssues.push(`plan "${planId}": a refresh's refreshedRecord targets a superseded record — a re-attestation binds the authoritative latest record of its key (as of the refresh's own raw position)`);
+    }
+  }
+  if (referenceIssues.length > 0) return { integrityClean: false, refusals: referenceIssues };
+  const open = !state.completed && !state.parked && state.mode === 'in-step';
+  if (!open) return { integrityClean: true, refusals: [] };
+  if (chain[0].owner !== owner) {
+    advisories.push(`plan "${planId}": an OPEN chain owned by "${chain[0].owner}" (a foreign worktree) — advisory visibility only, never this tree's refusal (#57)`);
+    return { integrityClean: true, refusals: [] };
+  }
+  return { integrityClean: true, refusals: [`plan "${planId}" has an OPEN chain owned by this worktree ("${owner}"): step "${state.stepId}" is not converged — a commit closes only at a terminal. ${parkRecovery(planId)}`] };
+};
+
+// The custody arm verifies the PERSISTED proof against a bare declaration (#60): the masked
+// recompute must equal fingerprintBefore, and every delta must be re-attested by a SUBSEQUENT
+// chain refresh binding {refreshedRecord, fingerprintBefore = the delta's fingerprintAfter} (#45)
+// — an earlier or fingerprint-mismatched record never satisfies (raw order decides). Satisfaction
+// is STORE-GLOBAL: the locked delta shape carries no chain field, so WHICH chain's refresh cap
+// the re-attestation consumes is the Plan-3 decideCheck arm (#61), not a Plan-2 refusal.
+// The recovery lane needs the invoker's OWN OPEN chains: a refresh is a within-step record, so
+// only such a chain can carry the re-attestation (and its refresh cap is what the mint consumes,
+// #61). A command under a "pasteable" label is always CONCRETE — with no own open chain the
+// recovery states the precondition instead of printing a placeholder command.
+const ownOpenChainPlanIds = (records, owner) =>
+  [...new Set(records.filter((r) => r.kind === CHAIN_KIND).map((r) => r.planId))].filter((planId) => {
+    const chain = records.filter((r) => r.kind === CHAIN_KIND && r.planId === planId);
+    if (chain[0].owner !== owner || chain[0].purpose !== 'adoption' || !validateChainSequence(chain).ok) return false;
+    const state = walkChainState(chain);
+    return !state.completed && !state.parked && state.mode === 'in-step';
+  });
+
+// The ONE per-record custody predicate (Plan 4 Phase 3, round-2 fold): the confinement equality
+// + the mint-only invariants the record-level shape validation cannot see — shared by the
+// gate-time walk below and the writer's terminal move validation, so a forged proof can neither
+// pass the gates nor carry a terminal. → issue string | null.
+export const deltaCustodyIssue = (r) => {
+  if (r.custodyProof.maskedFingerprint !== r.fingerprintBefore) {
+    return `the persisted custody proof does not prove confinement (maskedFingerprint ${short(r.custodyProof.maskedFingerprint)} ≠ fingerprintBefore ${short(r.fingerprintBefore)}) — a bare or tampered declaration never passes; re-mint through mintBookkeepingDelta`;
+  }
+  const proof = r.custodyProof;
+  const mintInvariant = !proof.tracked ? null
+    : proof.preClass !== 'present' ? 'a tracked path with an absent pre-state never mints'
+    : proof.indexDigest === null ? 'a staged deletion (a HEAD entry without an index entry) never mints'
+    : proof.worktreeDigest !== proof.indexDigest ? 'the clean-at-path rule (pre-change worktree bytes = the index entry) never minted this'
+    : null;
+  return mintInvariant === null ? null : `the persisted custody proof violates a mint invariant — ${mintInvariant}; an unmintable proof never passes (fail closed)`;
+};
+
+const deltaRefusals = (records, owner) => {
+  const refusals = [];
+  const openPlanIds = ownOpenChainPlanIds(records, owner);
+  // The re-attestation OBLIGATION binds only AUTHORITATIVE deltas: a superseded same-key delta
+  // never enters classifyDeltaChain and the refresh preflight refuses to reference it, so
+  // demanding its refresh would be exactly the unrecoverable red the plan bans — supersession is
+  // the store's own recovery valve. Custody and mint checks stay RAW-wide (tamper detection).
+  const authoritative = new Set(authoritativeFlowRecords(records));
+  records.forEach((r, i) => {
+    if (r.kind !== 'bookkeeping-delta') return;
+    const custody = deltaCustodyIssue(r);
+    if (custody !== null) {
+      refusals.push(`bookkeeping-delta at ${r.path}: ${custody}`);
+      return;
+    }
+    if (!authoritative.has(r)) return;
+    const digest = canonicalFlowDigest(r);
+    const satisfied = records.some((s, j) => j > i && s.kind === CHAIN_KIND && s.purpose === 'refresh'
+      && s.refreshedRecord === digest && s.fingerprintBefore === r.fingerprintAfter);
+    if (!satisfied) {
+      const recovery = openPlanIds.length > 0
+        ? `recovery (pasteable; choose the chain whose refresh cap this consumes, #61): ${openPlanIds.map((planId) => writerCommand(`refresh --cause='bookkeeping delta re-attestation' --refreshed-record=${digest} -- ${shellQuote(planId)}`)).join('  OR  ')}`
+        : `recovery: no own OPEN chain can carry the re-attestation yet — open the owning plan's step round, then mint the refresh binding --refreshed-record=${digest}`;
+      refusals.push(`bookkeeping-delta at ${r.path}: no satisfying re-attestation — a SUBSEQUENT chain refresh must bind {refreshedRecord: ${short(digest)}, fingerprintBefore: ${short(r.fingerprintAfter)}}; an earlier or fingerprint-mismatched record never satisfies. ${recovery}`);
+    }
+  });
+  return refusals;
+};
+
+// Degrade-before-final (#64), decidable from RAW core-store order and grouped BY FINGERPRINT: a
+// 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 refusals = [];
+  coreRecords.forEach((r, i) => {
+    if (r.kind !== 'degrade') 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
+      && coreRecords.some((c, k) => k > j && c.kind === 'final' && c.attempt === s.attempt && c.fingerprintBefore === s.fingerprint));
+    if (!cured) {
+      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`);
+    }
+  });
+  return refusals;
+};
+
+// #62: base delta ∩ plan surface — disjoint ⇒ re-baseline, intersecting/undecidable ⇒ refresh.
+export const classifyBaseMotion = ({ baseDelta, changedSurface }) => {
+  if (!baseDelta?.ok) {
+    return { motion: 'undecidable', requires: 'refresh', reason: `the base delta is undecidable (${baseDelta?.reason ?? 'no delta supplied'}) — fail closed: a refresh dispatch is REQUIRED (#62)` };
+  }
+  if (!changedSurface?.ok) {
+    return { motion: 'undecidable', requires: 'refresh', reason: `the changed surface is undecidable (${changedSurface?.reason ?? 'no surface supplied'}) — fail closed: a refresh dispatch is REQUIRED (#62)` };
+  }
+  const surface = new Set(changedSurface.paths);
+  const witness = baseDelta.paths.find((p) => surface.has(p));
+  if (witness !== undefined) return { motion: 'intersecting', requires: 'refresh', witness };
+  return { motion: 'disjoint', requires: 're-baseline' };
+};
+
+// In-step base transitions of the LAST segment (lifecycle projection — round revisions collapsed)
+// must land the class the delta requires; boundary and park→resume are exempt (every commit moves
+// HEAD); the tail binds only a live in-step chain.
+const baseMotionRefusals = (chain, planId, owner, motion) => {
+  if (chain[0].owner !== owner) return [];
+  const display = (b) => (b == null ? 'null' : short(b));
+  const refusals = [];
+  const classify = (fromBase, toBase) => classifyBaseMotion({
+    baseDelta: motion.resolveBaseDelta(fromBase, toBase),
+    changedSurface: motion.resolveChangedSurface(),
+  });
+  const requirement = (cls) => (cls.motion === 'disjoint' ? 'the delta is disjoint from the plan surface — re-baseline only, never a dispatch (#40)'
+    : cls.motion === 'intersecting' ? `the delta intersects the plan surface at ${cls.witness}`
+    : cls.reason);
+  const seenRounds = new Set();
+  const lifecycle = chain.filter((r) => {
+    if (r.purpose !== 'round') return true;
+    const key = JSON.stringify([r.cycle, r.stepId, r.round]);
+    if (seenRounds.has(key)) return false;
+    seenRounds.add(key);
+    return true;
+  });
+  const isSegmentStart = (r) => r.purpose === 'resume' || r.purpose === 'unfreeze' || (r.purpose === 'round' && r.opensFrom !== null);
+  const states = [];
+  const walk = { mode: 'boundary', parked: false };
+  for (const r of lifecycle) {
+    states.push({ ...walk });
+    if (r.purpose === 'park') walk.parked = true;
+    else if (r.purpose === 'resume') walk.parked = false;
+    else if (r.purpose === 'converged' || r.purpose === 'complete') walk.mode = 'boundary';
+    else if (r.purpose === 'unfreeze' || (r.purpose === 'round' && walk.mode === 'boundary')) walk.mode = 'in-step';
+  }
+  const segStart = lifecycle.reduce((last, r, i) => (isSegmentStart(r) ? i : last), 0);
+  for (let i = segStart + 1; i < lifecycle.length; i += 1) {
+    const prev = lifecycle[i - 1];
+    const r = lifecycle[i];
+    if (states[i].mode !== 'in-step' || states[i].parked || r.base === prev.base) continue;
+    const cls = classify(prev.base, r.base);
+    if (r.purpose !== cls.requires) {
+      refusals.push(`plan "${planId}": a mid-step base transition (${display(prev.base)} → ${display(r.base)}) landed a "${r.purpose}" record but requires a ${cls.requires} record — ${requirement(cls)}; final gates must re-run after base motion (#62)`);
+      continue;
+    }
+    if (r.purpose === 're-baseline' && r.baseBefore !== prev.base) {
+      refusals.push(`plan "${planId}": the mid-step re-baseline's baseBefore (${display(r.baseBefore)}) does not match the previous record's base (${display(prev.base)}) — a re-baseline binds the actual pre-motion base (#62)`);
+    }
+  }
+  const state = walkChainState(chain);
+  if (state.completed || state.parked || state.mode !== 'in-step') return refusals;
+  const recorded = lifecycle[lifecycle.length - 1].base;
+  if (recorded === motion.currentBase) return refusals;
+  const cls = classify(recorded, motion.currentBase);
+  const recovery = cls.requires === 're-baseline'
+    ? writerCommand(`re-baseline -- ${shellQuote(planId)}`)
+    : writerCommand(`refresh --cause='base motion' --refreshed-record=${canonicalFlowDigest(chain[chain.length - 1])} -- ${shellQuote(planId)}`);
+  const tailRequirement = cls.requires === 're-baseline'
+    ? 'a re-baseline record suffices (the delta is disjoint from the plan surface)'
+    : `a refresh dispatch is REQUIRED (${cls.motion === 'intersecting' ? `the delta intersects the plan surface at ${cls.witness}` : cls.reason})`;
+  refusals.push(`plan "${planId}": the base moved under the armed chain (recorded ${display(recorded)} → current ${display(motion.currentBase)}) and no ${cls.requires} record landed — ${tailRequirement}; final gates must re-run after base motion (#62). recovery (pasteable): ${recovery}`);
+  return refusals;
+};
+
+// decideFlowCheck({ flowRead, coreRead, owner, motion?, evidence?, consumer? }) → { refusals,
+// advisories }. Pure — consumes the FULL read-results of both stores; store health fails closed
+// BEFORE any content judgment. `motion` ({ currentBase, resolveBaseDelta, resolveChangedSurface })
+// arms the Step-1.4 base-motion refusals; `evidence` ({ receipts, tree, backends }) arms the three
+// 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' }) => {
+  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)`);
+  else if (flowRead.malformed > 0) refusals.push(`the flow store carries ${flowRead.malformed} malformed line(s) (${flowRead.malformedReasons[0]}) — unknown kinds and broken records fail closed; inspect ${flowPath}`);
+  if (coreRead.readError) refusals.push(`the core evidence store is unreadable (${coreRead.readError}) — inspect ${corePath} (fail closed)`);
+  else if ((coreRead.malformed ?? 0) > 0) refusals.push(`the core evidence store carries ${coreRead.malformed} malformed line(s) (${coreRead.malformedReasons[0]}) — inspect ${corePath} (fail closed)`);
+  if (refusals.length > 0) return { refusals, advisories };
+  const records = flowRead.records;
+  const sup = validateSupersessions(records);
+  if (!sup.ok) refusals.push(`supersession legality: ${sup.reason} — inspect ${flowPath}`);
+  for (const planId of [...new Set(records.filter((r) => r.kind === CHAIN_KIND).map((r) => r.planId))]) {
+    const chain = records.filter((r) => r.kind === CHAIN_KIND && r.planId === planId);
+    const plan = planRefusals(records, chain, planId, owner, advisories);
+    refusals.push(...plan.refusals);
+    if (motion != null && plan.integrityClean) refusals.push(...baseMotionRefusals(chain, planId, owner, motion));
+  }
+  refusals.push(...deltaRefusals(records, owner));
+  refusals.push(...degradeOrderingRefusals(coreRead.records));
+  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 }));
+  }
+  return { refusals, advisories };
+};

package/tools/flow-check-git-lane.mjs

@@ -0,0 +1,56 @@
+// flow-check-git-lane.mjs — the all-path git lane for the checker's base-motion inputs (#62/P22):
+// toplevel-rooted, submodules never ignored, test files included. Split out of flow-check.mjs
+// (baseline-practices tranche 1) and deliberately a LEAF — it imports no flow-check sibling, so the
+// pure decision cores can never reach a git spawn through it.
+
+import { spawnSync } from 'node:child_process';
+
+const short = (digest) => `${digest.slice(0, 12)}…`;
+
+// computeChangedSurface exists for COVERAGE and excludes test files by design — the base-
+// intersection inputs come from these helpers instead: every changed path counts, tests included.
+const gitPathList = (args, cwd) => {
+  const r = spawnSync('git', args, { cwd, maxBuffer: 256 * 1024 * 1024, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  return r.stdout.toString('utf8').split('\0').filter(Boolean);
+};
+
+export const resolveGitToplevel = (cwd) => {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  const top = r.stdout.toString('utf8').replace(/\r?\n$/, '');
+  return top === '' ? null : top;
+};
+
+export const computeAllPathBaseDelta = (cwd, fromBase, toBase) => {
+  const isSha = (v) => typeof v === 'string' && /^([0-9a-f]{40}|[0-9a-f]{64})$/.test(v);
+  if (!isSha(fromBase) || !isSha(toBase)) {
+    return { ok: false, reason: `a base delta needs two shas (got ${JSON.stringify(fromBase)} → ${JSON.stringify(toBase)})` };
+  }
+  const root = resolveGitToplevel(cwd);
+  if (root == null) return { ok: false, reason: 'not inside a git work tree — the base delta is unresolvable (fail closed)' };
+  const paths = gitPathList(['diff', '--name-only', '--no-renames', '--ignore-submodules=none', '-z', fromBase, toBase], root);
+  if (paths == null) return { ok: false, reason: `git diff ${short(fromBase)} ${short(toBase)} failed — an unresolvable base delta fails closed` };
+  return { ok: true, paths };
+};
+
+export const computeAllPathWorktreeSurface = (cwd) => {
+  const root = resolveGitToplevel(cwd);
+  if (root == null) return { ok: false, reason: 'not inside a git work tree — the worktree surface is unresolvable (fail closed)' };
+  // assume-unchanged/skip-worktree lie to git diff — any flagged entry fails the surface closed.
+  const flagged = gitPathList(['ls-files', '-v', '-z'], root);
+  if (flagged == null) return { ok: false, reason: 'the worktree surface is unresolvable (git ls-files -v failed) — fail closed' };
+  for (const entry of flagged) {
+    if (entry.length < 3 || entry[1] !== ' ') return { ok: false, reason: `the worktree surface is unresolvable (unparseable ls-files -v entry ${JSON.stringify(entry)}) — fail closed` };
+    const assumeUnchanged = /[a-z]/.test(entry[0]);
+    const skipWorktree = entry[0].toUpperCase() === 'S';
+    if (assumeUnchanged || skipWorktree) {
+      const flags = [assumeUnchanged ? 'assume-unchanged' : null, skipWorktree ? 'skip-worktree' : null].filter(Boolean).join(' + ');
+      return { ok: false, reason: `index-flagged entry ${entry.slice(2)} (${flags}) hides changes from git diff — the worktree surface is undecidable (fail closed)` };
+    }
+  }
+  const tracked = gitPathList(['diff', 'HEAD', '--name-only', '--no-renames', '--ignore-submodules=none', '-z'], root);
+  const untracked = gitPathList(['ls-files', '--others', '--exclude-standard', '-z'], root);
+  if (tracked == null || untracked == null) return { ok: false, reason: 'the worktree surface is unresolvable (git diff/ls-files failed) — fail closed' };
+  return { ok: true, paths: [...new Set([...tracked, ...untracked])] };
+};