@ngockhoale/ukit 3.4.47 → 3.4.48

package/scripts/bench/sqlite-spike.mjs

@@ -1,451 +0,0 @@
-#!/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', timeout: 10_000 }).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);
-});