@ngockhoale/ukit 3.0.8 → 3.0.9

package/scripts/bench/memory-bench.mjs

@@ -0,0 +1,661 @@
+#!/usr/bin/env node
+// TASK-003 — W3 memory benchmark runner (SPEC §5 FR-005/FR-006).
+//
+// Loads a generated corpus (TASK-001: records.json + manifest.json) into a
+// mkdtemp project store, runs each requested retrieval variant over every
+// manifest query, and emits report.json + report.md with env block,
+// correctness metrics, latency percentiles, disk footprint, and a 4×10
+// write-burst result.
+//
+// Isolation contract (FR-006, same as memory-baseline.mjs): every probe runs
+// with cwd/HOME pointed at the temp fixture — the repo's own .ukit/ and the
+// real HOME are never touched. Probe arguments are redacted to `<query-id>`;
+// record bodies and query text never reach the report.
+//
+// Variant adapter contract (SPEC §8, TASK-004):
+//   createVariant(name, {recordsPath, projectRoot})
+//     → {index(), query(text, {scope, projectId, limit}) → hits[],
+//        invalidate(generation), close()}
+// `--variant-module` defaults to scripts/bench/memory-ablation.mjs; a missing
+// module or missing createVariant marks non-inline variants `unsupported`.
+// The `lexical` variant is implemented inline (same eligible() policy + same
+// token-overlap scoring as src/core/memory/retrieval.js) so the runner is
+// usable before TASK-004 lands.
+//
+// Exit codes: 0 = ran to completion (verdicts are data; interrupted/failed
+// probes → {complete:false}), 1 = usage/fixture error, 2 = harness crash.
+
+import { execSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+import {
+  precisionAtK,
+  recallAtK,
+  scopeLeakRate,
+  falseAuthorityRate,
+  staleHitRate,
+  summarizeRuns,
+  footprintBytes,
+} from './memory-metrics.mjs';
+import { eligible, resolveEffectiveScope } from '../../src/core/memory/policy.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const NODE = process.execPath;
+const UKIT_BIN = path.join(REPO_ROOT, 'bin/ukit');
+const ROUTE_TASK = path.join(REPO_ROOT, 'template_project/.claude/ukit/index/route-task.mjs');
+const REINJECT = path.join(REPO_ROOT, 'template_project/.claude/ukit/runtime/reinject-context.mjs');
+const DEFAULT_VARIANT_MODULE = path.join(REPO_ROOT, 'scripts/bench/memory-ablation.mjs');
+
+const DEFAULT_RUNS = 9;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const BURST_PROCESSES = 4;
+const BURST_WRITES_PER_PROCESS = 10;
+const TOP_K = 5;
+const SEARCH_LIMIT = 10;
+const ALL_SURFACES = ['inproc', 'cli', 'route', 'reinject'];
+// The temp project is bound to proj-alpha — the project the corpus's
+// scope-boundary query is bound against (SPEC §7 boundProjectId).
+const BENCH_PROJECT_ID = 'proj-alpha';
+
+const USAGE = `Usage: node scripts/bench/memory-bench.mjs --fixture-root <dir> --out <file.json> [options]
+
+Runs the W3 memory benchmark (SPEC §5 FR-005) over a generated corpus and
+writes <file.json> plus a sibling .md report.
+
+Options:
+  --fixture-root <dir>    Corpus dir with records.json + manifest.json (required)
+  --out <file.json>       Report output path; <file>.md written beside it (required)
+  --variants <csv>        Variant names (default: lexical)
+  --variant-module <path> Adapter module exporting createVariant
+                          (default: scripts/bench/memory-ablation.mjs)
+  --surfaces <csv>        inproc,cli,route,reinject (default: inproc,cli)
+  --runs <n>              Latency repetitions per probe (default ${DEFAULT_RUNS})
+  --timeout <ms>          Per-probe timeout (default ${DEFAULT_TIMEOUT_MS})
+  --help                  Show this help
+
+Exit codes: 0 = completed (verdicts are data), 1 = usage/fixture error, 2 = crash.`;
+
+// ---------- small helpers ----------
+
+function parseArgs(argv) {
+  const opts = {
+    variants: ['lexical'],
+    surfaces: ['inproc', 'cli'],
+    variantModule: DEFAULT_VARIANT_MODULE,
+    runs: DEFAULT_RUNS,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  };
+  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 === '--fixture-root') opts.fixtureRoot = takeValue();
+    else if (arg === '--out') opts.out = takeValue();
+    else if (arg === '--variants') opts.variants = takeValue().split(',').map((s) => s.trim()).filter(Boolean);
+    else if (arg === '--surfaces') opts.surfaces = takeValue().split(',').map((s) => s.trim()).filter(Boolean);
+    else if (arg === '--variant-module') opts.variantModule = path.resolve(takeValue());
+    else if (arg === '--runs') opts.runs = Number(takeValue());
+    else if (arg === '--timeout') opts.timeoutMs = Number(takeValue());
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return opts;
+}
+
+/**
+ * Spawn one probe command. `redactArgs` lists argv indices replaced by
+ * `<query-id>` in the recorded cmd string so query text never reaches the
+ * report.
+ */
+function runCommand({ id, argv, cwd, env, stdin, timeoutMs, redactArgs = [] }) {
+  const redact = new Set(redactArgs);
+  const cmd = argv.map((a, i) => (redact.has(i) ? '<query-id>' : a)).join(' ');
+  return new Promise((resolve) => {
+    const started = Date.now();
+    let timedOut = false;
+    let spawnError = null;
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), {
+        cwd,
+        env: { ...process.env, ...env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      resolve({ id, cmd, exitCode: -1, durationMs: Date.now() - started, verdict: 'error', note: String(error?.message ?? error) });
+      return;
+    }
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+    child.stdout.resume();
+    child.stderr.resume();
+    child.on('error', (error) => { spawnError = error; });
+    if (stdin != null) child.stdin.write(stdin);
+    child.stdin.end();
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const durationMs = Date.now() - started;
+      let verdict;
+      if (timedOut || spawnError) verdict = 'error';
+      else verdict = code === 0 ? 'measured' : 'fail';
+      const entry = { id, cmd, exitCode: timedOut || code == null ? -1 : code, durationMs, verdict };
+      if (spawnError) entry.note = String(spawnError.message ?? spawnError);
+      resolve(entry);
+    });
+  });
+}
+
+// ---------- inline lexical variant (same semantics as retrieval.js) ----------
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',
+  'this', 'that', 'it', 'as', 'by', 'be', 'use', 'using', 'implement', 'fix', 'task',
+  'cần', 'và', 'là', 'cho', 'một', 'những', 'dùng',
+]);
+const RECORD_TYPE_WEIGHTS = Object.freeze({
+  project_rule: 7, derived_fact: 5, procedure: 5, episode: 3,
+});
+const LEGACY_SCOPE_MATCH = {
+  user: (record) => record.scope === 'user',
+  project: (record) => record.scope === 'repo' || record.scope === 'task',
+  session: (record) => record.type === 'episode' || record.scope === 'session',
+};
+
+function tokenize(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s./:_-]/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter((token) => token && !STOPWORDS.has(token) && token.length > 1);
+}
+
+function scoreRecord(record, queryTokens) {
+  const typeWeight = RECORD_TYPE_WEIGHTS[record.type] ?? 1;
+  if (queryTokens.length === 0) {
+    return typeWeight * Math.max(0.1, record.confidence ?? 1);
+  }
+  const recordTokens = new Set(tokenize(`${record.text ?? ''} ${record.provenance ?? ''}`));
+  let matched = 0;
+  for (const token of queryTokens) {
+    if (recordTokens.has(token)) matched += 1;
+  }
+  if (matched === 0) return 0;
+  const recencyBonus = record.created_at > 0 ? Math.min(1, record.created_at / Date.now()) : 0;
+  return typeWeight * matched * Math.max(0.1, record.confidence ?? 1) + recencyBonus;
+}
+
+function recordMatchesRequestedScope(record, scope) {
+  if (scope === 'all') return true;
+  const matcher = LEGACY_SCOPE_MATCH[scope];
+  return matcher ? matcher(record) : (record.scope === scope || record.type === scope);
+}
+
+function createInlineLexical({ recordsPath }) {
+  let records = [];
+  return {
+    name: 'lexical',
+    async index() {
+      const doc = JSON.parse(fs.readFileSync(recordsPath, 'utf8'));
+      records = Array.isArray(doc.records) ? doc.records : [];
+    },
+    async query(text, { scope = 'all', projectId = null, limit = SEARCH_LIMIT } = {}) {
+      const effective = resolveEffectiveScope({ projectId }, scope);
+      if (effective.denied) return [];
+      const ctx = { projectId: effective.projectId, includeUser: effective.includeUser };
+      const queryTokens = tokenize(text);
+      return records
+        .filter((record) => eligible(record, ctx).ok)
+        .filter((record) => recordMatchesRequestedScope(record, scope))
+        .map((record) => ({ record, score: scoreRecord(record, queryTokens) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score
+          || (b.record.created_at ?? 0) - (a.record.created_at ?? 0)
+          || String(b.record.text ?? '').localeCompare(String(a.record.text ?? '')))
+        .slice(0, limit)
+        .map(({ record }) => ({
+          id: record.id,
+          project_id: record.project_id,
+          status: record.status,
+          labels: Array.isArray(record.meta?.bench_label) ? record.meta.bench_label
+            : (record.meta?.bench_label ? [record.meta.bench_label] : []),
+        }));
+    },
+    async invalidate() {},
+    async close() {},
+  };
+}
+
+// ---------- fixture / env ----------
+
+function loadCorpus(fixtureRoot) {
+  const recordsPath = path.join(fixtureRoot, 'records.json');
+  const manifestPath = path.join(fixtureRoot, 'manifest.json');
+  if (!fs.existsSync(recordsPath)) throw new Error(`records.json not found: ${recordsPath}`);
+  if (!fs.existsSync(manifestPath)) throw new Error(`manifest.json not found: ${manifestPath}`);
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  if (!Array.isArray(manifest.queries)) throw new Error('manifest.json has no queries[] array');
+  return { recordsPath, manifest };
+}
+
+function envBlock() {
+  const env = {
+    sha: 'unknown', package: 'unknown', node: process.version,
+    os: process.platform, arch: process.arch, fs: 'local',
+  };
+  try {
+    env.sha = execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+  } catch { /* leave 'unknown' */ }
+  try {
+    env.package = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version ?? 'unknown';
+  } catch { /* leave 'unknown' */ }
+  return env;
+}
+
+/**
+ * Temp project store: <tmp>/project/.ukit/storage/memory/v2/records.json plus
+ * a minimal config; temp HOME registry binds the project root to
+ * BENCH_PROJECT_ID so the CLI surface resolves the same identity the inproc
+ * probes use.
+ */
+function seedTempStores(tmpRoot, recordsPath) {
+  const projectRoot = path.join(tmpRoot, 'project');
+  const v2Dir = path.join(projectRoot, '.ukit', 'storage', 'memory', 'v2');
+  fs.mkdirSync(v2Dir, { recursive: true });
+  fs.copyFileSync(recordsPath, path.join(v2Dir, 'records.json'));
+  fs.writeFileSync(path.join(projectRoot, '.ukit', 'storage', 'config.json'), '{}\n');
+
+  const home = path.join(tmpRoot, 'home');
+  const registryDir = path.join(home, '.ukit', 'storage', 'projects');
+  fs.mkdirSync(registryDir, { recursive: true });
+  const realRoot = fs.realpathSync(projectRoot);
+  const now = new Date().toISOString();
+  fs.writeFileSync(path.join(registryDir, 'registry.json'), `${JSON.stringify({
+    schemaVersion: 1,
+    projects: {
+      [BENCH_PROJECT_ID]: {
+        roots: [realRoot], gitCommonDirs: [], aliases: [], createdAt: now, updatedAt: now,
+      },
+    },
+    aliasIndex: {},
+  }, null, 2)}\n`);
+
+  // User-level store for the write burst (memory --user add).
+  const userV2 = path.join(home, '.ukit', 'storage', 'memory', 'v2');
+  fs.mkdirSync(userV2, { recursive: true });
+  fs.writeFileSync(path.join(userV2, 'records.json'),
+    '{"schemaVersion":2,"generation":1,"tombstones":[],"records":[]}\n');
+
+  return { projectRoot, home };
+}
+
+// ---------- variant loading ----------
+
+async function loadVariantFactory(opts, report) {
+  let createVariant = null;
+  try {
+    const mod = await import(pathToFileURL(opts.variantModule).href);
+    if (typeof mod.createVariant === 'function') createVariant = mod.createVariant;
+  } catch (error) {
+    report.verdicts.push({
+      id: 'variant-module', verdict: 'unsupported',
+      note: `variant module unavailable: ${error?.message ?? error}`,
+    });
+  }
+  return (name, args) => {
+    if (name === 'lexical' && createVariant === null) return createInlineLexical(args);
+    if (createVariant === null) {
+      const err = new Error(`variant '${name}' unsupported: no adapter module`);
+      err.unsupported = true;
+      throw err;
+    }
+    return createVariant(name, args);
+  };
+}
+
+// ---------- probes ----------
+
+function meanDefined(values) {
+  const nums = values.filter((v) => typeof v === 'number' && Number.isFinite(v));
+  if (nums.length === 0) return 'UNKNOWN';
+  return nums.reduce((a, b) => a + b, 0) / nums.length;
+}
+
+async function measureVariant(ctx, name) {
+  const { queries, recordsPath, projectRoot, runs } = ctx;
+  const entry = {
+    correctness: {
+      precisionAt5: 'UNKNOWN', recallAt5: 'UNKNOWN', scopeLeakRate: 'UNKNOWN',
+      falseAuthorityRate: 'UNKNOWN', staleHitRate: 'UNKNOWN',
+    },
+    latency: { n: 0, p50: 'UNKNOWN', p95: 'UNKNOWN', p99: 'UNKNOWN' },
+    footprintBytes: 'UNKNOWN',
+    notes: [],
+    verdict: 'measured',
+  };
+
+  let variant;
+  try {
+    variant = await ctx.makeVariant(name, { recordsPath, projectRoot });
+    await variant.index();
+  } catch (error) {
+    entry.verdict = error?.unsupported ? 'unsupported' : 'error';
+    entry.notes.push(String(error?.message ?? error));
+    ctx.report.verdicts.push({ id: `variant:${name}`, verdict: entry.verdict, note: entry.notes[0] });
+    return entry;
+  }
+
+  try {
+    const allHits = [];
+    const p5 = [];
+    const r5 = [];
+    const durations = [];
+    for (const q of queries) {
+      const scope = q.scope ?? 'all';
+      const projectId = q.boundProjectId ?? BENCH_PROJECT_ID;
+      let hits;
+      try {
+        hits = await variant.query(q.text, { scope, projectId, limit: SEARCH_LIMIT });
+      } catch (error) {
+        entry.verdict = 'error';
+        entry.notes.push(`${q.id}: ${error?.message ?? error}`);
+        ctx.report.verdicts.push({ id: `query:${q.id}`, verdict: 'error', note: String(error?.message ?? error) });
+        continue;
+      }
+      hits = Array.isArray(hits) ? hits : [];
+      allHits.push(...hits);
+      const rankedIds = hits.map((h) => h.id);
+      p5.push(precisionAtK(rankedIds, q.relevantIds, TOP_K));
+      r5.push(recallAtK(rankedIds, q.relevantIds, TOP_K));
+      for (let run = 0; run < runs; run += 1) {
+        const started = performance.now();
+        await variant.query(q.text, { scope, projectId, limit: SEARCH_LIMIT });
+        durations.push(performance.now() - started);
+      }
+      ctx.report.verdicts.push({ id: `query:${q.id}`, variant: name, verdict: 'measured', hits: hits.length });
+    }
+    entry.correctness.precisionAt5 = meanDefined(p5);
+    entry.correctness.recallAt5 = meanDefined(r5);
+    entry.correctness.scopeLeakRate = scopeLeakRate(allHits, BENCH_PROJECT_ID);
+    entry.correctness.falseAuthorityRate = falseAuthorityRate(allHits);
+    entry.correctness.staleHitRate = staleHitRate(allHits, ctx.manifest);
+    entry.latency = summarizeRuns(durations);
+    entry.footprintBytes = await footprintBytes(path.join(projectRoot, '.ukit'));
+  } finally {
+    try { await variant.close?.(); } catch { /* close errors are not data */ }
+  }
+  return entry;
+}
+
+async function probeCliSurface(ctx) {
+  const { queries, projectRoot, home, runs, timeoutMs } = ctx;
+  const cold = [];
+  const warm = [];
+  for (const q of queries) {
+    for (let run = 0; run < runs; run += 1) {
+      const entry = await runCommand({
+        id: `cli-search:${q.id}`,
+        argv: [NODE, UKIT_BIN, 'memory', 'search', q.text],
+        cwd: projectRoot,
+        env: { HOME: home, UKIT_CLI_DEADLINE_MS: String(Math.min(timeoutMs, 25_000)) },
+        timeoutMs,
+        redactArgs: [4],
+      });
+      ctx.report.verdicts.push({ ...entry, surface: 'cli' });
+      if (entry.verdict === 'measured') (run === 0 ? cold : warm).push(entry.durationMs);
+    }
+  }
+  return { cold: summarizeRuns(cold), warm: summarizeRuns(warm) };
+}
+
+async function probeRouteSurface(ctx) {
+  const { queries, projectRoot, home, timeoutMs } = ctx;
+  for (const q of queries) {
+    const entry = await runCommand({
+      id: `route:${q.id}`,
+      argv: [NODE, ROUTE_TASK, q.text, '--root', projectRoot],
+      cwd: ctx.tmpRoot,
+      env: { HOME: home },
+      timeoutMs,
+      redactArgs: [2],
+    });
+    ctx.report.verdicts.push({ ...entry, surface: 'route' });
+  }
+}
+
+async function probeReinjectSurface(ctx) {
+  const { projectRoot, home, timeoutMs } = ctx;
+  const entry = await runCommand({
+    id: 'reinject-context',
+    argv: [NODE, REINJECT],
+    cwd: ctx.tmpRoot,
+    env: { HOME: home, CLAUDE_PROJECT_DIR: projectRoot },
+    stdin: JSON.stringify({ session_id: 'bench' }),
+    timeoutMs,
+  });
+  ctx.report.verdicts.push({ ...entry, surface: 'reinject' });
+}
+
+async function probeWriteBurst(ctx) {
+  const { home, timeoutMs } = ctx;
+  const expected = BURST_PROCESSES * BURST_WRITES_PER_PROCESS;
+  const started = Date.now();
+  let spawnFailures = 0;
+  const lanes = [];
+  for (let lane = 0; lane < BURST_PROCESSES; lane += 1) {
+    lanes.push((async () => {
+      for (let w = 0; w < BURST_WRITES_PER_PROCESS; w += 1) {
+        const marker = `burst-${lane}-${w}`;
+        const entry = await runCommand({
+          id: 'write-burst',
+          argv: [NODE, UKIT_BIN, 'memory', '--user', 'add', '--type', 'derived_fact', marker],
+          cwd: ctx.tmpRoot,
+          env: { HOME: home, UKIT_CLI_DEADLINE_MS: '25000' },
+          timeoutMs,
+          redactArgs: [7],
+        });
+        if (entry.verdict !== 'measured') spawnFailures += 1;
+      }
+    })());
+  }
+  await Promise.all(lanes);
+  const durationMs = Date.now() - started;
+
+  let persisted = 0;
+  let parseOk = true;
+  try {
+    const doc = JSON.parse(fs.readFileSync(
+      path.join(home, '.ukit', 'storage', 'memory', 'v2', 'records.json'), 'utf8'));
+    persisted = (doc.records ?? [])
+      .filter((r) => typeof r.text === 'string' && r.text.startsWith('burst-')).length;
+  } catch {
+    parseOk = false;
+  }
+  const lostUpdates = Math.max(0, expected - persisted);
+  const verdict = !parseOk || spawnFailures === expected
+    ? 'error'
+    : lostUpdates > 0 ? 'reproduced' : 'not-reproduced';
+  ctx.report.verdicts.push({
+    id: 'write-burst',
+    cmd: `${NODE} bin/ukit memory --user add <query-id> ×${expected} (${BURST_PROCESSES}×${BURST_WRITES_PER_PROCESS})`,
+    exitCode: spawnFailures === 0 ? 0 : 1,
+    durationMs,
+    verdict,
+  });
+  return { expected, persisted, lostUpdates, spawnFailures, verdict };
+}
+
+// ---------- report ----------
+
+function renderMarkdown(report) {
+  const lines = [];
+  lines.push('# Memory bench report');
+  lines.push('');
+  lines.push('## Env');
+  lines.push('');
+  lines.push(`- sha: \`${report.env.sha}\` · package: \`${report.env.package}\``);
+  lines.push(`- node: \`${report.env.node}\` · os: \`${report.env.os}\` · arch: \`${report.env.arch}\` · fs: \`${report.env.fs}\``);
+  lines.push(`- corpus: tier=\`${report.corpus.tier}\` seed=\`${report.corpus.seed}\` records=${report.corpus.recordCount}`);
+  lines.push(`- complete: **${report.complete}**`);
+  lines.push('');
+  lines.push('## Variants');
+  lines.push('');
+  lines.push('| variant | verdict | p@5 | r@5 | scopeLeak | falseAuth | stale | p50 | p95 | p99 | footprint |');
+  lines.push('|---------|---------|-----|-----|-----------|-----------|-------|-----|-----|-----|-----------|');
+  for (const [name, v] of Object.entries(report.variants)) {
+    const c = v.correctness ?? {};
+    const l = v.latency ?? {};
+    const fmt = (x) => (typeof x === 'number' ? x.toFixed(3) : (x ?? 'n/a'));
+    lines.push(`| ${name} | ${v.verdict} | ${fmt(c.precisionAt5)} | ${fmt(c.recallAt5)} `
+      + `| ${fmt(c.scopeLeakRate)} | ${fmt(c.falseAuthorityRate)} | ${fmt(c.staleHitRate)} `
+      + `| ${fmt(l.p50)} | ${fmt(l.p95)} | ${fmt(l.p99)} | ${v.footprintBytes} |`);
+  }
+  lines.push('');
+  if (report.surfaces?.cli) {
+    lines.push('## CLI surface (ms)');
+    lines.push('');
+    lines.push('| probe | n | p50 | p95 | p99 |');
+    lines.push('|-------|---|-----|-----|-----|');
+    for (const [id, s] of Object.entries(report.surfaces.cli)) {
+      lines.push(`| cli-${id} | ${s.n} | ${s.p50} | ${s.p95} | ${s.p99} |`);
+    }
+    lines.push('');
+  }
+  lines.push('## Write burst');
+  lines.push('');
+  const wb = report.writeBurst;
+  lines.push(`- expected: ${wb.expected} · persisted: ${wb.persisted} · lostUpdates: ${wb.lostUpdates}`);
+  lines.push(`- verdict: **${wb.verdict ?? 'n/a'}**`);
+  lines.push('');
+  lines.push('## Verdicts');
+  lines.push('');
+  for (const v of report.verdicts) {
+    lines.push(`- ${v.id}${v.variant ? ` (${v.variant})` : ''}: ${v.verdict}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ---------- main ----------
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`[memory-bench] ${error.message}\n\n${USAGE}`);
+    process.exit(1);
+  }
+  if (opts.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (!opts.fixtureRoot || !opts.out) {
+    console.error(`[memory-bench] --fixture-root and --out are required.\n\n${USAGE}`);
+    process.exit(1);
+  }
+  if (!Number.isFinite(opts.runs) || opts.runs < 1) {
+    console.error('[memory-bench] --runs must be a positive integer.');
+    process.exit(1);
+  }
+  const badSurface = opts.surfaces.find((s) => !ALL_SURFACES.includes(s));
+  if (badSurface) {
+    console.error(`[memory-bench] unknown surface: ${badSurface} (expected ${ALL_SURFACES.join(',')})`);
+    process.exit(1);
+  }
+
+  const fixtureRoot = path.resolve(opts.fixtureRoot);
+  if (!fs.existsSync(fixtureRoot)) {
+    console.error(`[memory-bench] fixture root not found: ${fixtureRoot}`);
+    process.exit(1);
+  }
+  let corpus;
+  try {
+    corpus = loadCorpus(fixtureRoot);
+  } catch (error) {
+    console.error(`[memory-bench] fixture error: ${error.message}`);
+    process.exit(1);
+  }
+
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ukit-bench-'));
+  const { projectRoot, home } = seedTempStores(tmpRoot, corpus.recordsPath);
+
+  const report = {
+    schemaVersion: 1,
+    complete: true,
+    env: envBlock(),
+    corpus: {
+      seed: corpus.manifest.seed ?? 'UNKNOWN',
+      tier: corpus.manifest.tier ?? 'UNKNOWN',
+      recordCount: corpus.manifest.recordCount ?? 'UNKNOWN',
+    },
+    variants: {},
+    surfaces: {},
+    writeBurst: {
+      expected: BURST_PROCESSES * BURST_WRITES_PER_PROCESS,
+      persisted: 0, lostUpdates: 0, verdict: 'skipped',
+    },
+    verdicts: [],
+  };
+
+  const ctx = {
+    manifest: corpus.manifest,
+    queries: corpus.manifest.queries,
+    recordsPath: path.join(projectRoot, '.ukit', 'storage', 'memory', 'v2', 'records.json'),
+    projectRoot,
+    home,
+    tmpRoot,
+    runs: opts.runs,
+    timeoutMs: opts.timeoutMs,
+    report,
+  };
+
+  ctx.makeVariant = await loadVariantFactory(opts, report);
+
+  for (const name of opts.variants) {
+    report.variants[name] = await measureVariant(ctx, name);
+    const v = report.variants[name];
+    console.log(`[memory-bench] ${name}: p@5=${v.correctness?.precisionAt5} `
+      + `p95=${v.latency?.p95} verdict=${v.verdict}`);
+  }
+
+  if (opts.surfaces.includes('cli')) {
+    report.surfaces.cli = await probeCliSurface(ctx);
+  }
+  if (opts.surfaces.includes('route')) {
+    await probeRouteSurface(ctx);
+  }
+  if (opts.surfaces.includes('reinject')) {
+    await probeReinjectSurface(ctx);
+  }
+  report.writeBurst = await probeWriteBurst(ctx);
+
+  if (report.verdicts.some((v) => v.verdict === 'error' || v.verdict === 'fail')) {
+    report.complete = false;
+  }
+
+  const outPath = path.resolve(opts.out);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`);
+  const mdPath = outPath.replace(/\.json$/i, '') + '.md';
+  fs.writeFileSync(mdPath, renderMarkdown(report));
+
+  console.log(`[memory-bench] report written: ${outPath}`);
+  console.log(`[memory-bench] markdown:       ${mdPath}`);
+  console.log(`[memory-bench] complete=${report.complete} writeBurst=${report.writeBurst.verdict}`);
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error(`[memory-bench] harness crash: ${error?.stack ?? error}`);
+  process.exit(2);
+});