@shadowforge0/aquifer-memory 1.5.8 → 1.5.12

package/scripts/backfill-canonical-key.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Backfill canonical_key_v2 for legacy insights rows.
+ *
+ * Pre-1.5.3 rows (those predating the Phase 2 C1 canonical-identity
+ * layer) carry `canonical_key_v2 IS NULL`, so they never match the
+ * canonical lookup inside commitInsight and never participate in the
+ * revision/supersede path. This script fills the key deterministically
+ * from `title` using the same normalization and hashing functions the
+ * writer uses, so backfilled rows behave identically to a freshly
+ * written row whose LLM extractor happened to emit a canonicalClaim
+ * equal to its title.
+ *
+ * Why JS not SQL: pgcrypto is NOT a default-installed extension in
+ * our production PG (verified 2026-04-20). Even with pgcrypto, matching
+ * JS's Unicode NFKC normalization in pure SQL is fragile. Single source
+ * of truth lives in core/insights.js; this script reuses it.
+ *
+ * Idempotent: every UPDATE is guarded by WHERE canonical_key_v2 IS NULL,
+ * so reruns and concurrent live writers converge cleanly.
+ */
+
+const { Pool } = require('pg');
+const { defaultCanonicalKey } = require('../core/insights');
+
+const BACKFILL_METADATA_PATCH = { canonicalBackfill: 'title_deterministic' };
+
+function printUsageAndExit(code = 0) {
+  const usage = [
+    'Usage: node scripts/backfill-canonical-key.js --schema <name> [options]',
+    '',
+    'Required:',
+    '  --schema <name>        Target schema (e.g. miranda, jenny)',
+    '  --agent <id>           Limit to one agent (or use --all-agents)',
+    '',
+    'Optional:',
+    '  --all-agents           Backfill across all agents in the tenant',
+    '                         (mutually exclusive with --agent)',
+    '  --tenant-id <id>       Default: $AQUIFER_TENANT_ID or "default"',
+    '  --batch-size <N>       Rows per batch (1..1000, default 50)',
+    '  --dry-run              Print would-updates, do not execute',
+    '  -h, --help             Show this help',
+    '',
+    'Env:',
+    '  DATABASE_URL           Postgres connection string (required)',
+    '  AQUIFER_TENANT_ID      Fallback tenant id',
+    '',
+  ].join('\n');
+  (code === 0 ? console.log : console.error)(usage);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const args = {
+    schema: null,
+    agent: null,
+    allAgents: false,
+    tenantId: process.env.AQUIFER_TENANT_ID || 'default',
+    batchSize: 50,
+    dryRun: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i], v = argv[i + 1];
+    if (a === '--schema') { args.schema = v; i++; }
+    else if (a === '--agent') { args.agent = v; i++; }
+    else if (a === '--all-agents') { args.allAgents = true; }
+    else if (a === '--tenant-id') { args.tenantId = v; i++; }
+    else if (a === '--batch-size') {
+      const n = parseInt(v, 10);
+      if (!Number.isFinite(n) || n < 1) {
+        console.error(`--batch-size must be an integer >= 1, got: ${v}`);
+        process.exit(2);
+      }
+      args.batchSize = Math.min(n, 1000);
+      i++;
+    } else if (a === '--dry-run') { args.dryRun = true; }
+    else if (a === '-h' || a === '--help') { args.help = true; }
+    else {
+      console.error(`Unknown argument: ${a}`);
+      printUsageAndExit(2);
+    }
+  }
+  return args;
+}
+
+function validate(args) {
+  if (args.help) printUsageAndExit(0);
+  if (!args.schema) {
+    console.error('Missing required --schema');
+    printUsageAndExit(2);
+  }
+  if (!args.agent && !args.allAgents) {
+    console.error('Must specify --agent <id> or --all-agents');
+    printUsageAndExit(2);
+  }
+  if (args.agent && args.allAgents) {
+    console.error('--agent and --all-agents are mutually exclusive');
+    printUsageAndExit(2);
+  }
+  if (!process.env.DATABASE_URL) {
+    console.error('DATABASE_URL is required');
+    printUsageAndExit(2);
+  }
+}
+
+// Safe schema identifier quoting — same pattern as
+// scripts/extract-insights-from-recent-sessions.js:218-219.
+const qi = (s) => `"${String(s).replace(/"/g, '""')}"`;
+
+function truncateForLog(s, n = 60) {
+  if (typeof s !== 'string') return '';
+  return s.length > n ? s.slice(0, n) + '…' : s;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  validate(args);
+
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+  const schemaIdent = qi(args.schema);
+  const agentLabel = args.allAgents ? '(all)' : args.agent;
+  console.log(
+    `[backfill] tenant=${args.tenantId} schema=${args.schema} `
+    + `agent=${agentLabel} batch_size=${args.batchSize} dry_run=${args.dryRun}`
+  );
+  if (args.dryRun) {
+    console.log('[backfill] DRY RUN — no updates will be executed.');
+  }
+
+  const whereClauses = [
+    'canonical_key_v2 IS NULL',
+    `status = 'active'`,
+    'tenant_id = $1',
+  ];
+  const whereParams = [args.tenantId];
+  if (!args.allAgents) {
+    whereClauses.push(`agent_id = $${whereParams.length + 1}`);
+    whereParams.push(args.agent);
+  }
+
+  let totalBackfilled = 0;
+  let totalSkipped = 0;
+  let totalAlreadySet = 0;
+  let batchNum = 0;
+  // Id watermark: prevents infinite loop when a batch yields no state
+  // transitions (dry-run always, or when every row has empty title, or
+  // when races cause 0 UPDATEs). WHERE id > $N advances the cursor even
+  // if the current rows aren't removed from the candidate set.
+  let lastId = 0;
+
+  try {
+    while (true) {
+      batchNum += 1;
+
+      const selectSql =
+        `SELECT id, tenant_id, agent_id, insight_type, title
+           FROM ${schemaIdent}.insights
+          WHERE ${whereClauses.join(' AND ')}
+            AND id > $${whereParams.length + 1}
+          ORDER BY id ASC
+          LIMIT $${whereParams.length + 2}`;
+      const res = await pool.query(selectSql, [...whereParams, lastId, args.batchSize]);
+
+      if (res.rowCount === 0) break;
+      lastId = Number(res.rows[res.rows.length - 1].id);
+
+      let batchBackfilled = 0;
+      let batchSkipped = 0;
+      let batchAlreadySet = 0;
+
+      for (const row of res.rows) {
+        const title = typeof row.title === 'string' ? row.title.trim() : '';
+        if (!title) {
+          console.warn(
+            `[backfill] skip id=${row.id} empty or whitespace title`
+          );
+          batchSkipped += 1;
+          continue;
+        }
+
+        const canonicalKey = defaultCanonicalKey({
+          tenantId: row.tenant_id,
+          agentId: row.agent_id,
+          type: row.insight_type,
+          canonicalClaim: title,
+          entities: [],
+        });
+
+        if (args.dryRun) {
+          console.log(
+            `[backfill] would_update id=${row.id} agent=${row.agent_id} `
+            + `type=${row.insight_type} title="${truncateForLog(title)}"`
+          );
+          batchBackfilled += 1;
+          continue;
+        }
+
+        const updSql =
+          `UPDATE ${schemaIdent}.insights
+              SET canonical_key_v2 = $1,
+                  metadata = metadata || $2::jsonb,
+                  updated_at = now()
+            WHERE id = $3 AND canonical_key_v2 IS NULL`;
+        const upd = await pool.query(updSql, [
+          canonicalKey,
+          JSON.stringify(BACKFILL_METADATA_PATCH),
+          row.id,
+        ]);
+        if (upd.rowCount === 0) {
+          batchAlreadySet += 1;
+        } else {
+          batchBackfilled += 1;
+        }
+      }
+
+      totalBackfilled += batchBackfilled;
+      totalSkipped += batchSkipped;
+      totalAlreadySet += batchAlreadySet;
+
+      console.log(
+        `[backfill] batch ${batchNum}: selected=${res.rowCount} `
+        + `${args.dryRun ? 'would_backfill' : 'backfilled'}=${batchBackfilled} `
+        + `skipped=${batchSkipped} already_set=${batchAlreadySet}`
+      );
+
+      // No all-skip-break guard needed: the `id > lastId` cursor
+      // advances past skipped rows each iteration, so an empty-title
+      // row in an otherwise healthy batch doesn't trap the loop.
+    }
+
+    const verb = args.dryRun ? 'would_backfill' : 'backfilled';
+    console.log(
+      `[backfill] DONE${args.dryRun ? ' dry_run' : ''} total: `
+      + `${verb}=${totalBackfilled} skipped=${totalSkipped} `
+      + `already_set=${totalAlreadySet}`
+    );
+  } catch (e) {
+    console.error('[backfill] fatal:', e.stack || e.message);
+    await pool.end().catch(() => {});
+    process.exit(1);
+  }
+
+  await pool.end().catch(() => {});
+}
+
+main();

package/scripts/queries.json

@@ -1,45 +0,0 @@
-{
-  "version": 1,
-  "queries": [
-    {
-      "id": "q-001",
-      "lang": "en",
-      "text": "How do I set up Aquifer memory storage with PostgreSQL?"
-    },
-    {
-      "id": "q-002",
-      "lang": "en",
-      "text": "What is the difference between memory_search and session_recall in Aquifer?"
-    },
-    {
-      "id": "q-003",
-      "lang": "zh",
-      "text": "Aquifer 的 session recall 是怎麼做 hybrid 檢索的？"
-    },
-    {
-      "id": "q-004",
-      "lang": "zh",
-      "text": "為什麼 zhcfg 會依賴 jieba 或 zhparser？"
-    },
-    {
-      "id": "q-005",
-      "lang": "mixed",
-      "text": "How to debug fts-zhcfg pipeline 在 jieba migration 後失敗的問題？"
-    },
-    {
-      "id": "q-006",
-      "lang": "mixed",
-      "text": "memory_search 找不到結果時，應該先看哪個 log 或 table？"
-    },
-    {
-      "id": "q-007",
-      "lang": "en",
-      "text": "How does hybrid-rerank differ from hybrid mode in retro recall bench?"
-    },
-    {
-      "id": "q-008",
-      "lang": "zh",
-      "text": "Aquifer 初始化後要如何驗證 embeddings pipeline 有正常工作？"
-    }
-  ]
-}

package/scripts/retro-recall-bench.js

@@ -1,409 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Retro recall bench — runs the same query set across 6 pipelines and
- * reports nDCG@5 / MRR / latency / empty-rate. Designed for the post-1.3.0
- * Phase 0 audit; see ~/.claude/develop-runs/20260419-142432-aquifer-memory-routes/spec.md.
- *
- * Pipelines:
- *   fts-simple       storage.searchSessions(ftsConfig='simple')
- *   fts-zhcfg        storage.searchSessions(ftsConfig='zhcfg')   [skip if zhcfg missing]
- *   summary-vector   storage.searchSummaryEmbeddings
- *   turn-only        storage.searchTurnEmbeddings
- *   hybrid           aquifer.recall(mode='hybrid', rerank disabled)
- *   hybrid-rerank    aquifer.recall(mode='hybrid', rerank forced)
- *
- * Usage:
- *   node scripts/retro-recall-bench.js \
- *     --query-set queries.json \
- *     [--judgements judgements.json] \
- *     [--output report.json] \
- *     [--markdown summary.md] \
- *     [--pipelines fts-simple,fts-zhcfg,summary-vector,turn-only,hybrid,hybrid-rerank] \
- *     [--limit 5] [--warmup 1] [--schema miranda] [--tenant-id default]
- *
- * env:
- *   DATABASE_URL          required
- *   AQUIFER_SCHEMA        default 'miranda'
- *   EMBED_PROVIDER + key  required for vector pipelines
- *   AQUIFER_LLM_PROVIDER  unused here (no enrich)
- *   OPENROUTER_API_KEY    required for hybrid-rerank pipeline
- */
-
-const fs = require('fs');
-const { Pool } = require('pg');
-const aquiferIndex = require('..');
-const storage = require('../core/storage');
-const { createEmbedder } = require('..');
-
-const ALL_PIPELINES = [
-  'fts-simple',
-  'fts-zhcfg',
-  'summary-vector',
-  'turn-only',
-  'hybrid',
-  'hybrid-rerank',
-];
-
-function parseArgs(argv) {
-  const args = {
-    querySet: null,
-    judgements: null,
-    output: null,
-    markdown: null,
-    pipelines: ALL_PIPELINES,
-    limit: 5,
-    warmup: 1,
-    schema: process.env.AQUIFER_SCHEMA || 'miranda',
-    tenantId: process.env.AQUIFER_TENANT_ID || 'default',
-    rerankTopK: 20,
-  };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    const v = argv[i + 1];
-    if (a === '--query-set') { args.querySet = v; i++; }
-    else if (a === '--judgements') { args.judgements = v; i++; }
-    else if (a === '--output') { args.output = v; i++; }
-    else if (a === '--markdown') { args.markdown = v; i++; }
-    else if (a === '--pipelines') { args.pipelines = v.split(',').map(s => s.trim()).filter(Boolean); i++; }
-    else if (a === '--limit') { args.limit = parseInt(v, 10); i++; }
-    else if (a === '--warmup') { args.warmup = parseInt(v, 10); i++; }
-    else if (a === '--schema') { args.schema = v; i++; }
-    else if (a === '--tenant-id') { args.tenantId = v; i++; }
-    else if (a === '--rerank-topk') { args.rerankTopK = parseInt(v, 10); i++; }
-    else if (a === '-h' || a === '--help') { args.help = true; }
-  }
-  return args;
-}
-
-function printHelp() {
-  console.log(fs.readFileSync(__filename, 'utf8').split('\n').slice(0, 36).join('\n'));
-}
-
-function detectFtsConfigsAvailable(pool) {
-  return pool.query(`SELECT cfgname FROM pg_ts_config WHERE cfgname IN ('simple','zhcfg')`)
-    .then(r => new Set(r.rows.map(row => row.cfgname)));
-}
-
-async function withLatency(fn) {
-  const t0 = process.hrtime.bigint();
-  let result; let error = null;
-  try { result = await fn(); } catch (e) { error = e; }
-  const t1 = process.hrtime.bigint();
-  return { latencyMs: Number(t1 - t0) / 1e6, result, error };
-}
-
-function normalizeHits(rows, scoreKey) {
-  return rows.map((r, i) => ({
-    rank: i + 1,
-    sessionId: r.session_id || r.sessionId,
-    sessionRowId: r.id || r.session_row_id || r.sessionRowId || null,
-    agentId: r.agent_id || r.agentId || null,
-    score: r[scoreKey] ?? null,
-    summaryDistance: r.distance ?? null,
-    turnDistance: r.turn_distance ?? null,
-  }));
-}
-
-function normalizeAquiferHits(rows) {
-  return rows.map((r, i) => ({
-    rank: i + 1,
-    sessionId: r.sessionId,
-    sessionRowId: null,
-    agentId: r.agentId,
-    score: r.score ?? null,
-    summaryDistance: r._debug?.hybridScore ?? null,
-    turnDistance: null,
-    rerankApplied: r._debug?.rerankApplied ?? false,
-    rerankReason: r._debug?.rerankReason ?? null,
-  }));
-}
-
-async function runPipeline(name, ctx, query) {
-  const { pool, schema, tenantId, limit, queryVec, aquifer, ftsAvailable } = ctx;
-  switch (name) {
-    case 'fts-simple': {
-      if (!ftsAvailable.has('simple')) return { skipped: true, reason: 'simple tsconfig missing' };
-      return withLatency(async () => {
-        const rows = await storage.searchSessions(pool, query.text, {
-          schema, tenantId, agentId: query.agentId, limit, ftsConfig: 'simple',
-        });
-        return normalizeHits(rows, 'fts_rank');
-      });
-    }
-    case 'fts-zhcfg': {
-      if (!ftsAvailable.has('zhcfg')) return { skipped: true, reason: 'zhcfg tsconfig missing — install zhparser' };
-      return withLatency(async () => {
-        const rows = await storage.searchSessions(pool, query.text, {
-          schema, tenantId, agentId: query.agentId, limit, ftsConfig: 'zhcfg',
-        });
-        return normalizeHits(rows, 'fts_rank');
-      });
-    }
-    case 'summary-vector': {
-      if (!queryVec) return { skipped: true, reason: 'no embed provider' };
-      return withLatency(async () => {
-        const { rows } = await storage.searchSummaryEmbeddings(pool, {
-          schema, tenantId, queryVec, agentId: query.agentId, limit,
-        });
-        return normalizeHits(rows, 'distance');
-      });
-    }
-    case 'turn-only': {
-      if (!queryVec) return { skipped: true, reason: 'no embed provider' };
-      return withLatency(async () => {
-        const { rows } = await storage.searchTurnEmbeddings(pool, {
-          schema, tenantId, queryVec, agentId: query.agentId, limit,
-        });
-        return normalizeHits(rows, 'turn_distance');
-      });
-    }
-    case 'hybrid': {
-      return withLatency(async () => {
-        const rows = await aquifer.recall(query.text, {
-          agentId: query.agentId, limit, mode: 'hybrid', rerank: false,
-        });
-        return normalizeAquiferHits(rows);
-      });
-    }
-    case 'hybrid-rerank': {
-      return withLatency(async () => {
-        const rows = await aquifer.recall(query.text, {
-          agentId: query.agentId, limit, mode: 'hybrid', rerank: true,
-        });
-        return normalizeAquiferHits(rows);
-      });
-    }
-    default:
-      return { skipped: true, reason: `unknown pipeline ${name}` };
-  }
-}
-
-function dcg(rels) {
-  return rels.reduce((acc, rel, i) => acc + (Math.pow(2, rel) - 1) / Math.log2(i + 2), 0);
-}
-
-function nDcgAtK(judgedHits, k) {
-  const at = judgedHits.slice(0, k);
-  const ideal = [...judgedHits].sort((a, b) => b - a).slice(0, k);
-  const idcg = dcg(ideal);
-  if (idcg === 0) return null;
-  return dcg(at) / idcg;
-}
-
-function reciprocalRank(judgedHits) {
-  const idx = judgedHits.findIndex(r => r > 0);
-  return idx < 0 ? 0 : 1 / (idx + 1);
-}
-
-function computeMetrics(runs, judgements, k) {
-  const judgeMap = new Map();
-  for (const j of judgements) {
-    judgeMap.set(`${j.queryId}::${j.sessionId}`, j.relevance);
-  }
-  const byPipeline = {};
-  for (const run of runs) {
-    if (run.skipped || run.error) continue;
-    const arr = byPipeline[run.pipeline] || (byPipeline[run.pipeline] = { judged: [], latency: [], empty: 0, total: 0, judgeable: 0 });
-    arr.total++;
-    arr.latency.push(run.latencyMs);
-    if (!run.hits || run.hits.length === 0) arr.empty++;
-    const rels = (run.hits || []).map(h => judgeMap.get(`${run.queryId}::${h.sessionId}`) ?? 0);
-    if (rels.some(r => r > 0)) arr.judgeable++;
-    arr.judged.push(rels);
-  }
-  const result = [];
-  for (const [pipeline, agg] of Object.entries(byPipeline)) {
-    const ndcgs = agg.judged.map(rels => nDcgAtK(rels, k)).filter(v => v !== null);
-    const mrrs = agg.judged.map(reciprocalRank);
-    const lat = agg.latency.slice().sort((a, b) => a - b);
-    const p = (frac) => lat.length === 0 ? null : lat[Math.min(lat.length - 1, Math.floor(frac * lat.length))];
-    result.push({
-      pipeline,
-      count: agg.total,
-      nDCG5: ndcgs.length ? ndcgs.reduce((a, b) => a + b, 0) / ndcgs.length : null,
-      MRR: mrrs.length ? mrrs.reduce((a, b) => a + b, 0) / mrrs.length : null,
-      latencyMs: {
-        mean: lat.length ? lat.reduce((a, b) => a + b, 0) / lat.length : null,
-        p50: p(0.5),
-        p95: p(0.95),
-      },
-      emptyResultRate: agg.total ? agg.empty / agg.total : 0,
-      judgeableRate: agg.total ? agg.judgeable / agg.total : 0,
-    });
-  }
-  return result;
-}
-
-function renderMarkdown(report, k) {
-  const lines = [];
-  lines.push(`# Aquifer Retro Recall Bench`);
-  lines.push('');
-  lines.push(`- Generated: ${report.meta.generatedAt}`);
-  lines.push(`- Schema: \`${report.meta.schema}\` / Tenant: \`${report.meta.tenantId}\``);
-  lines.push(`- Queries: ${report.queries.length} (warmup ${report.meta.warmup} excluded from metrics)`);
-  lines.push(`- Pipelines: ${report.meta.pipelines.join(', ')}`);
-  lines.push('');
-  lines.push(`## Overall (top ${k})`);
-  lines.push('| Pipeline | nDCG@5 | MRR | Mean ms | p50 | p95 | Empty% | Judgeable% | N |');
-  lines.push('|---|---|---|---|---|---|---|---|---|');
-  for (const m of report.metrics.overall) {
-    lines.push(`| ${m.pipeline} | ${fmt(m.nDCG5)} | ${fmt(m.MRR)} | ${fmtMs(m.latencyMs.mean)} | ${fmtMs(m.latencyMs.p50)} | ${fmtMs(m.latencyMs.p95)} | ${pct(m.emptyResultRate)} | ${pct(m.judgeableRate)} | ${m.count} |`);
-  }
-  if (report.metrics.zhMixed) {
-    lines.push('');
-    lines.push(`## ZH+Mixed subset (top ${k})`);
-    lines.push('| Pipeline | nDCG@5 | MRR | Empty% | N |');
-    lines.push('|---|---|---|---|---|');
-    for (const m of report.metrics.zhMixed) {
-      lines.push(`| ${m.pipeline} | ${fmt(m.nDCG5)} | ${fmt(m.MRR)} | ${pct(m.emptyResultRate)} | ${m.count} |`);
-    }
-  }
-  if (report.metrics.en) {
-    lines.push('');
-    lines.push(`## EN subset (top ${k})`);
-    lines.push('| Pipeline | nDCG@5 | MRR | Empty% | N |');
-    lines.push('|---|---|---|---|---|');
-    for (const m of report.metrics.en) {
-      lines.push(`| ${m.pipeline} | ${fmt(m.nDCG5)} | ${fmt(m.MRR)} | ${pct(m.emptyResultRate)} | ${m.count} |`);
-    }
-  }
-  if (report.skipped.length > 0) {
-    lines.push('');
-    lines.push('## Skipped pipelines');
-    for (const s of report.skipped) lines.push(`- \`${s.pipeline}\`: ${s.reason}`);
-  }
-  return lines.join('\n') + '\n';
-}
-
-function fmt(v) { return (v === null || v === undefined) ? '—' : v.toFixed(3); }
-function fmtMs(v) { return (v === null || v === undefined) ? '—' : v.toFixed(1); }
-function pct(v) { return (v === null || v === undefined) ? '—' : `${(v * 100).toFixed(0)}%`; }
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.help || !args.querySet) { printHelp(); process.exit(args.help ? 0 : 2); }
-
-  const querySet = JSON.parse(fs.readFileSync(args.querySet, 'utf8'));
-  const queries = querySet.queries || [];
-  if (queries.length === 0) { console.error('Empty query set'); process.exit(2); }
-
-  const judgements = args.judgements
-    ? (JSON.parse(fs.readFileSync(args.judgements, 'utf8')).judgements || [])
-    : [];
-
-  const dbUrl = process.env.DATABASE_URL || process.env.AQUIFER_DB_URL;
-  if (!dbUrl) { console.error('DATABASE_URL is required'); process.exit(2); }
-
-  const pool = new Pool({ connectionString: dbUrl });
-  const ftsAvailable = await detectFtsConfigsAvailable(pool);
-
-  const embedFn = (() => {
-    try {
-      const e = createEmbedder({});  // autodetect via EMBED_PROVIDER
-      return (texts) => e.embedBatch(texts);
-    } catch (err) {
-      console.warn(`[bench] embed unavailable: ${err.message} — vector pipelines will skip`);
-      return null;
-    }
-  })();
-
-  const aquifer = aquiferIndex.createAquifer({
-    db: pool,
-    schema: args.schema,
-    tenantId: args.tenantId,
-    embed: embedFn ? { fn: embedFn } : undefined,
-    rerank: process.env.OPENROUTER_API_KEY
-      ? { provider: 'openrouter', openrouterApiKey: process.env.OPENROUTER_API_KEY, topK: args.rerankTopK, autoTrigger: { enabled: false } }
-      : null,
-  });
-
-  const ctx = {
-    pool, schema: args.schema, tenantId: args.tenantId,
-    limit: args.limit, queryVec: null, aquifer, ftsAvailable,
-  };
-
-  const runs = [];
-  const skipped = new Set();
-
-  // Warmup: just run hybrid once to prime the pool.
-  for (let w = 0; w < args.warmup; w++) {
-    try { await aquifer.recall(queries[0].text, { limit: args.limit }); } catch { /* ignore */ }
-  }
-
-  for (const q of queries) {
-    let queryVec = null;
-    if (embedFn) {
-      try { queryVec = (await embedFn([q.text]))[0]; }
-      catch (err) { console.warn(`[bench] embed failed for "${q.id}": ${err.message}`); }
-    }
-    ctx.queryVec = queryVec;
-
-    for (const pipeline of args.pipelines) {
-      const r = await runPipeline(pipeline, ctx, q);
-      if (r.skipped) {
-        skipped.add(JSON.stringify({ pipeline, reason: r.reason }));
-        continue;
-      }
-      runs.push({
-        queryId: q.id,
-        pipeline,
-        latencyMs: r.latencyMs,
-        empty: !r.result || r.result.length === 0,
-        error: r.error ? { code: r.error.code || 'ERR', message: r.error.message } : null,
-        hits: r.result || [],
-      });
-    }
-  }
-
-  await aquifer.close?.().catch(() => {});
-  await pool.end().catch(() => {});
-
-  const overallRuns = runs;
-  const zhMixedQueries = new Set(queries.filter(q => q.lang === 'zh' || q.lang === 'mixed').map(q => q.id));
-  const enQueries = new Set(queries.filter(q => q.lang === 'en').map(q => q.id));
-  const subset = (set) => runs.filter(r => set.has(r.queryId));
-
-  const report = {
-    meta: {
-      generatedAt: new Date().toISOString(),
-      schema: args.schema,
-      tenantId: args.tenantId,
-      limit: args.limit,
-      warmup: args.warmup,
-      pipelines: args.pipelines,
-      ftsConfigsAvailable: [...ftsAvailable],
-    },
-    queries,
-    judgements,
-    runs,
-    metrics: {
-      overall: computeMetrics(overallRuns, judgements, args.limit),
-      zhMixed: zhMixedQueries.size > 0 ? computeMetrics(subset(zhMixedQueries), judgements, args.limit) : null,
-      en: enQueries.size > 0 ? computeMetrics(subset(enQueries), judgements, args.limit) : null,
-    },
-    skipped: [...skipped].map(s => JSON.parse(s)),
-  };
-
-  const outPath = args.output || `bench-report-${Date.now()}.json`;
-  fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
-  console.log(`Wrote ${outPath}`);
-
-  const md = renderMarkdown(report, args.limit);
-  const mdPath = args.markdown || outPath.replace(/\.json$/, '.md');
-  fs.writeFileSync(mdPath, md);
-  console.log(`Wrote ${mdPath}`);
-
-  if (judgements.length === 0) {
-    console.log('\nNo judgements provided — metrics are coverage/latency only.');
-    console.log('Edit the JSON output to add judgements like:');
-    console.log('  "judgements": [{"queryId":"q-001","sessionId":"sess_abc","relevance":3}, ...]');
-    console.log('then re-run with --judgements <path>.');
-  }
-}
-
-main().catch(err => {
-  console.error('[bench] fatal:', err.stack || err.message);
-  process.exit(1);
-});