rcf-lite 0.29.0 → 0.30.0

package/src/cli/readiness.js

@@ -16,7 +16,7 @@
 // every other query verb has.
 
 import { parseArgs } from 'node:util';
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { resolveTestPointers, walkTree } from '#core/store';
@@ -29,13 +29,17 @@ import {
   STAGE_GATES,
   STAGE_ORDER,
   STAGE_SHORT_NAMES,
+  ackable,
+  extractInterfacePathTokens,
   stagePolicy,
 } from '../query/gates.js';
 import {
   computeReadiness,
+  countLitmusReadersAtHash,
   formatTreeLine,
   formatVerdictLines,
   parseLevelFlag,
+  parseLitmusFlag,
   parsePersonaFlag,
 } from '../query/readiness.js';
 import { runWithAdmissibilityGate } from '../query/index.js';
@@ -45,6 +49,7 @@ const OPTION_SPEC = {
   check: { type: 'string' },
   level: { type: 'string' },
   persona: { type: 'string' },
+  litmus: { type: 'string' },
   help: { type: 'boolean' },
 };
 
@@ -73,11 +78,16 @@ Options:
                             brief | skeleton | shapes | stories |
                             crosscut | consistency | decisions |
                             freeze. Exits 4 on a blocking-stage
-                            failure (D1 / D2 / D4 / D7 / D8); exits 0
-                            with a visible '[warn]' line on an
-                            unacknowledged warn-with-ack failure
-                            (D3 / D5 / D6). Use --check all to print
-                            every stage under this exit-code policy.
+                            failure (D1 / D2 / D4 / D7 / D8) and on
+                            an unacknowledged D3 or D5 bite failure
+                            (ADR-4131, 0.30.0 PR 5 and PR 6); exits 0
+                            when D3 or D5 is acknowledged at the
+                            current tree hash; exits 0 with a visible
+                            '[warn]' line on an unacknowledged warn-
+                            with-ack failure (D6 until PR 7 bites it).
+                            Use
+                            --check all to print every stage under
+                            this exit-code policy.
   --level <intent|build>    Pick which verdict the exit code follows.
                             --level intent exits 4 when
                             levels.intentComplete.ok is false
@@ -97,6 +107,17 @@ Options:
                             per-stage detail to matching-persona
                             checks. Never affects the exit code or
                             the JSON content.
+  --litmus <n>              Require n distinct litmus readings at the
+                            current tree hash before passing (0.30.0
+                            PR 7, ADR-4131 extended). A litmus reading
+                            is a probe-ledger entry whose finding
+                            begins litmus:<reader>: and whose text
+                            includes the current tree hash. Fewer
+                            than n distinct readers exits 4 naming
+                            the shortfall. No process is spawned and
+                            no network call is made; the harness
+                            lands the readings through
+                            rcf define ledger probes add.
   --help                    Print this help.
 `;
 
@@ -108,6 +129,42 @@ const STATE_LABEL = {
   notApplicable: 'notApplicable',
 };
 
+/**
+ * ADR-4131 (0.30.0 PR 5): walk the tree's TAC interfaces, extract the
+ * `path:` tokens the engineer named, resolve each one against
+ * `projectRoot` on disk, and return the set of tokens that resolve.
+ * `shapes:pathsResolve` reads the set from the stage context and
+ * decides the D3 bite without I/O. The compute is pure; this helper is
+ * the one place I/O happens for the check.
+ *
+ * @param {string} projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @returns {Promise<Set<string>>}
+ */
+async function resolveInterfacePaths(projectRoot, tree) {
+  const resolved = new Set();
+  /** @type {Set<string>} */
+  const candidates = new Set();
+  for (const tac of tree.tacs ?? []) {
+    for (const iface of tac.interfaces ?? []) {
+      const desc = typeof iface?.description === 'string' ? iface.description : '';
+      for (const token of extractInterfacePathTokens(desc)) {
+        candidates.add(token);
+      }
+    }
+  }
+  await Promise.all([...candidates].map(async (token) => {
+    try {
+      await stat(join(projectRoot, token));
+      resolved.add(token);
+    } catch {
+      // Missing path stays out of the set; the gate decides whether
+      // `authoredAt: D3` lets it through.
+    }
+  }));
+  return resolved;
+}
+
 /**
  * Read `rcf/.identity/profile.md` when it exists; return null on
  * ENOENT. Any other read error surfaces as null so the profile
@@ -209,6 +266,15 @@ export async function main(argv, deps = {}) {
     return 2;
   }
 
+  /** @type {number | null} */
+  let litmus;
+  try {
+    litmus = parseLitmusFlag(flags.litmus);
+  } catch (err) {
+    stderr.write(`[error] usage readiness: ${/** @type {Error} */ (err).message}\n`);
+    return 2;
+  }
+
   const projectRoot = await findProjectRoot(cwd);
   if (!projectRoot) {
     stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
@@ -219,11 +285,12 @@ export async function main(argv, deps = {}) {
   const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
   const validateErrors = [...errors, ...staleErrors];
 
-  const [freeze, ledgers, testPointers, profileText] = await Promise.all([
+  const [freeze, ledgers, testPointers, profileText, resolvedPaths] = await Promise.all([
     loadFreezeRecord({ projectRoot }),
     loadAllLedgers({ projectRoot }),
     resolveTestPointers({ projectRoot, tree }),
     readProfileText(projectRoot),
+    resolveInterfacePaths(projectRoot, tree),
   ]);
 
   const startedAt = Date.now();
@@ -232,33 +299,34 @@ export async function main(argv, deps = {}) {
     : null;
 
   // Readiness is a diagnostic: even a chain that refuses admissibility
-  // wants to know which stage gate blocks it. The wrap runs first so
-  // the ruleset toolScope guard is honoured (NV-BL-SR-03 addendum);
-  // on refuse the refusal envelope is threaded through as informational
-  // context and the compute still runs (ADR-4123).
+  // wants to know which stage gate blocks it (AC-17902-4). Compute
+  // readiness once up front, then run the admissibility wrap passing
+  // the computed stages and validate-errors so it can cite
+  // NV-DL-ADM-02 (D4 floor), NV-DL-ADM-03 (D3 bite) and NV-DL-ADM-04
+  // (validate findings) alongside the NV-BL rules (PR 9).
+  /** @type {import('../query/readiness.js').ReadinessResult} */
+  const result = computeReadiness(tree, {
+    freeze,
+    ledgers,
+    profile: undefined,
+    profileText,
+    testPointers,
+    validateErrors,
+    resolvedPaths,
+  });
   const gated = await runWithAdmissibilityGate({
     tree,
     chainRulesetVersion,
-    produce: () => computeReadiness(tree, {
-      freeze,
-      ledgers,
-      profile: undefined,
-      profileText,
-      testPointers,
-      validateErrors,
-    }),
+    defineStages: result.stages,
+    defineValidateErrors: validateErrors,
+    produce: () => result,
   });
-
-  /** @type {import('../query/readiness.js').ReadinessResult} */
-  const result = gated.status === 'refused-admissibility'
-    ? computeReadiness(tree, {
-      freeze, ledgers, profile: undefined, profileText, testPointers, validateErrors,
-    })
-    : gated.payload;
   const wallMs = Date.now() - startedAt;
 
   if (gated.status === 'refused-admissibility') {
     stderr.write(`[warn] readiness: chain admissibility refused (informational; the readiness compute still ran). ${gated.refusal}\n`);
+  } else if (Array.isArray(gated.defineRules) && gated.defineRules.length > 0) {
+    stderr.write(`[warn] readiness: DEFINE-stage admissibility rules bite (informational; the readiness compute still ran): [${gated.defineRules.join(', ')}]. Resolve the failing stages or record an --ack reason on freeze.gates to satisfy recordedInChain.\n`);
   }
 
   if (flags.json) {
@@ -267,13 +335,13 @@ export async function main(argv, deps = {}) {
     // `_meta.level` is null when the flag was absent (spec section
     // 3.3): consumers can tell "no --level given" from "--level
     // build" explicitly, which matters for the ticket artefact.
-    const envelope = { ...result, _meta: { wallMs, level } };
+    const envelope = { ...result, _meta: { wallMs, level, litmus } };
     stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
-    return decideExitCode(result, checkStage, level, stderr);
+    return decideExitCode(result, checkStage, level, litmus, ledgers, stderr);
   }
 
   renderText(stdout, stderr, result, wallMs, checkStage, level, persona, profileText);
-  return decideExitCode(result, checkStage, level, stderr);
+  return decideExitCode(result, checkStage, level, litmus, ledgers, stderr);
 }
 
 /**
@@ -426,13 +494,15 @@ function formatChipLine(result) {
 
 /**
  * Decide the exit code for an invocation (spec section 3.2 matrix):
- *   - No `--check` and no `--level`: always 0.
+ *   - No `--check`, no `--level`, no `--litmus`: always 0.
  *   - `--check` alone: today's stage policy (4 on blocking failure,
  *     0 with `[warn]` on warn-with-ack failure).
  *   - `--level intent`: 4 iff `levels.intentComplete.ok === false`.
  *   - `--level build`: 4 iff `levels.readyToBuild.ok === false`
  *     (stricter than `--check all`; the warn line still prints).
- *   - Both: 4 if either policy says 4.
+ *   - `--litmus <n>`: 4 iff fewer than n distinct litmus readings at
+ *     the current tree hash (spec section 11.6, ADR-4131 extended).
+ *   - Several: 4 if any policy says 4.
  *
  * Warn lines are emitted whenever a warn-with-ack stage is failing,
  * independent of exit code, so an operator always sees why.
@@ -440,13 +510,27 @@ function formatChipLine(result) {
  * @param {import('../query/readiness.js').ReadinessResult} result
  * @param {string | null} checkStage
  * @param {'intent' | 'build' | null} level
+ * @param {number | null} litmus
+ * @param {object} ledgers
  * @param {NodeJS.WritableStream} stderr
  * @returns {number}
  */
-function decideExitCode(result, checkStage, level, stderr) {
+function decideExitCode(result, checkStage, level, litmus, ledgers, stderr) {
   let exitCode = 0;
 
-  // --check policy (unchanged from PR A).
+  // --check policy. ADR-4131 (0.30.0 PR 5): D3 bites, so a failing D3
+  // without an acknowledgement at the current tree hash exits 4.
+  // 0.30.0 PR 6 lifts the bite to D5 (crosscut:catalogue, the four new
+  // D4/D2 engineer checks ride D5's ack because the --ack channel is
+  // per gate). 0.30.0 PR 7 lifts the bite to D6 (the four consistency
+  // scans; the --ack channel D3/D5/D6 already share stays unchanged).
+  // The 'acknowledged' state is already folded by foldState() in
+  // gates.js when the freeze record acknowledges the gate at the
+  // current hash, so a failing-but-unacked bite stays failing here and
+  // exit 4 is the right answer. `ackable(stage)` names the three gates
+  // that accept an --ack override; a failing ackable stage that is not
+  // acknowledged bites.
+  const BITING_STAGES = new Set(['D3', 'D5', 'D6']);
   if (checkStage) {
     const stages = checkStage === 'all'
       ? result.stages
@@ -454,9 +538,10 @@ function decideExitCode(result, checkStage, level, stderr) {
     for (const s of stages) {
       if (s.state !== 'failing') continue;
       const policy = stagePolicy(s.stage);
-      if (policy === 'blocking') {
+      const bites = BITING_STAGES.has(s.stage);
+      if (policy === 'blocking' || bites) {
         exitCode = 4;
-      } else {
+      } else if (ackable(s.stage)) {
         stderr.write(`[warn] readiness: ${s.stage} (${s.gate}) is failing without an acknowledgement at the current tree hash. Run \`rcf define freeze --ack ${s.gate} --reason "<text>"\` to acknowledge, or edit the tree to clear the failure.\n`);
       }
     }
@@ -490,6 +575,22 @@ function decideExitCode(result, checkStage, level, stderr) {
     }
   }
 
+  // --litmus policy (0.30.0 PR 7, ADR-4131 extended; R9 clarified
+  // 2026-10-03, w-2026-10-03-dave-011). Count distinct readers who
+  // have landed a probe-ledger entry at the current LITMUS HASH whose
+  // finding begins litmus:<reader>:; exit 4 when fewer than n have
+  // attested. The litmus hash is the tree hash computed with the
+  // probes ledger excluded (see computeLitmusHash in src/query/readiness.js)
+  // so a reader's own write does not shift the hash it is attesting to.
+  if (typeof litmus === 'number' && litmus > 0) {
+    const hash = result.tree.litmusHash;
+    const readers = countLitmusReadersAtHash(ledgers, hash);
+    if (readers.size < litmus) {
+      stderr.write(`[warn] readiness: --litmus ${litmus} requires ${litmus} distinct litmus reading(s) at litmus hash ${hash}; found ${readers.size}. Spawn ${litmus - readers.size} more fresh-context reader(s) and land their readings through \`rcf define ledger probes add --req <reqId> --finding "litmus:<reader>: ..." --severity low\` with the litmus hash in the finding text (read it from \`rcf define readiness --json\` under \`tree.litmusHash\`).\n`);
+      exitCode = 4;
+    }
+  }
+
   return exitCode;
 }
 

package/src/cli/validate.js

@@ -8,6 +8,8 @@ import { formatErrors } from '#core/errors';
 import { checkCodeNodeResolution, walkTree } from '#core/store';
 import { validateCompanionPinsResolvable } from '../blueprint/companions.js';
 import { findProjectRoot } from '../view/index.js';
+// 0.30.0 PR 8 (REQ-178 / TAC-4126): define-validate findings.
+import { collectDefineValidateFindings } from '../define/validate-findings.js';
 
 const OPTION_SPEC = {
   quiet: { type: 'boolean' },
@@ -133,6 +135,12 @@ export async function main(argv, deps = {}) {
   // a pin that names no known provider is exit 3.
   const companionsErrors = await validateCompanionPinsResolvable({ projectRoot, tree });
   errors.push(...companionsErrors);
+  // 0.30.0 PR 8 (REQ-178, TAC-4126): interface kind outside vocabulary,
+  // bracketed AC class prefix outside the known classes, tacIds naming
+  // a non-TAC, and an unresolving ownerRef or deliveredBy. Absence of
+  // a class marker is NOT a finding (decision 10 kept).
+  const defineValidateFindings = collectDefineValidateFindings(tree);
+  errors.push(...defineValidateFindings);
   if (flags.json) {
     const issues = errors.map((e) => ({
       id: e.documentId ?? null,

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

@@ -44,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
@@ -245,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/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';
+}