rcf-lite 0.28.1 → 0.28.4

package/src/feedback/redact.js

@@ -20,6 +20,7 @@
 // secret-shape check the last line of defence, which is what the
 // residual-match refusal in rule 8 leans on.
 
+import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -43,6 +44,14 @@ export const BODY_CAP_BYTES = 8 * 1024;
  * conservative: anything a normal profile.md ## Name line might carry
  * as a common English or engineering noun.
  */
+
+// Codex P1-4: per-call collision-safe stash marker suffix. The suffix is
+// 32 hex chars from randomUUID, which is astronomically unlikely to
+// appear as a literal substring in prose the operator would submit.
+function gitStashUuid() {
+  return randomUUID().replace(/-/g, '');
+}
+
 export const RESERVED_IDENTITY_TOKENS = Object.freeze(new Set([
   'agent', 'agents', 'user', 'users', 'operator', 'operators',
   'admin', 'admins', 'root', 'client', 'clients', 'server', 'servers',
@@ -435,18 +444,98 @@ export function redact(input, context = {}) {
     }
   }
 
+  // 0.28.3 (Codex P1-1): move the rule-4 allowlist plumbing up so
+  // R5f's bare-remote stash can decide whether to preserve or fold the
+  // host before it hides the token. Duplicated later in the rule-4
+  // block was removed at the same time.
+  const allowHosts = new Set([
+    ...BUNDLED_ALLOWLIST.hosts,
+    ...(Array.isArray(context.allowHosts) ? context.allowHosts : []),
+  ].map((h) => h.toLowerCase()));
+  const allowExtensions = new Set([
+    ...(Array.isArray(BUNDLED_ALLOWLIST.extensions) ? BUNDLED_ALLOWLIST.extensions : []),
+    ...(Array.isArray(context.allowExtensions) ? context.allowExtensions : []),
+  ].map((e) => String(e).toLowerCase()));
+
+  // Rule 3-guard (design amendment R5f, issue #243, 0.28.3): protect the
+  // git protocol sentinel `git@<host>` before rule 3 runs. In a URL whose
+  // scheme is git+ssh/ssh/git, and in the bare git-remote shape
+  // `git@<host>:<owner>/<repo>`, `git@<host>` is URI userinfo, not an
+  // email. Folding it destroys evidence pointers copied from git remotes
+  // and clone URLs. We stash the full matched span before the email regex
+  // runs and restore it before rule 4 so the host inside the span is
+  // still eligible for the URL / bare-host fold.
+  const gitProtoRe = /(?:git\+ssh|ssh|git):\/\/git@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+  const gitRemoteBareRe = /(?<![A-Za-z0-9._%+-])git@[A-Za-z0-9.-]+\.[A-Za-z]{2,}(?=:[^\s]+\/)/g;
+  const gitStash = [];
+  // Use a per-invocation random marker so a literal `GITPROTO0GITPROTO`
+  // in the operator's prose cannot be replayed as a restore token
+  // (Codex P1-4). The marker is 32 hex chars from randomUUID, wrapped
+  // in an unusual sigil (`\u0002...\u0003`) that would not survive
+  // the ctrl-char strip pass at rule 8a-late anyway, guaranteeing
+  // collision-free restoration for the duration of this call.
+  const GIT_STASH_TAG = `GITPROTO_${gitStashUuid()}`;
+  // Precompute a bare-remote host allowlist check per candidate:
+  // Codex P1-1 called out that a bare `git@<host>:...` remote used
+  // to have its host folded via the pre-fix email rule, and the R5f
+  // protection accidentally shielded the host too. Restore the host-
+  // level allowlist gate here: an allowlisted host stays verbatim,
+  // an unallowlisted host has the host portion folded to `<host>`
+  // before we stash, so the sentinel-plus-<host> shape survives
+  // through the pipeline.
+  function stashBareRemote(m) {
+    const at = m.indexOf('@');
+    const host = m.slice(at + 1);
+    if (isHostAllowed(host, allowHosts)) {
+      gitStash.push(m);
+    } else {
+      // Record a hostname ledger row so the operator disclosure names
+      // what was folded, matching the shape rule 4 would have used.
+      const before = host;
+      const after = '<host>';
+      // We push a synthetic ledger row for the hostname family (one
+      // per bare-remote fold). Deduplicated within the pass.
+      ledger.push({ rule: 'hostname', before, after, count: 1 });
+      gitStash.push(`git@${after}`);
+    }
+    return `${GIT_STASH_TAG}${gitStash.length - 1}${GIT_STASH_TAG}`;
+  }
+  text = text.replace(gitProtoRe, (m) => {
+    gitStash.push(m);
+    return `${GIT_STASH_TAG}${gitStash.length - 1}${GIT_STASH_TAG}`;
+  });
+  text = text.replace(gitRemoteBareRe, stashBareRemote);
+
   // Rule 3: emails -> <email>. RFC-5322 lite; case-insensitive.
   const emailRe = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
   text = replaceRegex(text, emailRe, () => '<email>', 'email', ledger);
 
+  // R5f: restore git protocol sentinels. The stashed spans now re-enter
+  // the pipeline for rule 4 (URL / bare-host). Rule 4's URL regex is
+  // extended below to match git+ssh/ssh/git schemes with optional
+  // userinfo, so a non-allowlisted host inside a restored clone URL
+  // (e.g. `ssh://git@example.internal/owner/repo.git`) folds via that
+  // path while the `git@` userinfo is preserved. A bare
+  // `git@<host>:<owner>/<repo>` remote is left as-is by rule 4 because
+  // it has no scheme prefix and the bareHost lookbehind excludes `@`;
+  // the sentinel-protection posture is sufficient for that shape.
+  if (gitStash.length > 0) {
+    text = text.replace(new RegExp(`${GIT_STASH_TAG}(\\d+)${GIT_STASH_TAG}`, 'g'), (_m, i) => gitStash[Number(i)]);
+  }
+
   // Rule 4: hostnames and URLs whose registrable domain is not on the
   // allowlist. URLs keep their path suffix; bare hostnames collapse.
   // Loopback (localhost, 127.0.0.1) and everything on the allowlist
   // survive; every other public hostname or URL loses its host.
-  const allowHosts = new Set([
-    ...BUNDLED_ALLOWLIST.hosts,
-    ...(Array.isArray(context.allowHosts) ? context.allowHosts : []),
-  ].map((h) => h.toLowerCase()));
+  // allowHosts / allowExtensions declared earlier (Codex P1-1) so the
+  // rule-3 bare-remote stash can gate on the host allowlist too. Rule
+  // 4 narrowing (0.28.2, issue #233, design amendment R5d): a token
+  // whose trailing dot-label is a known file extension is NOT a
+  // hostname, killing the `Backstory-product-brief.md` and
+  // `intake.json` false positives Barry hit in the WSD round-trip.
+  // The bundled shortlist lives in redact-allowlist.json under the
+  // `extensions` field; the operator overlay merges via
+  // context.allowExtensions.
 
   // Rule 9: URL-embedded credentials (design amendment R3b, added
   // round 4 for F-P0-B). Runs BEFORE the rule-4 hostname pass so a
@@ -459,20 +548,46 @@ export function redact(input, context = {}) {
   // `url-credential`; false positives are visible in the disclosure.
   text = redactUrlCredentials(text, ledger);
 
-  // URLs first (http/https), then bare hostnames.
-  const urlRe = /https?:\/\/([A-Za-z0-9.-]+)((?::[0-9]+)?(?:\/[^\s)]*)?)/g;
-  text = replaceRegex(text, urlRe, (_m, host, tail) => {
-    if (isHostAllowed(host, allowHosts)) return `https://${host}${tail}`;
-    return `<host>${tail}`;
+  // URLs first (http/https/git+ssh/ssh/git), then bare hostnames.
+  // 0.28.3 (R5f, issue #243): the URL rule accepts git+ssh/ssh/git
+  // schemes with an optional userinfo prefix so the host inside a git
+  // clone URL can be folded by the same code path that folds an https
+  // URL host. The rule-3 guard above has already protected the `git@`
+  // sentinel from the email rule; here the sentinel is preserved and
+  // only the host portion is folded.
+  const urlRe = /(https?|git\+ssh|ssh|git):\/\/((?:[A-Za-z0-9._%+-]+@)?)([A-Za-z0-9.-]+)((?::[0-9]+)?(?:\/[^\s)]*)?)/g;
+  text = replaceRegex(text, urlRe, (_m, scheme, userinfo, host, tail) => {
+    if (isHostAllowed(host, allowHosts)) return `${scheme}://${userinfo}${host}${tail}`;
+    return `${scheme}://${userinfo}<host>${tail}`;
   }, 'hostname', ledger);
   // Bare hostnames: a word that looks like a domain (has a dot,
   // ends with a 2+ letter TLD) and is not on the allowlist. Skip if
   // preceded by @ (already handled by rule 3), a slash or backslash
   // (path fragment; the winAbsRe substitution leaves `<path>\file.ext`
   // which must not fold to `<host>`), a digit-dot (IP handled by
-  // rule 5b), or another word character (a longer host suffix).
-  const bareHostRe = /(?<![@/\\\w.])(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}(?![\w.-])/g;
+  // rule 5b), a hyphen or another word character (a longer host
+  // suffix or a filename-internal segment). Adding `-` to the
+  // lookbehind is the 0.28.2 (issue #233) fix that stops
+  // `Backstory-product-brief.md` folding on its internal
+  // `product-brief.md` slice; the extension-refusal step below is the
+  // second layer. Design amendment R5e (0.28.3, issue #247): the
+  // `{2,}` trailing class also functions as the single-letter-TLD
+  // exclusion - a token like `a.b.c` has a one-letter tail and is
+  // treated as a filename fragment, not a hostname.
+  const bareHostRe = /(?<![@/\\\w.\-])(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}(?![\w.-])/g;
   text = replaceRegex(text, bareHostRe, (host) => {
+    // 0.28.2 (issue #233, design amendment R5d): a candidate whose
+    // trailing dot-label is a known file extension is not a hostname;
+    // leave it intact and record no ledger row (we are not redacting,
+    // we are correctly leaving alone). This narrowing catches shapes
+    // like `report.log`, `intake.json` and `Backstory-example.md`
+    // that pass the lookbehind guard because they start after a
+    // whitespace or line boundary.
+    const lastDot = host.lastIndexOf('.');
+    if (lastDot > 0) {
+      const trailingLabel = host.slice(lastDot + 1).toLowerCase();
+      if (allowExtensions.has(trailingLabel)) return host;
+    }
     if (isHostAllowed(host, allowHosts)) return host;
     return '<host>';
   }, 'hostname', ledger);

package/src/feedback/render.js

@@ -110,27 +110,39 @@ function truncateToBytes(text, maxBytes) {
 }
 
 /**
- * Render the `+1 from another reporter` comment body used on the
- * dedupe path (slice 4). Kept in this module because triage sees one
- * shape from `create` and `comment`.
+ * Render the fold comment body used on the dedupe path (slice 4).
+ * 0.28.2 (issue #234, Barry ruling 2026-09-21): the retired
+ * "+1 from another reporter." payload is gone; the comment always
+ * carries the full report so a human can judge whether the fold is
+ * correct. The header line names the fold decision. The visible
+ * fingerprint line at the bottom stays so a later submit can still
+ * match on it.
  *
  * @param {object} entry
- * @param {{ body: string, ledger: Array<{ rule: string, count: number }> }} redacted
- * @param {{ fingerprint: string, includeBody?: boolean }} meta
+ * @param {{ title: string, body: string, evidence: Array<{ kind: string, value: string }>, ledger: Array<{ rule: string, count: number }> }} redacted
+ * @param {{ fingerprint: string, matchedTitle?: string }} meta
  * @returns {RenderedComment}
  */
 export function renderComment(entry, redacted, meta) {
   const lines = [];
-  lines.push('+1 from another reporter.');
+  lines.push('Apparent duplicate of the issue subject; posting the full report so a human can judge.');
+  lines.push('');
+  lines.push(`## Report: ${renderTitle(entry, redacted.title)}`);
+  lines.push('');
+  lines.push(redacted.body);
   lines.push('');
-  lines.push(...renderEnvironmentTable(entry).split('\n'));
-  if (meta.includeBody) {
-    lines.push('');
-    lines.push('Report body:');
-    lines.push('');
-    lines.push(redacted.body);
+  lines.push('---');
+  lines.push('**Evidence**');
+  if (Array.isArray(redacted.evidence) && redacted.evidence.length > 0) {
+    for (const ev of redacted.evidence) {
+      lines.push(`- \`${ev.value}\` (${ev.kind})`);
+    }
+  } else {
+    lines.push('- (none)');
   }
   lines.push('');
+  lines.push(renderEnvironmentTable(entry));
+  lines.push('');
   lines.push(`rcf-feedback-fingerprint: ${meta.fingerprint}`);
   return { body: `${lines.join('\n')}\n` };
 }
@@ -241,10 +253,20 @@ function renderEnvironmentTable(entry) {
       t.libraryPrefix ? `(library ${t.libraryPrefix}${t.libraryRef ? ` ${t.libraryRef}` : ''}${t.resolvedSha ? `, git ${String(t.resolvedSha).slice(0, 7)}` : t.tarballSha256 ? `, tarball ${String(t.tarballSha256).slice(0, 7)}` : ''})` : null,
     ].filter(Boolean).join(' ')
     : 'n/a';
+  // 0.28.2 (issue #234): a "target" row goes on the environment
+  // table for core entries too, so submit's fingerprint-verification
+  // step can compare the entry's verb path against a candidate's
+  // recorded target and refuse to fold across differing targets. For
+  // blueprint entries the blueprint cell already carries the target
+  // identity, so the target row is left as "-" to avoid duplication.
+  const targetCell = kind === 'blueprint'
+    ? '-'
+    : (typeof t.ref === 'string' && t.ref.length > 0 ? t.ref : '-');
   const rows = [
     ['field', 'value'],
     ['kind', kind],
     ['blueprint', blueprintCell],
+    ['target', targetCell],
     ['anchor', entry?.anchor ?? '-'],
     ['symptom class', entry?.symptomClass ?? '-'],
     ['severity', entry?.severity ?? '-'],

package/src/intake/manifest-writer.js

@@ -9,7 +9,7 @@ import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
 import { rcfError } from '#core/errors';
-import { validateDocument } from '#core/store';
+import { buildNextManifest, validateDocument } from '#core/store';
 
 const ID_RE = /^ic-\d{4}-\d{2}-\d{2}-(\d{3})$/;
 
@@ -73,8 +73,11 @@ export function composeIntakeRecord({ manifest, fidelity, artefacts, validationF
  * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
  */
 export async function writeIntakeRecord({ projectRoot, tree, record }) {
-  const manifest = tree?.manifest ?? {};
-  const nextManifest = { ...manifest, intakeClassification: record };
+  // 0.28.2 (Codex review follow-up on #230): the writer synthesises
+  // the next manifest via the same `buildNextManifest` helper the
+  // dry-run branch uses, so preview and write share one composition
+  // path. `validateDocument` then runs on the identical shape.
+  const nextManifest = buildNextManifest({ manifest: tree?.manifest ?? {}, record, verb: 'intake' });
   const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: 'rcf/manifest.json' });
   if (validation) return validation;
   const abs = join(projectRoot, 'rcf', 'manifest.json');

package/src/intake/orchestrator.js

@@ -82,23 +82,60 @@ export async function runIntakePhases({ projectRoot, artefactPaths, kindHint = n
 
   // Fold non-interactive input: extra findings, operator responses,
   // and elicitationScope hints all land here.
+  //
+  // 0.28.2 (issue #229): findings are material-scoped, not
+  // artefact-scoped. Two artefacts that both trip the same branch
+  // ("web UI but no sign-in surface named") emit the same finding
+  // twice with byte-identical detail text, and downstream that
+  // inflated `findings=2` on a record with one finding. Dedupe by
+  // `${kind}::${detail}` (first-wins) before timestamping so the
+  // material carries one finding, not N.
+  //
+  // Same commit fixes the second half of #229: operator-supplied
+  // `validationFindings` on --input were dropped unless the kind was
+  // `otherDeclared`. Fold every input finding into the same map so
+  // an operator-authored `impliedButNotStated`, `contradiction` or
+  // `missingLoadBearingConstraint` survives the round-trip and
+  // coalesces with a scanned duplicate (the operator's response is
+  // preserved when it does).
   const inputFindings = Array.isArray(input?.validationFindings) ? input.validationFindings : [];
+
+  /** @type {Map<string, object>} */
+  const foldedFindings = new Map();
+  const foldKey = (f) => `${String(f.kind ?? '')}::${String(f.detail ?? '')}`;
+  for (const f of allFindings) {
+    const k = foldKey(f);
+    if (!foldedFindings.has(k)) foldedFindings.set(k, f);
+  }
+  for (const f of inputFindings) {
+    if (typeof f?.kind !== 'string' || typeof f?.detail !== 'string') continue;
+    const k = foldKey(f);
+    if (!foldedFindings.has(k)) foldedFindings.set(k, f);
+  }
+
+  // 0.28.2 (Codex review follow-up on #229): the response lookup is
+  // keyed by (kind, detail) too, so resolving one finding never
+  // silently marks a different-kind finding with the same detail as
+  // resolved. Previously the lookup was `detail` only and an
+  // answered `impliedButNotStated` leaked its response onto an
+  // unanswered `contradiction` with the same detail string.
   const inputResponses = new Map();
   for (const f of inputFindings) {
-    if (typeof f?.detail === 'string' && typeof f?.operatorResponse === 'string') {
-      inputResponses.set(f.detail, f.operatorResponse);
+    if (typeof f?.kind === 'string'
+      && typeof f?.detail === 'string'
+      && typeof f?.operatorResponse === 'string') {
+      inputResponses.set(foldKey(f), f.operatorResponse);
     }
-    if (f?.kind === 'otherDeclared') allFindings.push(f);
   }
 
   const isoNow = now.toISOString();
-  const findingsWithTimestamps = allFindings.map((f) => {
-    const entry = { kind: f.kind, detail: f.detail, raisedAt: isoNow };
+  const findingsWithTimestamps = Array.from(foldedFindings.values()).map((f) => {
+    const entry = { kind: f.kind, detail: f.detail, raisedAt: f.raisedAt ?? isoNow };
     if (f.kindDescription) entry.kindDescription = f.kindDescription;
-    const response = inputResponses.get(f.detail) ?? input?.operatorResponse;
+    const response = f.operatorResponse ?? inputResponses.get(foldKey(f)) ?? input?.operatorResponse;
     if (typeof response === 'string' && response.length > 0) {
       entry.operatorResponse = response;
-      entry.resolvedAt = isoNow;
+      entry.resolvedAt = f.resolvedAt ?? isoNow;
     }
     return entry;
   });

package/src/preflight/manifest-writer.js

@@ -19,7 +19,7 @@ import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
 import { rcfError } from '#core/errors';
-import { validateDocument } from '#core/store';
+import { buildNextManifest, validateDocument } from '#core/store';
 
 /**
  * @typedef {object} PreflightServiceRuling
@@ -210,16 +210,16 @@ export function composeOptOutRecord({
 export async function writePreflightRecord({
   projectRoot, tree, record, optOuts = [], options = {},
 }) {
-  const manifest = tree.manifest ?? {};
-  const nextManifest = { ...manifest };
-
-  const existingPfc = Array.isArray(nextManifest.preFlightConfig) ? nextManifest.preFlightConfig : [];
-  nextManifest.preFlightConfig = [...existingPfc, record];
-
-  if (optOuts.length > 0) {
-    const existingOptOuts = Array.isArray(nextManifest.baselineAcOptOuts) ? nextManifest.baselineAcOptOuts : [];
-    nextManifest.baselineAcOptOuts = [...existingOptOuts, ...optOuts];
-  }
+  // 0.28.2 (Codex review follow-up on #232): compose the next
+  // manifest via the shared `buildNextManifest` helper so the write
+  // and dry-run branches produce byte-identical shapes; validation
+  // then runs on the same result.
+  const nextManifest = buildNextManifest({
+    manifest: tree.manifest ?? {},
+    record,
+    verb: 'preflight',
+    extraRecords: optOuts,
+  });
 
   const relPath = 'rcf/manifest.json';
   const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });

package/src/query/delta.js

@@ -0,0 +1,276 @@
+// 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).
+ */
+
+/**
+ * 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,
+    };
+  }
+
+  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,
+  };
+}