@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/src/facets/classifier.mjs

@@ -0,0 +1,146 @@
+/**
+ * Tiny local facet classifier (multinomial Naive Bayes over char bigrams).
+ *
+ * This is the "small model" seam: it learns from accepted facet labels and can
+ * be replaced by an ONNX embedding/SetFit model later without changing the
+ * index/query API. No external dependency.
+ */
+import { SLOTS, VALUES, normalizeFacets } from './schema.mjs';
+
+const ALPHA = 1;
+
+function tokens(text) {
+  const source = String(text ?? '').toLowerCase();
+  const out = [];
+  const words = source.match(/[a-z0-9_]+/g) ?? [];
+  for (const word of words) out.push(`w:${word}`);
+  for (const chunk of source.match(/[\u4e00-\u9fff]+/g) ?? []) {
+    const chars = [...chunk];
+    for (let i = 0; i < chars.length; i += 1) {
+      out.push(`c:${chars[i]}`);
+      if (i + 1 < chars.length) out.push(`b:${chars[i]}${chars[i + 1]}`);
+    }
+  }
+  return [...new Set(out)].slice(0, 800);
+}
+
+export function trainFacetClassifier(rows) {
+  const model = { version: 1, slots: {}, vocab: new Set() };
+  for (const slot of SLOTS) {
+    model.slots[slot] = {
+      docs: 0,
+      values: Object.fromEntries(VALUES[slot].map((value) => [value, { docs: 0, tokens: new Map(), total: 0 }])),
+    };
+  }
+  for (const row of rows) {
+    const facets = normalizeFacets(row.facets ?? {});
+    const list = tokens(row.text);
+    for (const token of list) model.vocab.add(token);
+    for (const slot of SLOTS) {
+      const value = facets[slot];
+      if (value === undefined) continue;
+      const bucket = model.slots[slot];
+      const cell = bucket.values[value];
+      bucket.docs += 1;
+      cell.docs += 1;
+      for (const token of list) {
+        cell.tokens.set(token, (cell.tokens.get(token) ?? 0) + 1);
+        cell.total += 1;
+      }
+    }
+  }
+  model.vocab = [...model.vocab];
+  return model;
+}
+
+export function predictFacets(model, text) {
+  const list = tokens(text);
+  const facets = {};
+  const confidence = {};
+  for (const slot of SLOTS) {
+    const bucket = model.slots?.[slot];
+    if (!bucket || bucket.docs === 0) continue;
+    const vocabSize = Math.max(1, model.vocab?.length ?? 1);
+    const scored = [];
+    for (const value of VALUES[slot]) {
+      const cell = bucket.values[value];
+      if (!cell || cell.docs === 0) continue;
+      let score = Math.log((cell.docs + ALPHA) / (bucket.docs + ALPHA * VALUES[slot].length));
+      const denom = cell.total + ALPHA * vocabSize;
+      for (const token of list) {
+        const count = cell.tokens.get(token) ?? 0;
+        score += Math.log((count + ALPHA) / denom);
+      }
+      scored.push({ value, score });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    if (scored.length === 0) continue;
+    const top = scored[0];
+    const second = scored[1];
+    const margin = second === undefined ? 1 : top.score - second.score;
+    if (margin < 0.2) continue;
+    facets[slot] = top.value;
+    confidence[slot] = Math.min(1, margin / 2);
+  }
+  return { facets, confidence, unknown: Object.keys(facets).length === 0 };
+}
+
+export function evaluate(model, rows) {
+  const report = {};
+  for (const slot of SLOTS) {
+    let total = 0;
+    let correct = 0;
+    let covered = 0;
+    for (const row of rows) {
+      const truth = normalizeFacets(row.facets ?? {})[slot];
+      if (truth === undefined) continue;
+      total += 1;
+      const predicted = predictFacets(model, row.text).facets[slot];
+      if (predicted === undefined) continue;
+      covered += 1;
+      if (predicted === truth) correct += 1;
+    }
+    report[slot] = {
+      total,
+      covered,
+      correct,
+      coverage: total === 0 ? 0 : covered / total,
+      accuracy: covered === 0 ? 0 : correct / covered,
+    };
+  }
+  return report;
+}
+
+export function classifierExtractor(model) {
+  return (text) => predictFacets(model, text);
+}
+
+export function serializeClassifier(model) {
+  const slots = {};
+  for (const [slot, bucket] of Object.entries(model.slots ?? {})) {
+    slots[slot] = {
+      docs: bucket.docs,
+      values: Object.fromEntries(Object.entries(bucket.values).map(([value, cell]) => [value, {
+        docs: cell.docs,
+        total: cell.total,
+        tokens: [...cell.tokens.entries()],
+      }])),
+    };
+  }
+  return { version: 1, vocab: model.vocab ?? [], slots };
+}
+
+export function deserializeClassifier(raw) {
+  const model = { version: 1, vocab: Array.isArray(raw?.vocab) ? raw.vocab : [], slots: {} };
+  for (const [slot, bucket] of Object.entries(raw?.slots ?? {})) {
+    model.slots[slot] = {
+      docs: Number(bucket.docs) || 0,
+      values: Object.fromEntries(Object.entries(bucket.values ?? {}).map(([value, cell]) => [value, {
+        docs: Number(cell.docs) || 0,
+        total: Number(cell.total) || 0,
+        tokens: new Map(Array.isArray(cell.tokens) ? cell.tokens : []),
+      }])),
+    };
+  }
+  return model;
+}

package/src/facets/embedding-service.mjs

@@ -0,0 +1,53 @@
+/**
+ * Main-thread client for the embedding facet worker.
+ */
+import { Worker } from 'node:worker_threads';
+
+export function createEmbeddingFacetService({ prototypesPath, model, nbModelPath, timeoutMs = 120000 } = {}) {
+  if (typeof prototypesPath !== 'string' || prototypesPath.length === 0) {
+    throw new Error('embedding service: prototypesPath is required');
+  }
+  const worker = new Worker(new URL('./embedding-worker.mjs', import.meta.url), {
+    workerData: { prototypesPath, model, nbModelPath },
+  });
+  let nextId = 1;
+  const pending = new Map();
+
+  worker.on('message', (message) => {
+    const entry = pending.get(message?.id);
+    if (entry === undefined) return;
+    pending.delete(message.id);
+    clearTimeout(entry.timer);
+    if (message.ok) entry.resolve(message.result);
+    else entry.reject(new Error(message.error));
+  });
+  worker.on('error', (error) => {
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    pending.clear();
+  });
+
+  return {
+    extract(text) {
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error('embedding service: timeout'));
+        }, timeoutMs);
+        pending.set(id, { resolve, reject, timer });
+        worker.postMessage({ id, text: String(text ?? '') });
+      });
+    },
+    async close() {
+      for (const entry of pending.values()) {
+        clearTimeout(entry.timer);
+        entry.reject(new Error('embedding service: closed'));
+      }
+      pending.clear();
+      await worker.terminate();
+    },
+  };
+}

package/src/facets/embedding-worker.mjs

@@ -0,0 +1,27 @@
+/**
+ * Embedding facet worker. Loads prototypes and the ONNX/WASM embedding model
+ * inside worker_threads; the host never blocks on model inference.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import fs from 'node:fs';
+import { deserializePrototypes, fuseFacets, predictEmbedding } from './embedding.mjs';
+import { deserializeClassifier } from './classifier.mjs';
+import { hybridExtractor } from './hybrid.mjs';
+
+const prototypes = deserializePrototypes(JSON.parse(fs.readFileSync(workerData.prototypesPath, 'utf8')));
+const model = workerData.model ?? prototypes.model;
+const fallback = workerData.nbModelPath
+  ? hybridExtractor(deserializeClassifier(JSON.parse(fs.readFileSync(workerData.nbModelPath, 'utf8'))))
+  : null;
+
+parentPort.on('message', async (message) => {
+  const id = message?.id;
+  try {
+    const text = String(message?.text ?? '');
+    const embedded = await predictEmbedding(prototypes, text, model);
+    const result = fallback === null ? embedded : fuseFacets(embedded, fallback(text));
+    parentPort.postMessage({ id, ok: true, result });
+  } catch (error) {
+    parentPort.postMessage({ id, ok: false, error: String(error?.message ?? error) });
+  }
+});

package/src/facets/embedding.mjs

@@ -0,0 +1,163 @@
+/**
+ * Local embedding prototypes for facets.
+ *
+ * Uses transformers.js (ONNX/WASM) with a multilingual small embedding model.
+ * The model is downloaded once into the local HF cache; no text leaves the
+ * machine. Prototypes are built from accepted facet labels.
+ */
+import { SLOTS, VALUES, normalizeFacets } from './schema.mjs';
+import { detectRandom } from './random.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let extractorPromise = null;
+const MODEL_ID = 'Xenova/bge-small-zh-v1.5';
+const LOCAL_MODELS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../models');
+
+export async function loadEmbedder(model = MODEL_ID) {
+  if (extractorPromise !== null) return extractorPromise;
+  const { pipeline, env } = await import('@huggingface/transformers');
+  const localConfig = path.join(LOCAL_MODELS, model, 'config.json');
+  if (fs.existsSync(localConfig)) {
+    env.allowRemoteModels = false;
+    env.localModelPath = LOCAL_MODELS;
+  } else {
+    env.allowRemoteModels = true;
+    env.remoteHost = process.env.FACET_HF_ENDPOINT || 'https://hf-mirror.com';
+  }
+  try {
+    extractorPromise = await pipeline('feature-extraction', model, { dtype: 'q8' });
+  } catch (error) {
+    extractorPromise = null;
+    throw new Error(
+      'embedding runtime unavailable: '
+      + `${error?.message ?? error}. `
+      + 'If pnpm skipped onnxruntime-node, run "pnpm approve-builds" then '
+      + '"pnpm rebuild onnxruntime-node sharp" in the DSH profile, and retry.',
+    );
+  }
+  return extractorPromise;
+}
+
+export async function embedTexts(texts, model) {
+  const extractor = await loadEmbedder(model);
+  const output = await extractor(texts, { pooling: 'mean', normalize: true });
+  return output.tolist();
+}
+
+function normalizeVector(vector) {
+  const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0)) || 1;
+  return vector.map((value) => value / norm);
+}
+
+function average(vectors) {
+  if (vectors.length === 0) return [];
+  const dims = vectors[0].length;
+  const sum = new Array(dims).fill(0);
+  for (const vector of vectors) {
+    for (let i = 0; i < dims; i += 1) sum[i] += vector[i];
+  }
+  return normalizeVector(sum.map((value) => value / vectors.length));
+}
+
+function cosine(a, b) {
+  if (a.length !== b.length) return 0;
+  let dot = 0;
+  for (let i = 0; i < a.length; i += 1) dot += a[i] * b[i];
+  return dot;
+}
+
+export async function buildEmbeddingPrototypes(rows, model) {
+  const source = rows.filter((row) => row.text && row.facets);
+  const vectors = await embedTexts(source.map((row) => row.text), model);
+  const slots = {};
+  for (const slot of SLOTS) {
+    slots[slot] = { values: {} };
+    for (const value of VALUES[slot]) {
+      const selected = [];
+      source.forEach((row, index) => {
+        if (normalizeFacets(row.facets)[slot] === value) selected.push(vectors[index]);
+      });
+      if (selected.length > 0) slots[slot].values[value] = average(selected);
+    }
+  }
+  return { model, slots };
+}
+
+export async function predictEmbedding(prototypes, text, model) {
+  const [vector] = await embedTexts([text], model ?? prototypes.model);
+  const facets = {};
+  const confidence = {};
+  for (const slot of SLOTS) {
+    let best = null;
+    let second = null;
+    for (const [value, centroid] of Object.entries(prototypes.slots?.[slot]?.values ?? {})) {
+      const score = cosine(vector, centroid);
+      if (best === null || score > best.score) {
+        second = best;
+        best = { value, score };
+      } else if (second === null || score > second.score) {
+        second = { value, score };
+      }
+    }
+    if (best === null) continue;
+    const margin = second === null ? 1 : best.score - second.score;
+    if (margin < 0.01) continue;
+    facets[slot] = best.value;
+    confidence[slot] = margin;
+  }
+  const random = detectRandom(text);
+  facets.random = random.value;
+  confidence.random = random.value === '有' ? 1 : 0.5;
+  return {
+    facets,
+    confidence,
+    unknown: !Object.keys(facets).some((slot) => slot !== 'random'),
+  };
+}
+
+export function embeddingExtractor(prototypes, model) {
+  return async (text) => predictEmbedding(prototypes, text, model);
+}
+
+export function serializePrototypes(prototypes) {
+  return {
+    model: prototypes.model,
+    slots: Object.fromEntries(Object.entries(prototypes.slots ?? {}).map(([slot, bucket]) => [slot, {
+      values: Object.fromEntries(Object.entries(bucket.values ?? {})),
+    }])),
+  };
+}
+
+export function deserializePrototypes(raw) {
+  return {
+    model: raw?.model,
+    slots: Object.fromEntries(Object.entries(raw?.slots ?? {}).map(([slot, bucket]) => [slot, {
+      values: Object.fromEntries(Object.entries(bucket.values ?? {})),
+    }])),
+  };
+}
+
+/**
+ * Slot-aware fusion: embedding wins only where it is calibrated; participants
+ * stays with the local NB because embedding prototypes overfit that slot.
+ */
+export function fuseFacets(embedding, fallback, {
+  embeddingSlots = ['activity', 'interaction', 'medium', 'topic'],
+} = {}) {
+  const facets = { ...fallback.facets };
+  const confidence = { ...fallback.confidence };
+  for (const slot of embeddingSlots) {
+    if (embedding?.facets?.[slot] === undefined) continue;
+    facets[slot] = embedding.facets[slot];
+    confidence[slot] = embedding.confidence?.[slot] ?? 0;
+  }
+  if (embedding?.facets?.random !== undefined) facets.random = embedding.facets.random;
+  return {
+    facets,
+    confidence,
+    unknown: !Object.keys(facets).some((slot) => slot !== 'random'),
+  };
+}
+

package/src/facets/extract.mjs

@@ -0,0 +1,80 @@
+/**
+ * Rule-based fallback extractor for facet MVP.
+ *
+ * This is intentionally not an LLM. It gives the index/query path something
+ * runnable before a local ONNX classifier is added. Missing slots stay missing;
+ * they are not guessed.
+ */
+import { SLOTS, VALUES, normalizeFacets } from './schema.mjs';
+
+const LEXICON = {
+  activity: {
+    跑团: ['跑团', '掷骰', '骰子', 'D20', '角色卡', '检定', 'KP', '守渡人', '剧情推进'],
+    开发: ['开发', '实现', '写代码', '补丁', '插件', '接口'],
+    调试: ['调试', '排查', '探针', '日志', '报错', '崩溃'],
+    测试: ['测试', '自检', '验收', '用例', '回归'],
+    文档: ['文档', '手册', '说明', 'README', '写文档'],
+    对话: ['对话', '聊天', '你觉得', '感受', '关系'],
+  },
+  interaction: {
+    回合制: ['回合', '轮到我', '下一回合', '行动', '掷骰'],
+    指令式: ['命令', '执行', '运行', '工具', '脚本'],
+    自由对话: ['聊天', '对话', '问', '回答'],
+  },
+  random: {
+    有: ['掷骰', '骰子', 'D20', '随机', '概率', '检定'],
+    无: [],
+  },
+  participants: {
+    单人: ['单人', '我自己', '独自'],
+    多人: ['多人'],
+    协作: ['协作', '一起', '帮我', '我们', '配合'],
+    对抗: ['对抗', '敌人', '战斗'],
+  },
+  medium: {
+    文字: ['文字', '正文', '文本', '故事'],
+    代码: ['代码', '函数', '源码', '脚本'],
+    图像: ['图片', '头像', '画图', '图像'],
+    语音: ['语音', '口述'],
+  },
+  topic: {
+    剧情: ['剧情', '故事', '角色', '场景', '任务'],
+    技术: ['技术', '代码', '插件', '系统', '接口'],
+    设备: ['设备', '手机', '电脑', '硬件'],
+    记忆: ['记忆', '回忆', '上下文', '线头'],
+    规则: ['规则', '判据', '阈值', '闸', '约束'],
+  },
+};
+
+function scoreSlot(text, slot) {
+  const values = LEXICON[slot] ?? {};
+  let best = null;
+  for (const [value, words] of Object.entries(values)) {
+    if (!VALUES[slot].includes(value)) continue;
+    let score = 0;
+    for (const word of words) {
+      if (text.includes(word)) score += 1;
+    }
+    if (score > 0 && (best === null || score > best.score)) best = { value, score };
+  }
+  return best;
+}
+
+export function extractFacets(text) {
+  const source = String(text ?? '');
+  const facets = {};
+  const evidence = {};
+  for (const slot of SLOTS) {
+    const hit = scoreSlot(source, slot);
+    if (hit !== null) {
+      facets[slot] = hit.value;
+      evidence[slot] = hit.score;
+    }
+  }
+  // random is binary: if the text has no random signal, it is not guessed here.
+  return {
+    facets: normalizeFacets(facets),
+    evidence,
+    unknown: Object.keys(facets).length === 0,
+  };
+}

package/src/facets/fold-plan.mjs

@@ -0,0 +1,84 @@
+/**
+ * Facet-aware fold planning.
+ *
+ * Produces candidate contiguous ranges for the high-trigger compaction path.
+ * The engine still decides policy; this module only ranks old ranges and
+ * protects high-relevance current-topic turns.
+ */
+import { facetScore } from './sensitivity.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function loadFacetFoldFile(file) {
+  const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const entries = Array.isArray(raw?.entries) ? raw.entries : [];
+  const query = raw?.query ?? {};
+  const idf = new Map(Array.isArray(raw?.idf) ? raw.idf : []);
+  return { entries, query, idf };
+}
+
+export function defaultFacetFoldFile({
+  home = process.env.USERPROFILE ?? process.env.HOME,
+} = {}) {
+  return path.join(String(home ?? ''), '.dsh', 'continuity', 'facet-fold.json');
+}
+
+export function planFacetFold(entries, {
+  query = {},
+  idf = null,
+  recentTurns = 20,
+  budgetTokens = 20000,
+  tokensBySeq = new Map(),
+  protectScore = 0.5,
+} = {}) {
+  if (entries.length === 0) return { ranges: [], protected: [], seqs: [], tokens: 0 };
+  const latestTurn = Math.max(...entries.map((entry) => entry.turn));
+  const protectedEntries = [];
+  const candidates = [];
+  for (const entry of entries) {
+    const score = facetScore(entry.facets, query, idf).score;
+    const old = latestTurn - entry.turn > recentTurns;
+    if (score >= protectScore || !old) {
+      protectedEntries.push({ turn: entry.turn, seqStart: entry.seqStart, seqEnd: entry.seqEnd, score });
+      continue;
+    }
+    candidates.push({ ...entry, score, priority: (1 - Math.min(1, score)) * (latestTurn - entry.turn) });
+  }
+  candidates.sort((a, b) => b.priority - a.priority);
+
+  const ranges = [];
+  let used = 0;
+  const usedSeqs = new Set();
+  for (const entry of candidates) {
+    const seqs = [];
+    const start = Number(entry.seqStart);
+    const end = Number(entry.seqEnd);
+    if (!Number.isInteger(start) || !Number.isInteger(end) || end < start) continue;
+    let tokens = 0;
+    for (let seq = start; seq <= end; seq += 1) {
+      if (usedSeqs.has(seq)) continue;
+      const next = Number(tokensBySeq.get?.(seq) ?? 0);
+      if (used + tokens + next > budgetTokens) break;
+      seqs.push(seq);
+      tokens += next;
+    }
+    if (seqs.length === 0) continue;
+    for (const seq of seqs) usedSeqs.add(seq);
+    used += tokens;
+    ranges.push({
+      seqStart: seqs[0],
+      seqEnd: seqs[seqs.length - 1],
+      turns: 1,
+      tokens,
+      score: entry.score,
+      priority: entry.priority,
+    });
+    if (used >= budgetTokens) break;
+  }
+  return {
+    ranges,
+    protected: protectedEntries,
+    seqs: [...usedSeqs].sort((a, b) => a - b),
+    tokens: used,
+  };
+}

package/src/facets/hybrid.mjs

@@ -0,0 +1,29 @@
+/**
+ * Hybrid local extractor: Naive Bayes for the learned slots, explicit rules for
+ * binary signals that the tiny student model cannot learn from 100 examples.
+ */
+import { predictFacets } from './classifier.mjs';
+import { detectRandom } from './random.mjs';
+
+export function hybridExtractor(model, { minConfidence = 0 } = {}) {
+  const threshold = Number(minConfidence) || 0;
+  return (text) => {
+    const base = predictFacets(model, text);
+    const facets = { ...base.facets };
+    const confidence = { ...base.confidence };
+    const random = detectRandom(text);
+    facets.random = random.value;
+    confidence.random = random.value === '有' ? 1 : 0.5;
+    if (threshold > 0) {
+      for (const slot of Object.keys(facets)) {
+        if (slot === 'random') continue;
+        if ((confidence[slot] ?? 0) < threshold) delete facets[slot];
+      }
+    }
+    return {
+      facets,
+      confidence,
+      unknown: !Object.keys(facets).some((slot) => slot !== 'random'),
+    };
+  };
+}

package/src/facets/index.mjs

@@ -0,0 +1,113 @@
+/**
+ * Facet index + alias query. Pure data; no session reads.
+ *
+ * entries: [{ turn, seqStart, seqEnd, facets: {slot:value}, unknown }]
+ * query:  alias string -> aliasFacets() OR explicit facet object
+ */
+import { SLOTS, aliasFacets, normalizeFacets } from './schema.mjs';
+import { extractFacets } from './extract.mjs';
+
+function facetEntries(facets) {
+  return Object.entries(normalizeFacets(facets ?? {}));
+}
+
+export function buildFacetIndex(rows, { extract = extractFacets } = {}) {
+  const entries = [];
+  const df = new Map();
+  for (const row of [...rows].sort((a, b) => a.turn - b.turn)) {
+    const extracted = row.facets !== undefined
+      ? { facets: normalizeFacets(row.facets), evidence: {}, unknown: false }
+      : extract(row.text ?? '');
+    const facets = extracted.facets ?? {};
+    const keys = facetEntries(facets);
+    for (const [slot, value] of keys) {
+      const key = `${slot}:${value}`;
+      df.set(key, (df.get(key) ?? 0) + 1);
+    }
+    entries.push({
+      turn: row.turn,
+      seqStart: row.seqStart,
+      seqEnd: row.seqEnd,
+      facets,
+      unknown: extracted.unknown === true || keys.length === 0,
+    });
+  }
+  const total = entries.length;
+  const idf = new Map();
+  for (const [key, count] of df) {
+    idf.set(key, Math.log((1 + total) / (1 + count)) + 1);
+  }
+  return { entries, idf, total };
+}
+
+function resolveQuery(query, index) {
+  if (query !== null && typeof query === 'object' && !Array.isArray(query)) {
+    return { name: null, facets: normalizeFacets(query) };
+  }
+  const name = String(query ?? '').trim();
+  const facets = aliasFacets(name);
+  if (Object.keys(facets).length > 0) return { name, facets };
+  const extracted = extractFacets(name);
+  return { name, facets: extracted.facets };
+}
+
+export function queryFacets(index, query, { topK = 20, minCoverage = 0.6 } = {}) {
+  const resolved = resolveQuery(query, index);
+  const queryEntries = facetEntries(resolved.facets);
+  if (queryEntries.length === 0) return { query: resolved.name, facets: {}, matches: [], ranges: [] };
+
+  const matches = [];
+  for (const entry of index.entries) {
+    const matchesList = [];
+    let idfSum = 0;
+    for (const [slot, value] of queryEntries) {
+      if (entry.facets[slot] !== value) continue;
+      const key = `${slot}:${value}`;
+      const weight = index.idf.get(key) ?? 1;
+      idfSum += weight;
+      matchesList.push(key);
+    }
+    const coverage = matchesList.length / queryEntries.length;
+    if (coverage < minCoverage) continue;
+    matches.push({
+      turn: entry.turn,
+      seqStart: entry.seqStart,
+      seqEnd: entry.seqEnd,
+      coverage,
+      score: idfSum * coverage,
+      matched: matchesList,
+    });
+  }
+  matches.sort((a, b) => b.score - a.score || a.turn - b.turn);
+  const top = matches.slice(0, Math.max(1, topK));
+  const ranges = [];
+  for (const hit of top) {
+    const last = ranges[ranges.length - 1];
+    if (last !== undefined && hit.turn === last.lastTurn + 1) {
+      last.lastTurn = hit.turn;
+      last.seqEnd = Math.max(last.seqEnd, hit.seqEnd);
+      last.turns += 1;
+    } else {
+      ranges.push({ seqStart: hit.seqStart, seqEnd: hit.seqEnd, turns: 1, lastTurn: hit.turn, score: hit.score });
+    }
+  }
+  return {
+    query: resolved.name,
+    facets: resolved.facets,
+    matches: top,
+    ranges,
+  };
+}
+
+export function indexStats(index) {
+  const unknown = index.entries.filter((entry) => entry.unknown).length;
+  const bySlot = Object.fromEntries(SLOTS.map((slot) => [slot, {}]));
+  for (const entry of index.entries) {
+    for (const slot of SLOTS) {
+      const value = entry.facets[slot];
+      if (value === undefined) continue;
+      bySlot[slot][value] = (bySlot[slot][value] ?? 0) + 1;
+    }
+  }
+  return { total: index.total, unknown, bySlot };
+}