rcf-lite 0.28.4 → 0.30.0

package/src/cli/view.js

@@ -92,6 +92,13 @@ Options:
                     and CI is unset).
   --verbose         Log each watch event and each SSE broadcast to
                     stderr.
+  --test-host       Mount the wespa host fixture at /test-host.html
+                    plus its client script at /test-host.js. Off by
+                    default; the fixture is a test-suite proof that
+                    the viewer honours Dex's embedding contract (viewer
+                    UI refresh PR 9; TAC-4134, ADR-4136), not a shipped
+                    UI, so wespa's reverse-proxy allow-list is
+                    unaffected. Can also be set via RCF_VIEW_TEST_HOST=1.
   --help            Print this help and exit.
 
 Security posture:
@@ -130,6 +137,7 @@ export function parseArgs(argv) {
     help: false,
     noOpen: false,
     port: null,
+    testHost: false,
   };
   const errors = [];
   for (let i = 0; i < argv.length; i += 1) {
@@ -148,6 +156,13 @@ export function parseArgs(argv) {
       case '-h':
         opts.help = true;
         break;
+      case '--test-host':
+        // Viewer UI refresh PR 9 (TAC-4134, ADR-4136): mount the wespa
+        // host fixture at /test-host.html plus its client at
+        // /test-host.js. Off by default; the fixture is a test-suite
+        // proof, not a shipped UI.
+        opts.testHost = true;
+        break;
       case '--port': {
         const next = argv[i + 1];
         if (next === undefined || next.startsWith('--')) {
@@ -170,6 +185,19 @@ export function parseArgs(argv) {
   return { opts, errors };
 }
 
+/**
+ * Resolve the testHost gate: `--test-host` beats `RCF_VIEW_TEST_HOST=1`
+ * env beats default (false). Viewer UI refresh PR 9 (TAC-4134).
+ *
+ * @param {boolean} flagTestHost
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {boolean}
+ */
+export function resolveTestHost(flagTestHost, env) {
+  if (flagTestHost === true) return true;
+  return env.RCF_VIEW_TEST_HOST === '1';
+}
+
 /**
  * Resolve port precedence: --port beats RCF_VIEW_PORT env beats default.
  *
@@ -294,6 +322,7 @@ export async function main(argv, deps = {}) {
       projectRoot,
       port: resolvedPort,
       log: logSink,
+      testHost: resolveTestHost(opts.testHost, env),
     });
   } catch (err) {
     if (/** @type {NodeJS.ErrnoException} */ (err).code === 'EADDRINUSE') {

package/src/define/concern-catalogue.js

@@ -0,0 +1,130 @@
+// Concern catalogue (REQ-174 amendment paragraph; spec 2026-10-01
+// section 4 row "D5 catalogue", 0.30.0 PR 6).
+//
+// Eight concerns keyed by REQ shape. For every REQ in scope, D5's
+// crosscut:catalogue check enumerates the applicable (reqShape,
+// concern) pairs via this module and asserts a concern-ledger entry
+// keyed <REQ>:<concern> exists with disposition applied or waived (a
+// waived entry carries a reason).
+//
+// The catalogue is deliberately keyed on the concern name so a
+// shape-wise question like "what concerns apply to this REQ?" is a
+// filter against one map, not a scan across eight. The reverse view
+// (which shape triggers which concern) is a transpose and lives in
+// applicableConcernsFor().
+//
+// Keys share names with the baseline catalogue
+// (packages/rcf-lite/src/core/baseline-catalog) where names coincide:
+// `auth` is the only name the two share today (the baseline-AC
+// catalogue has no per-concern crosscut keys yet). The gate reader
+// composes the ledger key as `<REQ>:<concern>`, so no key translation
+// is needed between the two surfaces.
+//
+// Pure: no I/O, no state, no time. The export is frozen at module
+// load so a consumer cannot mutate the shared source.
+
+/**
+ * Canonical ordering of concern names (spec section 4 row 'D5
+ * catalogue'). Readers that iterate the catalogue use this so display
+ * order stays stable.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const CONCERN_KEYS = Object.freeze([
+  'auth',
+  'errorEnvelope',
+  'loggingAudit',
+  'retention',
+  'performance',
+  'secrets',
+  'timeAndTimezone',
+  'concurrencyIdempotency',
+]);
+
+/**
+ * The eight REQ shapes the catalogue reasons over. These are the
+ * values a REQ's shapeClassification.shapes array may carry; a REQ
+ * may carry more than one. `other` is the catch-all whose only
+ * applicable concern today is none.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const REQ_SHAPES = Object.freeze([
+  'auth',
+  'httpApi',
+  'cliCommand',
+  'persistence',
+  'batch',
+  'externalIntegration',
+  'webUi',
+  'other',
+]);
+
+/**
+ * Shape set helper. The `loggingAudit` row below reads "every shape
+ * but other"; expressing that once beats enumerating the seven
+ * concrete shapes.
+ */
+const ALL_BUT_OTHER = Object.freeze(REQ_SHAPES.filter((s) => s !== 'other'));
+
+/**
+ * Per-concern applicability map keyed by concern name (spec section 4
+ * row 'D5 catalogue', verbatim):
+ *
+ *   auth                   -> auth, httpApi
+ *   errorEnvelope          -> httpApi, cliCommand
+ *   loggingAudit           -> every REQ shape but other
+ *   retention              -> persistence
+ *   performance            -> httpApi, batch
+ *   secrets                -> auth, externalIntegration
+ *   timeAndTimezone        -> persistence, batch
+ *   concurrencyIdempotency -> httpApi, persistence
+ *
+ * @type {Readonly<Record<string, ReadonlyArray<string>>>}
+ */
+export const CONCERN_APPLICABILITY = Object.freeze({
+  auth: Object.freeze(['auth', 'httpApi']),
+  errorEnvelope: Object.freeze(['httpApi', 'cliCommand']),
+  loggingAudit: ALL_BUT_OTHER,
+  retention: Object.freeze(['persistence']),
+  performance: Object.freeze(['httpApi', 'batch']),
+  secrets: Object.freeze(['auth', 'externalIntegration']),
+  timeAndTimezone: Object.freeze(['persistence', 'batch']),
+  concurrencyIdempotency: Object.freeze(['httpApi', 'persistence']),
+});
+
+/**
+ * Which concerns apply to a REQ shape. Reads the per-concern map
+ * once and returns the names, in CONCERN_KEYS order, whose shape set
+ * contains the input. An unknown shape returns [].
+ *
+ * @param {string} reqShape
+ * @returns {string[]}
+ */
+export function applicableConcernsFor(reqShape) {
+  if (typeof reqShape !== 'string' || reqShape.length === 0) return [];
+  const out = [];
+  for (const concern of CONCERN_KEYS) {
+    const shapes = CONCERN_APPLICABILITY[concern];
+    if (shapes && shapes.includes(reqShape)) out.push(concern);
+  }
+  return out;
+}
+
+/**
+ * Union of applicable concerns across a set of REQ shapes. A REQ
+ * carries an array of shapes (shapeClassification.shapes); the
+ * applicable concerns for that REQ are the union of applicableConcerns
+ * for each shape, in CONCERN_KEYS order with no duplicates.
+ *
+ * @param {Iterable<string>} shapes
+ * @returns {string[]}
+ */
+export function applicableConcernsForShapes(shapes) {
+  const seen = new Set();
+  for (const shape of shapes ?? []) {
+    for (const c of applicableConcernsFor(shape)) seen.add(c);
+  }
+  // Preserve canonical order.
+  return CONCERN_KEYS.filter((c) => seen.has(c));
+}

package/src/define/freeze-record.js

@@ -27,6 +27,13 @@
 //     override: null | { reason, by, at }                     // required (nullable)
 //   }
 //
+// `override` is required-nullable: the validator throws when the key
+// is missing; every writer stamps `override: null` on a fresh freeze.
+// The loader tolerates older records that lack the key by defaulting
+// to null on read, so a pre-slice-3 freeze.json survives a load
+// without a migration step (the next write converges the on-disk
+// shape).
+//
 // 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
@@ -37,6 +44,8 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
+import { computeTreeHash } from '../query/delta.js';
+
 /**
  * Relative path (under the project root) of the freeze record. Used by
  * the walker-invisibility invariant test and by every caller that
@@ -149,24 +158,23 @@ export function validateFreezeRecord(raw, filePath) {
     );
   }
 
-  if (Object.prototype.hasOwnProperty.call(body, 'override')) {
-    const override = body.override;
-    if (override !== null) {
-      if (override === undefined || typeof override !== 'object' || Array.isArray(override)) {
+  require('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' must be null or { reason, by, at }.",
-          { filePath, field: 'override' },
+          `Freeze record 'override.${f}' must be a non-empty string.`,
+          { filePath, field: `override.${f}` },
         );
       }
-      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}` },
-          );
-        }
-      }
     }
   }
 
@@ -204,6 +212,15 @@ export async function loadFreezeRecord({ projectRoot }) {
       { filePath: relPath, code: 'parseFailure' },
     );
   }
+  // Back-compat: older freeze records were written before override
+  // became a required-nullable field. Fill in null on read so a
+  // pre-slice-3 record survives; the writer stamps override: null on
+  // every fresh freeze so the on-disk shape converges on the current
+  // schema without a migration step.
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+    && !Object.prototype.hasOwnProperty.call(parsed, 'override')) {
+    /** @type {Record<string, unknown>} */ (parsed).override = null;
+  }
   return validateFreezeRecord(parsed, relPath);
 }
 
@@ -230,3 +247,75 @@ export async function saveFreezeRecord({ projectRoot, record }) {
   await writeFile(filePath, `${JSON.stringify(validated, null, 2)}\n`, 'utf8');
   return { filePath };
 }
+
+/**
+ * Apply `freeze.override { reason, by, at }` to the project's freeze
+ * record and persist it (0.30.0 PR 8, REQ-177 / TAC-4125). When no
+ * freeze record exists, a minimal placeholder is created so the
+ * override has a home: `frozenAt = at`, `treeHash` from the live tree
+ * via computeTreeHash on the supplied `docHashes` (passed by the
+ * caller so this module stays pure of walker I/O), `briefStatements`
+ * from the caller (defaults to 0 when the brief ledger is absent).
+ * On an existing record the override is set in place and every other
+ * field is preserved.
+ *
+ * The writer validates through saveFreezeRecord so the on-disk schema
+ * stays canonical. A missing-non-empty reason throws before any write.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.reason - operator-supplied non-empty reason string.
+ * @param {string} args.by - author identity recorded on the override.
+ * @param {string} args.at - ISO-8601 timestamp.
+ * @param {Record<string, string>} [args.docHashes] - the live tree's docHashes map; used only when no prior record exists so a minimal record can be stamped.
+ * @param {string} [args.treeHash] - the live tree hash; used only when no prior record exists.
+ * @param {number} [args.briefStatements] - brief ledger high-water mark; used only when no prior record exists.
+ * @returns {Promise<{ filePath: string, record: import('../query/delta.js').FreezeRecord & Record<string, unknown> }>}
+ */
+export async function applyOverrideToFreezeRecord({
+  projectRoot,
+  reason,
+  by,
+  at,
+  docHashes = {},
+  treeHash = null,
+  briefStatements = 0,
+}) {
+  if (typeof reason !== 'string' || reason.length === 0) {
+    throw new FreezeRecordError(
+      "applyOverrideToFreezeRecord: 'reason' must be a non-empty string.",
+      { filePath: FREEZE_RECORD_REL_PATH, field: 'override.reason' },
+    );
+  }
+  if (typeof by !== 'string' || by.length === 0) {
+    throw new FreezeRecordError(
+      "applyOverrideToFreezeRecord: 'by' must be a non-empty string.",
+      { filePath: FREEZE_RECORD_REL_PATH, field: 'override.by' },
+    );
+  }
+  if (typeof at !== 'string' || at.length === 0) {
+    throw new FreezeRecordError(
+      "applyOverrideToFreezeRecord: 'at' must be a non-empty string.",
+      { filePath: FREEZE_RECORD_REL_PATH, field: 'override.at' },
+    );
+  }
+  const existing = await loadFreezeRecord({ projectRoot });
+  // On an unfrozen tree, mint a minimal record whose treeHash is the
+  // live tree hash computed from the caller-supplied docHashes map,
+  // so the override is attached to a verifiable snapshot rather than a
+  // placeholder. Callers (the build CLI) pass computeDelta's
+  // currentDocHashes so the hash agrees with the delta model.
+  const computedTreeHash = treeHash ?? computeTreeHash(docHashes);
+  /** @type {import('../query/delta.js').FreezeRecord & Record<string, unknown>} */
+  const record = existing
+    ? { ...existing, override: { reason, by, at } }
+    : {
+      frozenAt: at,
+      treeHash: computedTreeHash,
+      docHashes: { ...docHashes },
+      briefStatements,
+      override: { reason, by, at },
+    };
+  const { filePath } = await saveFreezeRecord({ projectRoot, record });
+  return { filePath, record };
+}

package/src/define/ledgers.js

@@ -189,6 +189,11 @@ function validateEntry(name, entry, filePath, where = 'entry') {
         filePath, field: `${where}.source`,
       });
     }
+    if (e.resolvedBy !== undefined && typeof e.resolvedBy !== 'string') {
+      throw new LedgerError(`brief ${where}.resolvedBy must be a string when present.`, {
+        filePath, field: `${where}.resolvedBy`,
+      });
+    }
   } else if (name === 'decisions') {
     if (typeof e.question !== 'string' || e.question.length === 0) {
       throw new LedgerError(`decisions ${where}.question must be non-empty.`, {
@@ -443,37 +448,231 @@ export function resolveEntry({ name, body, id, patch = {}, now }) {
   return { body: nextBody, entry: updated };
 }
 
+const RESOLVED_BY_GRAMMAR_RE = /^(REQ-\d+|TAD\.entity:.+|PRD\.user:.+|TAD\.system:.+|TAC-\d+(?:-[A-Za-z0-9-]+)?|omitted:.+)$/;
+
+/**
+ * True when `pointer` matches the closed grammar for a `resolvedBy`
+ * value. Shape-only; does NOT verify that the pointed-to id or name
+ * resolves against a tree (that is D2's `skeleton:resolvedBy` check).
+ *
+ * @param {string} pointer
+ * @returns {boolean}
+ */
+export function isResolvedByGrammar(pointer) {
+  if (typeof pointer !== 'string') return false;
+  return RESOLVED_BY_GRAMMAR_RE.test(pointer.trim());
+}
+
+const KIND_MARKER_RE = /^\[([^\]]+)\]\s*/;
+const SOURCE_MARKER_RE = /\s*\(source:\s*([^)]+)\)\s*$/;
+const QUESTION_PREFIX_RE = /^(TBC|TBD|Open|Question)\b[:.]?\s*/i;
+
 /**
  * Parse `--from <file>` content into brief-statement drafts: one entry
- * per non-empty line, stripping a leading `- `, `* ` or `<n>. ` bullet.
- * The caller supplies the `kind` (or `capability` as the default). All
- * statements land as `status: 'open'` at the same `addedAt`; the CLI
- * assigns sequential ids.
+ * per non-empty line. Each line optionally carries a leading `[kind]`
+ * marker and a trailing `(source: ...)` marker. A line without
+ * `[kind]` takes `opts.kind` (default `capability`); a line without
+ * `(source: ...)` takes `opts.source` or no source. Heuristics kind a
+ * line `openQuestion` when it ends with `?` or begins with `TBC`,
+ * `TBD`, `Open:` or `Question:`, unless a `[kind]` marker says
+ * otherwise. Unknown `[kind]` values raise `LedgerError` (code
+ * `usage`) before any write.
  *
  * @param {string} content
  * @param {object} [opts]
- * @param {string} [opts.kind] default kind for every extracted line
- * @param {string} [opts.source] optional source-span label per entry
+ * @param {string} [opts.kind] default kind for every unmarked line
+ * @param {string} [opts.source] default source for every unmarked line
  * @returns {Array<{ text: string, kind: string, source?: string }>}
  */
 export function parseBriefFromFile(content, opts = {}) {
-  const kind = opts.kind ?? 'capability';
+  const defaultKind = opts.kind ?? 'capability';
   /** @type {Array<{ text: string, kind: string, source?: string }>} */
   const drafts = [];
   for (const raw of content.split(/\r?\n/)) {
     const trimmed = raw.trim();
     if (!trimmed) continue;
-    const stripped = trimmed
+    let line = trimmed
       .replace(/^[-*]\s+/, '')
       .replace(/^\d+[.)]\s+/, '');
-    if (!stripped) continue;
-    const entry = { text: stripped, kind };
-    if (opts.source) entry.source = opts.source;
+    if (!line) continue;
+
+    // Trailing (source: ...) marker.
+    let source = opts.source;
+    const srcMatch = line.match(SOURCE_MARKER_RE);
+    if (srcMatch) {
+      source = srcMatch[1].trim();
+      line = line.slice(0, srcMatch.index).trimEnd();
+    }
+
+    // Leading [kind] marker.
+    let kind = null;
+    const kindMatch = line.match(KIND_MARKER_RE);
+    if (kindMatch) {
+      kind = kindMatch[1].trim();
+      line = line.slice(kindMatch[0].length).trim();
+      if (!BRIEF_KINDS.includes(/** @type {any} */ (kind))) {
+        throw new LedgerError(
+          `brief --from: unknown kind '${kind}' (expected one of: ${BRIEF_KINDS.join(', ')})`,
+          { field: 'kind', code: 'usage' },
+        );
+      }
+    }
+
+    if (!line) continue;
+
+    // Heuristics for openQuestion when no [kind] marker was given.
+    if (!kind) {
+      if (line.endsWith('?') || QUESTION_PREFIX_RE.test(line)) {
+        kind = 'openQuestion';
+      } else {
+        kind = defaultKind;
+      }
+    }
+
+    const entry = { text: line, kind };
+    if (source) entry.source = source;
     drafts.push(entry);
   }
   return drafts;
 }
 
+/**
+ * Parse a `resolvedBy` pointer against the walker tree. The six
+ * accepted forms are `REQ-nnn`, `TAD.entity:<name>`, `PRD.user:<name>`,
+ * `TAD.system:<name>`, `TAC-nnnn`, and `omitted:<reason>`. Resolution
+ * checks the pointed-to id or name actually exists in the tree
+ * (except for `omitted:`, which always passes once the reason is
+ * non-empty).
+ *
+ * @param {string} pointer
+ * @param {object} tree  walker tree (TreeModel-like)
+ * @returns {{ ok: true, kind: string, target: string } | { ok: false, why: string }}
+ */
+export function parseResolvedBy(pointer, tree) {
+  if (typeof pointer !== 'string' || pointer.length === 0) {
+    return { ok: false, why: 'pointer must be a non-empty string' };
+  }
+  const p = pointer.trim();
+
+  // omitted:<reason>
+  const omittedMatch = p.match(/^omitted:(.+)$/);
+  if (omittedMatch) {
+    const reason = omittedMatch[1].trim();
+    if (!reason) return { ok: false, why: 'omitted: pointer needs a reason' };
+    return { ok: true, kind: 'omitted', target: reason };
+  }
+
+  // REQ-nnn
+  if (/^REQ-\d+$/.test(p)) {
+    const found = (tree?.requirements ?? []).some((r) => r?.reqId === p);
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'req', target: p };
+  }
+
+  // TAC-nnnn (short form, resolves to a tree TAC whose id starts
+  // with that prefix) or TAC-nnnn-<slug> (exact-match long form).
+  // Codex review 2026-10-02: an unanchored /^TAC-\d+/ let arbitrary
+  // suffixes (TAC-4130-made-up) pass as long as the numeric prefix
+  // matched an existing TAC; anchor the regex and gate the prefix
+  // fallback to the short form only.
+  const tacMatch = p.match(/^TAC-\d+(?:-[A-Za-z0-9-]+)?$/);
+  if (tacMatch) {
+    const tacs = tree?.tacs ?? [];
+    const isShortForm = /^TAC-\d+$/.test(p);
+    const found = tacs.some((t) => {
+      if (!t?.tacId) return false;
+      if (t.tacId === p) return true;
+      if (!isShortForm) return false;
+      return t.tacId.split('-').slice(0, 2).join('-') === p;
+    });
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'tac', target: p };
+  }
+
+  // TAD.entity:<name>
+  const entityMatch = p.match(/^TAD\.entity:(.+)$/);
+  if (entityMatch) {
+    const name = entityMatch[1].trim();
+    if (!name) return { ok: false, why: 'TAD.entity: pointer needs a name' };
+    const entities = tree?.tad?.dataArchitecture?.coreEntities ?? [];
+    const found = Array.isArray(entities)
+      && entities.some((e) => (typeof e === 'string' ? e : e?.name) === name);
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'tadEntity', target: name };
+  }
+
+  // PRD.user:<name>
+  const userMatch = p.match(/^PRD\.user:(.+)$/);
+  if (userMatch) {
+    const name = userMatch[1].trim();
+    if (!name) return { ok: false, why: 'PRD.user: pointer needs a name' };
+    // Codex review 2026-10-02: the production PRD schema uses
+    // `targetUsers`; keep `users` as a fallback for the test
+    // fixtures but prefer the real path.
+    const users = tree?.prd?.targetUsers ?? tree?.prd?.users ?? [];
+    const found = Array.isArray(users)
+      && users.some((u) => (typeof u === 'string' ? u : u?.name) === name);
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'prdUser', target: name };
+  }
+
+  // TAD.system:<name>
+  const systemMatch = p.match(/^TAD\.system:(.+)$/);
+  if (systemMatch) {
+    const name = systemMatch[1].trim();
+    if (!name) return { ok: false, why: 'TAD.system: pointer needs a name' };
+    // Codex review 2026-10-02: the production TAD schema puts
+    // externalSystems inside integrationArchitecture; keep the
+    // top-level path as a fallback for the test fixtures.
+    const systems = tree?.tad?.integrationArchitecture?.externalSystems ?? tree?.tad?.externalSystems ?? [];
+    const found = Array.isArray(systems)
+      && systems.some((s) => (typeof s === 'string' ? s : s?.name) === name);
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'tadSystem', target: name };
+  }
+
+  return { ok: false, why: 'pointer outside grammar (REQ-nnn, TAD.entity:<name>, PRD.user:<name>, TAD.system:<name>, TAC-nnnn, omitted:<reason>)' };
+}
+
+/**
+ * Patch a ledger entry in place. Field patches honour `add`-side
+ * validation by re-running `validateLedger` on the resulting body.
+ * Throws `LedgerError` (code `usage`) when the id is unknown. The
+ * entry's `id` and `addedAt` are never touched; `status`, `addedAt`
+ * and `resolvedAt` are passed through from the current entry unless
+ * explicitly patched.
+ *
+ * @param {object} args
+ * @param {LedgerName} args.name
+ * @param {Record<string, unknown[]>} args.body
+ * @param {number} args.id
+ * @param {Record<string, unknown>} args.patch
+ * @returns {{ body: Record<string, unknown[]>, entry: Record<string, unknown> }}
+ */
+export function updateEntry({ name, body, id, patch }) {
+  const cfg = LEDGER_CONFIG[name];
+  if (!cfg) throw new LedgerError(`Unknown ledger '${name}'.`, { code: 'usage' });
+  const list = /** @type {any[]} */ (body[cfg.arrayKey] ?? []);
+  const idx = list.findIndex((e) => Number(e?.id) === Number(id));
+  if (idx < 0) {
+    throw new LedgerError(`${name} ledger has no entry with id ${id}.`, {
+      filePath: ledgerRelPath(name), field: `id ${id}`, code: 'usage',
+    });
+  }
+  const current = list[idx];
+  const next = { ...current };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue;
+    if (key === 'id' || key === 'addedAt') continue;
+    next[key] = value;
+  }
+  const nextList = [...list];
+  nextList[idx] = next;
+  const nextBody = { ...body, [cfg.arrayKey]: nextList };
+  validateLedger(name, nextBody, ledgerRelPath(name));
+  return { body: nextBody, entry: next };
+}
+
 /**
  * Load every ledger the project has actually authored, keyed by name.
  *

package/src/define/probe-runner.js

@@ -0,0 +1,55 @@
+// Probe runner seam (REQ-175; spec 2026-10-01 section 4 row 'D6 scans
+// and the injectable probe runner' and section 11.6; ADR-4131 extended
+// by DEFINE step 3 PR 7).
+//
+// A probeRunner is `({ reqId, tree }) => findings[]` where each
+// finding is `{ reqId, finding, severity?, hash?, status? }`. The
+// shape mirrors a probe-ledger entry minus the ids and timestamps
+// computeReadiness assigns when it merges the findings into the probe
+// ledger it hands the gate.
+//
+// IMPORTANT: NO RUNNER SHIPS. rcf-lite has no LLM at runtime and does
+// not spawn processes or make network calls. The harness is the
+// runner: it either calls `ledger probes add` directly, or it drives a
+// test invocation that passes a stub runner into computeReadiness. The
+// seam exists so a test harness or a future harness-driven call site
+// has one named extension point rather than monkey-patching the
+// probe-ledger reader.
+//
+// Shape alone; the function stays as a type-level reference and is not
+// invoked by the CLI today.
+
+/**
+ * @typedef {{
+ *   reqId: string,
+ *   finding: string,
+ *   severity?: 'low' | 'medium' | 'high',
+ *   hash?: string,
+ *   status?: 'open' | 'closed' | 'attested',
+ * }} ProbeFinding
+ */
+
+/**
+ * @typedef {(args: { reqId: string, tree: unknown }) => ProbeFinding[]} ProbeRunner
+ */
+
+/**
+ * The default "no runner" sentinel. computeReadiness treats a null or
+ * absent runner as "do not inject findings"; its result then equals
+ * the 0.29.0 result on the same fixture (AC-17504-2).
+ *
+ * @type {ProbeRunner | null}
+ */
+export const NO_PROBE_RUNNER = null;
+
+/**
+ * Guard that a value is a usable probeRunner function. Pure. Exported
+ * so computeReadiness can skip injection cleanly on a non-function
+ * (`undefined`, `null`, or a mis-typed value) without throwing.
+ *
+ * @param {unknown} value
+ * @returns {value is ProbeRunner}
+ */
+export function isProbeRunner(value) {
+  return typeof value === 'function';
+}