@shadowforge0/aquifer-memory 1.0.2 → 1.2.1

package/pipeline/summarize.js

@@ -206,6 +206,9 @@ async function summarize(messages, {
   try {
     const prompt = buildPrompt(messages, { mergeEntities });
     const response = await llmFn(prompt);
+    if (typeof response !== 'string' || response.trim() === '') {
+      return extractiveFallback(messages);
+    }
 
     // Parse structured fields
     const structuredSummary = _parseStructuredSummary(response);
@@ -232,7 +235,7 @@ async function summarize(messages, {
       entityRaw,
       isExtractive: false,
     };
-  } catch (err) {
+  } catch {
     // LLM failure: fall back to extractive
     return extractiveFallback(messages);
   }

package/schema/001-base.sql

@@ -43,27 +43,6 @@ CREATE INDEX IF NOT EXISTS idx_sessions_processing_status
   ON ${schema}.sessions (processing_status)
   WHERE processing_status IN ('pending', 'processing');
 
--- =========================================================================
--- Session segments: conversation boundary metadata
--- =========================================================================
-CREATE TABLE IF NOT EXISTS ${schema}.session_segments (
-  id                  BIGSERIAL    PRIMARY KEY,
-  session_row_id      BIGINT       NOT NULL REFERENCES ${schema}.sessions(id) ON DELETE CASCADE,
-  segment_no          INT          NOT NULL,
-  start_msg_idx       INT,
-  end_msg_idx         INT,
-  started_at          TIMESTAMPTZ,
-  ended_at            TIMESTAMPTZ,
-  raw_msg_count       INT          NOT NULL DEFAULT 0,
-  effective_msg_count INT          NOT NULL DEFAULT 0,
-  boundary_type       TEXT,
-  boundary_meta       JSONB        NOT NULL DEFAULT '{}',
-  UNIQUE (session_row_id, segment_no)
-);
-
-CREATE INDEX IF NOT EXISTS idx_session_segments_row
-  ON ${schema}.session_segments (session_row_id);
-
 -- =========================================================================
 -- Session summaries: LLM-generated or extractive summaries
 -- =========================================================================
@@ -78,8 +57,6 @@ CREATE TABLE IF NOT EXISTS ${schema}.session_summaries (
   message_count            INT          NOT NULL DEFAULT 0,
   user_message_count       INT          NOT NULL DEFAULT 0,
   assistant_message_count  INT          NOT NULL DEFAULT 0,
-  boundary_count           INT          NOT NULL DEFAULT 0,
-  fresh_tail_count         INT          NOT NULL DEFAULT 0,
   started_at               TIMESTAMPTZ,
   ended_at                 TIMESTAMPTZ,
   summary_text             TEXT,
@@ -92,6 +69,23 @@ CREATE TABLE IF NOT EXISTS ${schema}.session_summaries (
   updated_at               TIMESTAMPTZ  NOT NULL DEFAULT now()
 );
 
+-- Cleanup legacy segment-era schema artifacts so migrate() converges old installs.
+-- Wrapped because the implicit sequence on session_segments can be referenced from
+-- other schemas (e.g. bench/staging created via CREATE TABLE LIKE), which would
+-- otherwise hard-fail the migration. Operators get a NOTICE and must decouple
+-- dependents themselves before the table will actually drop.
+DO $$
+BEGIN
+  BEGIN
+    DROP TABLE IF EXISTS ${schema}.session_segments;
+  EXCEPTION
+    WHEN dependent_objects_still_exist THEN
+      RAISE NOTICE '[aquifer] skipped session_segments drop: %; decouple cross-schema dependents and re-run migrate to complete cleanup', SQLERRM;
+  END;
+END$$;
+ALTER TABLE ${schema}.session_summaries DROP COLUMN IF EXISTS boundary_count;
+ALTER TABLE ${schema}.session_summaries DROP COLUMN IF EXISTS fresh_tail_count;
+
 CREATE INDEX IF NOT EXISTS idx_summaries_tenant
   ON ${schema}.session_summaries (tenant_id);
 
@@ -105,6 +99,27 @@ CREATE INDEX IF NOT EXISTS idx_summaries_embedding
   ON ${schema}.session_summaries (session_row_id)
   WHERE embedding IS NOT NULL;
 
+-- HNSW approximate nearest-neighbor index for cosine-distance vector search.
+-- Without this, ORDER BY embedding <=> $vec degrades to seq scan at scale.
+-- Requires pgvector >= 0.5.0. HNSW cannot build on an empty unsized `vector`
+-- column (can't infer dim), so we defer on failure — re-running migrate()
+-- after the first insert will finish the job.
+DO $$
+BEGIN
+  BEGIN
+    EXECUTE 'CREATE INDEX IF NOT EXISTS idx_summaries_embedding_hnsw ON ${schema}.session_summaries USING hnsw (embedding vector_cosine_ops)';
+  EXCEPTION
+    WHEN invalid_parameter_value THEN
+      RAISE NOTICE '[aquifer] HNSW index on session_summaries.embedding deferred; re-run migrate() after the first embedded row';
+    WHEN feature_not_supported THEN
+      RAISE NOTICE '[aquifer] HNSW not available on this pgvector; upgrade to >= 0.5.0 for index-accelerated vector search';
+    WHEN out_of_memory THEN
+      RAISE WARNING '[aquifer] HNSW build on session_summaries.embedding ran out of memory; raise maintenance_work_mem and re-run migrate()';
+    WHEN program_limit_exceeded THEN
+      RAISE WARNING '[aquifer] HNSW build on session_summaries.embedding exceeded an internal limit; inspect pgvector logs';
+  END;
+END$$;
+
 -- FTS trigger: auto-update search_tsv on INSERT/UPDATE
 CREATE OR REPLACE FUNCTION ${schema}.session_summaries_search_tsv_update()
 RETURNS trigger
@@ -158,8 +173,12 @@ $$;
 DROP TRIGGER IF EXISTS trg_session_summaries_search_tsv
   ON ${schema}.session_summaries;
 
+-- Trigger fires on input-column changes only. search_text is a trigger output
+-- (derived from structured_summary + summary_text) and listing it here was
+-- redundant — PG's BEFORE semantics already prevent the assignment inside the
+-- trigger body from re-firing the trigger.
 CREATE TRIGGER trg_session_summaries_search_tsv
-  BEFORE INSERT OR UPDATE OF summary_text, structured_summary, search_text
+  BEFORE INSERT OR UPDATE OF summary_text, structured_summary
   ON ${schema}.session_summaries
   FOR EACH ROW
   EXECUTE FUNCTION ${schema}.session_summaries_search_tsv_update();
@@ -189,3 +208,21 @@ CREATE INDEX IF NOT EXISTS idx_turn_emb_session_row
 
 CREATE INDEX IF NOT EXISTS idx_turn_emb_tenant_agent
   ON ${schema}.turn_embeddings (tenant_id, agent_id, source);
+
+-- HNSW approximate nearest-neighbor index for turn-level vector search.
+-- See notes on session_summaries.embedding HNSW above.
+DO $$
+BEGIN
+  BEGIN
+    EXECUTE 'CREATE INDEX IF NOT EXISTS idx_turn_emb_embedding_hnsw ON ${schema}.turn_embeddings USING hnsw (embedding vector_cosine_ops)';
+  EXCEPTION
+    WHEN invalid_parameter_value THEN
+      RAISE NOTICE '[aquifer] HNSW index on turn_embeddings.embedding deferred; re-run migrate() after the first embedded row';
+    WHEN feature_not_supported THEN
+      RAISE NOTICE '[aquifer] HNSW not available on this pgvector; upgrade to >= 0.5.0 for index-accelerated vector search';
+    WHEN out_of_memory THEN
+      RAISE WARNING '[aquifer] HNSW build on turn_embeddings.embedding ran out of memory; raise maintenance_work_mem and re-run migrate()';
+    WHEN program_limit_exceeded THEN
+      RAISE WARNING '[aquifer] HNSW build on turn_embeddings.embedding exceeded an internal limit; inspect pgvector logs';
+  END;
+END$$;

package/schema/002-entities.sql

@@ -28,10 +28,24 @@ CREATE TABLE IF NOT EXISTS ${schema}.entities (
   last_seen_at    TIMESTAMPTZ  NOT NULL DEFAULT now()
 );
 
--- Migration: add entity_scope if missing (idempotent)
--- For upgrades: backfill from agent_id so existing data keeps its scope
+-- Migration: add entity_scope if missing (idempotent, scope-corruption-safe).
+-- For upgrades: backfill from agent_id ONLY on the first run of this migration,
+-- detected via the column still being NULL-able. Once SET NOT NULL below fires,
+-- subsequent runs skip the backfill so operator-assigned 'default' values are
+-- never clobbered.
 ALTER TABLE ${schema}.entities ADD COLUMN IF NOT EXISTS entity_scope TEXT DEFAULT 'default';
-UPDATE ${schema}.entities SET entity_scope = agent_id WHERE entity_scope IS NULL OR entity_scope = 'default';
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = '${schema}' AND table_name = 'entities'
+      AND column_name = 'entity_scope' AND is_nullable = 'YES'
+  ) THEN
+    UPDATE ${schema}.entities
+      SET entity_scope = agent_id
+      WHERE entity_scope IS NULL OR entity_scope = 'default';
+  END IF;
+END$$;
 ALTER TABLE ${schema}.entities ALTER COLUMN entity_scope SET NOT NULL;
 
 -- Unique constraint: entity identity is (tenant, name, scope)

package/schema/004-facts.sql

@@ -0,0 +1,67 @@
+-- Aquifer facts / consolidation extension
+-- Requires: 001-base.sql applied first
+-- Usage: replace ${schema} with actual schema name
+--
+-- Facts store long-lived subject/statement pairs with a lifecycle:
+--   candidate → active → (stale | archived | superseded)
+-- Consumers write candidates during enrich (via writeFactCandidates).
+-- consolidate() then promotes / updates / confirms / archives them.
+
+-- =========================================================================
+-- Facts: long-lived current-state statements per (subject, agent)
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.facts (
+  id                 BIGSERIAL    PRIMARY KEY,
+  tenant_id          TEXT         NOT NULL DEFAULT 'default',
+  subject_key        TEXT         NOT NULL,
+  subject_label      TEXT         NOT NULL,
+  statement          TEXT         NOT NULL,
+  status             TEXT         NOT NULL DEFAULT 'candidate'
+                       CHECK (status IN ('candidate','active','stale','archived','superseded')),
+  importance         SMALLINT     NOT NULL DEFAULT 5,
+  source_session_id  TEXT,
+  agent_id           TEXT         NOT NULL DEFAULT 'main',
+  evidence           JSONB        NOT NULL DEFAULT '[]'::jsonb,
+  superseded_by      BIGINT       REFERENCES ${schema}.facts(id) ON DELETE SET NULL,
+  first_seen_at      TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  last_confirmed_at  TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+
+-- Migration: add tenant_id if upgrading from a legacy facts table (no tenant column).
+ALTER TABLE ${schema}.facts ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'default';
+
+-- At most one active fact per (tenant, subject, agent)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_facts_active_subject
+  ON ${schema}.facts (tenant_id, subject_key, agent_id)
+  WHERE status = 'active';
+
+CREATE INDEX IF NOT EXISTS idx_facts_active_agent
+  ON ${schema}.facts (tenant_id, agent_id, importance DESC, last_confirmed_at DESC)
+  WHERE status = 'active';
+
+CREATE INDEX IF NOT EXISTS idx_facts_status_created
+  ON ${schema}.facts (tenant_id, status, first_seen_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_facts_subject
+  ON ${schema}.facts (tenant_id, subject_key);
+
+CREATE INDEX IF NOT EXISTS idx_facts_source_session
+  ON ${schema}.facts (source_session_id)
+  WHERE source_session_id IS NOT NULL;
+
+COMMENT ON TABLE ${schema}.facts IS 'Fact candidates and active facts per (tenant, subject, agent) with consolidation lifecycle';
+
+-- =========================================================================
+-- Fact ↔ Entity join (optional, only when entities enabled)
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.fact_entities (
+  id         BIGSERIAL    PRIMARY KEY,
+  fact_id    BIGINT       NOT NULL REFERENCES ${schema}.facts(id) ON DELETE CASCADE,
+  entity_id  BIGINT       NOT NULL,
+  UNIQUE (fact_id, entity_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_fact_entities_entity_id
+  ON ${schema}.fact_entities (entity_id);
+
+COMMENT ON TABLE ${schema}.fact_entities IS 'Join table linking facts to entities (FK to entities is soft — entities table is optional)';

package/scripts/diagnose-fts-zh.js

@@ -1,161 +1,195 @@
 'use strict';
 
 /**
- * FTS 中文診斷：檢查 'simple' tokenizer 在實際中文資料上的表現
+ * Aquifer FTS 中文診斷
  *
- * 測試項目：
- * 1. FTS tokenization — 實際 token 長什麼樣
- * 2. FTS recall — 常見中文查詢的命中率
- * 3. FTS vs vector — FTS 有沒有在幫忙還是在拖後腿
+ * 測 aquifer 實際搜尋主路徑（trigram ILIKE on search_text + similarity ranking）
+ * vs fallback 路徑（tsvector @@ plainto_tsquery('simple', q)）對中文 query 的表現。
+ *
+ * env:
+ *   DATABASE_URL       — required
+ *   AQUIFER_SCHEMA     — default 'public'
+ *   DIAGNOSE_QUERIES   — comma-separated, overrides built-in set
  */
 
 const { Pool } = require('pg');
 
-const DB_URL = process.env.DATABASE_URL || 'postgresql://burk:790476@localhost:5432/openclaw_db';
-const SCHEMA = process.env.AQUIFER_SCHEMA || 'miranda';
+const DB_URL = process.env.DATABASE_URL;
+if (!DB_URL) {
+  console.error('DATABASE_URL is required');
+  process.exit(2);
+}
+const SCHEMA = process.env.AQUIFER_SCHEMA || 'public';
+
+const DEFAULT_QUERIES = [
+  // latin
+  'afterburn', 'bootstrap', 'session', 'recall', 'entity', 'OpenCode', 'Jenny', 'Aquifer',
+  // CJK short tokens — 最容易暴露 tokenizer 問題
+  '記憶', '時區', '去重', '架構', '修復',
+  // CJK phrase
+  '消化模式', 'daily entries',
+];
+const QUERIES = process.env.DIAGNOSE_QUERIES
+  ? process.env.DIAGNOSE_QUERIES.split(',').map(s => s.trim()).filter(Boolean)
+  : DEFAULT_QUERIES;
 
 const pool = new Pool({ connectionString: DB_URL });
+const qi = (s) => `"${s.replace(/"/g, '""')}"`;
 
-async function run() {
-  const qi = (s) => `"${s}"`;
-
-  console.log('=== FTS 中文診斷 ===\n');
-
-  // 1. 看 token 分佈
-  console.log('--- 1. Token 分析 ---');
-  const tokenSample = await pool.query(`
-    SELECT ss.session_id,
-           array_length(tsvector_to_array(ss.search_tsv), 1) as token_count,
-           left(ss.summary_text, 80) as preview
-    FROM ${qi(SCHEMA)}.session_summaries ss
-    WHERE ss.search_tsv IS NOT NULL
-    ORDER BY ss.updated_at DESC
-    LIMIT 10
-  `);
-
-  let totalTokens = 0;
-  let sessionCount = 0;
-  for (const r of tokenSample.rows) {
-    totalTokens += r.token_count || 0;
-    sessionCount++;
-    console.log(`  ${r.session_id?.slice(0, 8)} | ${r.token_count || 0} tokens | ${r.preview}`);
-  }
-  console.log(`  avg: ${sessionCount ? Math.round(totalTokens / sessionCount) : 0} tokens/session\n`);
+function pct(n, d) {
+  if (d === 0) return n === 0 ? '—' : '∞%';
+  return `${Math.round((n / d) * 100)}%`;
+}
 
-  // 2. 看一個 session 的實際 token
-  console.log('--- 2. Token 範例（最近 session）---');
+async function main() {
+  console.log(`=== Aquifer FTS 中文診斷 (schema=${SCHEMA}) ===\n`);
+
+  // -------------------------------------------------------------------------
+  // 0. 覆蓋率：search_text NULL 率 → 看 fallback 觸發比例
+  // -------------------------------------------------------------------------
+  const cov = await pool.query(`
+    SELECT
+      COUNT(*)                                          AS total,
+      COUNT(*) FILTER (WHERE search_text IS NOT NULL)   AS with_text,
+      COUNT(*) FILTER (WHERE search_tsv  IS NOT NULL)   AS with_tsv,
+      COUNT(*) FILTER (WHERE search_text IS NULL
+                         AND search_tsv  IS NOT NULL)   AS tsv_only
+    FROM ${qi(SCHEMA)}.session_summaries
+  `);
+  const c = cov.rows[0];
+  console.log('--- 0. 搜尋欄位覆蓋率 ---');
+  console.log(`  total rows       : ${c.total}`);
+  console.log(`  has search_text  : ${c.with_text} (${pct(c.with_text, c.total)})`);
+  console.log(`  has search_tsv   : ${c.with_tsv} (${pct(c.with_tsv, c.total)})`);
+  console.log(`  tsv-only (NULL search_text, falls back to FTS): ${c.tsv_only} (${pct(c.tsv_only, c.total)})\n`);
+
+  // -------------------------------------------------------------------------
+  // 1. Token 範例（tsvector lexeme 粒度觀察）
+  // -------------------------------------------------------------------------
+  console.log('--- 1. tsvector lexeme 粒度範例（最近 1 筆）---');
   const tokenDetail = await pool.query(`
-    SELECT ss.session_id,
-           array_to_string(tsvector_to_array(ss.search_tsv), ' | ') as tokens
-    FROM ${qi(SCHEMA)}.session_summaries ss
-    WHERE ss.search_tsv IS NOT NULL
-    ORDER BY ss.updated_at DESC
+    SELECT session_id,
+           array_length(tsvector_to_array(search_tsv), 1) AS token_count,
+           array_to_string(tsvector_to_array(search_tsv), ' | ') AS tokens
+    FROM ${qi(SCHEMA)}.session_summaries
+    WHERE search_tsv IS NOT NULL
+    ORDER BY updated_at DESC
     LIMIT 1
   `);
   if (tokenDetail.rows[0]) {
-    console.log(`  session: ${tokenDetail.rows[0].session_id?.slice(0, 8)}`);
-    const tokens = tokenDetail.rows[0].tokens || '';
-    // 分類 token
-    const all = tokens.split(' | ');
+    const r = tokenDetail.rows[0];
+    const all = (r.tokens || '').split(' | ').filter(Boolean);
     const cjk = all.filter(t => /[\u4e00-\u9fff]/.test(t));
     const latin = all.filter(t => /^[a-z0-9]/.test(t));
-    const other = all.filter(t => !(/[\u4e00-\u9fff]/.test(t)) && !(/^[a-z0-9]/.test(t)));
-    console.log(`  total: ${all.length} | latin: ${latin.length} | cjk: ${cjk.length} | other: ${other.length}`);
-    console.log(`  CJK tokens (前 20): ${cjk.slice(0, 20).join(' | ')}`);
-    console.log(`  Latin tokens (前 20): ${latin.slice(0, 20).join(' | ')}\n`);
+    console.log(`  session: ${String(r.session_id).slice(0, 8)} | total tokens: ${r.token_count || 0}`);
+    console.log(`  latin: ${latin.length} | cjk-containing: ${cjk.length}`);
+    console.log(`  CJK lexemes (前 15): ${cjk.slice(0, 15).join(' | ')}`);
+    console.log(`  → CJK lexeme 若是 phrase 級（整句無空白），簡 tokenizer 對中文短 query 會 miss\n`);
+  } else {
+    console.log('  (no rows)\n');
   }
 
-  // 3. 中文查詢命中率測試
-  console.log('--- 3. 中文查詢 FTS 命中率 ---');
-  const testQueries = [
-    'afterburn',
-    'bootstrap',
-    'session',
-    'recall',
-    '記憶',
-    '修復',
-    '架構',
-    '時區',
-    '去重',
-    'daily entries',
-    'OpenCode',
-    'entity',
-    'Jenny',
-    'Aquifer',
-    '消化模式',
-  ];
-
-  // 總 session 數
-  const totalResult = await pool.query(`
-    SELECT COUNT(*) as cnt FROM ${qi(SCHEMA)}.session_summaries WHERE search_tsv IS NOT NULL
-  `);
-  const totalSessions = parseInt(totalResult.rows[0].cnt);
-  console.log(`  total sessions with FTS index: ${totalSessions}\n`);
-
-  for (const q of testQueries) {
-    const ftsResult = await pool.query(`
-      SELECT COUNT(*) as cnt
-      FROM ${qi(SCHEMA)}.session_summaries ss
-      WHERE ss.search_tsv @@ plainto_tsquery('simple', $1)
-    `, [q]);
-    const ftsHits = parseInt(ftsResult.rows[0].cnt);
-
-    // 同時看 summary_text ILIKE 能找到幾筆（ground truth）
-    const ilikeResult = await pool.query(`
-      SELECT COUNT(*) as cnt
-      FROM ${qi(SCHEMA)}.session_summaries ss
-      WHERE ss.summary_text ILIKE $1
-         OR ss.structured_summary::text ILIKE $1
-    `, [`%${q}%`]);
-    const ilikeHits = parseInt(ilikeResult.rows[0].cnt);
-
-    const ftsRecall = ilikeHits > 0 ? Math.round(ftsHits / ilikeHits * 100) : (ftsHits === 0 ? 100 : 0);
-    const status = ftsHits === ilikeHits ? '✓' : (ftsHits < ilikeHits ? '✗ MISS' : '?');
-    console.log(`  "${q}" | FTS: ${ftsHits} | ILIKE: ${ilikeHits} | recall: ${ftsRecall}% | ${status}`);
-  }
-
-  // 4. FTS 對 RRF 的貢獻度
-  console.log('\n--- 4. FTS 在 hybrid search 中的貢獻度 ---');
-  // 跑幾個查詢，看 FTS 跟 vector 的 session 重疊率
-  const overlapQueries = ['afterburn', 'bootstrap', '記憶', 'recall', 'entity'];
-  for (const q of overlapQueries) {
-    const ftsResult = await pool.query(`
-      SELECT ss.session_id
-      FROM ${qi(SCHEMA)}.session_summaries ss
-      JOIN ${qi(SCHEMA)}.sessions s ON s.id = ss.session_row_id
-      WHERE ss.search_tsv @@ plainto_tsquery('simple', $1)
-        AND s.processing_status = 'succeeded'
-      ORDER BY ts_rank(ss.search_tsv, plainto_tsquery('simple', $1)) DESC
-      LIMIT 10
-    `, [q]);
-    const ftsIds = new Set(ftsResult.rows.map(r => r.session_id));
-
-    // vector search (if embedding available)
-    const embResult = await pool.query(`
-      SELECT ss.session_id
-      FROM ${qi(SCHEMA)}.session_summaries ss
-      JOIN ${qi(SCHEMA)}.sessions s ON s.id = ss.session_row_id
-      WHERE ss.embedding IS NOT NULL
-        AND s.processing_status = 'succeeded'
-      ORDER BY ss.embedding <=> (
-        SELECT ss2.embedding FROM ${qi(SCHEMA)}.session_summaries ss2
-        WHERE ss2.search_tsv @@ plainto_tsquery('simple', $1)
-        ORDER BY ts_rank(ss2.search_tsv, plainto_tsquery('simple', $1)) DESC
-        LIMIT 1
+  // -------------------------------------------------------------------------
+  // 2. 主路徑 vs fallback：binary match 比對
+  //
+  // Ground truth = search_text ILIKE '%q%'（所有源欄位拼出的純文字 superset）
+  // 主路徑        = search_text ILIKE（GIN trgm 加速，語意等價 ILIKE）
+  // Fallback     = search_tsv @@ plainto_tsquery('simple', q)
+  // -------------------------------------------------------------------------
+  console.log('--- 2. 主路徑（trigram）vs fallback（tsvector）binary match ---');
+  console.log('  query               | truth | trgm  | tsv   | trgm% | tsv%  | tsv-extra');
+  console.log('  ' + '-'.repeat(82));
+
+  const rowCount = await pool.query(
+    `SELECT COUNT(*) AS n FROM ${qi(SCHEMA)}.session_summaries WHERE search_text IS NOT NULL`
+  );
+  const withTextN = parseInt(rowCount.rows[0].n, 10);
+  console.log(`  (ground truth 基數：含 search_text 的 row ${withTextN})`);
+
+  const summary = [];
+  for (const q of QUERIES) {
+    const r = await pool.query(
+      `
+      WITH base AS (
+        SELECT search_text,
+               search_tsv,
+               (search_text ILIKE '%' || $1 || '%')                                 AS trgm_hit,
+               (search_tsv  @@ plainto_tsquery('simple', $2))                       AS tsv_hit
+        FROM ${qi(SCHEMA)}.session_summaries
+        WHERE search_text IS NOT NULL
       )
-      LIMIT 10
-    `, [q]);
-    const embIds = new Set(embResult.rows.map(r => r.session_id));
-
-    const overlap = [...ftsIds].filter(id => embIds.has(id)).length;
-    const ftsOnly = [...ftsIds].filter(id => !embIds.has(id)).length;
-    const embOnly = [...embIds].filter(id => !ftsIds.has(id)).length;
-
-    console.log(`  "${q}" | FTS top10: ${ftsIds.size} | Vec top10: ${embIds.size} | overlap: ${overlap} | FTS-only: ${ftsOnly} | Vec-only: ${embOnly}`);
+      SELECT
+        COUNT(*) FILTER (WHERE trgm_hit)                         AS truth,
+        COUNT(*) FILTER (WHERE trgm_hit)                         AS trgm,
+        COUNT(*) FILTER (WHERE tsv_hit)                          AS tsv,
+        COUNT(*) FILTER (WHERE tsv_hit AND NOT trgm_hit)         AS tsv_extra
+      FROM base
+      `,
+      [q.replace(/[%_\\]/g, '\\$&'), q]
+    );
+    const { truth, trgm, tsv, tsv_extra } = r.rows[0];
+    const T = parseInt(truth, 10);
+    const A = parseInt(trgm, 10);
+    const B = parseInt(tsv, 10);
+    const E = parseInt(tsv_extra, 10);
+    summary.push({ q, T, A, B, E });
+    console.log(
+      `  ${q.padEnd(19)} | ${String(T).padStart(5)} | ${String(A).padStart(5)} | ${String(B).padStart(5)} | ${pct(A, T).padStart(5)} | ${pct(B, T).padStart(5)} | ${String(E).padStart(5)}`
+    );
+  }
+  console.log('  (tsv-extra = tsvector 命中但 trigram 沒命中 → 通常是 0，代表 tsv 對整體搜尋無額外貢獻)\n');
+
+  // -------------------------------------------------------------------------
+  // 3. Ranking 品質對比：舊 ranking (similarity only) vs 新 ranking (substr-hit first)
+  // -------------------------------------------------------------------------
+  console.log('--- 3. Ranking 品質對比：top-5 substring-hit 命中率 ---');
+  console.log('  query               | truth | old (sim only) | new (hit+sim)');
+  console.log('  ' + '-'.repeat(70));
+  for (const q of QUERIES) {
+    const like = q.replace(/[%_\\]/g, '\\$&');
+    const truthR = await pool.query(
+      `SELECT COUNT(*) AS n
+         FROM ${qi(SCHEMA)}.session_summaries
+         WHERE search_text ILIKE '%' || $1 || '%'`,
+      [like]
+    );
+    const T = parseInt(truthR.rows[0].n, 10);
+
+    const oldR = await pool.query(
+      `
+      SELECT (search_text ILIKE '%' || $1 || '%') AS substr_hit
+      FROM ${qi(SCHEMA)}.session_summaries
+      WHERE search_text IS NOT NULL
+      ORDER BY similarity(search_text, $2) DESC
+      LIMIT 5
+      `,
+      [like, q]
+    );
+    const oldHits = oldR.rows.filter(x => x.substr_hit).length;
+
+    const newR = await pool.query(
+      `
+      SELECT (search_text ILIKE '%' || $1 || '%') AS substr_hit
+      FROM ${qi(SCHEMA)}.session_summaries
+      WHERE search_text IS NOT NULL
+      ORDER BY
+        (search_text ILIKE '%' || $1 || '%') DESC,
+        similarity(search_text, $2) DESC
+      LIMIT 5
+      `,
+      [like, q]
+    );
+    const newHits = newR.rows.filter(x => x.substr_hit).length;
+
+    const expected = Math.min(5, T);
+    console.log(
+      `  ${q.padEnd(19)} | ${String(T).padStart(5)} | ${String(oldHits).padStart(3)}/5 → ${String(expected).padStart(1)}/5 ${oldHits < expected ? '✗' : '✓'}      | ${String(newHits).padStart(3)}/5 ${newHits < expected ? '✗' : '✓'}`
+    );
   }
+  console.log('  (truth = 含該字串的 row 數；ideal top-5 substr-hit = min(truth, 5))');
 
   await pool.end();
   console.log('\n=== 完成 ===');
 }
 
-run().catch(err => { console.error(err); process.exit(1); });
+main().catch(err => { console.error(err); process.exit(1); });