rcf-lite 0.28.1 → 0.28.4

package/src/query/index.js

@@ -4,6 +4,42 @@
 export { computeCoverage, classifyCoverageScope } from './coverage.js';
 export { computeTrace, kindOf } from './trace.js';
 export { computeImpact, labelFor } from './impact.js';
+// Detection model (REQ-172, proposal 2026-09-22 §2.2 v3). Pure hashes
+// over the parsed tree; every downstream DEFINE gate reads this delta.
+export {
+  canonicaliseJson,
+  hashDocument,
+  computeTreeHash,
+  computeDelta,
+} from './delta.js';
+// DEFINE stage gates (REQ-174; proposal §2.4, §3.2 v3). One check
+// function per stage; foldState + parseAcClass helpers.
+export {
+  STAGE_ORDER,
+  STAGE_GATES,
+  STAGE_SHORT_NAMES,
+  STAGE_ALIASES,
+  INTERFACE_KINDS,
+  stagePolicy,
+  parseAcClass,
+  foldState,
+  runStage,
+  checkD1Brief,
+  checkD2Skeleton,
+  checkD3Shapes,
+  checkD4Stories,
+  checkD5Crosscut,
+  checkD6Consistency,
+  checkD7Decisions,
+  checkD8Freeze,
+} from './gates.js';
+// Readiness composer (REQ-175; proposal §2.4, §6 v3).
+export {
+  computeReadiness,
+  deriveNextAction,
+  shortHash,
+  formatTreeLine,
+} from './readiness.js';
 export { formatTable } from './formatters/table.js';
 export { formatJson } from './formatters/json.js';
 export { formatMermaid } from './formatters/mermaid.js';

package/src/query/readiness.js

@@ -0,0 +1,333 @@
+// Readiness compute (REQ-175; proposal 2026-09-22 §2.4, §6 v3).
+//
+// One pure composer over the DEFINE detection primitives:
+//   1. `computeDelta` (slice 1) -> changed / added / removed / briefSince
+//   2. `computeImpact` per id in changed union added -> fan-out
+//   3. Eight gate check functions from `./gates.js` -> stage[]
+//   4. `computeCoverage` tree-wide plus per REQ ancestor of the delta
+//   5. Open decisions from the decisions ledger
+//   6. Fold to `freezeable` (every stage passed / acknowledged /
+//      notApplicable) and `nextAction` (first failing stage + check)
+//
+// Return shape mirrors proposal §2.4 exactly. The CLI (rcf define
+// readiness) and the viewer's Readiness tab (slice 5) render the same
+// object; the freeze verb (slice 3) refuses on any failing stage.
+
+import { computeQueue } from '../build/queue.js';
+import { computeCoverage } from './coverage.js';
+import { computeDelta } from './delta.js';
+import { computeImpact } from './impact.js';
+import {
+  STAGE_GATES,
+  STAGE_ORDER,
+  STAGE_SHORT_NAMES,
+  checkD1Brief,
+  checkD2Skeleton,
+  checkD3Shapes,
+  checkD4Stories,
+  checkD5Crosscut,
+  checkD6Consistency,
+  checkD7Decisions,
+  checkD8Freeze,
+} from './gates.js';
+
+/**
+ * @typedef {object} ReadinessTree
+ * @property {boolean} frozen
+ * @property {string | null} frozenAt
+ * @property {string | null} treeHash
+ * @property {string} currentTreeHash
+ * @property {string | null} buildAt   fbsId at the queue head, or null
+ * @property {number} fbsTotal
+ */
+
+/**
+ * @typedef {object} ReadinessDelta
+ * @property {string[]} changed
+ * @property {string[]} added
+ * @property {string[]} removed
+ * @property {number[]} briefSince
+ * @property {import('./impact.js').ImpactNode[]} impacted
+ * @property {string[]} impactedFbs
+ */
+
+/**
+ * @typedef {object} StageResult
+ * @property {string} stage
+ * @property {string} gate
+ * @property {'passed'|'failing'|'acknowledged'|'notApplicable'} state
+ * @property {Array<{ name: string, ok: boolean, over: 'delta'|'tree', pass: number, total: number, failing: Array<{ id: string, why: string }> }>} checks
+ * @property {string} [reason]
+ */
+
+/**
+ * @typedef {object} NextAction
+ * @property {string} stage
+ * @property {string} check
+ * @property {string[]} ids
+ * @property {string} command
+ */
+
+/**
+ * @typedef {object} ReadinessResult
+ * @property {ReadinessTree} tree
+ * @property {ReadinessDelta} delta
+ * @property {StageResult[]} stages
+ * @property {NextAction | null} nextAction
+ * @property {{ tree: import('./coverage.js').CoverageResult, delta: import('./coverage.js').CoverageResult[] }} coverage
+ * @property {Array<Record<string, unknown>>} decisions
+ * @property {boolean} freezeable
+ */
+
+/**
+ * Compute the readiness object.
+ *
+ * Pure over its inputs. Callers supply the ledgers bundle, freeze
+ * record, testPointers map (resolveTestPointers output) and optional
+ * profile switches; nothing else touches the filesystem.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {object} args
+ * @param {import('./delta.js').FreezeRecord | null | undefined} [args.freeze]
+ * @param {import('./delta.js').LedgerBundle | undefined} [args.ledgers]
+ * @param {{ skipReviewFor?: string } | undefined} [args.profile]
+ * @param {string | null | undefined} [args.profileText]  rcf/.identity/profile.md contents
+ * @param {Map<string, unknown> | undefined} [args.testPointers]
+ * @param {Array<unknown> | undefined} [args.validateErrors]  tree-wide validate + walker errors
+ * @returns {ReadinessResult}
+ */
+export function computeReadiness(tree, args = {}) {
+  const {
+    freeze = null,
+    ledgers = {},
+    profile = undefined,
+    profileText = null,
+    testPointers = undefined,
+    validateErrors = [],
+  } = args;
+
+  // 1. Delta.
+  const delta = computeDelta(tree, freeze, ledgers);
+
+  // 2. Fan-out via computeImpact per id in changed union added.
+  // Standalone-document ids only; ledger:<name> entries have no fan-out.
+  const pivotIds = [
+    ...delta.changed.filter((id) => !id.startsWith('ledger:')),
+    ...delta.added.filter((id) => !id.startsWith('ledger:')),
+  ];
+  const pivotSet = new Set(pivotIds);
+  /** @type {import('./impact.js').ImpactNode[]} */
+  const impactedNodes = [];
+  const impactedSeen = new Set();
+  const impactedFbsSeen = new Set();
+  // Skip fan-out when the tree is unfrozen: the delta IS the whole tree
+  // (proposal §2.2 "before the first freeze the delta is the whole
+  // tree"), so a per-id fan-out is quadratic for no signal.
+  const runFanOut = delta.frozen === true;
+  if (runFanOut) {
+    for (const id of pivotIds) {
+      const impact = computeImpact(tree, { id });
+      if (!impact.found || !Array.isArray(impact.nodes)) continue;
+      for (const node of impact.nodes) {
+        if (node.role === 'pivot') continue;
+        if (pivotSet.has(node.id)) continue;
+        if (!impactedSeen.has(node.id)) {
+          impactedSeen.add(node.id);
+          impactedNodes.push(node);
+        }
+        if (node.kind === 'fbs' && node.actionNeeded === 're-execute') {
+          impactedFbsSeen.add(node.id);
+        }
+      }
+    }
+  }
+  const impactedFbs = [...impactedFbsSeen].sort();
+
+  // 3. Compose scope = changed union added union impacted (dedup, sort).
+  const scopeSet = new Set([
+    ...delta.changed.filter((id) => !id.startsWith('ledger:')),
+    ...delta.added.filter((id) => !id.startsWith('ledger:')),
+    ...impactedSeen,
+  ]);
+
+  // 4. Coverage: tree-wide plus per REQ ancestor of the delta.
+  const coverageTree = computeCoverage(tree, { testPointers, strict: true });
+  const deltaReqIds = collectDeltaReqAncestors(tree, pivotIds);
+  const coverageDelta = [];
+  for (const reqId of deltaReqIds) {
+    coverageDelta.push(computeCoverage(tree, { testPointers, strict: true, scopeId: reqId }));
+  }
+
+  // 5. Run the eight gate check functions in order. D8 reads the
+  // prior stage states, so compose sequentially.
+  /** @type {StageResult[]} */
+  const stages = [];
+  const currentTreeHash = delta.currentTreeHash;
+  /** @type {import('./gates.js').StageContext} */
+  const ctx = {
+    tree,
+    ledgers,
+    delta,
+    freeze,
+    scope: scopeSet,
+    validateErrors,
+    // Prefer the caller-supplied probe count when it is passed; falls
+    // back to the ledger scan inside checkD6Consistency.
+    probeOpenCount: undefined,
+    coverageTree,
+    profileText,
+    profile,
+    currentTreeHash,
+    priorStages: undefined,
+  };
+  stages.push(checkD1Brief(ctx));
+  stages.push(checkD2Skeleton(ctx));
+  stages.push(checkD3Shapes(ctx));
+  stages.push(checkD4Stories(ctx));
+  stages.push(checkD5Crosscut(ctx));
+  stages.push(checkD6Consistency(ctx));
+  stages.push(checkD7Decisions(ctx));
+  stages.push(checkD8Freeze({ ...ctx, priorStages: stages.map((s) => ({ stage: s.stage, state: s.state })) }));
+
+  // 6. Open decisions in the #241 format for the surface consumer.
+  const decisions = /** @type {any} */ (ledgers?.decisions);
+  const decisionEntries = Array.isArray(decisions?.decisions) ? decisions.decisions : [];
+  const openDecisions = decisionEntries.filter((d) => d?.status === 'open');
+
+  // 7. Fold freezeable + nextAction.
+  const freezeable = stages.every((s) => s.state === 'passed' || s.state === 'acknowledged' || s.state === 'notApplicable');
+  const nextAction = freezeable ? null : deriveNextAction(stages);
+
+  // 8. Build the tree summary line inputs.
+  const queue = computeQueue(tree);
+  const fbsTotal = (tree.fbsItems ?? []).length;
+
+  /** @type {ReadinessResult} */
+  return {
+    tree: {
+      frozen: delta.frozen,
+      frozenAt: delta.frozenAt,
+      treeHash: delta.treeHash,
+      currentTreeHash: delta.currentTreeHash,
+      buildAt: queue.nextActionable ?? null,
+      fbsTotal,
+    },
+    delta: {
+      changed: delta.changed,
+      added: delta.added,
+      removed: delta.removed,
+      briefSince: delta.briefSince,
+      impacted: impactedNodes,
+      impactedFbs,
+    },
+    stages,
+    nextAction,
+    coverage: { tree: coverageTree, delta: coverageDelta },
+    decisions: openDecisions,
+    freezeable,
+  };
+}
+
+/**
+ * Walk back from every delta pivot to its REQ ancestor and collect
+ * the unique REQ ids. The walker records parent-child edges under
+ * `parentByChild`; the walk terminates at the first REQ hit.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {string[]} pivotIds
+ * @returns {string[]}
+ */
+function collectDeltaReqAncestors(tree, pivotIds) {
+  const seen = new Set();
+  for (const id of pivotIds) {
+    let cursor = id;
+    let hops = 0;
+    while (cursor && hops < 32) {
+      hops += 1;
+      const kind = tree.kindById?.get(cursor);
+      if (kind === 'req') {
+        seen.add(cursor);
+        break;
+      }
+      // Some kinds carry an explicit reqId; use that when the parent
+      // chain skips the REQ (e.g. a TC leaf whose parent is a TS).
+      const doc = tree.byId?.get(cursor);
+      if (doc && typeof doc === 'object' && typeof /** @type {any} */ (doc).reqId === 'string') {
+        seen.add(/** @type {any} */ (doc).reqId);
+        break;
+      }
+      const parent = tree.parentByChild?.get(cursor);
+      if (!parent) break;
+      cursor = parent;
+    }
+  }
+  return [...seen].sort();
+}
+
+/**
+ * Pick the first failing stage in D1..D8 order and the first failing
+ * check inside it, then compose a `NextAction`.
+ *
+ * @param {StageResult[]} stages
+ * @returns {NextAction | null}
+ */
+export function deriveNextAction(stages) {
+  const byStage = new Map(stages.map((s) => [s.stage, s]));
+  for (const stageId of STAGE_ORDER) {
+    const s = byStage.get(stageId);
+    if (!s || s.state !== 'failing') continue;
+    // First failing check; tie-break by the largest failing list so
+    // the operator sees the most impactful gap first.
+    const failing = s.checks.filter((c) => !c.ok);
+    if (failing.length === 0) continue;
+    const check = failing.reduce((a, b) => (b.failing.length > a.failing.length ? b : a), failing[0]);
+    const ids = [...new Set(check.failing.map((f) => f.id))].slice(0, 20);
+    const shortName = STAGE_SHORT_NAMES[stageId] ?? stageId;
+    return {
+      stage: stageId,
+      check: check.name,
+      ids,
+      command: `rcf define readiness --check ${shortName}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Short 8-character prefix of a `sha256:<hex>` string, or '(none)' when
+ * absent. Kept exported so text formatters share one convention.
+ *
+ * @param {string | null | undefined} hash
+ * @returns {string}
+ */
+export function shortHash(hash) {
+  if (typeof hash !== 'string' || !hash.startsWith('sha256:')) return '(none)';
+  return hash.slice('sha256:'.length, 'sha256:'.length + 8);
+}
+
+/**
+ * One-line tree summary matching proposal §6.2:
+ *   "Frozen at 9f3a2c on 2026-09-20. 4 documents changed since, 11
+ *    impacted. Build at FBS-031 of 41; 2 FBS impacted."
+ *   "Unfrozen. 30 documents; the whole tree is the delta."
+ *
+ * @param {ReadinessResult} result
+ * @returns {string}
+ */
+export function formatTreeLine(result) {
+  const t = result.tree;
+  const d = result.delta;
+  if (!t.frozen) {
+    const total = d.added.length + d.changed.length;
+    return `Unfrozen. ${total} document${total === 1 ? '' : 's'}; the whole tree is the delta.`;
+  }
+  const changedCount = d.changed.length + d.added.length + d.removed.length;
+  const impactedCount = d.impacted.length;
+  const buildAt = t.buildAt ?? '(none)';
+  const impactedFbs = d.impactedFbs.length;
+  const at = t.frozenAt ? t.frozenAt.split('T')[0] : '(no timestamp)';
+  return `Frozen at ${shortHash(t.treeHash)} on ${at}. ${changedCount} document${changedCount === 1 ? '' : 's'} changed since, ${impactedCount} impacted. Build at ${buildAt} of ${t.fbsTotal}; ${impactedFbs} FBS impacted.`;
+}
+
+// Re-export for CLI convenience.
+export { STAGE_GATES, STAGE_ORDER, STAGE_SHORT_NAMES };

package/src/req-baseline/sweep.js

@@ -87,10 +87,20 @@ export async function applySweepDecisions({ projectRoot, tree, decisions, now =
     const usDoc = tree.byId.get(usId);
     if (!usDoc) continue;
 
+    // 0.28.2 (issue #231): a per-US allocator seeded ONCE from the
+    // current maxN on `usDoc.acceptanceCriteria`, then handed to each
+    // `composeBaselineAc` for the run. `nextAcId` was stateless
+    // across iterations, so every candidate accepted for one US
+    // received the identical `AC-<usNum>-<maxN+1>` and the writer's
+    // post-write validation refused the tree with a duplicate-id
+    // breakage. Ordinal allocation is monotone within a batch and
+    // across batches (a later sweep on the same US resumes from the
+    // new maxN in the tree).
+    const allocator = makeAcIdAllocator(usDoc);
     const acsToAppend = [];
     for (const d of list) {
       if (d.action === 'accept') {
-        const ac = composeBaselineAc({ usDoc, candidate: d.candidate, now });
+        const ac = composeBaselineAc({ usDoc, candidate: d.candidate, now, idOverride: allocator() });
         acsToAppend.push(ac);
         writtenAcIds.push(ac.id);
         accepted += 1;
@@ -172,9 +182,9 @@ export async function applyPendingBaselinesForUs({ tree, usId }) {
  * @param {Date} args.now
  * @returns {object}
  */
-export function composeBaselineAc({ usDoc, candidate, now }) {
+export function composeBaselineAc({ usDoc, candidate, now, idOverride = null }) {
   const isoNow = now.toISOString();
-  const id = nextAcId(usDoc);
+  const id = typeof idOverride === 'string' && idOverride.length > 0 ? idOverride : nextAcId(usDoc);
   const canonicalText = candidate.canonicalText;
   const gwt = candidate.given || candidate.when || candidate.then
     ? { given: candidate.given ?? '', when: candidate.when ?? '', then: candidate.then ?? '' }
@@ -200,8 +210,22 @@ export function composeBaselineAc({ usDoc, candidate, now }) {
 const AC_HIER_ID_RE = /^AC-(\d{3,})-(\d+)$/;
 
 function nextAcId(usDoc) {
+  const alloc = makeAcIdAllocator(usDoc);
+  return alloc();
+}
+
+/**
+ * 0.28.2 (issue #231): return a monotone AC-id allocator seeded once
+ * from `usDoc.acceptanceCriteria`. Every subsequent call returns
+ * `AC-<usNum>-<n++>`; a caller that accepts N baseline candidates for
+ * one US in one sweep now gets N distinct ids, and the writer's
+ * duplicate-id refusal on `updateDocument` no longer bites.
+ *
+ * @param {object} usDoc
+ * @returns {() => string}
+ */
+export function makeAcIdAllocator(usDoc) {
   const acs = Array.isArray(usDoc.acceptanceCriteria) ? usDoc.acceptanceCriteria : [];
-  // Prefer hierarchical form matching the US id, e.g. US-201 → AC-201-1.
   const usNum = (usDoc.usId ?? '').match(/^US-(\d+)$/)?.[1];
   let maxN = 0;
   for (const ac of acs) {
@@ -212,7 +236,12 @@ function nextAcId(usDoc) {
     const n = Number.parseInt(tail, 10);
     if (Number.isFinite(n) && n > maxN) maxN = n;
   }
-  return usNum ? `AC-${usNum}-${maxN + 1}` : `AC-${(Math.floor(Math.random() * 999)).toString().padStart(3, '0')}-1`;
+  let counter = maxN;
+  return () => {
+    counter += 1;
+    if (!usNum) return `AC-${(Math.floor(Math.random() * 999)).toString().padStart(3, '0')}-${counter}`;
+    return `AC-${usNum}-${counter}`;
+  };
 }
 
 function extractGwt(text) {

package/src/server/index.js

@@ -11,6 +11,7 @@
 // on top; the server itself does not `process.exit`.
 
 import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { LIVE_CLIENT_PATH, STYLE_CSS_PATH, VENDORED_MERMAID_PATH, renderModelToPage } from '../view/index.js';
@@ -42,6 +43,25 @@ import { createSseHub } from './sse.js';
  *   rewalk: () => Promise<void>,
  * }>}
  */
+
+/**
+ * Issue #248 (0.28.3): read a shipped static asset once and return
+ * `{ buffer, size, contentType }`. Any read failure surfaces here so
+ * `startServer` can fail fast with an ioFailure before it binds.
+ *
+ * @param {string} path
+ * @param {string} contentType
+ */
+async function loadStaticAsset(path, contentType) {
+  // Codex P2-1: derive size from the actual captured buffer, not from
+  // a parallel stat that could snapshot a different revision if the
+  // file is being replaced concurrently. A wrong content-length header
+  // would cause truncation or mis-alignment for the entire server
+  // lifetime because we cache both values together.
+  const buffer = await readFile(path);
+  return { buffer, size: buffer.length, contentType };
+}
+
 export async function startServer(args) {
   const projectRoot = args.projectRoot;
   const port = typeof args.port === 'number' ? args.port : 4373;
@@ -76,6 +96,7 @@ export async function startServer(args) {
           fullPageHtml: result.fullPageHtml,
           contentHtml: result.contentHtml,
           errors: result.errors,
+          pmPartials: result.pmPartials,
         };
         sse.broadcast('tree-update', { version, contentHtml: result.contentHtml });
         if (result.errors && result.errors.length > 0) {
@@ -97,10 +118,26 @@ export async function startServer(args) {
   // and the first SSE connect gets a real payload.
   await rewalk();
 
+  // Issue #248 (0.28.3): snapshot the shipped static assets at startup
+  // so a checkout branch switch during the server's lifetime cannot
+  // change what gets served. The tree walker is the only path that
+  // re-reads disk on rcf/ change; every other asset is fixed at boot.
+  const [styleAsset, mermaidAsset, liveClientAsset] = await Promise.all([
+    loadStaticAsset(STYLE_CSS_PATH, 'text/css; charset=utf-8'),
+    loadStaticAsset(VENDORED_MERMAID_PATH, 'application/javascript; charset=utf-8'),
+    loadStaticAsset(LIVE_CLIENT_PATH, 'application/javascript; charset=utf-8'),
+  ]);
+
   const scopeHandler = createScopeHandler({ projectRoot });
   const router = createRouter({
     currentState: () => state,
     sse,
+    // Snapshotted assets take precedence; the legacy path props are
+    // still passed so tests that mount the router directly with a
+    // path (no asset load) keep working.
+    styleAsset,
+    mermaidAsset,
+    liveClientAsset,
     stylePath: STYLE_CSS_PATH,
     mermaidPath: VENDORED_MERMAID_PATH,
     liveClientPath: LIVE_CLIENT_PATH,

package/src/server/routes.js

@@ -12,6 +12,22 @@
 
 import { readFile, stat } from 'node:fs/promises';
 
+// Issue #248 (0.28.3): the shipped static assets (style.css,
+// mermaid.min.js, live-client.js) MUST be resolved once at server
+// startup, not read from disk on every HTTP request. If the checkout
+// switches branches or the file mutates while the server runs, per-
+// request reads return the new bytes even though the HTML that
+// references them was rendered from a walk taken at startup. The
+// asymmetry produced the 2026-09-22 Product Map "unstyled preview"
+// regression: HTML from the store walker was old, style.css was
+// current, and the browser combined them.
+//
+// `deps.styleAsset`, `deps.mermaidAsset` and `deps.liveClientAsset`
+// carry `{ buffer, size, contentType }` snapshotted at startup. The
+// legacy `stylePath`/`mermaidPath`/`liveClientPath` props are kept
+// for backwards compatibility with tests that pass a path; the
+// router reads on-demand in that fallback path.
+
 const MIME = {
   html: 'text/html; charset=utf-8',
   css: 'text/css; charset=utf-8',
@@ -68,15 +84,33 @@ export function createRouter(deps) {
       return;
     }
     if (path === '/style.css') {
-      serveFile(res, deps.stylePath, MIME.css).catch((err) => fail(res, err));
+      serveAsset(res, deps.styleAsset, deps.stylePath, MIME.css).catch((err) => fail(res, err));
       return;
     }
     if (path === '/mermaid.min.js') {
-      serveFile(res, deps.mermaidPath, MIME.js).catch((err) => fail(res, err));
+      serveAsset(res, deps.mermaidAsset, deps.mermaidPath, MIME.js).catch((err) => fail(res, err));
       return;
     }
     if (path === '/live-client.js') {
-      serveFile(res, deps.liveClientPath, MIME.js).catch((err) => fail(res, err));
+      serveAsset(res, deps.liveClientAsset, deps.liveClientPath, MIME.js).catch((err) => fail(res, err));
+      return;
+    }
+    if (path.startsWith('/product-map/')) {
+      const state = deps.currentState();
+      if (!state || !state.pmPartials) {
+        res.writeHead(503, { 'content-type': MIME.txt });
+        res.end('view server initialising\n');
+        return;
+      }
+      const group = path.slice('/product-map/'.length);
+      const html = state.pmPartials[group];
+      if (typeof html !== 'string') {
+        res.writeHead(404, { 'content-type': MIME.txt });
+        res.end('unknown grouping\n');
+        return;
+      }
+      res.writeHead(200, { 'content-type': MIME.html, 'cache-control': 'no-store' });
+      res.end(html);
       return;
     }
     if (path === '/scope.json') {
@@ -94,6 +128,34 @@ export function createRouter(deps) {
   };
 }
 
+/**
+ * Issue #248 (0.28.3): serve a snapshotted asset when the server has
+ * one, otherwise fall through to the legacy per-request read. The
+ * happy path never touches the filesystem after startup, so a checkout
+ * switch during the server's lifetime cannot change what gets served.
+ *
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ buffer: Buffer, size: number, contentType?: string } | undefined | null} asset
+ * @param {string | undefined} fallbackPath
+ * @param {string} contentType
+ */
+async function serveAsset(res, asset, fallbackPath, contentType) {
+  if (asset && asset.buffer) {
+    res.writeHead(200, {
+      'content-type': asset.contentType ?? contentType,
+      'content-length': String(asset.size),
+    });
+    res.end(asset.buffer);
+    return;
+  }
+  if (fallbackPath) {
+    await serveFile(res, fallbackPath, contentType);
+    return;
+  }
+  res.writeHead(404, { 'content-type': MIME.txt });
+  res.end('not found\n');
+}
+
 async function serveFile(res, path, contentType) {
   let body;
   let size;

package/src/ui-baseline/manifest-writer.js

@@ -18,7 +18,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';
 
 import { composeDefaults, deepGet, deepSet } from './defaults.js';
 import { CATALOGUE_V1 } from '../preflight/design-shapes.js';
@@ -150,15 +150,16 @@ export function preflightSeamOverrides(manifest, catalogue = CATALOGUE_V1) {
 export async function writeUiBaselineRecord({
   projectRoot, tree, record, options = {},
 }) {
-  const manifest = tree.manifest ?? {};
-  const nextManifest = { ...manifest };
-  const priorBaseline = nextManifest.uiBaseline ?? null;
-
-  if (priorBaseline && options.reset) {
-    const history = Array.isArray(nextManifest.uiBaselineHistory) ? nextManifest.uiBaselineHistory : [];
-    nextManifest.uiBaselineHistory = [...history, priorBaseline];
-  }
-  nextManifest.uiBaseline = record;
+  // 0.28.2 (Codex review follow-up on the shared helper): compose via
+  // the shared `buildNextManifest` helper so write and dry-run
+  // produce the same shape. `options.reset` still drives the
+  // history-move branch inside the helper.
+  const nextManifest = buildNextManifest({
+    manifest: tree.manifest ?? {},
+    record,
+    verb: 'uiBaselineInit',
+    options: { reset: Boolean(options.reset) },
+  });
 
   const relPath = 'rcf/manifest.json';
   const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });