@ngockhoale/ukit 3.0.8 → 3.0.10

package/scripts/bench/memory-gate.mjs

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+// TASK-006 — G3 decision gate (SPEC §5 FR-011/FR-012, M03-04).
+//
+// Consumes the bench report (TASK-003/004) and the SQLite spike report
+// (TASK-005), applies the signed G3 decision rule, and writes the ADR +
+// machine-readable verdict to docs/AI_HANDOFF/inventory/ (or --out).
+//
+// Decision rule (blueprint §W3/G3, SPEC FR-011): `sqlite` iff ALL of —
+//   (a) the JSON/lexical variant demonstrably fails a signed threshold:
+//       correctness floor breach (scopeLeakRate != 0 OR falseAuthorityRate
+//       != 0 OR staleHitRate != 0 OR precisionAt5 < 0.9) OR medium-tier
+//       CLI-search p95 > 150ms OR write-burst lostUpdates > 0;
+//   (b) the spike has no `failed` cell on availability / WAL / backup /
+//       migration;
+//   (c) the sqlite-fts5 variant shows a meaningful gain over lexical —
+//       strictly higher precisionAt5 or recallAt5, or strictly lower p95.
+// Otherwise `json`. Inconclusive evidence (missing/UNKNOWN metrics,
+// complete:false, missing spike cells) resolves to `json` with each gap
+// recorded in `inconclusiveGap`.
+//
+// Exit codes: 0 = verdict written (the decision is data), 1 = usage error,
+// 2 = harness crash.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const DEFAULT_OUT = path.join(REPO_ROOT, 'docs/AI_HANDOFF/inventory/g3-verdict.md');
+
+// FR-012 signed thresholds — emitted verbatim into the ADR.
+export const THRESHOLDS = Object.freeze({
+  scopeLeakRate: 0,
+  falseAuthorityRate: 0,
+  staleHitRate: 0,
+  precisionAt5Min: 0.9,
+  cliSearchP95MsMax: 150,
+  writeBurstLostUpdatesMax: 0,
+});
+
+// Spike cells gated by condition (b).
+const GATED_SPIKE_CELLS = [
+  'node-sqlite-availability', 'wal-mode', 'backup', 'migration-roundtrip',
+];
+
+const USAGE = `Usage: node scripts/bench/memory-gate.mjs --bench <report.json> --spike <spike.json> [--out <g3-verdict.md>]
+
+Consumes the W3 bench report + SQLite spike report, applies the signed G3
+decision rule (SPEC FR-011), and writes the ADR (<out>.md) plus a sibling
+verdict JSON (<out>.json).
+
+  --bench <f>   Bench report JSON from memory-bench.mjs (required).
+  --spike <f>   Spike report JSON from sqlite-spike.mjs (required).
+  --out <f>     ADR path (default ${path.relative(REPO_ROOT, DEFAULT_OUT)}); the
+                sibling .json verdict is always written next to it.
+
+Exit codes: 0 = verdict written, 1 = usage error, 2 = crash.`;
+
+function parseArgs(argv) {
+  const opts = { out: DEFAULT_OUT };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') return { help: true };
+    const takeValue = () => {
+      i += 1;
+      if (i >= argv.length) throw new Error(`Missing value for ${arg}`);
+      return argv[i];
+    };
+    if (arg === '--bench') opts.bench = takeValue();
+    else if (arg === '--spike') opts.spike = takeValue();
+    else if (arg === '--out') opts.out = takeValue();
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return opts;
+}
+
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+/** CLI-search p95: prefer warm, fall back to cold. */
+function cliP95(bench) {
+  const warm = bench?.surfaces?.cli?.warm?.p95;
+  if (isNum(warm)) return { value: warm, source: 'cli.warm' };
+  const cold = bench?.surfaces?.cli?.cold?.p95;
+  if (isNum(cold)) return { value: cold, source: 'cli.cold' };
+  return { value: 'UNKNOWN', source: 'cli' };
+}
+
+/**
+ * Evaluate the G3 rule. Returns
+ * {decision, rationale[], inconclusiveGap[], evidence:{breaches[],
+ *  spikeFailedCells[], ftsGain}}.
+ */
+export function evaluateGate(bench, spike) {
+  const rationale = [];
+  const gaps = [];
+  const breaches = [];
+
+  if (bench?.complete === false) {
+    gaps.push('bench report marked complete:false (interrupted/failed probes)');
+  }
+
+  // ---- condition (a): JSON/lexical demonstrably fails a signed threshold ----
+  const lexical = bench?.variants?.lexical;
+  if (!lexical || lexical.verdict !== 'measured') {
+    gaps.push('lexical variant missing or not measured in bench report');
+  } else {
+    const c = lexical.correctness ?? {};
+    if (!isNum(c.scopeLeakRate)) gaps.push('lexical scopeLeakRate UNKNOWN/missing');
+    else if (c.scopeLeakRate !== THRESHOLDS.scopeLeakRate) {
+      breaches.push(`scopeLeakRate=${c.scopeLeakRate} breaches floor ${THRESHOLDS.scopeLeakRate}`);
+    }
+    if (!isNum(c.falseAuthorityRate)) gaps.push('lexical falseAuthorityRate UNKNOWN/missing');
+    else if (c.falseAuthorityRate !== THRESHOLDS.falseAuthorityRate) {
+      breaches.push(`falseAuthorityRate=${c.falseAuthorityRate} breaches floor ${THRESHOLDS.falseAuthorityRate}`);
+    }
+    if (!isNum(c.staleHitRate)) gaps.push('lexical staleHitRate UNKNOWN/missing');
+    else if (c.staleHitRate !== THRESHOLDS.staleHitRate) {
+      breaches.push(`staleHitRate=${c.staleHitRate} breaches floor ${THRESHOLDS.staleHitRate}`);
+    }
+    if (!isNum(c.precisionAt5)) gaps.push('lexical precisionAt5 UNKNOWN/missing');
+    else if (c.precisionAt5 < THRESHOLDS.precisionAt5Min) {
+      breaches.push(`precisionAt5=${c.precisionAt5} below floor ${THRESHOLDS.precisionAt5Min}`);
+    }
+  }
+
+  const cli = cliP95(bench);
+  if (!isNum(cli.value)) {
+    gaps.push('CLI-search p95 UNKNOWN/missing (surfaces.cli warm+cold)');
+  } else if (cli.value > THRESHOLDS.cliSearchP95MsMax) {
+    breaches.push(`CLI-search p95=${cli.value}ms (${cli.source}) exceeds budget ${THRESHOLDS.cliSearchP95MsMax}ms`);
+  }
+
+  const wb = bench?.writeBurst;
+  if (!wb || !isNum(wb.lostUpdates)) {
+    gaps.push('writeBurst lostUpdates UNKNOWN/missing');
+  } else if (wb.lostUpdates > THRESHOLDS.writeBurstLostUpdatesMax) {
+    breaches.push(`write burst lostUpdates=${wb.lostUpdates} exceeds ${THRESHOLDS.writeBurstLostUpdatesMax}`);
+  }
+
+  const conditionA = breaches.length > 0;
+  rationale.push(conditionA
+    ? `(a) JSON/lexical fails signed threshold(s): ${breaches.join('; ')}`
+    : '(a) JSON/lexical meets every signed threshold — no demonstrable failure');
+
+  // ---- condition (b): no failed spike cell on availability/WAL/backup/migration ----
+  const spikeFailedCells = [];
+  const cells = spike?.cells ?? {};
+  for (const name of GATED_SPIKE_CELLS) {
+    const verdict = cells[name]?.verdict;
+    if (verdict === 'failed') spikeFailedCells.push(name);
+    else if (verdict === undefined) gaps.push(`spike cell '${name}' missing`);
+    else if (verdict === 'unsupported') gaps.push(`spike cell '${name}' unsupported: ${cells[name].detail}`);
+  }
+  const conditionB = spikeFailedCells.length === 0;
+  rationale.push(conditionB
+    ? '(b) spike shows no failed cell on availability/WAL/backup/migration'
+    : `(b) unmet: failed spike cell(s) ${spikeFailedCells.join(', ')}`);
+
+  // ---- condition (c): meaningful FTS5 gain over lexical ----
+  const fts = bench?.variants?.['sqlite-fts5'];
+  let ftsGain = null;
+  if (!fts || fts.verdict !== 'measured') {
+    gaps.push(`sqlite-fts5 variant missing or not measured (verdict=${fts?.verdict ?? 'absent'})`);
+    rationale.push('(c) unmet: sqlite-fts5 variant not measured — no gain evidence');
+  } else if (!lexical || lexical.verdict !== 'measured') {
+    gaps.push('cannot assess FTS5 gain: lexical baseline not measured');
+    rationale.push('(c) unmet: no lexical baseline to compare against');
+  } else {
+    const fp = fts.correctness?.precisionAt5;
+    const fr = fts.correctness?.recallAt5;
+    const lp = lexical.correctness?.precisionAt5;
+    const lr = lexical.correctness?.recallAt5;
+    const fp95 = fts.latency?.p95;
+    const lp95 = lexical.latency?.p95;
+    const gains = [];
+    if (isNum(fp) && isNum(lp) && fp > lp) gains.push(`precisionAt5 ${lp}→${fp}`);
+    if (isNum(fr) && isNum(lr) && fr > lr) gains.push(`recallAt5 ${lr}→${fr}`);
+    if (isNum(fp95) && isNum(lp95) && fp95 < lp95) gains.push(`p95 ${lp95}ms→${fp95}ms`);
+    if ((!isNum(fp) || !isNum(lp)) && (!isNum(fp95) || !isNum(lp95))) {
+      gaps.push('FTS5-vs-lexical comparison metrics UNKNOWN/missing');
+    }
+    ftsGain = gains.length > 0 ? gains : null;
+    rationale.push(ftsGain
+      ? `(c) FTS5 shows meaningful gain over lexical: ${gains.join('; ')}`
+      : '(c) unmet: no meaningful FTS5 quality or latency gain over lexical');
+  }
+
+  const conditionC = ftsGain !== null;
+  // Inconclusive evidence resolves to json: any recorded gap blocks sqlite
+  // even when all three conditions are met (FR-011).
+  const decision = conditionA && conditionB && conditionC && gaps.length === 0
+    ? 'sqlite' : 'json';
+  rationale.push(decision === 'sqlite'
+    ? 'decision=sqlite — all three conditions of FR-011 satisfied, no gaps'
+    : `decision=json — breaches=${conditionA} spikeClean=${conditionB} `
+      + `ftsGain=${conditionC} gaps=${gaps.length}; inconclusive evidence resolves to json`);
+
+  return {
+    decision,
+    rationale,
+    inconclusiveGap: gaps,
+    evidence: { breaches, spikeFailedCells, ftsGain, cliP95: cli },
+  };
+}
+
+// ---------- ADR rendering ----------
+
+function renderAdr({ bench, spike, benchRef, spikeRef, result }) {
+  const v = result.decision;
+  const lines = [];
+  lines.push('# ADR — Memory storage/retrieval engine: guarded JSON vs SQLite+FTS5 (gate G3)');
+  lines.push('');
+  lines.push(`- Status: ${v === 'sqlite' ? 'accepted — migrate to SQLite+FTS5' : 'accepted — stay on guarded JSON'} (C59, TASK-006)`);
+  lines.push(`- Date: ${new Date().toISOString().slice(0, 10)}`);
+  lines.push('- Spec: SPEC §5 FR-011/FR-012, §7; blueprint §W3/G3');
+  lines.push(`- Evidence: bench \`${benchRef}\` · spike \`${spikeRef}\``);
+  lines.push('');
+  lines.push('## Context');
+  lines.push('');
+  lines.push('W1+W2 made ukit-memory reads policy-correct and writes guarded on the');
+  lines.push('JSON v2 store. Blueprint gate G3 requires measured evidence before');
+  lines.push('choosing the long-term storage/retrieval engine: guarded JSON +');
+  lines.push('lexical scan is the incumbent; SQLite+FTS5 is the challenger. The');
+  lines.push(`bench ran tier=\`${bench?.corpus?.tier ?? 'UNKNOWN'}\` `
+    + `(records=${bench?.corpus?.recordCount ?? 'UNKNOWN'}, `
+    + `seed=${bench?.corpus?.seed ?? 'UNKNOWN'}) on node \`${bench?.env?.node ?? '?'}\` `
+    + `${bench?.env?.os ?? '?'}/${bench?.env?.arch ?? '?'}.`);
+  lines.push('');
+  lines.push('Signed thresholds (FR-012, recorded verbatim):');
+  lines.push('');
+  lines.push(`- correctness floor: \`scopeLeakRate == ${THRESHOLDS.scopeLeakRate}\`, `
+    + `\`falseAuthorityRate == ${THRESHOLDS.falseAuthorityRate}\`, `
+    + `\`staleHitRate == ${THRESHOLDS.staleHitRate}\`, `
+    + `\`precisionAt5 ≥ ${THRESHOLDS.precisionAt5Min}\` on medium tier`);
+  lines.push(`- latency budget: CLI-search p95 ≤ ${THRESHOLDS.cliSearchP95MsMax}ms on medium tier `
+    + '(~3× the W0 small-corpus p95 of 56ms — provisional, first signed budget)');
+  lines.push(`- write burst: ${THRESHOLDS.writeBurstLostUpdatesMax} lost updates`);
+  lines.push('');
+  lines.push('## Options');
+  lines.push('');
+  lines.push('1. **Guarded JSON v2 + lexical scan (incumbent)** — single-file store,');
+  lines.push('   generation-guarded writes, in-process token-overlap retrieval.');
+  lines.push('   No new dependency, no migration surface.');
+  lines.push('2. **SQLite + FTS5** — embedded index over eligible text via');
+  lines.push('   `node:sqlite` (Node ≥22.5 unflagged; Node 20 needs');
+  lines.push('   `--experimental-sqlite`). Adds a file format, WAL semantics, and');
+  lines.push('   a migration path.');
+  lines.push('');
+  lines.push('Measured variants (bench report):');
+  lines.push('');
+  lines.push('| variant | verdict | p@5 | r@5 | scopeLeak | falseAuth | stale | p95 ms |');
+  lines.push('|---------|---------|-----|-----|-----------|-----------|-------|--------|');
+  for (const [name, entry] of Object.entries(bench?.variants ?? {})) {
+    const c = entry.correctness ?? {};
+    const fmt = (x) => (isNum(x) ? String(Math.round(x * 1000) / 1000) : (x ?? 'n/a'));
+    lines.push(`| ${name} | ${entry.verdict} | ${fmt(c.precisionAt5)} | ${fmt(c.recallAt5)} `
+      + `| ${fmt(c.scopeLeakRate)} | ${fmt(c.falseAuthorityRate)} | ${fmt(c.staleHitRate)} `
+      + `| ${fmt(entry.latency?.p95)} |`);
+  }
+  lines.push('');
+  const cli = result.evidence.cliP95;
+  const wb = bench?.writeBurst ?? {};
+  lines.push(`CLI-search p95 (${cli.source}): \`${cli.value}\` ms · `
+    + `write burst: expected=${wb.expected ?? 'n/a'} persisted=${wb.persisted ?? 'n/a'} `
+    + `lostUpdates=${wb.lostUpdates ?? 'n/a'} verdict=${wb.verdict ?? 'n/a'}`);
+  lines.push('');
+  const s = spike?.summary ?? {};
+  lines.push(`Spike cells: tested=${s.tested ?? 'n/a'} unsupported=${s.unsupported ?? 'n/a'} `
+    + `failed=${s.failed ?? 'n/a'} of ${s.total ?? 'n/a'}`);
+  if (result.evidence.breaches.length > 0) {
+    const measured = Object.values(bench?.variants ?? {}).filter((e) => e?.verdict === 'measured');
+    const ref = measured[0]?.correctness ?? {};
+    const identical = measured.length > 1 && measured.every((e) => {
+      const c = e.correctness ?? {};
+      return c.scopeLeakRate === ref.scopeLeakRate
+        && c.falseAuthorityRate === ref.falseAuthorityRate
+        && c.staleHitRate === ref.staleHitRate
+        && c.precisionAt5 === ref.precisionAt5;
+    });
+    if (identical) {
+      lines.push('Note: the correctness breaches above are identical across all');
+      lines.push('measured variants — they originate in the shared `eligible()`');
+      lines.push('policy/corpus labeling, not in the JSON storage layer. They are');
+      lines.push('recorded as a W4 policy-fix item, not as evidence for SQLite.');
+      lines.push('');
+    }
+  }
+  lines.push('');
+  lines.push('## Decision');
+  lines.push('');
+  lines.push(`**${v === 'sqlite' ? 'Option 2 — SQLite+FTS5' : 'Option 1 — stay on guarded JSON'}** `
+    + `(verdict \`${v}\`, ruleVersion 1). Rule evaluation:`);
+  lines.push('');
+  for (const r of result.rationale) lines.push(`- ${r}`);
+  lines.push('');
+  if (result.inconclusiveGap.length > 0) {
+    lines.push('Inconclusive gaps (resolved to `json` per FR-011):');
+    lines.push('');
+    for (const g of result.inconclusiveGap) lines.push(`- ${g}`);
+    lines.push('');
+  }
+  lines.push('## Reversal trigger');
+  lines.push('');
+  if (v === 'sqlite') {
+    lines.push('Revisit if the SQLite path shows a `failed` spike cell on a');
+    lines.push('supported engine matrix (Node 20 flag gating, network-FS WAL),');
+    lines.push('or if W4 implementation reveals migration cost exceeding the');
+    lines.push('measured gain recorded here.');
+  } else {
+    lines.push('Revisit when a measured bench run shows the JSON variant');
+    lines.push('breaching a signed threshold — correctness floor breach,');
+    lines.push(`CLI-search p95 > ${THRESHOLDS.cliSearchP95MsMax}ms on the medium tier, or lost`);
+    lines.push('updates in the write burst — AND the spike stays clean AND FTS5');
+    lines.push('shows a meaningful gain. The trigger is a number from');
+    lines.push('`scripts/bench/memory-bench.mjs`, not a guess.');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ---------- main ----------
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`[memory-gate] ${error.message}\n\n${USAGE}`);
+    process.exit(1);
+  }
+  if (opts.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (!opts.bench || !opts.spike) {
+    console.error(`[memory-gate] --bench and --spike are required.\n\n${USAGE}`);
+    process.exit(1);
+  }
+
+  const benchPath = path.resolve(opts.bench);
+  const spikePath = path.resolve(opts.spike);
+  let bench;
+  let spike;
+  try {
+    bench = JSON.parse(fs.readFileSync(benchPath, 'utf8'));
+  } catch (error) {
+    console.error(`[memory-gate] cannot read bench report: ${error.message}`);
+    process.exit(1);
+  }
+  try {
+    spike = JSON.parse(fs.readFileSync(spikePath, 'utf8'));
+  } catch (error) {
+    console.error(`[memory-gate] cannot read spike report: ${error.message}`);
+    process.exit(1);
+  }
+
+  const result = evaluateGate(bench, spike);
+  const benchRef = path.relative(REPO_ROOT, benchPath);
+  const spikeRef = path.relative(REPO_ROOT, spikePath);
+
+  const verdict = {
+    decision: result.decision,
+    ruleVersion: 1,
+    evidence: { benchRef, spikeRef },
+    thresholds: THRESHOLDS,
+    rationale: result.rationale,
+  };
+  if (result.inconclusiveGap.length > 0) verdict.inconclusiveGap = result.inconclusiveGap;
+
+  const outPath = path.resolve(opts.out);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, renderAdr({ bench, spike, benchRef, spikeRef, result }));
+  const jsonPath = outPath.replace(/\.md$/i, '') + '.json';
+  fs.writeFileSync(jsonPath, `${JSON.stringify(verdict, null, 2)}\n`);
+
+  console.log(`[memory-gate] decision=${verdict.decision} gaps=${result.inconclusiveGap.length}`);
+  console.log(`[memory-gate] ADR:     ${outPath}`);
+  console.log(`[memory-gate] verdict: ${jsonPath}`);
+  process.exit(0);
+}
+
+const invokedAsScript = process.argv[1]
+  && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedAsScript) {
+  main().catch((error) => {
+    console.error(`[memory-gate] harness crash: ${error?.stack ?? error}`);
+    process.exit(2);
+  });
+}

package/scripts/bench/memory-metrics.mjs

@@ -0,0 +1,179 @@
+// TASK-002 — memory bench correctness/latency metric module
+// (SPEC §5 FR-003/FR-004, §8, §10).
+//
+// Pure ESM; the only I/O is `footprintBytes` (recursive byte total). The bench
+// runner (TASK-003), ablation (TASK-004), and gate (TASK-006) all import these
+// functions so metric math lives in exactly one implementation — see
+// docs/AI_HANDOFF/benchmark/metric-spec.md for pre-registered definitions.
+//
+// UNKNOWN semantics: the literal string 'UNKNOWN' is returned wherever the
+// denominator or source data is absent/invalid. It is never 0, NaN, Infinity,
+// or an estimate — a string cannot silently coerce into numeric aggregates.
+//
+// Hit shape (contract emitted by TASK-004 variants):
+//   {id, project_id?, status?, labels?[]}
+
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const UNKNOWN = 'UNKNOWN';
+
+// Labels that mark a record as non-authoritative when surfaced as a hit.
+const NON_AUTHORITY_LABELS = new Set(['candidate', 'observation', 'injection']);
+// Manifest query kinds whose relevantIds form the stale id set.
+const STALE_QUERY_KINDS = new Set(['stale', 'superseded', 'expired']);
+
+function isNonEmptyArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}
+
+function isPositiveInt(value) {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+
+/**
+ * precision@k = |top-k ∩ relevant| / k.
+ *
+ * @param {string[]} rankedIds ranked hit ids (best first)
+ * @param {string[]} relevantIds ids considered relevant for the query
+ * @param {number} k cutoff
+ * @returns {number|'UNKNOWN'} ratio in [0,1], or 'UNKNOWN' when relevantIds is
+ *   empty/invalid or k is not a positive integer.
+ */
+export function precisionAtK(rankedIds, relevantIds, k) {
+  if (!Array.isArray(rankedIds) || !isNonEmptyArray(relevantIds) || !isPositiveInt(k)) {
+    return UNKNOWN;
+  }
+  const relevant = new Set(relevantIds);
+  const hits = rankedIds.slice(0, k).filter((id) => relevant.has(id)).length;
+  return hits / k;
+}
+
+/**
+ * recall@k = |top-k ∩ relevant| / |relevant|.
+ *
+ * @returns {number|'UNKNOWN'} 'UNKNOWN' on empty/invalid relevantIds or k.
+ */
+export function recallAtK(rankedIds, relevantIds, k) {
+  if (!Array.isArray(rankedIds) || !isNonEmptyArray(relevantIds) || !isPositiveInt(k)) {
+    return UNKNOWN;
+  }
+  const relevant = new Set(relevantIds);
+  const hits = rankedIds.slice(0, k).filter((id) => relevant.has(id)).length;
+  return hits / relevant.size;
+}
+
+/**
+ * scopeLeakRate = fraction of hits whose project_id is bound to a different
+ * project than `boundProjectId`. Hits with no project_id are not leaks (they
+ * are not bound to a *different* project); the denominator is total hits.
+ *
+ * @param {Array<{id: string, project_id?: string}>} hits
+ * @param {string} boundProjectId
+ * @returns {number|'UNKNOWN'} 'UNKNOWN' when hits is empty/invalid or
+ *   boundProjectId is absent.
+ */
+export function scopeLeakRate(hits, boundProjectId) {
+  if (!isNonEmptyArray(hits) || typeof boundProjectId !== 'string' || boundProjectId === '') {
+    return UNKNOWN;
+  }
+  const leaked = hits.filter(
+    (h) => h && typeof h.project_id === 'string' && h.project_id !== boundProjectId,
+  ).length;
+  return leaked / hits.length;
+}
+
+/**
+ * falseAuthorityRate = fraction of hits that are non-active / candidate /
+ * observation / injection-labeled records presented as current. A hit is
+ * flagged when `status` is a string other than 'active', or when `labels`
+ * contains a non-authority label.
+ *
+ * @param {Array<{id: string, status?: string, labels?: string[]}>} hits
+ * @returns {number|'UNKNOWN'} 'UNKNOWN' when hits is empty/invalid.
+ */
+export function falseAuthorityRate(hits) {
+  if (!isNonEmptyArray(hits)) return UNKNOWN;
+  const flagged = hits.filter((h) => {
+    if (!h || typeof h !== 'object') return false;
+    if (typeof h.status === 'string' && h.status !== 'active') return true;
+    return Array.isArray(h.labels) && h.labels.some((l) => NON_AUTHORITY_LABELS.has(l));
+  }).length;
+  return flagged / hits.length;
+}
+
+/**
+ * staleHitRate = fraction of hits whose id is in the manifest's
+ * stale/superseded/expired id set. The set comes from `manifest.staleIds`
+ * when present, else is derived from `manifest.queries` entries whose kind is
+ * stale/superseded/expired (their relevantIds are the stale records).
+ *
+ * @param {Array<{id: string}>} hits
+ * @param {{staleIds?: string[], queries?: Array<{kind: string, relevantIds?: string[]}>}} manifest
+ * @returns {number|'UNKNOWN'} 'UNKNOWN' when hits or manifest is empty/invalid.
+ */
+export function staleHitRate(hits, manifest) {
+  if (!isNonEmptyArray(hits) || !manifest || typeof manifest !== 'object') return UNKNOWN;
+  let staleIds;
+  if (Array.isArray(manifest.staleIds)) {
+    staleIds = manifest.staleIds;
+  } else if (Array.isArray(manifest.queries)) {
+    staleIds = manifest.queries
+      .filter((q) => q && STALE_QUERY_KINDS.has(q.kind) && Array.isArray(q.relevantIds))
+      .flatMap((q) => q.relevantIds);
+  } else {
+    return UNKNOWN;
+  }
+  const stale = new Set(staleIds);
+  const flagged = hits.filter((h) => h && stale.has(h.id)).length;
+  return flagged / hits.length;
+}
+
+/**
+ * Nearest-rank percentiles over run durations (same convention as
+ * scripts/bench/memory-baseline.mjs and metric-spec §7). Non-finite or
+ * negative entries are dropped; `n` counts valid durations only.
+ *
+ * @param {number[]} durations
+ * @returns {{n: number, p50: number|'UNKNOWN', p95: number|'UNKNOWN', p99: number|'UNKNOWN'}}
+ */
+export function summarizeRuns(durations) {
+  const valid = Array.isArray(durations)
+    ? durations.filter((d) => typeof d === 'number' && Number.isFinite(d) && d >= 0)
+    : [];
+  if (valid.length === 0) return { n: 0, p50: UNKNOWN, p95: UNKNOWN, p99: UNKNOWN };
+  const sorted = [...valid].sort((a, b) => a - b);
+  const rank = (q) => sorted[Math.max(1, Math.ceil((q / 100) * sorted.length)) - 1];
+  return { n: sorted.length, p50: rank(50), p95: rank(95), p99: rank(99) };
+}
+
+/**
+ * Recursive byte total of a directory — the only async/fs function in the
+ * module. Follows no symlinks (lstat-style via dirent), so cycles and links
+ * escaping the fixture cannot inflate the measurement.
+ *
+ * @param {string} dir
+ * @returns {Promise<number|'UNKNOWN'>} total bytes, or 'UNKNOWN' when dir is
+ *   not a readable directory.
+ */
+export async function footprintBytes(dir) {
+  if (typeof dir !== 'string' || dir === '') return UNKNOWN;
+  let total = 0;
+  const walk = async (current) => {
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(path);
+      } else if (entry.isFile()) {
+        total += (await stat(path)).size;
+      }
+    }
+  };
+  try {
+    await walk(dir);
+  } catch {
+    return UNKNOWN;
+  }
+  return total;
+}

package/scripts/bench/parallel-agents.mjs

@@ -15,6 +15,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 const SLOWDOWN_LIMIT = 2.0;
 
@@ -121,6 +122,28 @@ function fail(msg) {
   process.exit(1);
 }
 
+// BUG-C27-24: `wallClockMs === 0` (a sub-ms --cmd) made the base `base` 0 →
+// every slowdownFactor NaN → `eligible` empty → `eligible.reduce(..., eligible[0])`
+// dereffed undefined and threw a cryptic TypeError AFTER the whole benchmark ran.
+// `wallClockMs === 0` is below Date.now() resolution for a spawned child, so it is
+// marked unmeasurable and excluded; an empty `eligible` yields recommended=null so
+// main() fails with a clear message, and the reduce is seeded with rows[0] so it can
+// never deref undefined.
+export function computeRecommendation(rows) {
+  const base = rows[0].wallClockMs;
+  for (const row of rows) {
+    row.unmeasurable = row.wallClockMs === 0 || base === 0;
+    row.slowdownFactor = base === 0 ? NaN : row.wallClockMs / base;
+    row.perRunCost = row.wallClockMs / row.n;
+  }
+  const eligible = rows.filter((r) => !r.unmeasurable && r.slowdownFactor <= SLOWDOWN_LIMIT);
+  const recommended = eligible.length === 0
+    ? null
+    : eligible.reduce((best, r) => (r.perRunCost < best.perRunCost ? r : best), rows[0]).n;
+  return { recommended, eligible };
+}
+
+
 async function main() {
   const opts = (() => {
     try {
@@ -145,22 +168,18 @@ async function main() {
     // eslint-disable-next-line no-await-in-loop -- levels are measured sequentially on purpose
     rows.push(await runLevel(n, opts.cmd));
   }
-  const base = rows[0].wallClockMs;
-  for (const row of rows) {
-    row.slowdownFactor = row.wallClockMs / base;
-    row.perRunCost = row.wallClockMs / row.n;
+  const { recommended } = computeRecommendation(rows);
+  if (recommended === null) {
+    fail('no level met slowdown limit (base wall clock 0ms?) — benchmark is unmeasurable; rerun with a slower --cmd');
   }
 
-  const eligible = rows.filter((r) => r.slowdownFactor <= SLOWDOWN_LIMIT);
-  const recommended = eligible.reduce((best, r) => (r.perRunCost < best.perRunCost ? r : best), eligible[0]).n;
-
   const loadAvgEnd = os.loadavg();
   const finishedAt = new Date().toISOString();
 
   const result = {
     cpuCount,
-    levels: rows.map(({ n, wallClockMs, slowdownFactor, perRunCost, failures, concurrencyHighWaterMark, timedOut }) => ({
-      n, wallClockMs, slowdownFactor, perRunCost, failures, concurrencyHighWaterMark, timedOut,
+    levels: rows.map(({ n, wallClockMs, slowdownFactor, perRunCost, failures, concurrencyHighWaterMark, timedOut, unmeasurable }) => ({
+      n, wallClockMs, slowdownFactor, perRunCost, failures, concurrencyHighWaterMark, timedOut, unmeasurable,
     })),
     recommended,
     measurementConditions: { loadAvgStart, loadAvgEnd, startedAt, finishedAt, cpuCount },
@@ -173,7 +192,7 @@ async function main() {
     console.log(
       String(r.n).padStart(4)
       + '  ' + String(r.wallClockMs).padStart(12)
-      + '  ' + r.slowdownFactor.toFixed(2).padStart(15)
+      + '  ' + (r.unmeasurable ? 'unmeasurable'.padStart(15) : r.slowdownFactor.toFixed(2).padStart(15))
       + '  ' + r.perRunCost.toFixed(1).padStart(11)
       + '  ' + String(r.failures).padStart(8)
       + '  ' + String(r.concurrencyHighWaterMark).padStart(23),
@@ -199,4 +218,7 @@ async function main() {
   }
 }
 
-main().catch((err) => fail(err && err.message ? err.message : String(err)));
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((err) => fail(err && err.message ? err.message : String(err)));
+}