@ngockhoale/ukit 3.0.8 → 3.0.10

package/scripts/bench/recorder-overhead.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// recorder-overhead.mjs (TASK-001, SPEC §2 G2-FR03) — paired baseline vs
+// instrumented overhead measurement for the observer seam. REAL measurement
+// on this host; no fabricated targets.
+//
+// Workload: hook-telemetry-shaped events derived deterministically from the
+// seeded corpus (tests/fixtures/observability/corpus.json, seed=42) — one
+// event per corpus record, timings taken from the record's own duration so
+// the fixture stays the single source of truth.
+//
+//   baseline arm:     appendFileSync(JSON.stringify(row)) to a jsonl file —
+//                     the status-quo owner write path (hook-telemetry append).
+//   instrumented arm: adaptHookTelemetryEvent(row) → recorder.emit() → flush()
+//                     per event into a real temp segment store — the seam a
+//                     hook would run inside its deadline.
+//
+// Both arms repeat the same event corpus --reps times, interleaved per rep
+// (baseline pass, then instrumented pass) so drift hits both arms equally.
+//
+//   node scripts/bench/recorder-overhead.mjs [--json] [--reps N]
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { adaptHookTelemetryEvent } from '../../src/core/observability/adapters/hookTelemetryAdapter.js';
+import { createAdapterContext } from '../../src/core/observability/adapters/common.js';
+import { createRecorder } from '../../src/core/observability/emit/recorder.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const corpusPath = path.join(repoRoot, 'tests/fixtures/observability/corpus.json');
+
+const args = process.argv.slice(2);
+const json = args.includes('--json');
+const repsFlag = args.indexOf('--reps');
+const REPS = repsFlag !== -1 ? Number.parseInt(args[repsFlag + 1], 10) : 30;
+if (!Number.isInteger(REPS) || REPS <= 0) {
+  console.error('--reps must be a positive integer');
+  process.exit(2);
+}
+
+function percentile(sorted, p) {
+  if (sorted.length === 0) return null;
+  const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.max(0, idx)];
+}
+
+function stats(samples) {
+  const sorted = [...samples].sort((a, b) => a - b);
+  const n = sorted.length;
+  const mean = n ? sorted.reduce((s, v) => s + v, 0) / n : 0;
+  const variance = n ? sorted.reduce((s, v) => s + (v - mean) ** 2, 0) / n : 0;
+  return {
+    n,
+    min: n ? sorted[0] : null,
+    max: n ? sorted[n - 1] : null,
+    mean: Number(mean.toFixed(4)),
+    stdev: Number(Math.sqrt(variance).toFixed(4)),
+    p50: percentile(sorted, 50),
+    p95: percentile(sorted, 95),
+    p99: percentile(sorted, 99),
+  };
+}
+
+function dirBytes(dir) {
+  let total = 0;
+  if (!fs.existsSync(dir)) return 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) total += dirBytes(p);
+    else total += fs.statSync(p).size;
+  }
+  return total;
+}
+
+function gitRevision() {
+  try {
+    return execSync('git rev-parse --short HEAD', { cwd: repoRoot, encoding: 'utf8' }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+// --- workload: corpus records → hook-telemetry-shaped rows ------------------
+let corpus;
+let sourceRecords;
+try {
+  corpus = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+  sourceRecords = corpus.traces.flatMap((t) => t.records);
+} catch {
+  console.error(
+    `recorder-overhead: cannot load ${corpusPath} — run 'node scripts/bench/data-foundation.mjs --fixture' first`,
+  );
+  process.exit(1);
+}
+const events = sourceRecords.map((r, i) => ({
+  v: 1,
+  ts: Date.parse(r.wall_time_utc),
+  hookEvent: 'PostToolUse',
+  toolName: typeof r.payload?.tool_name === 'string' ? r.payload.tool_name : 'BenchTool',
+  toolUseId: `bench-${r.record_id ?? i}`,
+  hook: 'post-tool-use/bench-hook',
+  elapsedMs: Number.isFinite(r.payload?.duration_ms) ? r.payload.duration_ms : (i % 53),
+  outcome: 'ok',
+  ...(i % 3 === 0 ? { stageMs: i % 7 } : {}),
+}));
+
+const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ukit-bench-'));
+const baselineFile = path.join(tmpRoot, 'baseline.jsonl');
+const segmentRoot = path.join(tmpRoot, 'segments');
+
+const baselineMs = [];
+const emitMs = [];
+const flushMs = [];
+
+const heapBefore = process.memoryUsage().heapUsed;
+let recordsWritten = 0;
+let recordsEmitted = 0;
+let lastHealth = null;
+const wallStart = Date.now();
+
+const recorder = createRecorder({
+  root: segmentRoot,
+  config: { observability: { stage: 'default' } },
+});
+
+try {
+  for (let rep = 0; rep < REPS; rep += 1) {
+    // baseline arm — status-quo owner append path
+    for (const event of events) {
+      const line = JSON.stringify(event) + '\n';
+      const t0 = process.hrtime.bigint();
+      fs.appendFileSync(baselineFile, line);
+      baselineMs.push(Number(process.hrtime.bigint() - t0) / 1e6);
+    }
+    // instrumented arm — adapt → emit → flush per event (hook-deadline seam)
+    const ctx = createAdapterContext({ writerId: 'adapter-hook-bench' });
+    for (const event of events) {
+      const t0 = process.hrtime.bigint();
+      const record = adaptHookTelemetryEvent(event, ctx);
+      if (record) recorder.emit(record);
+      emitMs.push(Number(process.hrtime.bigint() - t0) / 1e6);
+
+      const f0 = process.hrtime.bigint();
+      await recorder.flush({ deadlineMs: 100 });
+      flushMs.push(Number(process.hrtime.bigint() - f0) / 1e6);
+    }
+    const h = recorder.health();
+    lastHealth = h;
+    recordsEmitted += events.length;
+  }
+} finally {
+  const heapAfter = process.memoryUsage().heapUsed;
+  const segmentBytes = dirBytes(segmentRoot);
+  recordsWritten = lastHealth ? lastHealth.written : 0;
+
+  const report = {
+    bench: 'recorder-overhead',
+    host: {
+      platform: os.platform(),
+      arch: os.arch(),
+      release: os.release(),
+      cpu: os.cpus()?.[0]?.model ?? 'unknown',
+      node: process.version,
+    },
+    revision: gitRevision(),
+    measured_at: new Date().toISOString(),
+    workload: {
+      corpus: path.relative(repoRoot, corpusPath),
+      seed: corpus.seed,
+      events_per_rep: events.length,
+      reps: REPS,
+    },
+    reps: REPS,
+    baseline: stats(baselineMs),
+    emit: stats(emitMs),
+    flush: stats(flushMs),
+    bytesPerRecord: recordsWritten > 0 ? Math.round(segmentBytes / recordsWritten) : null,
+    heapDeltaBytes: heapAfter - heapBefore,
+    wall_clock_ms: Date.now() - wallStart,
+    instrumented: {
+      events: recordsEmitted,
+      recordsWritten,
+      segmentBytes,
+      health: lastHealth,
+    },
+    baselineBytes: fs.existsSync(baselineFile) ? fs.statSync(baselineFile).size : 0,
+  };
+
+  if (json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  } else {
+    const f = (v) => (v === null ? 'null' : v.toFixed(3));
+    console.log(`reps=${report.reps} events/rep=${events.length} node=${report.host.node} rev=${report.revision}`);
+    console.log(`baseline append ms  p50=${f(report.baseline.p50)} p95=${f(report.baseline.p95)} p99=${f(report.baseline.p99)}`);
+    console.log(`instrumented emit ms p50=${f(report.emit.p50)} p95=${f(report.emit.p95)} p99=${f(report.emit.p99)} stdev=${report.emit.stdev}`);
+    console.log(`instrumented flush ms p50=${f(report.flush.p50)} p95=${f(report.flush.p95)} p99=${f(report.flush.p99)}`);
+    console.log(`bytes/record=${report.bytesPerRecord} heapDelta=${report.heapDeltaBytes}B written=${recordsWritten}`);
+  }
+
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+}

package/scripts/bench/sqlite-spike.mjs

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+// TASK-005 — SQLite viability spike (SPEC §5 FR-009/FR-010, M03-03).
+//
+// Prototype-only probe matrix answering the runtime/packaging questions for
+// gate G3: node:sqlite availability across Node >=20 (20.x needs
+// --experimental-sqlite; >=22.5 is unflagged), WAL behavior, busy-timeout
+// under a second writer, concurrent-writer burst, backup(), schema migration
+// roundtrip, file footprint vs JSON, license. Every cell gets an explicit
+// verdict `tested|unsupported|failed` + detail string — verdicts are data.
+//
+// Isolation (FR-010): writes only under a mkdtemp dir or an explicit
+// --wal-dir target; never touches repo stores or package.json. Temp dirs are
+// cleaned up; files created inside --wal-dir are prefixed `ukit-spike-` and
+// removed after the run.
+//
+// Exit codes: 0 = ran to completion (verdicts are data), 1 = usage error,
+// 2 = harness crash.
+//
+// Test hook: UKIT_SPIKE_SQLITE_IMPORT=fail forces the node:sqlite import to
+// fail so the unsupported path is exercisable on Node >=22.5.
+
+import { execSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const NODE = process.execPath;
+const SPIKE_PREFIX = 'ukit-spike-';
+const BURST_PROCESSES = 2;
+const BURST_ROWS_PER_PROCESS = 25;
+const FOOTPRINT_ROWS = 500;
+
+const ALL_CELLS = [
+  'node-sqlite-availability',
+  'open-create',
+  'wal-mode',
+  'busy-timeout',
+  'concurrent-writers',
+  'backup',
+  'migration-roundtrip',
+  'footprint',
+  'license',
+];
+
+const USAGE = `Usage: node scripts/bench/sqlite-spike.mjs --out <file.json> [--wal-dir <dir>]
+
+Options:
+  --out <file.json>   Report output path; <file>.md is written beside it (required)
+  --wal-dir <dir>     Target dir for the WAL/busy-timeout probes (default: mkdtemp
+                      local dir). Point at a network-FS mount to probe WAL there.
+
+Exit codes: 0 = completed (verdicts are data), 1 = usage error, 2 = crash.`;
+
+// ---------- small helpers ----------
+
+function parseArgs(argv) {
+  const opts = { out: null, walDir: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--out') { opts.out = argv[++i]; }
+    else if (arg === '--wal-dir') { opts.walDir = argv[++i]; }
+    else if (arg === '--help' || arg === '-h') { console.log(USAGE); process.exit(0); }
+    else { throw new Error(`unknown argument: ${arg}\n${USAGE}`); }
+  }
+  if (!opts.out) throw new Error(`--out is required\n${USAGE}`);
+  return opts;
+}
+
+function cell(verdict, detail) {
+  return { verdict, detail: String(detail) };
+}
+
+function spawnNode(argv, { timeoutMs = 30_000 } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(NODE, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      resolve({ exitCode: null, signal: 'SIGKILL', stdout, stderr, timedOut: true });
+    }, timeoutMs);
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      resolve({ exitCode: null, signal: null, stdout, stderr: stderr + String(error), timedOut: false });
+    });
+    child.on('close', (exitCode, signal) => {
+      clearTimeout(timer);
+      resolve({ exitCode, signal, stdout, stderr, timedOut: false });
+    });
+  });
+}
+
+/** Child helper source: open db, BEGIN EXCLUSIVE, print 'locked', hold, commit. */
+const LOCK_HOLDER_SOURCE = `
+import('node:sqlite').then(({ DatabaseSync }) => {
+  const db = new DatabaseSync(process.argv[1]);
+  db.exec('CREATE TABLE IF NOT EXISTS spike_lock (id INTEGER PRIMARY KEY, v TEXT)');
+  db.exec('BEGIN EXCLUSIVE');
+  process.stdout.write('locked\\n');
+  setTimeout(() => { db.exec('COMMIT'); db.close(); process.exit(0); }, 1500);
+}).catch((e) => { process.stderr.write(String(e)); process.exit(1); });
+`;
+
+/** Child helper source: insert N rows with busy_timeout, print inserted count. */
+const BURST_WRITER_SOURCE = `
+import('node:sqlite').then(({ DatabaseSync }) => {
+  const [dbPath, tag, n] = [process.argv[1], process.argv[2], Number(process.argv[3])];
+  const db = new DatabaseSync(dbPath);
+  db.exec('PRAGMA busy_timeout = 10000');
+  const ins = db.prepare('INSERT INTO spike_burst (writer, seq) VALUES (?, ?)');
+  for (let i = 0; i < n; i += 1) ins.run(tag, i);
+  db.close();
+  process.stdout.write(String(n));
+  process.exit(0);
+}).catch((e) => { process.stderr.write(String(e)); process.exit(1); });
+`;
+
+// ---------- probes ----------
+
+async function probeAvailability() {
+  const major = Number(process.versions.node.split('.')[0]);
+  const minor = Number(process.versions.node.split('.')[1]);
+  const flagNote = major === 20
+    ? 'Node 20.x requires --experimental-sqlite'
+    : (major === 22 && minor < 5)
+      ? 'node:sqlite lands in Node 22.5; earlier 22.x unavailable'
+      : 'unflagged on this Node';
+  if (process.env.UKIT_SPIKE_SQLITE_IMPORT === 'fail') {
+    return cell('unsupported', `node:sqlite import failed (injected); ${flagNote}`);
+  }
+  try {
+    const mod = await import('node:sqlite');
+    if (typeof mod.DatabaseSync !== 'function') {
+      return cell('unsupported', `node:sqlite imported but DatabaseSync missing; ${flagNote}`);
+    }
+    const warned = major < 22 || (major === 22 && minor < 5)
+      ? 'experimental flag required'
+      : 'experimental-warning emitted on stderr (still experimental)';
+    return cell('tested', `node ${process.version}: DatabaseSync present; ${flagNote}; ${warned}`);
+  } catch (error) {
+    return cell('unsupported', `node:sqlite import failed: ${error?.message ?? error}; ${flagNote}`);
+  }
+}
+
+async function withDb(dir, name, fn) {
+  const { DatabaseSync } = await import('node:sqlite');
+  const dbPath = path.join(dir, `${SPIKE_PREFIX}${name}.db`);
+  const db = new DatabaseSync(dbPath);
+  try {
+    return await fn(db, dbPath);
+  } finally {
+    try { db.close(); } catch { /* already closed */ }
+  }
+}
+
+async function probeOpenCreate(dir) {
+  try {
+    return await withDb(dir, 'open', async (db, dbPath) => {
+      db.exec('CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)');
+      db.prepare('INSERT INTO t (v) VALUES (?)').run('x');
+      const row = db.prepare('SELECT COUNT(*) AS n FROM t').get();
+      const bytes = fs.statSync(dbPath).size;
+      return cell('tested', `open+create+insert ok; rows=${row.n}; fileBytes=${bytes}`);
+    });
+  } catch (error) {
+    return cell('failed', `open-create threw: ${error?.message ?? error}`);
+  }
+}
+
+async function probeWalMode(dir) {
+  try {
+    return await withDb(dir, 'wal', async (db, dbPath) => {
+      const mode = db.prepare('PRAGMA journal_mode = WAL').get()?.journal_mode;
+      db.exec('CREATE TABLE t (id INTEGER PRIMARY KEY)');
+      db.prepare('INSERT INTO t DEFAULT VALUES').run();
+      const walExists = fs.existsSync(`${dbPath}-wal`) || mode === 'wal';
+      if (mode !== 'wal') {
+        return cell('failed', `journal_mode=${mode} (expected wal); dir=${path.basename(dir)}`);
+      }
+      return cell('tested', `journal_mode=wal verified; walFileObserved=${walExists}`);
+    });
+  } catch (error) {
+    return cell('failed', `wal-mode threw: ${error?.message ?? error}`);
+  }
+}
+
+async function probeBusyTimeout(dir) {
+  try {
+    const dbPath = path.join(dir, `${SPIKE_PREFIX}busy.db`);
+    const holder = spawn(NODE, ['--input-type=module', '-e', LOCK_HOLDER_SOURCE, dbPath],
+      { stdio: ['ignore', 'pipe', 'pipe'] });
+    let locked = false;
+    await new Promise((resolve) => {
+      const timer = setTimeout(resolve, 10_000);
+      holder.stdout.on('data', (d) => {
+        if (String(d).includes('locked')) { locked = true; clearTimeout(timer); resolve(); }
+      });
+      holder.on('exit', () => { clearTimeout(timer); resolve(); });
+    });
+    if (!locked) {
+      holder.kill('SIGKILL');
+      return cell('failed', 'lock-holder child never acquired the write lock');
+    }
+    const { DatabaseSync } = await import('node:sqlite');
+    const db = new DatabaseSync(dbPath);
+    try {
+      db.exec('PRAGMA busy_timeout = 5000');
+      const started = Date.now();
+      db.exec('INSERT INTO spike_lock (v) VALUES (\'waited\')');
+      const waitedMs = Date.now() - started;
+      const row = db.prepare('SELECT COUNT(*) AS n FROM spike_lock').get();
+      await new Promise((resolve) => holder.on('close', resolve));
+      return cell('tested', `busy_timeout=5000 waited ${waitedMs}ms for second writer; rows=${row.n}`);
+    } finally {
+      try { db.close(); } catch { /* noop */ }
+    }
+  } catch (error) {
+    return cell('failed', `busy-timeout threw: ${error?.message ?? error}`);
+  }
+}
+
+async function probeConcurrentWriters(dir) {
+  try {
+    const dbPath = path.join(dir, `${SPIKE_PREFIX}burst.db`);
+    // Parent creates the schema + WAL first: concurrent CREATE TABLE /
+    // journal_mode changes are not covered by busy_timeout and race.
+    {
+      const { DatabaseSync } = await import('node:sqlite');
+      const setup = new DatabaseSync(dbPath);
+      setup.exec('PRAGMA journal_mode = WAL');
+      setup.exec('CREATE TABLE IF NOT EXISTS spike_burst (id INTEGER PRIMARY KEY, writer TEXT, seq INTEGER)');
+      setup.close();
+    }
+    const expected = BURST_PROCESSES * BURST_ROWS_PER_PROCESS;
+    const runs = [];
+    for (let i = 0; i < BURST_PROCESSES; i += 1) {
+      runs.push(spawnNode(
+        ['--input-type=module', '-e', BURST_WRITER_SOURCE, dbPath, `w${i}`, String(BURST_ROWS_PER_PROCESS)],
+        { timeoutMs: 30_000 },
+      ));
+    }
+    const results = await Promise.all(runs);
+    const spawnFailures = results.filter((r) => r.exitCode !== 0).length;
+    const { DatabaseSync } = await import('node:sqlite');
+    const db = new DatabaseSync(dbPath);
+    let persisted = 0;
+    try {
+      persisted = db.prepare('SELECT COUNT(*) AS n FROM spike_burst').get().n;
+    } finally {
+      db.close();
+    }
+    const lost = expected - persisted;
+    if (spawnFailures > 0) {
+      const err = results.find((r) => r.exitCode !== 0)?.stderr?.trim() ?? 'unknown';
+      return cell('failed', `${spawnFailures}/${BURST_PROCESSES} writer processes failed: ${err}; persisted=${persisted}/${expected}`);
+    }
+    if (lost !== 0) {
+      return cell('failed', `lost updates: persisted=${persisted}/${expected} lost=${lost}`);
+    }
+    return cell('tested', `${BURST_PROCESSES} processes x ${BURST_ROWS_PER_PROCESS} inserts; persisted=${persisted}/${expected}; lost=0`);
+  } catch (error) {
+    return cell('failed', `concurrent-writers threw: ${error?.message ?? error}`);
+  }
+}
+
+async function probeBackup(dir) {
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    const srcPath = path.join(dir, `${SPIKE_PREFIX}backup-src.db`);
+    const dstPath = path.join(dir, `${SPIKE_PREFIX}backup-dst.db`);
+    const src = new DatabaseSync(srcPath);
+    src.exec('CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)');
+    const ins = src.prepare('INSERT INTO t (v) VALUES (?)');
+    for (let i = 0; i < 10; i += 1) ins.run(`row-${i}`);
+    if (typeof src.backup !== 'function') {
+      src.close();
+      return cell('unsupported', 'DatabaseSync.backup() not present on this Node');
+    }
+    await src.backup(dstPath);
+    src.close();
+    const dst = new DatabaseSync(dstPath);
+    const row = dst.prepare('SELECT COUNT(*) AS n FROM t').get();
+    dst.close();
+    if (row.n !== 10) return cell('failed', `backup copy row-count=${row.n} (expected 10)`);
+    return cell('tested', `backup() snapshot reopened; row-count=${row.n} equal`);
+  } catch (error) {
+    return cell('failed', `backup threw: ${error?.message ?? error}`);
+  }
+}
+
+async function probeMigration(dir) {
+  try {
+    return await withDb(dir, 'migrate', async (db) => {
+      db.exec('CREATE TABLE m (id INTEGER PRIMARY KEY, a TEXT)');
+      db.prepare('INSERT INTO m (a) VALUES (?)').run('before');
+      db.exec('ALTER TABLE m ADD COLUMN b TEXT DEFAULT \'d\'');
+      db.prepare('UPDATE m SET b = ? WHERE id = 1').run('after');
+      const row = db.prepare('SELECT a, b FROM m WHERE id = 1').get();
+      if (row.a !== 'before' || row.b !== 'after') {
+        return cell('failed', `roundtrip mismatch: ${JSON.stringify(row)}`);
+      }
+      return cell('tested', 'create→alter→read roundtrip ok; added column readable');
+    });
+  } catch (error) {
+    return cell('failed', `migration-roundtrip threw: ${error?.message ?? error}`);
+  }
+}
+
+async function probeFootprint(dir) {
+  try {
+    const rows = [];
+    for (let i = 0; i < FOOTPRINT_ROWS; i += 1) {
+      rows.push({ id: `rec-${i}`, text: `synthetic memory record ${i} lorem ipsum dolor sit amet`, kind: 'fact' });
+    }
+    const jsonPath = path.join(dir, `${SPIKE_PREFIX}footprint.json`);
+    fs.writeFileSync(jsonPath, JSON.stringify({ schemaVersion: 2, records: rows }));
+    const jsonBytes = fs.statSync(jsonPath).size;
+    return await withDb(dir, 'footprint', async (db, dbPath) => {
+      db.exec('CREATE TABLE r (id TEXT PRIMARY KEY, text TEXT, kind TEXT)');
+      const ins = db.prepare('INSERT INTO r (id, text, kind) VALUES (?, ?, ?)');
+      for (const r of rows) ins.run(r.id, r.text, r.kind);
+      db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+      const dbBytes = fs.statSync(dbPath).size;
+      const ratio = jsonBytes > 0 ? (dbBytes / jsonBytes).toFixed(2) : 'n/a';
+      return cell('tested', `${FOOTPRINT_ROWS} rows: sqlite=${dbBytes}B json=${jsonBytes}B ratio=${ratio}`);
+    });
+  } catch (error) {
+    return cell('failed', `footprint threw: ${error?.message ?? error}`);
+  }
+}
+
+function probeLicense() {
+  return cell('tested', 'SQLite is public domain; node:sqlite ships with Node — no new runtime dependency, no license obligation');
+}
+
+// ---------- report ----------
+
+function renderMarkdown(report) {
+  const lines = [];
+  lines.push('# SQLite viability spike report');
+  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}\``);
+  lines.push(`- date: ${report.env.date} · wal-dir: \`${report.env.walDir}\``);
+  lines.push('');
+  lines.push('| cell | verdict | detail |');
+  lines.push('|------|---------|--------|');
+  for (const name of ALL_CELLS) {
+    const c = report.cells[name] ?? { verdict: 'failed', detail: 'cell missing' };
+    lines.push(`| ${name} | ${c.verdict} | ${String(c.detail).replaceAll('|', '\\|')} |`);
+  }
+  lines.push('');
+  const s = report.summary;
+  lines.push(`Summary: ${s.tested} tested · ${s.unsupported} unsupported · ${s.failed} failed (${s.total} cells)`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function summarize(cells) {
+  const s = { tested: 0, unsupported: 0, failed: 0, total: ALL_CELLS.length };
+  for (const name of ALL_CELLS) {
+    const v = cells[name]?.verdict ?? 'failed';
+    if (v === 'tested') s.tested += 1;
+    else if (v === 'unsupported') s.unsupported += 1;
+    else s.failed += 1;
+  }
+  return s;
+}
+
+// ---------- main ----------
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ukit-sqlite-spike-'));
+  const walDir = opts.walDir ? path.resolve(opts.walDir) : tmpRoot;
+  const createdInWalDir = [];
+
+  const env = {
+    sha: 'unknown',
+    package: 'unknown',
+    node: process.version,
+    os: process.platform,
+    arch: process.arch,
+    date: new Date().toISOString(),
+    fs: opts.walDir ? 'user-provided (--wal-dir)' : 'local (mkdtemp)',
+    walDir,
+  };
+  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' */ }
+
+  const cells = {};
+  try {
+    cells['node-sqlite-availability'] = await probeAvailability();
+
+    if (cells['node-sqlite-availability'].verdict === 'unsupported') {
+      for (const name of ALL_CELLS) {
+        if (!cells[name]) cells[name] = cell('unsupported', 'node:sqlite unavailable — probe not runnable');
+      }
+    } else {
+      cells['open-create'] = await probeOpenCreate(tmpRoot);
+      cells['wal-mode'] = await probeWalMode(walDir);
+      cells['busy-timeout'] = await probeBusyTimeout(walDir);
+      cells['concurrent-writers'] = await probeConcurrentWriters(tmpRoot);
+      cells.backup = await probeBackup(tmpRoot);
+      cells['migration-roundtrip'] = await probeMigration(tmpRoot);
+      cells.footprint = await probeFootprint(tmpRoot);
+      cells.license = probeLicense();
+    }
+  } finally {
+    // FR-010 cleanup: remove mkdtemp tree and any spike files left in --wal-dir.
+    try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    if (opts.walDir) {
+      try {
+        for (const entry of fs.readdirSync(walDir)) {
+          if (entry.startsWith(SPIKE_PREFIX)) {
+            createdInWalDir.push(entry);
+            fs.rmSync(path.join(walDir, entry), { recursive: true, force: true });
+          }
+        }
+      } catch { /* unreadable wal-dir is already recorded as cell data */ }
+    }
+  }
+
+  const report = { env, cells, summary: summarize(cells) };
+
+  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));
+
+  const s = report.summary;
+  console.log(`[sqlite-spike] report written: ${outPath}`);
+  console.log(`[sqlite-spike] markdown:       ${mdPath}`);
+  console.log(`[sqlite-spike] cells=${s.total} tested=${s.tested} unsupported=${s.unsupported} failed=${s.failed}`);
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error(`[sqlite-spike] harness crash: ${error?.stack ?? error}`);
+  process.exit(2);
+});