thumbgate 1.30.0 → 1.31.0

package/scripts/async-eval-observability.js

@@ -3,11 +3,19 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const {
+  claimSupportScore,
+  evaluateAnswerQuality,
+  queryCoverage,
+  splitAnswerClaims,
+} = require('./rag-structured-output');
 
 const DEFAULT_THRESHOLDS = {
   faithfulness: 0.72,
   answerRelevance: 0.45,
   contextPrecision: 0.5,
+  groundedness: 0.75,
+  citationPrecision: 1,
 };
 
 function tokenize(value) {
@@ -30,10 +38,7 @@ function overlapScore(left, right) {
 }
 
 function splitClaims(response) {
-  return String(response || '')
-    .split(/(?:[.!?]\s+|\n+)/)
-    .map((claim) => claim.trim())
-    .filter((claim) => claim.length > 0);
+  return splitAnswerClaims(response);
 }
 
 function normalizeContexts(contexts) {
@@ -44,11 +49,10 @@ function normalizeContexts(contexts) {
 
 function scoreFaithfulness(response, contexts) {
   const claims = splitClaims(response);
-  const contextText = normalizeContexts(contexts).join('\n');
+  const contextItems = normalizeContexts(contexts);
   if (claims.length === 0) return { score: 0, supportedClaims: 0, totalClaims: 0 };
   const supportedClaims = claims.filter((claim) => {
-    const normalized = claim.toLowerCase();
-    return contextText.toLowerCase().includes(normalized) || overlapScore(claim, contextText) >= 0.58;
+    return contextItems.some((context) => claimSupportScore(claim, context) >= 0.4);
   }).length;
   return {
     score: Number((supportedClaims / claims.length).toFixed(4)),
@@ -58,7 +62,7 @@ function scoreFaithfulness(response, contexts) {
 }
 
 function scoreAnswerRelevance(question, response) {
-  const score = overlapScore(question, response);
+  const score = queryCoverage(question, response);
   return {
     score: Number(score.toFixed(4)),
     matchedQuestionTerms: unique(tokenize(question).filter((token) => tokenize(response).includes(token))),
@@ -97,14 +101,29 @@ function evaluateGeneration(testCase, options = {}) {
     contexts,
     testCase.reference || testCase.groundTruth || ''
   );
+  const answerQuality = evaluateAnswerQuality({
+    query: testCase.question || testCase.user_input,
+    answer: testCase.response || testCase.answer,
+    referenceAnswer: testCase.reference || testCase.groundTruth || '',
+    citations: testCase.citations,
+    contexts: contexts.map((text, index) => ({ id: `context-${index + 1}`, text })),
+  }, {
+    minFaithfulness: thresholds.faithfulness,
+    minGroundedness: thresholds.groundedness,
+    minAnswerRelevance: thresholds.answerRelevance,
+  });
   const scores = {
     faithfulness: faithfulness.score,
     answerRelevance: answerRelevance.score,
     contextPrecision: contextPrecision.score,
+    groundedness: answerQuality.metrics.groundedness,
+    citationPrecision: answerQuality.metrics.citationPrecision,
   };
   const passed = scores.faithfulness >= thresholds.faithfulness
     && scores.answerRelevance >= thresholds.answerRelevance
-    && scores.contextPrecision >= thresholds.contextPrecision;
+    && scores.contextPrecision >= thresholds.contextPrecision
+    && scores.groundedness >= thresholds.groundedness
+    && scores.citationPrecision >= thresholds.citationPrecision;
 
   return {
     id: String(testCase.id || testCase.traceId || 'case'),
@@ -116,6 +135,7 @@ function evaluateGeneration(testCase, options = {}) {
       faithfulness,
       answerRelevance,
       contextPrecision,
+      answerQuality,
     },
   };
 }
@@ -155,6 +175,8 @@ function buildEvalReport(cases, options = {}) {
     faithfulness: average(results.map((result) => result.scores.faithfulness)),
     answerRelevance: average(results.map((result) => result.scores.answerRelevance)),
     contextPrecision: average(results.map((result) => result.scores.contextPrecision)),
+    groundedness: average(results.map((result) => result.scores.groundedness)),
+    citationPrecision: average(results.map((result) => result.scores.citationPrecision)),
   };
 
   return {
@@ -166,7 +188,7 @@ function buildEvalReport(cases, options = {}) {
     passRate: results.length === 0 ? 0 : Number(((passed / results.length) * 100).toFixed(2)),
     aggregate,
     passedThreshold: failed === 0,
-    metrics: ['faithfulness', 'answerRelevance', 'contextPrecision'],
+    metrics: ['faithfulness', 'answerRelevance', 'contextPrecision', 'groundedness', 'citationPrecision'],
     sinks: {
       ci: true,
       langsmithCompatible: true,
@@ -228,7 +250,10 @@ module.exports = {
   scoreFaithfulness,
 };
 
-if (require.main === module) {
+const invokedDirectly = Boolean(process.argv[1])
+  && path.resolve(process.argv[1]) === __filename;
+
+if (invokedDirectly) {
   main().catch((err) => {
     console.error(err.stack || err.message);
     process.exitCode = 1;

package/scripts/audit-trail.js

@@ -61,7 +61,18 @@ function recordAuditEvent(params = {}) {
     source: params.source || 'gates-engine',
   };
 
-  fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
+  // Safe stringify: never let circular/toxic tool inputs crash the gate path
+  // (Antithesis-style invariant: evaluation + audit must not throw).
+  let line;
+  try {
+    line = JSON.stringify(record);
+  } catch (err) {
+    line = JSON.stringify({
+      ...record,
+      toolInput: { _unserializable: true, reason: String(err.message || err).slice(0, 120) },
+    });
+  }
+  fs.appendFileSync(logPath, `${line}\n`);
   try {
     const { trainAndPersistInterventionPolicy } = require('./intervention-policy');
     trainAndPersistInterventionPolicy(path.dirname(logPath));
@@ -73,10 +84,13 @@ function recordAuditEvent(params = {}) {
 
 /**
  * Strip secrets and large payloads from tool input before audit storage.
+ * Drop circular references so JSON.stringify never throws mid-gate evaluation.
  */
 function sanitizeToolInput(toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return {};
   const safe = {};
   const MAX_VALUE_LEN = 200;
+  const seen = new WeakSet();
 
   for (const [key, value] of Object.entries(toolInput)) {
     if (typeof value === 'string') {
@@ -88,6 +102,17 @@ function sanitizeToolInput(toolInput) {
           ? value.slice(0, MAX_VALUE_LEN) + '...'
           : value;
       }
+    } else if (value && typeof value === 'object') {
+      if (seen.has(value)) {
+        safe[key] = '[Circular]';
+        continue;
+      }
+      seen.add(value);
+      try {
+        safe[key] = JSON.parse(JSON.stringify(value, getCircularReplacer()));
+      } catch {
+        safe[key] = `[unserializable:${typeof value}]`;
+      }
     } else {
       safe[key] = value;
     }
@@ -95,6 +120,17 @@ function sanitizeToolInput(toolInput) {
   return safe;
 }
 
+function getCircularReplacer() {
+  const seen = new WeakSet();
+  return function circularReplacer(_key, value) {
+    if (value && typeof value === 'object') {
+      if (seen.has(value)) return '[Circular]';
+      seen.add(value);
+    }
+    return value;
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Auto-feedback from audit events
 // ---------------------------------------------------------------------------

package/scripts/auto-promote-gates.js

@@ -84,8 +84,32 @@ function regressionCheck(gate, options = {}) {
   let matchesGate;
   try { ({ matchesGate } = require('./gates-engine')); } catch { return null; }
   if (typeof matchesGate !== 'function') return null;
-  const allowed = entries.filter((e) => e && e.decision === 'allow' && e.toolName);
+  let allowed = entries.filter((e) => e && e.decision === 'allow' && e.toolName);
   if (!allowed.length) return null;
+
+  // The command we just learned to block was, by definition, ALLOWED before we
+  // learned it — that prior allow IS the incident the operator thumbs-downed.
+  // Counting it as a false block quarantines every gate learned from a real
+  // failure, which is the normal path (run it, get burned, 👎 it). Exclude the
+  // originating contexts so the check only measures collateral damage to
+  // genuinely unrelated actions.
+  // Match on normalized command EQUALITY, not substring containment: a longer,
+  // genuinely different command that merely quotes the incident text (e.g.
+  // `notify-team --dry-run "<incident>"`) is real collateral damage and must
+  // still count toward quarantine.
+  const incidentSignatures = new Set(
+    (options.incidentContexts || [])
+      .map((c) => normalizeCommandSignature(String(c || '')))
+      .filter(Boolean),
+  );
+  if (incidentSignatures.size > 0) {
+    allowed = allowed.filter((e) => {
+      const cmd = (e.toolInput && (e.toolInput.command || e.toolInput.pattern)) || '';
+      return !incidentSignatures.has(normalizeCommandSignature(String(cmd)));
+    });
+    if (!allowed.length) return { falseBlocks: 0, allowSampleSize: 0 };
+  }
+
   let falseBlocks = 0;
   for (const e of allowed) {
     try {
@@ -163,14 +187,43 @@ function normalizeCommandSignature(input) {
   return tokens.join(' ').trim();
 }
 
-function extractPatternKey(entry) {
-  // Use tags as primary grouping key; fall back to context normalization
-  const tags = (entry.tags || []).filter((t) => !['feedback', 'negative', 'positive'].includes(t));
-  if (tags.length > 0) return tags.sort().join('+');
+/**
+ * Prefer an executable action we can match at PreToolUse time.
+ * Tag-only or pure prose feedback is useful memory — not an enforcement pattern.
+ */
+function extractExecutableAction(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const fromTool =
+    (entry.toolInput && (entry.toolInput.command || entry.toolInput.pattern))
+    || (entry.tool_input && (entry.tool_input.command || entry.tool_input.pattern))
+    || entry.command
+    || entry.failedCommand
+    || null;
+  if (fromTool && String(fromTool).trim().length >= 4) {
+    return String(fromTool).trim();
+  }
 
-  const ctx = (entry.context || entry.whatWentWrong || '').trim();
-  if (ctx.length < 10) return null;
-  return normalizeCommandSignature(ctx).slice(0, 100);
+  const ctx = String(entry.context || entry.whatWentWrong || '').trim();
+  if (ctx.length < 4) return null;
+
+  // Looks like a shell / CLI invocation (not free-form prose).
+  const looksExecutable = /^(?:sudo\s+)?(?:~\/|\.\/|\/)?(?:[A-Za-z0-9._+-]+\/)*[A-Za-z0-9._+-]+(?:\s|$)/.test(ctx)
+    && /\s|^[a-z0-9._+-]+(?:\s|$)/i.test(ctx)
+    && !/\s+(?:broke|failed|wrong|should|never|please|the agent)\b/i.test(ctx.slice(0, 80));
+  // Strong signal: known tool prefixes
+  const known = /^(?:sudo\s+)?(?:kubectl|git|npm|npx|yarn|pnpm|python|python3|node|curl|wget|docker|podman|rm|mv|cp|chmod|chown|psql|mysql|mongo|terraform|pulumi|aws|gcloud|az|helm|ssh|scp|rsync|make|cargo|go|ruby|perl|bash|sh|zsh)\b/i.test(ctx);
+  if (known || (looksExecutable && /[\s-]/.test(ctx) && ctx.length <= 200)) {
+    return ctx;
+  }
+  return null;
+}
+
+function extractPatternKey(entry) {
+  // Enforcement groups by executable action only. Tags remain diagnostic metadata
+  // and must not create hard-block thresholds for a single unrelated latest command.
+  const action = extractExecutableAction(entry);
+  if (!action) return null;
+  return normalizeCommandSignature(action).slice(0, 100);
 }
 
 function extractDiagnosticKeys(entry) {
@@ -203,27 +256,29 @@ function groupNegativeFeedback(entries, windowDays) {
     const ts = entry.timestamp ? new Date(entry.timestamp).getTime() : 0;
     if (ts < cutoff) continue;
 
-    const keys = [extractPatternKey(entry), ...extractDiagnosticKeys(entry)]
-      .filter(Boolean)
-      .filter((value, index, values) => values.indexOf(value) === index);
-    if (keys.length === 0) continue;
-
-    for (const key of keys) {
-      if (!groups[key]) {
-        groups[key] = {
-          key,
-          count: 0,
-          entries: [],
-          latestContext: '',
-          latestTimestamp: '',
-        };
-      }
-      groups[key].count++;
-      groups[key].entries.push(entry);
-      if (!groups[key].latestTimestamp || (entry.timestamp && entry.timestamp > groups[key].latestTimestamp)) {
-        groups[key].latestTimestamp = entry.timestamp || '';
-        groups[key].latestContext = entry.context || entry.whatWentWrong || '';
-      }
+    // Enforcement groups ONLY by executable action. Tag/diagnosis metadata is
+    // useful for memory and dashboards, but must not create hard-block thresholds
+    // that attach to an unrelated latest command.
+    const key = extractPatternKey(entry);
+    if (!key) continue;
+
+    if (!groups[key]) {
+      groups[key] = {
+        key,
+        count: 0,
+        entries: [],
+        latestContext: '',
+        latestTimestamp: '',
+        latestExecutable: '',
+      };
+    }
+    groups[key].count++;
+    groups[key].entries.push(entry);
+    if (!groups[key].latestTimestamp || (entry.timestamp && entry.timestamp > groups[key].latestTimestamp)) {
+      groups[key].latestTimestamp = entry.timestamp || '';
+      const action = extractExecutableAction(entry);
+      groups[key].latestContext = action || entry.context || entry.whatWentWrong || '';
+      groups[key].latestExecutable = action || '';
     }
   }
 
@@ -234,15 +289,48 @@ function patternToGateId(key) {
   return 'auto-' + key.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').slice(0, 50).toLowerCase();
 }
 
+/**
+ * Turn a captured context string into a pattern the gates engine can actually
+ * match. `gates-engine.js` compiles `gate.pattern` with `new RegExp(...)` and
+ * tests it against the tool-call text, so the pattern MUST be regex-safe text
+ * drawn from the command itself.
+ *
+ * It must NOT be the group key: keys are frequently tag-derived
+ * ("entity:Customer+entity:Funnel"), which is both meaningless against a command
+ * string and actively hazardous as a regex ('+' is a quantifier). Grouping by tag
+ * is correct — reusing that key as the match pattern is not.
+ */
+function contextToPattern(context) {
+  const raw = String(context || '').trim();
+  if (raw.length < 4) return null;
+  // Escape every regex metacharacter: the captured command is literal text.
+  return raw.slice(0, 120).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * A gate that cannot match the very context that produced it is inert — it
+ * shows up in the dashboard as an active blocking rule while enforcing nothing.
+ * That failure mode is worse than no gate at all, so callers drop these.
+ */
+function gateMatchesOwnContext(gate, context) {
+  if (!gate || !gate.pattern) return false;
+  try {
+    return new RegExp(gate.pattern).test(String(context || ''));
+  } catch {
+    return false;
+  }
+}
+
 function buildGateRule(group, actionOverride) {
   const action = actionOverride || (group.count === 'MANUAL' ? group.manualAction || 'block' : (group.count >= BLOCK_THRESHOLD ? 'block' : 'warn'));
   const severity = action === 'block' ? 'critical' : action === 'approve' ? 'high' : 'medium';
-  const context = group.latestContext.slice(0, 120);
+  const executable = (group.latestExecutable || extractExecutableAction({ context: group.latestContext }) || group.latestContext || '').slice(0, 120);
+  const context = executable;
   const kind = group.key.startsWith('diagnosis:')
     ? 'repeated diagnosis'
     : group.key.startsWith('constraint:')
       ? 'repeated constraint violation'
-      : 'repeated pattern';
+      : 'repeated executable action';
 
   const occurrencesText = group.count === 'MANUAL' ? 'manual' : `${group.count} occurrences`;
   const suggestedMessage = `Auto-promoted ${kind}: "${context}" (${occurrencesText} in ${WINDOW_DAYS} days)`;
@@ -257,7 +345,8 @@ function buildGateRule(group, actionOverride) {
   return {
     id: patternToGateId(group.key),
     trigger: `auto:${group.key}`,
-    pattern: group.key.replace(/^diagnosis:|constraint:/, ''),
+    // Derived from the executable action, NOT from tag keys — see contextToPattern.
+    pattern: contextToPattern(executable),
     action,
     message: suggestedMessage,
     severity,
@@ -393,6 +482,16 @@ function promote(feedbackLogPath, options) {
 
     const gateId = patternToGateId(group.key);
 
+    // Contexts that produced this gate. Their prior "allow" decisions are the
+    // incident the operator thumbs-downed, not false positives — both the
+    // new-gate and the warn->block upgrade path must exclude them from the
+    // regression check, or every gate learned from a real failure is held at warn.
+    const incidentContexts = [
+      group.latestContext,
+      ...(group.entries || []).map((e) => e && (e.context || e.whatWentWrong)),
+    ].filter(Boolean);
+    const regressionOpts = { ...opts, incidentContexts };
+
     // Check for existing gate — possibly upgrade
     const existingIdx = data.gates.findIndex((g) => g.id === gateId);
     if (existingIdx !== -1) {
@@ -400,7 +499,7 @@ function promote(feedbackLogPath, options) {
       const newAction = group.count >= BLOCK_THRESHOLD ? 'block' : 'warn';
       if (existing.action !== newAction && newAction === 'block') {
         // Self-Harness stage 3: regression-test before upgrading warn -> block.
-        const regression = opts.skipRegression ? null : safeRegressionCheck(buildGateRule(group, 'block'), opts);
+        const regression = opts.skipRegression ? null : safeRegressionCheck(buildGateRule(group, 'block'), regressionOpts);
         if (regression && regression.falseBlocks > REGRESSION_FALSE_BLOCK_LIMIT) {
           // Would block prior safe actions — hold at warn instead of upgrading.
           promotions.push({ type: 'upgrade-quarantined', gateId, from: existing.action, occurrences: group.count, falseBlocks: regression.falseBlocks });
@@ -418,12 +517,25 @@ function promote(feedbackLogPath, options) {
     // New gate — respect explicit gateAction override (e.g. 'approve' for human-approval rules)
     const gate = buildGateRule(group, opts.gateAction);
 
+    // Never persist a gate that cannot match the context that produced it. Such a
+    // gate renders in the dashboard as an active blocking rule while enforcing
+    // nothing, which reads as "the agent learned" when it did not.
+    if (!gateMatchesOwnContext(gate, group.latestContext)) {
+      promotions.push({
+        type: 'skipped-unmatchable',
+        gateId: gate.id,
+        reason: 'derived pattern does not match originating context',
+        occurrences: group.count,
+      });
+      continue;
+    }
+
     // Self-Harness stage 3: before a feedback rule goes live as a hard block,
     // regression-test it against prior allowed actions. If it would have blocked
     // safe actions, quarantine it to `warn` instead of `block`.
     let regression = null;
     if (gate.action === 'block' && !opts.gateAction && !opts.skipRegression) {
-      regression = safeRegressionCheck(gate, opts);
+      regression = safeRegressionCheck(gate, regressionOpts);
       if (regression && regression.falseBlocks > REGRESSION_FALSE_BLOCK_LIMIT) {
         gate.action = 'warn';
         gate.severity = 'medium';
@@ -506,10 +618,13 @@ module.exports = {
   groupNegativeFeedback,
   patternToGateId,
   buildGateRule,
+  contextToPattern,
+  gateMatchesOwnContext,
   regressionCheck,
   getAuditTrailPath,
   REGRESSION_FALSE_BLOCK_LIMIT,
   extractPatternKey,
+  extractExecutableAction,
   normalizeCommandSignature,
   isNegative,
   expireGates,

package/scripts/colbert-style-maxsim.js

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * ColBERT-style late interaction (MaxSim) for ThumbGate lesson reranking.
+ *
+ * This is NOT a pretrained ColBERT neural model. It implements the *interaction
+ * pattern* ColBERT made famous:
+ *   - encode query and document as multi-vector bags (one vector per token)
+ *   - score with MaxSim: sum over query tokens of max cosine vs any doc token
+ *
+ * Token vectors are deterministic hashed character-n-gram projections (local-only,
+ * no GPU, no network). That gives late interaction without shipping a 100MB model
+ * in the npm package — while remaining honest about model provenance.
+ *
+ * For true neural ColBERT, operators can plug vectors via `tokenEmbedder`.
+ *
+ * @see https://arxiv.org/abs/2004.12832 (ColBERT MaxSim)
+ */
+
+const DEFAULT_DIM = 32;
+const DEFAULT_NGRAM = 3;
+
+/**
+ * Deterministic 32-bit hash (FNV-1a style) for seedable projections.
+ * @param {string} str
+ * @returns {number}
+ */
+function hash32(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i += 1) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/**
+ * Tokenize into lowercase word tokens (length >= 2).
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenize(text) {
+  if (!text) return [];
+  return String(text)
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/[\s_]+/)
+    .filter((t) => t.length >= 2);
+}
+
+/**
+ * Character n-grams for a token (with edge markers).
+ * @param {string} token
+ * @param {number} n
+ * @returns {string[]}
+ */
+function charNgrams(token, n = DEFAULT_NGRAM) {
+  const padded = `#${token}#`;
+  if (padded.length < n) return [padded];
+  const grams = [];
+  for (let i = 0; i <= padded.length - n; i += 1) {
+    grams.push(padded.slice(i, i + n));
+  }
+  return grams;
+}
+
+/**
+ * Build a unit-length multi-dim embedding for one token via hashed n-grams.
+ * @param {string} token
+ * @param {{ dim?: number, ngram?: number }} [opts]
+ * @returns {Float64Array}
+ */
+function embedToken(token, opts = {}) {
+  const dim = opts.dim ?? DEFAULT_DIM;
+  const ngram = opts.ngram ?? DEFAULT_NGRAM;
+  const vec = new Float64Array(dim);
+  for (const gram of charNgrams(token, ngram)) {
+    const h = hash32(gram);
+    const idx = h % dim;
+    const sign = (h & 1) === 0 ? 1 : -1;
+    vec[idx] += sign;
+    // Second hash for denser projection (locality-sensitive bag)
+    const h2 = hash32(`${gram}:2`);
+    vec[h2 % dim] += ((h2 >> 1) & 1) === 0 ? 0.5 : -0.5;
+  }
+  // L2 normalize
+  let norm = 0;
+  for (let i = 0; i < dim; i += 1) norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm) || 1;
+  for (let i = 0; i < dim; i += 1) vec[i] /= norm;
+  return vec;
+}
+
+/**
+ * Cosine similarity for unit vectors (dot product).
+ * @param {Float64Array|number[]} a
+ * @param {Float64Array|number[]} b
+ * @returns {number}
+ */
+function cosine(a, b) {
+  const n = Math.min(a.length, b.length);
+  let s = 0;
+  for (let i = 0; i < n; i += 1) s += a[i] * b[i];
+  return s;
+}
+
+/**
+ * Encode text as a bag of token vectors (ColBERT multi-vector representation).
+ * @param {string} text
+ * @param {{ dim?: number, ngram?: number, maxTokens?: number, tokenEmbedder?: (t: string) => Float64Array|number[] }} [opts]
+ * @returns {{ tokens: string[], vectors: Array<Float64Array|number[]> }}
+ */
+function encodeMultiVector(text, opts = {}) {
+  const maxTokens = opts.maxTokens ?? 64;
+  const tokens = tokenize(text).slice(0, maxTokens);
+  const embedder = opts.tokenEmbedder || ((t) => embedToken(t, opts));
+  const vectors = tokens.map((t) => embedder(t));
+  return { tokens, vectors };
+}
+
+/**
+ * ColBERT MaxSim: Σ_i max_j cos(q_i, d_j), normalized by |Q|.
+ * @param {Array<Float64Array|number[]>} queryVectors
+ * @param {Array<Float64Array|number[]>} docVectors
+ * @returns {number} score in [0, 1] approximately
+ */
+function maxSim(queryVectors, docVectors) {
+  if (!queryVectors.length || !docVectors.length) return 0;
+  let total = 0;
+  for (const q of queryVectors) {
+    let best = -1;
+    for (const d of docVectors) {
+      const c = cosine(q, d);
+      if (c > best) best = c;
+    }
+    total += Math.max(0, best);
+  }
+  // Normalize by query length so longer queries don't dominate
+  return Math.min(1, total / queryVectors.length);
+}
+
+/**
+ * Score a (query, document) pair with ColBERT-style late interaction.
+ * @param {string} query
+ * @param {string} document
+ * @param {object} [opts]
+ * @returns {{ score: number, queryTokens: string[], docTokens: string[], mode: string }}
+ */
+function scoreLateInteraction(query, document, opts = {}) {
+  const q = encodeMultiVector(query, opts);
+  const d = encodeMultiVector(document, opts);
+  const score = maxSim(q.vectors, d.vectors);
+  return {
+    score: Number(score.toFixed(6)),
+    queryTokens: q.tokens,
+    docTokens: d.tokens,
+    mode: opts.tokenEmbedder ? 'colbert-style-external' : 'colbert-style-hash',
+  };
+}
+
+/**
+ * Rerank candidates by MaxSim late interaction.
+ * @param {string} query
+ * @param {Array<object>} candidates
+ * @param {{ topK?: number, textOf?: (c: object) => string, blendWeight?: number }} [options]
+ * @returns {Array<object>} candidates with maxSimScore + optional blend into rerankedScore
+ */
+function rerankWithMaxSim(query, candidates, options = {}) {
+  const {
+    topK = 5,
+    textOf = defaultTextOf,
+    blendWeight = 0.55,
+    dim,
+    ngram,
+    maxTokens,
+    tokenEmbedder,
+  } = options;
+
+  if (!candidates || candidates.length === 0) return [];
+  if (candidates.length === 1) {
+    const only = candidates[0];
+    return [{
+      ...only,
+      maxSimScore: 1,
+      rerankedScore: only.rerankedScore ?? only.relevanceScore ?? 1,
+      lateInteractionMode: 'trivial',
+    }].slice(0, topK);
+  }
+
+  const qEnc = encodeMultiVector(query, { dim, ngram, maxTokens, tokenEmbedder });
+  const scored = candidates.map((c) => {
+    const docText = textOf(c);
+    const dEnc = encodeMultiVector(docText, { dim, ngram, maxTokens, tokenEmbedder });
+    const ms = maxSim(qEnc.vectors, dEnc.vectors);
+    const orig = Number(c.rerankedScore ?? c.relevanceScore ?? c.score ?? 0);
+    const blended = blendWeight * ms + (1 - blendWeight) * Math.max(0, Math.min(1, orig));
+    return {
+      ...c,
+      maxSimScore: Number(ms.toFixed(6)),
+      rerankedScore: Number(blended.toFixed(6)),
+      lateInteractionMode: tokenEmbedder ? 'colbert-style-external' : 'colbert-style-hash',
+    };
+  });
+
+  return scored
+    .sort((a, b) => (b.rerankedScore || 0) - (a.rerankedScore || 0))
+    .slice(0, topK);
+}
+
+function defaultTextOf(candidate) {
+  if (!candidate || typeof candidate !== 'object') return String(candidate || '');
+  return [
+    candidate.title,
+    candidate.whatWentWrong,
+    candidate.whatToChange,
+    candidate.howToAvoid,
+    candidate.summary,
+    candidate.content,
+    candidate.context,
+    Array.isArray(candidate.tags) ? candidate.tags.join(' ') : '',
+  ].filter(Boolean).join(' ');
+}
+
+module.exports = {
+  hash32,
+  tokenize,
+  charNgrams,
+  embedToken,
+  cosine,
+  encodeMultiVector,
+  maxSim,
+  scoreLateInteraction,
+  rerankWithMaxSim,
+  DEFAULT_DIM,
+  DEFAULT_NGRAM,
+};