@sabaiway/agent-workflow-kit 5.1.0 → 5.2.0

package/tools/flow-record.mjs

@@ -0,0 +1,795 @@
+// flow-record.mjs — the CLOSED flow-record vocabulary (flow-orchestration, Phase 1). Pure form:
+// no filesystem, no git, no CLI, no side effects on import. The store IO (flow-store.mjs) and the
+// checker (flow-check.mjs) consume these predicates; nothing here reads or writes a store.
+//
+// The vocabulary is seeded VERBATIM from the flow design §5 closed kind set and fixed BEFORE any
+// reader/writer exists. Every seed member is ASSIGNED to a family (DESIGN_SEED_ASSIGNMENT — the
+// drift-guard test binds the shipped vocabulary to exactly this assignment):
+//   • chain family — ONE record kind ("chain") keyed {planId, cycle, stepId, round, purpose};
+//     design §5's "round-chain" member is realized as the "round" purpose. stepId ENTERS the key
+//     domain here (the Phase-1 fixture decision): a record of one step can then never supersede a
+//     record of another step. The round purpose carries the dispatch ledger (per-dispatch
+//     watermark + nonce + landed receipt/manifest digests — the #41/#42 binding) and the
+//     disposition ledger (folded/queued/rejected per finding, each with its proof — #13/#33).
+//   • store-global kinds — the rest, each with its own shape and supersession key; the down-mark
+//     family (down-mark / down-mark-up / down-mark-clear) shares ONE key so up/clear supersede the
+//     mark; maintainer-override keys on its veto instance (vetoReceiptDigest) and every override
+//     after the first must supersede the CURRENT head of that instance (#56 — explicit, unforkable
+//     supersession). internal-attestation carries the full #28 bound schema (lenses, degraded set,
+//     posture object, authority, plan/cycle/step/round + tree identity); consult-attestation binds
+//     the consult to the finding AND the proposed fix (#11/#33 — form-provable, semantics stay an
+//     honest limit).
+// Fail-closed in both directions: unknown schema, unknown kind, unknown purpose, a missing field,
+// a malformed field, and an unknown EXTRA field are all refusals — the per-record canonical digest
+// is the record's identity, so a stray key would fork it.
+//
+// Plan-4 addition (Decision 7/8 — NOT a design-§5 seed member; the drift-guard test records it as
+// the one post-seed addition): the store-global kind "subset-attempt" — the --pre-review subset
+// hard-stop counter. Key {planId, cycle, stepId, foldBatch, subsetDigest}; attemptIndex is the
+// monotonic per-key index (the locked append factory in flow-store.mjs computes it under the
+// lock); `diagnosis` rides ONLY attemptIndex >= 3 (Decision 8 — the recorded, self-servable
+// continuation past two reds; never a wait-for-maintainer).
+//
+// Tree identity (#21): every record carries {base, fingerprint}; the transition-shaped records
+// (chain/refresh, bookkeeping-delta) carry {fingerprintBefore, fingerprintAfter} and their singular
+// identity fingerprint IS fingerprintAfter (flowTreeIdentity). The bookkeeping-delta custody proof
+// persists the THREE-LAYER pre-state digest set {headDigest, indexDigest, worktreeDigest} plus the
+// derived tracked-ness (#60) — the fingerprint domain distinguishes staged, unstaged, and untracked
+// bytes, so a single content digest cannot represent the pre-state.
+//
+// Reference domain (#63): every inter-record reference is the per-record canonical digest — sha256
+// over the canonical (recursively key-sorted, byte-layout-independent) serialization of ONE record.
+// Newline rule: the single-record serialization carries NO trailing newline; multi-record framing
+// (one line per record) belongs to stores, never to this primitive. A parity test pins these bytes
+// against core-evidence's canonicalKindSerialization so the two disciplines cannot drift; the core
+// module itself is frozen and stays untouched.
+//
+// Honest residuals: reference RESOLUTION against a real store (forged / mismatched / superseded
+// targets, adoption content-digest binding) lands with flow-store/flow-check; this module resolves
+// references only inside an in-memory record list (validateSupersessions) and validates form,
+// per-chain sequence legality, and selection. Records remain forgeable — a self-discipline
+// mechanism, not a security boundary.
+
+import { createHash } from 'node:crypto';
+import { FLOW_SCHEMA_VERSION } from './orchestration-config.mjs';
+import { lexicalRepoRelative } from './repo-lex.mjs';
+
+export { FLOW_SCHEMA_VERSION };
+
+const deepFreeze = (value) => {
+  if (value !== null && typeof value === 'object') {
+    Object.values(value).forEach(deepFreeze);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+// ── the closed vocabulary ─────────────────────────────────────────────────────────────────────────
+
+export const CHAIN_KIND = 'chain';
+export const CHAIN_PURPOSES = deepFreeze(['adoption', 'round', 'refresh', 're-baseline', 'freeze', 'unfreeze', 'park', 'resume', 'converged', 'complete']);
+export const STEP_SCOPED_PURPOSES = deepFreeze(['round', 'refresh', 're-baseline', 'freeze', 'unfreeze', 'converged']);
+export const PLAN_LANE_PURPOSES = deepFreeze(['adoption', 'park', 'resume', 'complete']);
+export const GLOBAL_KINDS = deepFreeze(['internal-attestation', 'down-mark', 'down-mark-up', 'down-mark-clear', 'degrade-justification', 'rerun-cause', 'bookkeeping-delta', 'maintainer-override', 'consult-attestation', 'subset-attempt']);
+export const FLOW_KINDS = deepFreeze([CHAIN_KIND, ...GLOBAL_KINDS]);
+
+// Reserved lane-typed terminals (#16): converged terminates a CYCLE (its step's sequence), complete
+// terminates the PLAN. Park is a resumable suspension, never a terminal (#59).
+export const TERMINAL_LANES = deepFreeze({ converged: 'cycle', complete: 'plan' });
+
+// Design §5 seed member → family assignment; the drift-guard test binds this map to the verbatim
+// seed list on one side and to the shipped CHAIN_PURPOSES/GLOBAL_KINDS on the other.
+export const DESIGN_SEED_ASSIGNMENT = deepFreeze({
+  adoption: { family: 'chain', purpose: 'adoption' },
+  'round-chain': { family: 'chain', purpose: 'round' },
+  refresh: { family: 'chain', purpose: 'refresh' },
+  're-baseline': { family: 'chain', purpose: 're-baseline' },
+  unfreeze: { family: 'chain', purpose: 'unfreeze' },
+  freeze: { family: 'chain', purpose: 'freeze' },
+  converged: { family: 'chain', purpose: 'converged' },
+  park: { family: 'chain', purpose: 'park' },
+  resume: { family: 'chain', purpose: 'resume' },
+  complete: { family: 'chain', purpose: 'complete' },
+  'internal-attestation': { family: 'global', kind: 'internal-attestation' },
+  'down-mark': { family: 'global', kind: 'down-mark' },
+  'down-mark up': { family: 'global', kind: 'down-mark-up' },
+  'down-mark clear': { family: 'global', kind: 'down-mark-clear' },
+  'degrade-justification': { family: 'global', kind: 'degrade-justification' },
+  'rerun-cause': { family: 'global', kind: 'rerun-cause' },
+  'bookkeeping-delta': { family: 'global', kind: 'bookkeeping-delta' },
+  'maintainer-override': { family: 'global', kind: 'maintainer-override' },
+  'consult-attestation': { family: 'global', kind: 'consult-attestation' },
+});
+
+// The allowed-transition table — an exported frozen structure, never prose. Within a step:
+// converged ends the sequence (only the unfreeze lane reopens it, and only in its own cycle);
+// freeze admits only unfreeze/converged. Plan lane: park admits only resume (and both preserve the
+// pre-park cycle/round); complete admits nothing; adoption is only ever the chain's first record.
+// The boundary lane (between steps): the opener round, the unfreeze reopen, and a re-baseline for
+// disjoint base motion that reopens nothing. The cross-step edge (the opener's prior-terminal
+// reference) is enforced by validateChainSequence, distinct from the within-step successor rule.
+export const ALLOWED_TRANSITIONS = deepFreeze({
+  stepOpening: 'round',
+  withinStep: {
+    round: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    refresh: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    're-baseline': ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    freeze: ['unfreeze', 'converged'],
+    unfreeze: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    converged: ['unfreeze'],
+  },
+  planLane: {
+    adoption: ['round', 'park', 'complete'],
+    park: ['resume'],
+    resume: ['round', 'park', 'complete'],
+    complete: [],
+  },
+  boundary: ['round', 'unfreeze', 're-baseline'],
+});
+
+// ── field shapes (closed key set per kind/purpose) ────────────────────────────────────────────────
+
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const HEX40_RE = /^[0-9a-f]{40}$/;
+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' && HEX64_RE.test(v);
+const isSha = (v) => typeof v === 'string' && (HEX40_RE.test(v) || HEX64_RE.test(v));
+const isCanonicalInstant = (v) => typeof v === 'string' && Number.isFinite(Date.parse(v)) && new Date(v).toISOString() === v;
+const isUniqueNonEmptyStrings = (v) => Array.isArray(v) && v.every(isNonEmptyString) && new Set(v).size === v.length;
+
+const POSTURE_KEYS = ['model', 'effort', 'tier'];
+const isClosedPosture = (v) => isPlainObject(v)
+  && Object.keys(v).length === POSTURE_KEYS.length && POSTURE_KEYS.every((k) => k in v)
+  && isNonEmptyString(v.model)
+  && (v.effort === null || isNonEmptyString(v.effort))
+  && (v.tier === null || isNonEmptyString(v.tier));
+
+const FIELD_CHECKS = {
+  base: { ok: (v) => v === null || isSha(v), want: 'the 40- or 64-hex base sha, or null on an unborn branch' },
+  baseBefore: { ok: isSha, want: 'the 40- or 64-hex pre-motion base sha' },
+  timestamp: { ok: isNonEmptyString, want: 'a non-empty timestamp string' },
+  fingerprint: { ok: isHex64, want: 'a 64-hex tree fingerprint' },
+  fingerprintBefore: { ok: isHex64, want: 'a 64-hex tree fingerprint' },
+  fingerprintAfter: { ok: isHex64, want: 'a 64-hex tree fingerprint' },
+  planId: { ok: isNonEmptyString, want: 'a non-empty plan id' },
+  cycle: { ok: (v) => Number.isInteger(v) && v >= 1, want: 'a positive integer cycle index' },
+  round: { ok: (v) => Number.isInteger(v) && v >= 0, want: 'a non-negative integer round index' },
+  commitEpoch: { ok: (v) => Number.isInteger(v) && v >= 0, want: 'a non-negative integer commit epoch' },
+  owner: { ok: isNonEmptyString, want: 'the non-empty owning-worktree identity' },
+  stepId: { ok: isNonEmptyString, want: 'a non-empty step id' },
+  stepIdNull: { ok: (v) => v === null, want: 'null — this purpose is plan-lane, never step-scoped' },
+  stepIdOrNull: { ok: (v) => v === null || isNonEmptyString(v), want: 'a non-empty step id, or null at a pre-first-step boundary' },
+  opensFrom: { ok: (v) => v === null || isHex64(v), want: 'the 64-hex prior-terminal record digest, or null off the step opening' },
+  dispatches: { ok: Array.isArray, want: 'the dispatch-ledger array (may be empty until dispatches land)' },
+  dispositions: { ok: Array.isArray, want: 'the disposition-ledger array (may be empty until findings land)' },
+  planLabel: { ok: isNonEmptyString, want: 'the non-empty plan label' },
+  createdAt: { ok: isNonEmptyString, want: 'a non-empty created-at string' },
+  planDigest: { ok: isHex64, want: 'the 64-hex plan content digest' },
+  cause: { ok: isNonEmptyString, want: 'a non-empty declared cause' },
+  refreshedRecord: { ok: isHex64, want: 'the 64-hex digest of the record this refresh re-attests' },
+  backend: { ok: isNonEmptyString, want: 'a non-empty backend name' },
+  reason: { ok: isNonEmptyString, want: 'a non-empty reason' },
+  expiresAt: { ok: isCanonicalInstant, want: 'a canonical UTC ISO instant (toISOString round-trip)' },
+  target: { ok: isHex64, want: 'the 64-hex digest of the down-mark this record supersedes' },
+  downMark: { ok: isHex64, want: 'the 64-hex digest of the down-mark this justification rides on' },
+  degradeDigest: { ok: isHex64, want: 'the 64-hex per-record canonical digest of the core degrade record' },
+  attempt: { ok: isNonEmptyString, want: 'the non-empty red final attempt id' },
+  path: { ok: (v) => isNonEmptyString(v) && lexicalRepoRelative(v).ok, want: 'a non-empty lexically repo-relative path' },
+  contentDigest: { ok: (v) => v === null || isHex64(v), want: 'the 64-hex post-change content digest, or null when the path lands absent' },
+  custodyProof: { ok: isPlainObject, want: 'the persisted proof object {preClass, tracked, headDigest, indexDigest, worktreeDigest, maskedFingerprint}' },
+  vetoReceiptDigest: { ok: isHex64, want: 'the 64-hex digest of the vetoing receipt' },
+  verdict: { ok: isNonEmptyString, want: 'the non-empty vetoing verdict' },
+  chainRecord: { ok: isHex64, want: 'the 64-hex digest of the bound chain record' },
+  supersedes: { ok: (v) => v === null || isHex64(v), want: 'the 64-hex digest of the superseded override, or null on the first override of a veto instance' },
+  nonce: { ok: isNonEmptyString, want: 'the non-empty wrapper nonce' },
+  lenses: { ok: (v) => isUniqueNonEmptyStrings(v) && v.length > 0, want: 'a non-empty array of unique non-empty lens names (the required-lens set)' },
+  degraded: { ok: isUniqueNonEmptyStrings, want: 'an array of unique non-empty backend names (may be empty)' },
+  posture: { ok: isClosedPosture, want: 'the closed posture object {model: non-empty, effort: non-empty|null, tier: non-empty|null}' },
+  authority: { ok: isNonEmptyString, want: 'the non-empty attesting authority' },
+  findingDigest: { ok: isHex64, want: 'the 64-hex digest of the consulted finding' },
+  proposedFixDigest: { ok: isHex64, want: 'the 64-hex digest of the proposed fix under consult' },
+  foldBatch: { ok: isHex64, want: 'the 64-hex digest of the owning round identity projection {planId, cycle, stepId, round}' },
+  subsetDigest: { ok: isHex64, want: "the 64-hex digest of the derived subset's ordered gate ids" },
+  attemptIndex: { ok: (v) => Number.isInteger(v) && v >= 1, want: 'a positive integer attempt index (monotonic per counting context)' },
+  status: { ok: (v) => v === 'green' || v === 'red', want: 'the closed enum green | red' },
+  diagnosis: { ok: isNonEmptyString, want: 'a non-empty diagnosis statement (Decision 8 — the recorded continuation past two reds)' },
+};
+
+const CHAIN_COMMON_FIELDS = ['planId', 'cycle', 'round', 'commitEpoch', 'owner', 'base', 'timestamp'];
+
+// Per-purpose closed field sets. "stepIdNull" routes stepId through the plan-lane check; the
+// transition-shaped refresh carries fingerprintBefore/After and deliberately NO singular
+// fingerprint field (flowTreeIdentity supplies it). re-baseline's stepId is the prior-terminal
+// anchor at a boundary (null only before the first step) or the open step inside one.
+const PURPOSE_SHAPES = {
+  adoption: { stepId: 'stepIdNull', fields: ['fingerprint', 'planLabel', 'createdAt', 'planDigest'] },
+  round: { stepId: 'stepId', fields: ['fingerprint', 'opensFrom', 'dispatches', 'dispositions'] },
+  refresh: { stepId: 'stepId', fields: ['fingerprintBefore', 'fingerprintAfter', 'cause', 'refreshedRecord'] },
+  're-baseline': { stepId: 'stepIdOrNull', fields: ['fingerprint', 'baseBefore'] },
+  freeze: { stepId: 'stepId', fields: ['fingerprint'] },
+  unfreeze: { stepId: 'stepId', fields: ['fingerprint'] },
+  park: { stepId: 'stepIdNull', fields: ['fingerprint'] },
+  resume: { stepId: 'stepIdNull', fields: ['fingerprint'] },
+  converged: { stepId: 'stepId', fields: ['fingerprint'] },
+  complete: { stepId: 'stepIdNull', fields: ['fingerprint'] },
+};
+
+const GLOBAL_SHAPES = {
+  'internal-attestation': ['fingerprint', 'planId', 'stepId', 'cycle', 'round', 'lenses', 'degraded', 'posture', 'authority', 'base', 'timestamp'],
+  'down-mark': ['fingerprint', 'backend', 'reason', 'expiresAt', 'base', 'timestamp'],
+  'down-mark-up': ['fingerprint', 'backend', 'target', 'base', 'timestamp'],
+  'down-mark-clear': ['fingerprint', 'backend', 'target', 'base', 'timestamp'],
+  'degrade-justification': ['fingerprint', 'downMark', 'degradeDigest', 'base', 'timestamp'],
+  'rerun-cause': ['fingerprint', 'cause', 'attempt', 'base', 'timestamp'],
+  'bookkeeping-delta': ['fingerprintBefore', 'fingerprintAfter', 'path', 'contentDigest', 'custodyProof', 'base', 'timestamp'],
+  'maintainer-override': ['fingerprint', 'vetoReceiptDigest', 'backend', 'verdict', 'chainRecord', 'supersedes', 'base', 'timestamp'],
+  'consult-attestation': ['fingerprint', 'backend', 'nonce', 'planId', 'cycle', 'stepId', 'round', 'findingDigest', 'proposedFixDigest', 'base', 'timestamp'],
+  'subset-attempt': ['planId', 'cycle', 'stepId', 'foldBatch', 'subsetDigest', 'attemptIndex', 'status', 'base', 'fingerprint', 'timestamp'],
+};
+
+// Kind-scoped check overrides where a field name collides across kinds (Decision 7): the
+// subset-attempt stepId is nullable — attempts before any round key the ADOPTION context.
+const GLOBAL_FIELD_CHECK_OVERRIDES = {
+  'subset-attempt': { stepId: 'stepIdOrNull' },
+};
+
+// Decision 8: attempts 1-2 are the blind budget and never carry a diagnosis — this is the
+// earliest index one MAY ride. REQUIRED-ness keys on the key's red count (>= 2, past the second
+// red) and lives in the store gate + the locked factory: a record-local validator cannot see
+// the key history, and a green history never owes a diagnosis.
+export const SUBSET_ATTEMPT_DIAGNOSIS_FROM = 3;
+
+const refuse = (reason) => ({ ok: false, reason });
+
+const checkFields = (label, record, fieldToCheck) => {
+  const allowed = ['schema', 'kind', ...(record.kind === CHAIN_KIND ? ['purpose'] : []), ...Object.keys(fieldToCheck)];
+  const stray = Object.keys(record).find((k) => !allowed.includes(k));
+  if (stray !== undefined) return refuse(`${label}: unknown field "${stray}" — the key set is closed (the digest is identity; a stray key would fork it)`);
+  for (const [field, checkId] of Object.entries(fieldToCheck)) {
+    if (!(field in record)) return refuse(`${label}: missing field "${field}" — every required field is pinned`);
+    const check = FIELD_CHECKS[checkId];
+    if (!check.ok(record[field])) return refuse(`${label}: ${field} must be ${check.want}`);
+  }
+  return { ok: true };
+};
+
+// The per-dispatch ledger entry (#41/#42): watermark + nonce minted BEFORE dispatch; the receipt
+// digest and the finding-manifest digest land TOGETHER once the receipt arrives.
+const DISPATCH_KEYS = ['backend', 'dispatchBase', 'receiptWatermark', 'dispatchNonce', 'receiptDigest', 'findingManifestDigest'];
+
+const validateDispatches = (label, list) => {
+  const seenIdentities = new Set();
+  for (let i = 0; i < list.length; i += 1) {
+    const d = list[i];
+    const at = `${label}: dispatches[${i}]`;
+    if (!isPlainObject(d)) return refuse(`${at} must be an object`);
+    const stray = Object.keys(d).find((k) => !DISPATCH_KEYS.includes(k));
+    if (stray !== undefined) return refuse(`${at}: unknown field "${stray}" — the dispatch key set is closed`);
+    const missing = DISPATCH_KEYS.find((k) => !(k in d));
+    if (missing !== undefined) return refuse(`${at}: missing field "${missing}"`);
+    const identity = JSON.stringify([d.backend, d.dispatchNonce]);
+    if (seenIdentities.has(identity)) return refuse(`${at}: duplicate dispatch identity {backend, dispatchNonce} — one ledger entry per dispatch (the watermark is payload, never identity)`);
+    seenIdentities.add(identity);
+    if (!isNonEmptyString(d.backend)) return refuse(`${at}: backend must be a non-empty backend name`);
+    if (d.dispatchBase !== null && !isSha(d.dispatchBase)) return refuse(`${at}: dispatchBase must be the 40- or 64-hex base at dispatch, or null on an unborn branch`);
+    if (!Number.isInteger(d.receiptWatermark) || d.receiptWatermark < 0) return refuse(`${at}: receiptWatermark must be a non-negative integer (the receipts-file position minted before dispatch)`);
+    if (!isNonEmptyString(d.dispatchNonce)) return refuse(`${at}: dispatchNonce must be a non-empty string`);
+    for (const field of ['receiptDigest', 'findingManifestDigest']) {
+      if (d[field] !== null && !isHex64(d[field])) return refuse(`${at}: ${field} must be a 64-hex digest, or null while the dispatch is pending`);
+    }
+    if ((d.receiptDigest === null) !== (d.findingManifestDigest === null)) {
+      return refuse(`${at}: receiptDigest and findingManifestDigest land together — both null while pending, both 64-hex once the receipt landed`);
+    }
+  }
+  return { ok: true };
+};
+
+// The per-finding disposition ledger (#13/#33): every council finding lands as exactly one of the
+// three closed arms, each carrying its proof (a consult-attestation/red-proof digest, a debt entry,
+// or a stated rejection reason).
+const DISPOSITION_KEYS = {
+  folded: ['findingDigest', 'action', 'proofKind', 'proofDigest'],
+  queued: ['findingDigest', 'action', 'debtId', 'debtDigest'],
+  rejected: ['findingDigest', 'action', 'reason'],
+};
+
+const validateDispositions = (label, list) => {
+  const seenFindings = new Set();
+  for (let i = 0; i < list.length; i += 1) {
+    const d = list[i];
+    const at = `${label}: dispositions[${i}]`;
+    if (!isPlainObject(d)) return refuse(`${at} must be an object`);
+    const armKeys = Object.hasOwn(DISPOSITION_KEYS, d.action) ? DISPOSITION_KEYS[d.action] : undefined;
+    if (armKeys === undefined) return refuse(`${at}: action must be one of ${Object.keys(DISPOSITION_KEYS).join(' | ')} (got ${JSON.stringify(d.action)}) — an inherited prototype key never resolves an arm (fail closed)`);
+    const stray = Object.keys(d).find((k) => !armKeys.includes(k));
+    if (stray !== undefined) return refuse(`${at}: unknown field "${stray}" — the ${d.action} arm's key set is closed`);
+    const missing = armKeys.find((k) => !(k in d));
+    if (missing !== undefined) return refuse(`${at}: missing field "${missing}"`);
+    if (!isHex64(d.findingDigest)) return refuse(`${at}: findingDigest must be the 64-hex digest of the finding`);
+    if (seenFindings.has(d.findingDigest)) return refuse(`${at}: duplicate findingDigest — every finding gets exactly one disposition, whichever the arm`);
+    seenFindings.add(d.findingDigest);
+    if (d.action === 'folded') {
+      if (d.proofKind !== 'consult-attestation' && d.proofKind !== 'red-proof') return refuse(`${at}: proofKind must be consult-attestation | red-proof (the fold's proof record class)`);
+      if (!isHex64(d.proofDigest)) return refuse(`${at}: proofDigest must be the 64-hex digest of the proof record`);
+    } else if (d.action === 'queued') {
+      if (!isNonEmptyString(d.debtId)) return refuse(`${at}: debtId must be the non-empty stable debt-queue id`);
+      if (!isHex64(d.debtDigest)) return refuse(`${at}: debtDigest must be the 64-hex digest of the debt entry`);
+    } else if (!isNonEmptyString(d.reason)) {
+      return refuse(`${at}: reason must be a non-empty statement of why the finding is rejected`);
+    }
+  }
+  return { ok: true };
+};
+
+// The three-layer pre-state digest set (#60): HEAD entry, index entry, worktree bytes — null means
+// "no entry in that layer". tracked-ness is derived (a HEAD or index entry exists); the presence
+// class is the WORKTREE layer. The fingerprint domain (staged + unstaged + untracked) is exactly
+// what these three layers reconstruct for the masked recompute.
+const CUSTODY_PROOF_KEYS = ['preClass', 'tracked', 'headDigest', 'indexDigest', 'worktreeDigest', 'maskedFingerprint'];
+const PRE_STATE_CLASSES = ['present', 'absent'];
+
+const validateCustodyProof = (label, record) => {
+  const proof = record.custodyProof;
+  const stray = Object.keys(proof).find((k) => !CUSTODY_PROOF_KEYS.includes(k));
+  if (stray !== undefined) return refuse(`${label}: custodyProof carries unknown field "${stray}" — the proof key set is closed`);
+  const missing = CUSTODY_PROOF_KEYS.find((k) => !(k in proof));
+  if (missing !== undefined) return refuse(`${label}: custodyProof is missing field "${missing}"`);
+  if (!PRE_STATE_CLASSES.includes(proof.preClass)) return refuse(`${label}: custodyProof.preClass must be one of ${PRE_STATE_CLASSES.join(' | ')} — any other pre-state class refuses to mint by name (fail closed)`);
+  if (typeof proof.tracked !== 'boolean') return refuse(`${label}: custodyProof.tracked must be a boolean`);
+  for (const field of ['headDigest', 'indexDigest', 'worktreeDigest']) {
+    if (proof[field] !== null && !isHex64(proof[field])) return refuse(`${label}: custodyProof.${field} must be a 64-hex content digest, or null when that layer has no entry`);
+  }
+  if (!isHex64(proof.maskedFingerprint)) return refuse(`${label}: custodyProof.maskedFingerprint must be the 64-hex masked-recompute fingerprint`);
+  if ((proof.preClass === 'absent') !== (proof.worktreeDigest === null)) {
+    return refuse(`${label}: custodyProof.worktreeDigest must be null exactly when preClass is "absent" — the worktree layer IS the presence class`);
+  }
+  if (proof.tracked !== (proof.headDigest !== null || proof.indexDigest !== null)) {
+    return refuse(`${label}: custodyProof.tracked must equal the presence of a HEAD or index entry — a mismatched tracked-ness is a forged pre-state`);
+  }
+  if (proof.preClass === 'absent' && record.contentDigest === null) {
+    return refuse(`${label}: the absent→absent pre-state transition is unsupported — supported: present→present, present→absent, absent→present (fail closed)`);
+  }
+  return { ok: true };
+};
+
+// validateFlowRecord(record) → { ok: true } | { ok: false, reason }. Fail closed on unknown
+// schema/kind/purpose, a missing/malformed field, or any key outside the closed per-kind set.
+export const validateFlowRecord = (record) => {
+  if (!isPlainObject(record)) return refuse('record is not an object');
+  if (record.schema !== FLOW_SCHEMA_VERSION) {
+    return refuse(`unknown schema ${JSON.stringify(record.schema)} — this reader accepts flow schema ${FLOW_SCHEMA_VERSION} only (fail closed)`);
+  }
+  if (!FLOW_KINDS.includes(record.kind)) {
+    return refuse(`unknown kind ${JSON.stringify(record.kind)} — closed set: ${FLOW_KINDS.join(' | ')} (fail closed)`);
+  }
+  if (record.kind === CHAIN_KIND) {
+    if (!CHAIN_PURPOSES.includes(record.purpose)) {
+      return refuse(`chain: unknown purpose ${JSON.stringify(record.purpose)} — closed set: ${CHAIN_PURPOSES.join(' | ')} (fail closed)`);
+    }
+    const shape = PURPOSE_SHAPES[record.purpose];
+    const label = `chain/${record.purpose}`;
+    const fieldToCheck = Object.fromEntries([
+      ...CHAIN_COMMON_FIELDS.map((f) => [f, f]),
+      ['stepId', shape.stepId],
+      ...shape.fields.map((f) => [f, f]),
+    ]);
+    const checked = checkFields(label, record, fieldToCheck);
+    if (!checked.ok) return checked;
+    if (record.purpose !== 'round') return { ok: true };
+    const dispatches = validateDispatches(label, record.dispatches);
+    if (!dispatches.ok) return dispatches;
+    return validateDispositions(label, record.dispositions);
+  }
+  const overrides = GLOBAL_FIELD_CHECK_OVERRIDES[record.kind] ?? {};
+  const fieldToCheck = Object.fromEntries(GLOBAL_SHAPES[record.kind].map((f) => [f, overrides[f] ?? f]));
+  if (record.kind === 'subset-attempt' && 'diagnosis' in record) {
+    if (!(Number.isInteger(record.attemptIndex) && record.attemptIndex >= SUBSET_ATTEMPT_DIAGNOSIS_FROM)) {
+      return refuse(`subset-attempt: diagnosis rides only attemptIndex ${SUBSET_ATTEMPT_DIAGNOSIS_FROM} and later (Decision 8) — attempts 1-2 are the blind budget and never carry one`);
+    }
+    fieldToCheck.diagnosis = 'diagnosis';
+  }
+  const checked = checkFields(record.kind, record, fieldToCheck);
+  if (!checked.ok) return checked;
+  if (record.kind === 'down-mark') {
+    if (!isCanonicalInstant(record.timestamp)) return refuse('down-mark: timestamp must be a canonical UTC ISO instant (toISOString round-trip) — the TTL window needs comparable instants');
+    if (Date.parse(record.expiresAt) <= Date.parse(record.timestamp)) return refuse('down-mark: expiresAt must be strictly after timestamp — an already-expired mark is refused at the record level');
+    return { ok: true };
+  }
+  return record.kind === 'bookkeeping-delta' ? validateCustodyProof(record.kind, record) : { ok: true };
+};
+
+// ── per-kind keys + the authoritative latest-per-key selection ────────────────────────────────────
+
+// JSON-array keys (collision-proof across free-form fields — space-joining would let a planId forge
+// a separator). The down-mark family shares ONE key per backend so up/clear supersede the mark;
+// maintainer-override keys on its veto instance; internal-attestation keys on
+// {plan, cycle, step, round, tree}.
+export const flowRecordKey = (record) =>
+  record.kind === CHAIN_KIND ? JSON.stringify([CHAIN_KIND, record.planId, record.cycle, record.stepId, record.round, record.purpose])
+  : record.kind === 'internal-attestation' ? JSON.stringify([record.kind, record.planId, record.cycle, record.stepId, record.round, record.base, record.fingerprint])
+  : record.kind === 'down-mark' || record.kind === 'down-mark-up' || record.kind === 'down-mark-clear' ? JSON.stringify(['down-mark', record.backend])
+  : record.kind === 'degrade-justification' ? JSON.stringify([record.kind, record.downMark])
+  : record.kind === 'rerun-cause' ? JSON.stringify([record.kind, record.attempt])
+  : record.kind === 'bookkeeping-delta' ? JSON.stringify([record.kind, record.fingerprintBefore, record.fingerprintAfter, record.path])
+  : record.kind === 'maintainer-override' ? JSON.stringify([record.kind, record.vetoReceiptDigest])
+  : record.kind === 'consult-attestation' ? JSON.stringify([record.kind, record.backend, record.nonce])
+  : record.kind === 'subset-attempt' ? JSON.stringify([record.kind, record.planId, record.cycle, record.stepId, record.foldBatch, record.subsetDigest])
+  : null;
+
+// The authoritative subset: the LATEST record per key, in file order of that latest appearance.
+// Raw file order is a separate, surviving view — the transition/ordering checks consume ONLY raw.
+export const authoritativeFlowRecords = (records) => {
+  const lastByKey = new Map();
+  records.forEach((r, i) => {
+    const k = flowRecordKey(r);
+    if (k != null) lastByKey.set(k, i);
+  });
+  const keep = new Set(lastByKey.values());
+  return records.filter((_, i) => keep.has(i));
+};
+
+// ── tree identity (#21) ───────────────────────────────────────────────────────────────────────────
+
+export const isTransitionShaped = (record) =>
+  record.kind === 'bookkeeping-delta' || (record.kind === CHAIN_KIND && record.purpose === 'refresh');
+
+// The compound tree identity every flow record carries; for transition-shaped records the singular
+// fingerprint IS fingerprintAfter.
+export const flowTreeIdentity = (record) => ({
+  base: record.base,
+  fingerprint: isTransitionShaped(record) ? record.fingerprintAfter : record.fingerprint,
+});
+
+// ── per-record canonical digest (#63) — the record-reference id domain ────────────────────────────
+
+const serializeCanonical = (v) => {
+  if (Array.isArray(v)) return `[${v.map(serializeCanonical).join(',')}]`;
+  if (v !== null && typeof v === 'object') {
+    return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${serializeCanonical(v[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(v);
+};
+
+// Canonical bytes of ONE record: recursively key-sorted JSON, NO trailing newline (the newline is
+// store framing, not record identity). A parity test pins these bytes against core-evidence's
+// canonicalKindSerialization on single-record fixtures.
+export const flowCanonicalSerialization = (record) => serializeCanonical(record);
+
+export const canonicalFlowDigest = (record) => createHash('sha256').update(flowCanonicalSerialization(record), 'utf8').digest('hex');
+
+// ── Decision-7 derivation helpers (Plan 4) — pure digests over canonical bytes ────────────────────
+
+// foldBatch keys the IMMUTABLE round identity projection: a round-ledger REVISION keeps
+// {planId, cycle, stepId, round} (same digest — the budget never resets on supersession, #47),
+// a NEW round moves it (fresh budget).
+export const subsetFoldBatchDigest = ({ planId, cycle, stepId, round }) =>
+  createHash('sha256').update(flowCanonicalSerialization({ planId, cycle, stepId, round }), 'utf8').digest('hex');
+
+// The derived subset's counting identity — declaring pregateExclude changes the ordered gate-id
+// list, therefore the key, therefore the counting context (#47/#66).
+export const subsetGateIdsDigest = (gateIds) =>
+  createHash('sha256').update(flowCanonicalSerialization(gateIds), 'utf8').digest('hex');
+
+// ── the owner-scoped projection (Plan 4 Decision 2 / D10) — ONE pure helper, producer + consumer ──
+
+// The hash domain is the OWNER-SCOPED projection, never the whole common store (#57): (a) every
+// chain record whose owner is the committing worktree; (b) every planId-bearing global whose
+// planId belongs to an owned chain; (c) every planId-less global (the down-mark family,
+// degrade-justification, rerun-cause, bookkeeping-delta, maintainer-override — the rule is
+// structural over every planId-less kind) whose tree identity (fingerprintAfter for transitions)
+// is in {fingerprints appearing in owned-chain records} ∪ {the current tree fingerprint}. A
+// foreign worktree's records fall outside (a)-(c) and never move the hash; a same-fingerprint
+// foreign global is IN by (c) — same tree, same decision context. Raw store order is preserved:
+// the projection hash is order-sensitive, so any in-projection append moves it.
+export const ownerScopedFlowProjection = (records, { owner, currentFingerprint }) => {
+  const ownedChain = records.filter((r) => r.kind === CHAIN_KIND && r.owner === owner);
+  const ownedPlanIds = new Set(ownedChain.map((r) => r.planId));
+  const fingerprints = new Set(currentFingerprint == null ? [] : [currentFingerprint]);
+  for (const r of ownedChain) {
+    for (const field of ['fingerprint', 'fingerprintBefore', 'fingerprintAfter']) {
+      if (typeof r[field] === 'string') fingerprints.add(r[field]);
+    }
+  }
+  return records.filter((r) => {
+    if (r.kind === CHAIN_KIND) return r.owner === owner;
+    if (typeof r.planId === 'string') return ownedPlanIds.has(r.planId);
+    return fingerprints.has(flowTreeIdentity(r).fingerprint);
+  });
+};
+
+export const flowProjectionHash = (records, ctx) =>
+  createHash('sha256').update(ownerScopedFlowProjection(records, ctx).map(flowCanonicalSerialization).join('\n'), 'utf8').digest('hex');
+
+// 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 };
+};
+
+// ── 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 };
+};
+
+// ── 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 };
+};