rcf-lite 0.28.2 → 0.28.4

package/src/cli/readiness.js

@@ -0,0 +1,280 @@
+// `rcf define readiness` subcommand handler (REQ-175; proposal
+// 2026-09-22 §2.4, §6.2 v3).
+//
+// Prints the readiness object (§2.4) or its JSON envelope. `--check
+// <stage>` narrows the output to one stage; blocking stages exit 4 on
+// failure (matching `coverage`'s per-AC refusal exit); warn-with-ack
+// stages exit 0 with a visible `[warn]` line on unacknowledged
+// failure. The producer is wrapped with `runWithAdmissibilityGate`
+// (NV-BL-SR-03 addendum) so a chain that refuses admissibility short-
+// circuits with the same refusal envelope every other query verb has.
+
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { resolveTestPointers, walkTree } from '#core/store';
+import { checkCodeNodeResolution } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import { loadFreezeRecord } from '../define/freeze-record.js';
+import { loadAllLedgers } from '../define/ledgers.js';
+import {
+  STAGE_ALIASES,
+  STAGE_GATES,
+  STAGE_ORDER,
+  STAGE_SHORT_NAMES,
+  stagePolicy,
+} from '../query/gates.js';
+import { computeReadiness, formatTreeLine } from '../query/readiness.js';
+import { runWithAdmissibilityGate } from '../query/index.js';
+
+const OPTION_SPEC = {
+  json: { type: 'boolean' },
+  check: { type: 'string' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf define readiness [options]
+
+Compute and print the DEFINE readiness view: whether the tree is
+freezeable, which stage gate blocks, what the delta and its fan-out
+look like, and what the CLI recommends as the next action.
+
+The compute is pure: it composes the freeze delta, per-id impact,
+eight stage-gate checks (D1..D8), tree coverage and open decisions
+into one object. The viewer's Readiness tab (slice 5) will render the
+same object with no schema translation.
+
+Options:
+  --json                    Emit the full readiness object as JSON.
+  --check <stage>           Narrow the output to one stage. Accepts a
+                            stage id (D1..D8) or its short name:
+                            brief | skeleton | shapes | stories |
+                            crosscut | consistency | decisions |
+                            freeze. Exits 4 on a blocking-stage
+                            failure (D1 / D2 / D4 / D7 / D8); exits 0
+                            with a visible '[warn]' line on an
+                            unacknowledged warn-with-ack failure
+                            (D3 / D5 / D6). Use --check all to print
+                            every stage under this exit-code policy.
+  --help                    Print this help.
+`;
+
+/** Text label per stage state, for the chip line. */
+const STATE_LABEL = {
+  passed: 'passed',
+  failing: 'failing',
+  acknowledged: 'acknowledged',
+  notApplicable: 'notApplicable',
+};
+
+/**
+ * Read `rcf/.identity/profile.md` when it exists; return null on
+ * ENOENT. Any other read error surfaces as null so the profile
+ * markers just fail to appear (the D1 check treats absence as a
+ * finding, not a runtime error).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>}
+ */
+async function readProfileText(projectRoot) {
+  try {
+    return await readFile(join(projectRoot, 'rcf', '.identity', 'profile.md'), 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return null;
+    return null;
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+
+  const checkArg = flags.check;
+  let checkStage = null;
+  if (typeof checkArg === 'string') {
+    if (checkArg === 'all') {
+      checkStage = 'all';
+    } else if (STAGE_ALIASES[checkArg]) {
+      checkStage = STAGE_ALIASES[checkArg];
+    } else {
+      stderr.write(`[error] usage readiness: unknown --check ${checkArg} (expected D1..D8, one of ${Object.values(STAGE_SHORT_NAMES).join(' | ')}, or 'all')\n`);
+      return 2;
+    }
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+
+  const { tree, errors } = await walkTree({ projectRoot });
+  const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
+  const validateErrors = [...errors, ...staleErrors];
+
+  const [freeze, ledgers, testPointers, profileText] = await Promise.all([
+    loadFreezeRecord({ projectRoot }),
+    loadAllLedgers({ projectRoot }),
+    resolveTestPointers({ projectRoot, tree }),
+    readProfileText(projectRoot),
+  ]);
+
+  const startedAt = Date.now();
+  const chainRulesetVersion = typeof tree.manifest?.rulesetVersion === 'string'
+    ? tree.manifest.rulesetVersion
+    : null;
+
+  // Readiness is a diagnostic: even a chain that refuses admissibility
+  // wants to know which stage gate blocks it. The wrap runs first so
+  // the ruleset toolScope guard is honoured (NV-BL-SR-03 addendum);
+  // on refuse the refusal envelope is threaded through as informational
+  // context and the compute still runs (ADR-4123).
+  const gated = await runWithAdmissibilityGate({
+    tree,
+    chainRulesetVersion,
+    produce: () => computeReadiness(tree, {
+      freeze,
+      ledgers,
+      profile: undefined,
+      profileText,
+      testPointers,
+      validateErrors,
+    }),
+  });
+
+  /** @type {import('../query/readiness.js').ReadinessResult} */
+  const result = gated.status === 'refused-admissibility'
+    ? computeReadiness(tree, {
+      freeze, ledgers, profile: undefined, profileText, testPointers, validateErrors,
+    })
+    : gated.payload;
+  const wallMs = Date.now() - startedAt;
+
+  if (gated.status === 'refused-admissibility') {
+    stderr.write(`[warn] readiness: chain admissibility refused (informational; the readiness compute still ran). ${gated.refusal}\n`);
+  }
+
+  if (flags.json) {
+    // JSON emission carries the full object plus the wall-time hint
+    // as a stable side-band on `_meta` so consumers can spot
+    // regressions without changing shape.
+    const envelope = { ...result, _meta: { wallMs } };
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    return checkStage ? decideExitCode(result, checkStage, stderr) : 0;
+  }
+
+  renderText(stdout, result, wallMs, checkStage);
+  if (checkStage) {
+    return decideExitCode(result, checkStage, stderr);
+  }
+  return 0;
+}
+
+/**
+ * Emit the text summary: tree line, next action, chip line, then a
+ * per-stage failing-items block. When `--check <stage>` names a
+ * stage, only that stage's block is rendered.
+ *
+ * @param {NodeJS.WritableStream} stdout
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @param {number} wallMs
+ * @param {string | null} checkStage
+ */
+function renderText(stdout, result, wallMs, checkStage) {
+  stdout.write(`${formatTreeLine(result)}\n`);
+  if (!checkStage || checkStage === 'all') {
+    if (result.nextAction) {
+      const ids = result.nextAction.ids.length > 0 ? `; ids: ${result.nextAction.ids.join(', ')}` : '';
+      stdout.write(`Next action: ${result.nextAction.stage} / ${result.nextAction.check}${ids}. Run \`${result.nextAction.command}\` after editing.\n`);
+    } else {
+      stdout.write('Next action: none; every gate passed, acknowledged or notApplicable. Freezeable.\n');
+    }
+    stdout.write(`Chips: ${formatChipLine(result)}\n`);
+    stdout.write(`Delta: changed ${result.delta.changed.length}, added ${result.delta.added.length}, removed ${result.delta.removed.length}, briefSince ${result.delta.briefSince.length}, impacted ${result.delta.impacted.length}, impactedFbs ${result.delta.impactedFbs.length}.\n`);
+    stdout.write(`Coverage: tree ${result.coverage.tree.totals.covered}/${result.coverage.tree.totals.requirements} covered (strict), ${result.coverage.delta.length} REQ ancestor(s) scoped from the delta.\n`);
+    stdout.write(`Decisions open: ${result.decisions.length}.\n`);
+    stdout.write(`Freezeable: ${result.freezeable ? 'yes' : 'no'}. Compute: ${wallMs} ms.\n`);
+  }
+
+  for (const stage of result.stages) {
+    if (checkStage && checkStage !== 'all' && stage.stage !== checkStage) continue;
+    stdout.write(`\n${stage.stage} (${stage.gate}) -- ${STATE_LABEL[stage.state] ?? stage.state}${stage.reason ? ` (${stage.reason})` : ''}\n`);
+    for (const c of stage.checks) {
+      const mark = c.ok ? 'ok' : 'FAIL';
+      stdout.write(`  [${mark}] ${c.name} (${c.over}): ${c.pass}/${c.total}\n`);
+      for (const f of c.failing.slice(0, 20)) {
+        stdout.write(`      - ${f.id}: ${f.why}\n`);
+      }
+      if (c.failing.length > 20) {
+        stdout.write(`      ... ${c.failing.length - 20} more suppressed\n`);
+      }
+    }
+  }
+}
+
+/**
+ * Compose the chip line: "D1:passed D2:failing D3:acknowledged ..."
+ *
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @returns {string}
+ */
+function formatChipLine(result) {
+  return result.stages.map((s) => `${s.stage}:${s.state}`).join(' ');
+}
+
+/**
+ * Decide the exit code for a `--check <stage>` invocation:
+ * - passed / acknowledged / notApplicable -> 0
+ * - failing on a blocking stage (D1/D2/D4/D7/D8) -> 4
+ * - failing on a warn-with-ack stage (D3/D5/D6) -> 0 with a stderr [warn]
+ *
+ * The 'all' target folds the individual codes: if any blocking stage
+ * is failing, exit 4; otherwise 0 (warn lines print for each
+ * warn-with-ack failure).
+ *
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @param {string} checkStage
+ * @param {NodeJS.WritableStream} stderr
+ * @returns {number}
+ */
+function decideExitCode(result, checkStage, stderr) {
+  const stages = checkStage === 'all'
+    ? result.stages
+    : result.stages.filter((s) => s.stage === checkStage);
+  let exitCode = 0;
+  for (const s of stages) {
+    if (s.state !== 'failing') continue;
+    const policy = stagePolicy(s.stage);
+    if (policy === 'blocking') {
+      exitCode = 4;
+    } else {
+      stderr.write(`[warn] readiness: ${s.stage} (${s.gate}) is failing without an acknowledgement at the current tree hash. Run \`rcf define freeze --ack ${s.gate} --reason "<text>"\` to acknowledge, or edit the tree to clear the failure.\n`);
+    }
+  }
+  return exitCode;
+}
+
+// Re-export the gate map so consumers importing this module (help,
+// slice 3) share one seam.
+export { STAGE_GATES, STAGE_ORDER, STAGE_SHORT_NAMES };

package/src/core/store/writer.js

@@ -200,18 +200,98 @@ export function nextIdForKind(tree, kind, opts = {}) {
       // one numbering group.
       const groupNum = Number(normaliseId(match[1]));
       const groupLabel = String(groupNum);
+      // Occupancy is every US id in the tree. Each id is classified as
+      // ENCODED (`US-<reqNum><localTwoDigit>` where the reqNum names an
+      // existing REQ and local is 01..99) or FLAT (a bare sequential
+      // number that carries no parent-encoded suffix, as produced by
+      // legacy trees migrated in from WESPA v1). Classification decides
+      // the allocation rule:
+      //   - all-encoded tree (or empty): the historical rule, extend
+      //     `US-<groupLabel><nextLocal>`.
+      //   - all-flat tree: extend the flat sequence past the highest
+      //     existing US number (issue #256 / w-2026-09-29-dave-005).
+      //   - mixed tree: refuse the mint with an explicit error naming
+      //     both schemes, so an operator normalises the tree before a
+      //     new id is issued (Dave disposition 2026-09-30).
+      // AC minting is unchanged; #256 was reproduced against USes only.
+      // Classification prefers the doc's declared reqId (unambiguous) over
+      // the id-only heuristic. Without that, a legacy US-163 filed under
+      // REQ-053 would decompose as parent=1/local=63 and look encoded
+      // whenever REQ-001 happened to exist, defeating the whole rule.
+      const usIds = occupiedIdsOfKind(tree, 'userStory');
+      const reqNums = new Set();
+      for (const rId of occupiedIdsOfKind(tree, 'req')) {
+        const rn = idNumber(rId, 'REQ');
+        if (rn !== null) reqNums.add(rn);
+      }
+      const encoded = [];
+      const flat = [];
+      const seenUsNums = new Set();
+      for (const usId of usIds) {
+        const num = idNumber(usId, 'US');
+        if (num === null) continue;
+        // occupiedIdsOfKind emits both the on-disk id and the doc's
+        // declared id field, so the same numeric id appears twice.
+        // Dedupe on the numeric value to avoid double-counting.
+        if (seenUsNums.has(num)) continue;
+        seenUsNums.add(num);
+        const localPart = num % 100;
+        const parentPart = Math.floor(num / 100);
+        const doc = tree.byId.get(usId);
+        let declaredReqNum = null;
+        if (doc && typeof doc.reqId === 'string') {
+          const mReq = /^REQ-(\d+)$/.exec(doc.reqId);
+          if (mReq) declaredReqNum = Number(normaliseId(mReq[1]));
+        }
+        let isEncoded;
+        if (declaredReqNum !== null) {
+          // Encoded iff the id decomposes as <declaredReqNum><two-digit
+          // local in 01..99>. Any other shape is flat.
+          isEncoded = (localPart >= 1 && localPart <= 99 && parentPart === declaredReqNum);
+        } else {
+          // Invalid / unloadable doc: fall back to the id-only heuristic
+          // (matches historical behaviour when the parent-part names an
+          // existing REQ).
+          isEncoded = (localPart >= 1 && localPart <= 99 && reqNums.has(parentPart));
+        }
+        if (isEncoded) {
+          encoded.push({ id: usId, num, parentPart, localPart });
+        } else {
+          flat.push({ id: usId, num });
+        }
+      }
+
+      if (encoded.length > 0 && flat.length > 0) {
+        const encodedExample = encoded[0].id;
+        const flatExample = flat[0].id;
+        throw new TypeError(
+          'nextIdForKind us: refusing to mint - the tree mixes '
+          + `encoded US ids (e.g. ${encodedExample}, shape US-<reqNum><localTwoDigit>) `
+          + `and flat US ids (e.g. ${flatExample}, shape US-<seq>). `
+          + 'Normalise every US id to one scheme (rename the outliers, '
+          + 'update every reference) and retry, or ask HQ for a bulk '
+          + 're-mint. Auto-mint intentionally refuses on ambiguous trees.',
+        );
+      }
+
+      if (flat.length > 0 && encoded.length === 0) {
+        let maxFlat = 0;
+        for (const f of flat) {
+          if (f.num > maxFlat) maxFlat = f.num;
+        }
+        return `US-${maxFlat + 1}`;
+      }
+
+      // All-encoded (or empty) tree: keep the historical behaviour.
       // Occupancy is every US id that numerically falls in this group,
       // whatever `reqId` string it names. Filtering on an exact reqId
       // string match was the bug: a US filed under `REQ-0001` was
       // invisible when allocating for `REQ-001`, so US-101 got re-issued
       // on top of the existing US-101.
-      const usIds = occupiedIdsOfKind(tree, 'userStory');
       let maxLocal = 0;
-      for (const usId of usIds) {
-        const num = idNumber(usId, 'US');
-        if (num === null) continue;
-        const local = num - groupNum * 100;
-        if (local >= 1 && local <= 99 && local > maxLocal) maxLocal = local;
+      for (const e of encoded) {
+        if (e.parentPart !== groupNum) continue;
+        if (e.localPart > maxLocal) maxLocal = e.localPart;
       }
       const nextLocal = maxLocal + 1;
       return `US-${groupLabel}${String(nextLocal).padStart(2, '0')}`;

package/src/define/freeze-record.js

@@ -0,0 +1,232 @@
+// Freeze record I/O (REQ-172; proposal §2.1 v3).
+//
+// One file: `rcf/define/freeze.json`. Overwritten on every freeze; git
+// holds the history. Owned by rcf-lite, outside the shared rcf-schemas
+// package until 0.7 (ADR-4121). This module is the seam the freeze
+// verb calls in slice 3; the verb itself is not built yet.
+//
+// A missing file returns `null` (a fresh tree; the delta model treats
+// null as unfrozen, proposal §2.2). A malformed file (parse failure,
+// or a body that fails the local schema) raises a clear error
+// naming the file and the failing field. Silence is never the answer
+// to a broken freeze record: the DEFINE gates read this file on every
+// invocation and any downstream check would be lying if it kept going.
+//
+// Local schema (this file, not @stravica-ai/rcf-schemas):
+//
+//   {
+//     frozenAt: ISO-8601 timestamp string,
+//     treeHash: "sha256:<64 hex>",
+//     docHashes: { <docId>: "sha256:<64 hex>", ... },      // required
+//     briefStatements: integer >= 0,                        // required
+//     gates:    { [gate]: { state, at, failing?, reason? } }, // optional
+//     counts:   { req, us, ac, ... } (open object, integers, optional)
+//     litmus:   { attestedAt: string[], readers?: number },  // optional
+//     versions: { rcfLite, ruleset, schemas },                // optional
+//     note:     string | null,                                // optional
+//     override: null | { reason, by, at }                     // required (nullable)
+//   }
+//
+// The record is EXTENSIBLE: later slices add fields (2 gates the freeze
+// verb wrote at freeze time, 4 the `bundle --next` refusal read at
+// override time). This slice validates the fields it consumes and
+// tolerates the rest; unknown properties survive a load/save
+// round-trip so a newer rcf-lite writing the file does not lose them
+// to an older reader mid-migration.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/**
+ * Relative path (under the project root) of the freeze record. Used by
+ * the walker-invisibility invariant test and by every caller that
+ * wants to log the path in an error message.
+ */
+export const FREEZE_RECORD_REL_PATH = 'rcf/define/freeze.json';
+
+/**
+ * Absolute path of the freeze record for a project root.
+ *
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function freezeRecordPath(projectRoot) {
+  return join(projectRoot, FREEZE_RECORD_REL_PATH);
+}
+
+/**
+ * Structured error thrown on a malformed freeze record. Carries the
+ * file path and a short reason. `code` fixes the class so callers can
+ * distinguish parse failures from schema failures without matching on
+ * the message.
+ */
+export class FreezeRecordError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.filePath]
+   * @param {'parseFailure' | 'schemaFailure' | 'ioFailure'} [opts.code]
+   * @param {string} [opts.field]
+   */
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = 'FreezeRecordError';
+    this.filePath = opts.filePath;
+    this.code = opts.code ?? 'schemaFailure';
+    this.field = opts.field;
+  }
+}
+
+const SHA256_RE = /^sha256:[0-9a-f]{64}$/;
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * Validate the parsed body against the local schema described at the
+ * top of this file. Throws `FreezeRecordError` on the first violation
+ * (fail fast; the record is one file).
+ *
+ * @param {unknown} raw
+ * @param {string} [filePath]
+ * @returns {import('../query/delta.js').FreezeRecord & Record<string, unknown>}
+ */
+export function validateFreezeRecord(raw, filePath) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new FreezeRecordError('Freeze record must be a JSON object.', {
+      filePath, field: '(root)',
+    });
+  }
+  const body = /** @type {Record<string, unknown>} */ (raw);
+  const require = /** @type {(field: string) => void} */ ((field) => {
+    if (!Object.prototype.hasOwnProperty.call(body, field)) {
+      throw new FreezeRecordError(`Freeze record missing required field '${field}'.`, {
+        filePath, field,
+      });
+    }
+  });
+
+  require('frozenAt');
+  if (typeof body.frozenAt !== 'string' || !ISO_RE.test(body.frozenAt)) {
+    throw new FreezeRecordError(
+      "Freeze record 'frozenAt' must be an ISO-8601 timestamp string.",
+      { filePath, field: 'frozenAt' },
+    );
+  }
+
+  require('treeHash');
+  if (typeof body.treeHash !== 'string' || !SHA256_RE.test(body.treeHash)) {
+    throw new FreezeRecordError(
+      "Freeze record 'treeHash' must be a 'sha256:<64-hex>' string.",
+      { filePath, field: 'treeHash' },
+    );
+  }
+
+  require('docHashes');
+  const docHashes = body.docHashes;
+  if (docHashes === null || typeof docHashes !== 'object' || Array.isArray(docHashes)) {
+    throw new FreezeRecordError(
+      "Freeze record 'docHashes' must be an object mapping ids to sha256:<hex> strings.",
+      { filePath, field: 'docHashes' },
+    );
+  }
+  for (const [id, hash] of Object.entries(docHashes)) {
+    if (typeof hash !== 'string' || !SHA256_RE.test(hash)) {
+      throw new FreezeRecordError(
+        `Freeze record docHashes['${id}'] must be a 'sha256:<64-hex>' string.`,
+        { filePath, field: `docHashes.${id}` },
+      );
+    }
+  }
+
+  require('briefStatements');
+  if (
+    typeof body.briefStatements !== 'number'
+    || !Number.isInteger(body.briefStatements)
+    || body.briefStatements < 0
+  ) {
+    throw new FreezeRecordError(
+      "Freeze record 'briefStatements' must be a non-negative integer.",
+      { filePath, field: 'briefStatements' },
+    );
+  }
+
+  if (Object.prototype.hasOwnProperty.call(body, 'override')) {
+    const override = body.override;
+    if (override !== null) {
+      if (override === undefined || typeof override !== 'object' || Array.isArray(override)) {
+        throw new FreezeRecordError(
+          "Freeze record 'override' must be null or { reason, by, at }.",
+          { filePath, field: 'override' },
+        );
+      }
+      const o = /** @type {Record<string, unknown>} */ (override);
+      for (const f of ['reason', 'by', 'at']) {
+        if (typeof o[f] !== 'string' || o[f].length === 0) {
+          throw new FreezeRecordError(
+            `Freeze record 'override.${f}' must be a non-empty string.`,
+            { filePath, field: `override.${f}` },
+          );
+        }
+      }
+    }
+  }
+
+  return /** @type {import('../query/delta.js').FreezeRecord & Record<string, unknown>} */ (body);
+}
+
+/**
+ * Load and validate the freeze record for a project. Returns null
+ * when the file does not exist; throws `FreezeRecordError` on parse
+ * or schema failure.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<(import('../query/delta.js').FreezeRecord & Record<string, unknown>) | null>}
+ */
+export async function loadFreezeRecord({ projectRoot }) {
+  const filePath = freezeRecordPath(projectRoot);
+  const relPath = FREEZE_RECORD_REL_PATH;
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return null;
+    throw new FreezeRecordError(
+      `Failed to read ${relPath}: ${/** @type {Error} */ (err).message}`,
+      { filePath: relPath, code: 'ioFailure' },
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new FreezeRecordError(
+      `Freeze record parse failed: ${/** @type {Error} */ (err).message}`,
+      { filePath: relPath, code: 'parseFailure' },
+    );
+  }
+  return validateFreezeRecord(parsed, relPath);
+}
+
+/**
+ * Write the freeze record. Validates first (so a bad in-memory record
+ * never lands as JSON on disk), creates `rcf/define/` if needed, and
+ * writes pretty-printed JSON with a trailing newline (matches the
+ * neighbouring rcf/*.json files' shape).
+ *
+ * The slice-3 `rcf define freeze` verb is the intended caller; this
+ * slice exposes the writer so that verb can be built without another
+ * refactor. Every direct caller is expected to have run
+ * `computeReadiness` first and only write when the tree is freezeable.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('../query/delta.js').FreezeRecord & Record<string, unknown>} args.record
+ * @returns {Promise<{ filePath: string }>}
+ */
+export async function saveFreezeRecord({ projectRoot, record }) {
+  const validated = validateFreezeRecord(record, FREEZE_RECORD_REL_PATH);
+  const filePath = freezeRecordPath(projectRoot);
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(validated, null, 2)}\n`, 'utf8');
+  return { filePath };
+}