rcf-lite 0.28.2 → 0.29.0

package/src/mcp/tools.js

@@ -43,6 +43,14 @@ import {
 } from '../query/index.js';
 import { assembleBundle } from '../build/index.js';
 import { hasAgentMarker, SETUP_FUNNEL_INSTRUCTION } from '../setup/agent-setup.js';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { computeReadiness } from '../query/readiness.js';
+import { computeQuestions, PERSONAS as QUESTIONS_PERSONAS } from '../query/questions.js';
+import { loadFreezeRecord } from '../define/freeze-record.js';
+import { loadAllLedgers, LedgerError } from '../define/ledgers.js';
+import { STAGE_ALIASES } from '../query/gates.js';
+import { main as ledgerCliMain } from '../cli/ledger.js';
 
 // ---------------------------------------------------------------------------
 // Shared output-schema fragments
@@ -448,6 +456,93 @@ const BUILD_OUTPUT_SCHEMA = {
   ],
 };
 
+// REQ-186 (spec 2026-10-01 §1.2, §6): the questions object is wide
+// and recursive in its context field. The output schema stays loose
+// (an object with no additionalProperties: false) so the per-question
+// context carries any of statement, suggestions, decision, reqId,
+// profileField without a schema break per template addition.
+const QUESTIONS_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    treeHash: { type: ['string', 'null'] },
+    persona: { type: 'string', enum: ['productOwner', 'engineer'] },
+    level: { type: 'string', enum: ['intent', 'build'] },
+    ok: { type: 'boolean' },
+    remaining: { type: 'integer' },
+    groups: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          key: { type: 'string' },
+          label: { type: 'string' },
+          questionIds: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['key', 'label', 'questionIds'],
+      },
+    },
+    questions: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          stage: { type: 'string' },
+          check: { type: 'string' },
+          itemId: { type: 'string' },
+          heading: { type: 'string' },
+          ask: { type: 'string' },
+          context: { type: 'object' },
+          answerKinds: { type: 'array', items: { type: 'string' } },
+          writeBack: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                when: { type: 'string' },
+                command: { type: 'string' },
+              },
+              required: ['when', 'command'],
+            },
+          },
+          blocks: { type: 'string', enum: ['intent', 'build'] },
+        },
+        required: ['id', 'stage', 'check', 'itemId', 'heading', 'ask', 'answerKinds', 'writeBack', 'blocks'],
+      },
+    },
+    optional: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          ask: { type: 'string' },
+          blocks: { type: 'string', enum: ['build'] },
+        },
+        required: ['id', 'ask', 'blocks'],
+      },
+    },
+    engineer: {
+      type: 'object',
+      properties: {
+        blockers: { type: 'integer' },
+        nextAction: { type: ['object', 'null'] },
+      },
+    },
+  },
+  required: ['treeHash', 'persona', 'level', 'ok', 'remaining', 'groups', 'questions', 'optional'],
+};
+
+// REQ-186: `rcf_define_readiness` returns the readiness envelope.
+// Kept loose so new fields on readiness do not force an output-schema
+// bump; the parity test over the verb's --json locks the actual shape.
+const READINESS_OUTPUT_SCHEMA = { type: 'object' };
+
+// REQ-186: `rcf_define_ledger` wraps the four-ledger handler.
+// Return shape depends on the verb, so stays loose and the handler
+// echoes the verb's own JSON envelope verbatim.
+const LEDGER_OUTPUT_SCHEMA = { type: 'object' };
+
 // ---------------------------------------------------------------------------
 // Tool definitions (D5-D7, D17)
 // ---------------------------------------------------------------------------
@@ -661,6 +756,73 @@ const DEFINITIONS = [
     outputSchema: withErrorPayload(BUILD_OUTPUT_SCHEMA),
     annotations: { readOnlyHint: true },
   },
+  {
+    name: 'rcf_define_questions',
+    title: 'Persona question set for the intent-complete loop',
+    description: 'Returns the product-owner question set: one plain question per failing product-owner check with the exact write-back command that answers it. The compute is pure: no file under rcf/ is created or modified. Answers land through the write-back the question carries, then readiness recomputes; the loop ends when levels.intentComplete.ok is true. Method: a product-owner session starts with rcf_define_questions {persona: "productOwner"} and ends at the empty question set. {persona: "engineer"} returns the same shape over engineer blockers, but per-check question templates and write-backs for the engineer register are not part of DEFINE step 3 PR 2 (spec section 1.1 defers them to step 4); engineer-persona entries today carry empty answerKinds and writeBack and the harness runs the engineer verb by hand off the raw blocker.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        persona: { type: 'string', enum: ['productOwner', 'engineer'], description: 'Defaults to the register marker in rcf/.identity/profile.md, else productOwner.' },
+        stage: { type: 'string', description: 'Narrow to one stage (D1..D8 or short name).' },
+        limit: { type: 'integer', minimum: 0, description: 'Cap questions[] length; `remaining` still counts every matching item.' },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: withErrorPayload(QUESTIONS_OUTPUT_SCHEMA),
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'rcf_define_readiness',
+    title: 'DEFINE stage-gate readiness view',
+    description: 'Returns the DEFINE readiness object: freezeable verdict, every stage/check state, levels (intentComplete, readyToBuild), personas (productOwner, engineer), delta, coverage and open decisions. The same object the Readiness tab consumes and the verb\'s --json prints. Writes nothing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        level: { type: 'string', enum: ['intent', 'build'], description: 'Informational echo on the envelope _meta; does not filter the compute.' },
+        check: { type: 'string', description: 'Narrow the text summary to one stage (D1..D8 or short name). The structuredContent still carries every stage.' },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: withErrorPayload(READINESS_OUTPUT_SCHEMA),
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'rcf_define_ledger',
+    title: 'Sidecar-ledger CRUD under rcf/define/',
+    description: 'Thin wrapper over the `rcf define ledger` handler. verb is one of add | update | resolve | list over one of the four ledgers (brief | decisions | concerns | probes). The command\'s JSON envelope is returned as structuredContent.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', enum: ['brief', 'decisions', 'concerns', 'probes'] },
+        verb: { type: 'string', enum: ['add', 'update', 'resolve', 'list'] },
+        id: { type: 'integer', minimum: 1, description: 'Required for update and resolve: the statement id.' },
+        text: { type: 'string' },
+        kind: { type: 'string' },
+        source: { type: 'string' },
+        from: { type: 'string', description: 'Path to a statement file (brief add --from).' },
+        resolvedBy: { type: 'string', description: 'Closed-grammar pointer: REQ-nnn | TAD.entity:<name> | PRD.user:<name> | TAD.system:<name> | TAC-nnnn | omitted:<reason>.' },
+        answer: { type: 'string' },
+        question: { type: 'string' },
+        option: { type: 'array', items: { type: 'string' }, description: 'Letter-prefixed decision options, e.g. ["a:accept", "b:reject"].' },
+        default: { type: 'string', description: 'Decision default option letter.' },
+        blocks: { type: 'string', description: 'Decision blocks selector, e.g. "brief:7".' },
+        scan: { type: 'boolean' },
+        findings: { type: 'string' },
+        dryRun: { type: 'boolean' },
+        reason: { type: 'string', description: 'resolve/add reason (concerns, probes).' },
+        req: { type: 'string', description: 'REQ-id for concerns and probes.' },
+        concern: { type: 'string', description: 'Concern slug (auth, retention...).' },
+        disposition: { type: 'string', enum: ['applied', 'waived'], description: 'Concerns disposition.' },
+        finding: { type: 'string', description: 'Probe finding text.' },
+        severity: { type: 'string', enum: ['low', 'medium', 'high'], description: 'Probe finding severity.' },
+      },
+      required: ['name', 'verb'],
+      additionalProperties: false,
+    },
+    outputSchema: withErrorPayload(LEDGER_OUTPUT_SCHEMA),
+    annotations: { destructiveHint: false },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -849,6 +1011,92 @@ function okResult(envelope) {
   };
 }
 
+/**
+ * Read `rcf/.identity/profile.md` for the questions / readiness
+ * handlers. Returns null on any error (absence is a finding, not a
+ * tool error).
+ */
+async function readProfileTextForMcp(projectRoot) {
+  try {
+    return await readFile(join(projectRoot, 'rcf', '.identity', 'profile.md'), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick the ACTIVE register marker from the profile text. The template
+ * mentions all three marker words in its explanation; the chosen
+ * value is the bare word on a line of its own. The last such line
+ * wins; a "Register: engineer" prose line is honoured via the
+ * last-occurrence fallback. Matches the CLI's pickRegister.
+ */
+function pickRegisterForMcp(text) {
+  if (typeof text !== 'string' || text.length === 0) return 'unstated';
+  const markers = ['productOwner', 'engineer', 'unstated'];
+  const lines = text.split(/\r?\n/);
+  let bareLine = null;
+  for (const raw of lines) {
+    const trimmed = raw.trim();
+    if (markers.includes(trimmed)) bareLine = trimmed;
+  }
+  if (bareLine) return /** @type {any} */ (bareLine);
+  let bestIdx = -1;
+  let best = null;
+  for (const m of markers) {
+    const idx = text.lastIndexOf(m);
+    if (idx > bestIdx) { bestIdx = idx; best = m; }
+  }
+  return /** @type {any} */ (best) ?? 'unstated';
+}
+
+/**
+ * Translate the MCP tool arguments for `rcf_define_ledger` into an
+ * argv that `rcf define ledger` understands. Shared vocabulary and
+ * `--json` always appended so the handler can round-trip the envelope.
+ */
+function buildLedgerArgvFromMcp(args) {
+  const argv = [args.name, args.verb];
+  if (args.verb === 'update' || args.verb === 'resolve') {
+    argv.push(String(args.id ?? ''));
+  }
+  const pushFlag = (name, value) => {
+    if (value === undefined || value === null) return;
+    argv.push(`--${name}`);
+    argv.push(String(value));
+  };
+  const pushBool = (name, value) => {
+    if (value === true) argv.push(`--${name}`);
+    else if (value === false) argv.push(`--no-${name}`);
+  };
+  pushFlag('text', args.text);
+  pushFlag('kind', args.kind);
+  pushFlag('source', args.source);
+  pushFlag('from', args.from);
+  pushFlag('resolved-by', args.resolvedBy);
+  pushFlag('answer', args.answer);
+  pushFlag('question', args.question);
+  pushFlag('default', args.default);
+  pushFlag('blocks', args.blocks);
+  pushFlag('findings', args.findings);
+  pushFlag('reason', args.reason);
+  pushFlag('req', args.req);
+  pushFlag('concern', args.concern);
+  pushFlag('disposition', args.disposition);
+  pushFlag('finding', args.finding);
+  pushFlag('severity', args.severity);
+  if (Array.isArray(args.option)) {
+    for (const o of args.option) {
+      argv.push('--option');
+      argv.push(String(o));
+    }
+  }
+  if (args.scan !== undefined) pushBool('scan', args.scan);
+  if (args.dryRun) argv.push('--dry-run');
+  argv.push('--json');
+  return argv;
+}
+
 /**
  * Create the tool registry bound to one project root (D13: the root is
  * fixed for the process lifetime).
@@ -1119,6 +1367,112 @@ export function createToolRegistry({ projectRoot, log }) {
       // (reconciliation carry 2, OQ-P7-8 posture).
       return okResult({ ok: true, mode: 'bundle', ...bundle });
     },
+
+    rcf_define_readiness: async (args) => {
+      const { tree, errors } = await walkTree({ projectRoot });
+      const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
+      const validateErrors = [...errors, ...staleErrors];
+      // Validate --check / --level inputs the same way the CLI does.
+      let checkStage = null;
+      if (typeof args.check === 'string') {
+        if (args.check === 'all') checkStage = 'all';
+        else if (STAGE_ALIASES[args.check]) checkStage = STAGE_ALIASES[args.check];
+        else return usageErrorResult(`readiness: unknown --check '${args.check}'`);
+      }
+      const [freeze, ledgers, testPointers, profileText] = await Promise.all([
+        loadFreezeRecord({ projectRoot }),
+        loadAllLedgers({ projectRoot }),
+        resolveTestPointers({ projectRoot, tree }),
+        readProfileTextForMcp(projectRoot),
+      ]);
+      const result = computeReadiness(tree, {
+        freeze, ledgers, profile: undefined, profileText, testPointers, validateErrors,
+      });
+      const level = args.level ?? null;
+      return okResult({ ...result, _meta: { checkStage, level } });
+    },
+
+    rcf_define_questions: async (args) => {
+      const persona = args.persona;
+      if (persona !== undefined && !QUESTIONS_PERSONAS.includes(persona)) {
+        return usageErrorResult(`questions: unknown persona '${persona}' (expected one of ${QUESTIONS_PERSONAS.join(' | ')})`);
+      }
+      let stageFilter = null;
+      if (typeof args.stage === 'string') {
+        if (!STAGE_ALIASES[args.stage]) {
+          return usageErrorResult(`questions: unknown --stage '${args.stage}'`);
+        }
+        stageFilter = STAGE_ALIASES[args.stage];
+      }
+      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 }),
+        readProfileTextForMcp(projectRoot),
+      ]);
+      let resolvedPersona = persona;
+      if (resolvedPersona === undefined) {
+        resolvedPersona = pickRegisterForMcp(profileText) === 'engineer' ? 'engineer' : 'productOwner';
+      }
+      const readiness = computeReadiness(tree, {
+        freeze, ledgers, profile: undefined, profileText, testPointers, validateErrors,
+      });
+      const result = computeQuestions(readiness, {
+        tree, ledgers, profileText, persona: resolvedPersona,
+      });
+      let filtered = result.questions;
+      if (stageFilter) filtered = filtered.filter((q) => q.stage === stageFilter);
+      const remaining = filtered.length;
+      if (Number.isInteger(args.limit) && args.limit >= 0) {
+        filtered = filtered.slice(0, args.limit);
+      }
+      const groupMap = new Map();
+      for (const q of filtered) {
+        const key = q.context?.statement?.source ?? q.context?.sourceSpan ?? 'tree';
+        const existing = groupMap.get(key) ?? { key, label: result.groups.find((g) => g.key === key)?.label ?? key, questionIds: [] };
+        existing.questionIds.push(q.id);
+        groupMap.set(key, existing);
+      }
+      return okResult({
+        ...result,
+        questions: filtered,
+        groups: [...groupMap.values()],
+        remaining,
+      });
+    },
+
+    rcf_define_ledger: async (args) => {
+      const argv = buildLedgerArgvFromMcp(args);
+      // Capture the ledger CLI's stdout/stderr; the handler returns JSON
+      // via --json which we parse back for structuredContent.
+      let out = '';
+      let err = '';
+      const stdout = { write: (s) => { out += s; } };
+      const stderr = { write: (s) => { err += s; } };
+      let exitCode;
+      try {
+        exitCode = await ledgerCliMain(argv, { stdout, stderr, cwd: projectRoot });
+      } catch (e) {
+        return unexpectedFailureResult({ kind: 'ioFailure', message: /** @type {Error} */ (e).message, stack: /** @type {Error} */ (e).stack }, log);
+      }
+      if (exitCode === 2) {
+        return usageErrorResult(`ledger: ${err.trim() || 'usage error'}`);
+      }
+      if (exitCode !== 0) {
+        return errorResult([{ kind: 'ioFailure', message: `ledger ${args.verb} failed: ${err.trim() || out.trim()}`, documentId: null, field: null, rule: null }]);
+      }
+      // Try to parse JSON; if the verb printed text, pass the text back.
+      let envelope;
+      try {
+        envelope = JSON.parse(out);
+      } catch {
+        envelope = { ok: true, name: args.name, verb: args.verb, text: out };
+      }
+      return okResult(envelope);
+    },
   };
 
   async function linkHandler(args, removing) {

package/src/query/delta.js

@@ -0,0 +1,282 @@
+// Detection model foundation (REQ-172; proposal 2026-09-22 §2.2 v3).
+//
+// Three pure functions:
+//
+//   - `hashDocument(doc)`      SHA-256 over the canonical JSON of the
+//                              parsed document. `sha256:<hex>` string.
+//   - `computeTreeHash(hashes)` SHA-256 over the sorted `(id, docHash)`
+//                              pairs, canonically JSON-encoded.
+//   - `computeDelta(tree, freeze, ledgers)`
+//                              the whole change model, returning the
+//                              shape the proposal contracts in §2.2.
+//
+// Canonical JSON, chosen at proposal §2.1: keys sorted recursively, no
+// whitespace, no trailing separators. A hand reformat that changes
+// nothing is not a change; that is what an operator expects, and it
+// costs one canonicalise per document per read (milliseconds at the
+// backstory-scale tree of 700 criteria). Hashing raw bytes would be
+// one line shorter and would report drift after `rcf define update`
+// rewrote a file it did not semantically touch (ADR-4120).
+//
+// Document granularity (proposal §2.2, ADR-4120): the delta is a set of
+// standalone-document ids -- one entry per document the walker exposes
+// on `tree.byId` (PRD, TAD, BS, REQ, US, TAC, ADR, FBS, TS, CN, EVAL),
+// plus one `ledger:<name>` entry per sidecar ledger the caller passes.
+// Inline AC and TC entries ride inside the parent hash: editing
+// `AC-207-4` shows as `US-207 changed`, and the criterion-level diff is
+// git's job.
+//
+// Pure: no filesystem I/O, no state, no time. Every call takes plain
+// data in and returns plain data out.
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Canonicalise a value to the JSON string the hash is taken over.
+ *
+ * - Objects: keys sorted lexicographically, then each `<key>:<value>`
+ *   joined by `,` and wrapped in `{}`.
+ * - Arrays: elements in source order, canonicalised, joined by `,`
+ *   and wrapped in `[]`.
+ * - Strings: `JSON.stringify` (RFC 8259 escaping).
+ * - Numbers and booleans: `JSON.stringify` (finite numbers only; NaN
+ *   and +/-Infinity yield `null` in JSON, which is honest for a value
+ *   the parsed document could not legally hold).
+ * - `null` and `undefined`: `undefined` is omitted from objects and
+ *   arrays (matches `JSON.stringify` semantics); a top-level
+ *   `undefined` yields the empty string, which the caller treats as a
+ *   distinct value from `null` (never expected in a parsed document).
+ *
+ * No whitespace anywhere. Deterministic on the input tree.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicaliseJson(value) {
+  if (value === null) return 'null';
+  const t = typeof value;
+  if (t === 'string') return JSON.stringify(value);
+  if (t === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
+  if (t === 'boolean') return value ? 'true' : 'false';
+  if (t === 'undefined') return '';
+  if (Array.isArray(value)) {
+    const parts = [];
+    for (const el of value) {
+      // JSON.stringify drops undefined elements to null in arrays; keep
+      // that shape so an accidentally-sparse array hashes the same as
+      // its JSON.stringify form (never expected in a parsed document,
+      // where JSON.parse cannot produce one).
+      parts.push(el === undefined ? 'null' : canonicaliseJson(el));
+    }
+    return `[${parts.join(',')}]`;
+  }
+  if (t === 'object') {
+    const keys = Object.keys(/** @type {object} */ (value)).sort();
+    const parts = [];
+    for (const k of keys) {
+      const v = (/** @type {Record<string, unknown>} */ (value))[k];
+      if (v === undefined) continue; // JSON.stringify omits undefined in objects.
+      parts.push(`${JSON.stringify(k)}:${canonicaliseJson(v)}`);
+    }
+    return `{${parts.join(',')}}`;
+  }
+  // Functions, symbols, bigints: never legally present in a parsed
+  // document. Fall back to JSON.stringify's own null coercion.
+  return 'null';
+}
+
+/**
+ * Hash one parsed document. Returns `sha256:<64-hex>` per proposal
+ * §2.1. Accepts any value the walker's `tree.byId` map holds (an
+ * object) and also `null` / primitives (a ledger sidecar hashed as a
+ * whole, for example, may pass a plain array).
+ *
+ * @param {unknown} doc
+ * @returns {string}
+ */
+export function hashDocument(doc) {
+  const canonical = canonicaliseJson(doc);
+  const hex = createHash('sha256').update(canonical, 'utf8').digest('hex');
+  return `sha256:${hex}`;
+}
+
+/**
+ * Hash a `docHashes` map. Sorts the `(id, docHash)` pairs
+ * lexicographically by id, canonically encodes the array of pairs,
+ * and hashes that string. Matches proposal §2.1 ("the sorted (id,
+ * docHash) pairs"). Accepts a plain object or a Map.
+ *
+ * @param {Record<string, string> | Map<string, string>} docHashes
+ * @returns {string}
+ */
+export function computeTreeHash(docHashes) {
+  /** @type {[string, string][]} */
+  const pairs = [];
+  if (docHashes instanceof Map) {
+    for (const [id, h] of docHashes) pairs.push([String(id), String(h)]);
+  } else if (docHashes && typeof docHashes === 'object') {
+    for (const [id, h] of Object.entries(docHashes)) pairs.push([id, String(h)]);
+  }
+  pairs.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const hex = createHash('sha256').update(canonicaliseJson(pairs), 'utf8').digest('hex');
+  return `sha256:${hex}`;
+}
+
+/**
+ * Every standalone-document id the walker holds, sorted. Every id in
+ * `tree.byId` (PRD, TAD, BS, REQ, US, TAC, ADR, FBS, TS, CN, EVAL).
+ * Inline AC / TC ids ride inside their parent's hash and are NOT
+ * enumerated here; delta granularity is the standalone document
+ * (proposal §2.2, ADR-4120).
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @returns {string[]}
+ */
+function standaloneIds(tree) {
+  if (!tree || !tree.byId) return [];
+  return [...tree.byId.keys()].sort();
+}
+
+/**
+ * @typedef {object} LedgerBundle
+ * @property {unknown} [brief]     brief-ledger.json body (null / absent = untouched)
+ * @property {unknown} [decisions] decisions-ledger.json body
+ * @property {unknown} [concerns]  concern-ledger.json body
+ * @property {unknown} [probes]    probe-ledger.json body
+ *
+ * The delta hashes only the ledgers the caller passes -- if a project
+ * has not authored any decisions, the caller passes no `decisions`
+ * key and the delta records no `ledger:decisions` docHash. This
+ * keeps the model additive: sidecars appear when they exist, never
+ * before.
+ */
+
+/**
+ * @typedef {object} FreezeRecord
+ * @property {string} [frozenAt]
+ * @property {string} [treeHash]
+ * @property {Record<string, string>} [docHashes]
+ * @property {number} [briefStatements]
+ */
+
+/**
+ * @typedef {object} DeltaResult
+ * @property {boolean} frozen
+ *   false when the freeze record is absent (a fresh tree; everything
+ *   is `added`, per proposal §2.2 "before the first freeze the delta
+ *   is the whole tree").
+ * @property {string | null} frozenAt
+ * @property {string | null} treeHash
+ *   The tree hash the freeze record stored, or null when unfrozen.
+ * @property {string} currentTreeHash
+ *   The tree hash recomputed from the live tree.
+ * @property {string[]} changed  ids whose hash differs
+ * @property {string[]} added    ids not in `docHashes`
+ * @property {string[]} removed  ids in `docHashes` with no live document
+ * @property {number[]} briefSince
+ *   Ledger-brief statement ids above the freeze high-water mark.
+ * @property {number} unchanged  count of ids present in both maps with
+ *                               the same hash (excludes ledgers).
+ * @property {Record<string, string>} currentDocHashes
+ *   The live per-document hashes keyed by id (ledgers appear under
+ *   `ledger:<name>`). Exposed so the viewer can show a document-level
+ *   hash diff for every changed/added id (spec section 5 block 6).
+ */
+
+/**
+ * Compute the delta between the live tree and the freeze record.
+ *
+ * Pure. No filesystem, no time, no state. Runs on every read (the
+ * proposal's whole point: the freeze record and the tree are the only
+ * inputs to the change model).
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {FreezeRecord | null | undefined} freeze
+ * @param {LedgerBundle | null | undefined} [ledgers]
+ * @returns {DeltaResult}
+ */
+export function computeDelta(tree, freeze, ledgers) {
+  /** @type {Record<string, string>} */
+  const currentHashes = {};
+  for (const id of standaloneIds(tree)) {
+    currentHashes[id] = hashDocument(tree.byId.get(id));
+  }
+  const ledgerBundle = ledgers ?? {};
+  for (const [name, body] of Object.entries(ledgerBundle)) {
+    if (body === undefined || body === null) continue;
+    currentHashes[`ledger:${name}`] = hashDocument(body);
+  }
+
+  const currentTreeHash = computeTreeHash(currentHashes);
+
+  // Unfrozen path (proposal §2.2): the delta is the whole tree,
+  // reported as `added`. frozenAt / treeHash null; briefSince empty
+  // (there is no high-water mark to compare against yet, and D1's
+  // scoping rule keeps the greenfield brief in the delta by definition
+  // -- the ledger itself is a docHash entry when the caller passes one).
+  if (!freeze || typeof freeze !== 'object' || !freeze.docHashes) {
+    return {
+      frozen: false,
+      frozenAt: null,
+      treeHash: null,
+      currentTreeHash,
+      changed: [],
+      added: Object.keys(currentHashes).sort(),
+      removed: [],
+      briefSince: [],
+      unchanged: 0,
+      currentDocHashes: { ...currentHashes },
+    };
+  }
+
+  const frozenHashes = freeze.docHashes;
+  /** @type {string[]} */
+  const changed = [];
+  /** @type {string[]} */
+  const added = [];
+  /** @type {string[]} */
+  const removed = [];
+  let unchanged = 0;
+
+  const liveIds = Object.keys(currentHashes);
+  for (const id of liveIds) {
+    if (Object.prototype.hasOwnProperty.call(frozenHashes, id)) {
+      if (frozenHashes[id] === currentHashes[id]) unchanged += 1;
+      else changed.push(id);
+    } else {
+      added.push(id);
+    }
+  }
+  for (const id of Object.keys(frozenHashes)) {
+    if (!Object.prototype.hasOwnProperty.call(currentHashes, id)) removed.push(id);
+  }
+  changed.sort();
+  added.sort();
+  removed.sort();
+
+  const highWater = Number.isFinite(freeze.briefStatements) ? Number(freeze.briefStatements) : 0;
+  /** @type {number[]} */
+  const briefSince = [];
+  const brief = ledgerBundle.brief;
+  if (brief && typeof brief === 'object' && Array.isArray(/** @type {any} */ (brief).statements)) {
+    for (const s of /** @type {any} */ (brief).statements) {
+      if (!s || typeof s !== 'object') continue;
+      const n = Number(s.id);
+      if (Number.isFinite(n) && n > highWater) briefSince.push(n);
+    }
+    briefSince.sort((a, b) => a - b);
+  }
+
+  return {
+    frozen: true,
+    frozenAt: typeof freeze.frozenAt === 'string' ? freeze.frozenAt : null,
+    treeHash: typeof freeze.treeHash === 'string' ? freeze.treeHash : null,
+    currentTreeHash,
+    changed,
+    added,
+    removed,
+    briefSince,
+    unchanged,
+    currentDocHashes: { ...currentHashes },
+  };
+}