@sabaiway/agent-workflow-kit 5.11.1 → 5.11.2

package/CHANGELOG.md

@@ -4,6 +4,56 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 5.11.2 — the record vocabulary becomes a facade over five leaves (AD-103)
+
+**Nothing you import changes, and that is the whole claim — now certified rather than asserted.**
+`tools/flow-record.mjs` was the kit's most expensive module to read: 795 lines holding eleven of its
+own section seams, from the closed record vocabulary through the field shapes, the identity family,
+the two legality walks and the wrapper finding manifest. It keeps its path and its 29 export names,
+and becomes a 55-line re-export facade over five single-responsibility leaves.
+
+- **`tools/flow-record.mjs` keeps its path, its 29 export names and every one of its 30 import
+  sites.** The internals moved verbatim into `flow-vocabulary.mjs` (96, the lowest leaf: the closed
+  kinds, purposes, terminal lanes, seed assignment and transition table) · `flow-record-shape.mjs`
+  (283, the closed per-kind field shapes and `validateFlowRecord`) · `flow-record-identity.mjs` (115,
+  every answer to "what identifies this record or this set" — keys, tree identity, the canonical
+  digest, the owner-scoped projection) · `flow-legality.mjs` (248, the two raw-order legality walks)
+  · `flow-finding-manifest.mjs` (70). The edges run one way and the family is acyclic by
+  construction; no leaf reaches a write module, so "pure form" is a structural pin instead of a
+  header sentence.
+- **Conservation is certified by ORDER as well as by count.** A comparator normalises both sides
+  identically and then checks, per leaf, that its line SEQUENCE equals the concatenation of its
+  declared source ranges in declared order — a reordering is caught, not just a loss — AND that the
+  multiset over the union of the five leaves equals the pre-split module. Over the 587 executable
+  lines: five sequences EQUAL, the difference EMPTY in both directions. It was then run three more
+  times — against the unsplit module alone, with one leaf omitted, and with one line duplicated — so
+  a comparator that could not report loss or excess could not pass for one that does.
+- **The five shared grammars live in exactly one place.** `HEX64_RE`, `isHex64`, `isPlainObject`,
+  `isNonEmptyString` and `refuse` are exported off-surface from the lowest leaf and used by the
+  others. They are the record family's named grammars — `isHex64` IS the 64-hex digest grammar every
+  consumer takes by reference — and a per-leaf copy is the only way two of them could ever drift.
+  The layout suite pins that off-surface set exactly, so it cannot widen unnoticed.
+- **The owning suite never moved.** `tools/flow-record.test.mjs` is BYTE-IDENTICAL and reproduces
+  58/58; the fifteen named suites show an empty `git diff --name-only` in the worktree and under
+  `--cached`. `test/flow-record-layout.test.mjs` (not shipped) pins the frozen 29-name surface, the
+  facade-declared owner of every name, that the facade carries no logic at all, the size caps, and
+  the one-way edges including their negative direction — four of its five cases were red-proofed on
+  the unsplit tree before the split existed.
+- **`test/package-content.test.mjs` moves its payload pin from 227 to 232 files** and names the five
+  leaves: the facade imports all five, so a leaf falling out of the published tarball would break
+  every flow read at load, and the pin is what says so.
+- **One consumer line changed in the whole tree, and it is a comment.** `dispatch-record.mjs:15`
+  cited the fail-closed rule by line number (`flow-record.mjs:22-24`); the split falsified that
+  reference, so it now names the rule semantically.
+
+Recorded size effect, reason `tranche 3: flow-record split`:
+
+```text
+  agent-workflow-kit/test/package-content.test.mjs: lines 600 → 617 (raise)
+  agent-workflow-kit/tools/flow-record.mjs: lines 795 → none
+  agent-workflow-kit: aggregate lines 125315 → 125669 (raise)
+```
+
 ## 5.11.1 — the flow store becomes a facade over five leaves, and the direct-run guard fix finally reaches you (AD-102)
 
 **A tool invoked through a symlink used to run nothing and exit 0 — and five of the affected tools are

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '5.11.1'
+  version: '5.11.2'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "5.11.1",
+  "version": "5.11.2",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "5.11.1",
+  "version": "5.11.2",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/tools/dispatch-record.mjs

@@ -12,7 +12,7 @@
 //
 // The record family (D3, versioned + closed): pre-registration · dispatch · return · fold ·
 // observation · degrade. Fail-closed in BOTH directions — unknown schema, unknown kind, a missing
-// field, a malformed field and an unknown EXTRA field are all refusals (the flow-record.mjs:22-24
+// field, a malformed field and an unknown EXTRA field are all refusals (the flow-record.mjs header's
 // discipline): the per-record canonical digest is the record's identity, so a stray key would fork
 // it.
 //

package/tools/flow-finding-manifest.mjs

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

package/tools/flow-legality.mjs

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

package/tools/flow-record-identity.mjs

@@ -0,0 +1,115 @@
+// flow-record-identity.mjs — every answer to "what identifies this record, or this set of records":
+// the per-kind supersession keys and the authoritative latest-per-key selection, the compound tree
+// identity (#21), the canonical single-record serialization and its digest (#63 — the whole
+// inter-record reference domain), the two Decision-7 derivation digests, and the owner-scoped
+// projection with its order-sensitive hash. Split out of flow-record.mjs unchanged
+// (baseline-practices tranche 3), which now re-exports every name here.
+//
+// Pure form: no filesystem, no git, no CLI, no side effects on import — node:crypto for the digests
+// and the vocabulary leaf for the one kind constant are all it reaches. Imports run ONE way: the
+// legality leaf composes this module; nothing here reaches back up to the facade.
+
+import { createHash } from 'node:crypto';
+import { CHAIN_KIND } from './flow-vocabulary.mjs';
+
+// ── 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');