thumbgate 1.29.2 → 1.31.0

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/billing.js

@@ -30,6 +30,7 @@ const {
   resolveFallbackArtifactPath,
 } = require('./feedback-paths');
 const { getTelemetryAnalytics, getTelemetrySourceDiagnostics } = require('./telemetry-analytics');
+const { normalizeCampaignId } = require('./growth-campaigns');
 const {
   PRO_MONTHLY_PRICE_ID,
   PRO_ANNUAL_PRICE_ID,
@@ -1154,7 +1155,7 @@ function extractAttribution(metadata = {}) {
   return {
     source: normalizeText(safe.utmSource || safe.source),
     medium: normalizeText(safe.utmMedium || safe.medium),
-    campaign: normalizeText(safe.utmCampaign || safe.campaign),
+    campaign: normalizeCampaignId(safe.utmCampaign || safe.campaign),
     content: normalizeText(safe.utmContent || safe.content),
     term: normalizeText(safe.utmTerm || safe.term),
     creator: normalizeText(safe.creator || safe.creatorHandle || safe.creator_handle),
@@ -4237,6 +4238,7 @@ module.exports = {
   _TRIAL_EMAIL_LEDGER_PATH: () => CONFIG.TRIAL_EMAIL_LEDGER_PATH,
   _ORDER_EMAIL_LEDGER_PATH: () => CONFIG.ORDER_EMAIL_LEDGER_PATH,
   _LOCAL_MODE: () => LOCAL_MODE(),
+  _extractAttribution: extractAttribution,
   _withTimeout: withTimeout,
   _mailer: mailer,
 };

package/scripts/claude-feedback-sync.js

@@ -8,7 +8,6 @@ const {
   buildFeedbackSourceIdentity,
   getFeedbackPaths,
   readJSONL,
-  analyzeFeedback,
 } = require('./feedback-loop');
 const { detectFeedbackSignal, normalizeFeedbackText } = require('./feedback-quality');
 const {
@@ -279,6 +278,7 @@ function syncClaudeHistoryFeedback(options = {}) {
         whatWorked: candidate.signal === 'up' ? candidate.promptText : undefined,
         tags: ['claude-history-sync', 'auto-capture-fallback'],
         sourceEvent,
+        reviewOrigin: 'human',
       });
 
       if (captureResult?.duplicate) {
@@ -300,7 +300,8 @@ function syncClaudeHistoryFeedback(options = {}) {
     }, { feedbackDir });
 
     if (importedCount > 0) {
-      refreshStatuslineCache(analyzeFeedback(path.join(feedbackDir, 'feedback-log.jsonl')), path.join(feedbackDir, 'statusline_cache.json'));
+      const { analyzeFeedback } = require('./feedback-loop');
+      refreshStatuslineCache(analyzeFeedback(path.join(feedbackDir, 'feedback-log.jsonl'), { humanOnly: true }), path.join(feedbackDir, 'statusline_cache.json'));
     }
 
     return {

package/scripts/cli-feedback.js

@@ -13,13 +13,9 @@
  *   node scripts/cli-feedback.js down "what went wrong"
  */
 
-const { captureFeedback } = require('./feedback-loop');
+const { captureFeedback, analyzeFeedback } = require('./feedback-loop');
 const { loadOptionalModule } = require('./private-core-boundary');
-// `history-distiller` is a PRIVATE_CORE_MODULE — present in this checkout and
-// in ThumbGate-Core, but intentionally excluded from the public npm tarball.
-// The hard `require('./history-distiller')` form crashed `hook-auto-capture`
-// in published 1.19.0 with MODULE_NOT_FOUND. Public-shell fallback returns
-// null distillation; caller already handles a null distillResult.
+// Keep the optional distiller from breaking the public package.
 const { distillFromHistory } = loadOptionalModule('./history-distiller', () => ({
   distillFromHistory: () => null,
 }));
@@ -60,6 +56,7 @@ function processInlineFeedback({ signal, context, chatHistory, whatWentWrong, wh
       whatWorked: whatWorked || undefined,
       chatHistory,
       sourceEvent,
+      reviewOrigin: 'human',
     });
   } catch (err) {
     feedbackResult = { accepted: false, reason: err.message };
@@ -75,7 +72,16 @@ function processInlineFeedback({ signal, context, chatHistory, whatWentWrong, wh
 
   // 3. Get the most recent lesson and stats
   const recentLesson = getRecentLesson();
-  const stats = getLessonStats();
+  const lessonStats = getLessonStats();
+  const feedbackStats = analyzeFeedback(undefined, { humanOnly: true });
+  const stats = {
+    ...lessonStats,
+    total: feedbackStats.total,
+    positive: feedbackStats.totalPositive,
+    negative: feedbackStats.totalNegative,
+    rawTotal: feedbackStats.rawTotal,
+    excludedTotal: feedbackStats.excludedTotal,
+  };
 
   // 4. If the user wrote an explicit "never …" / "always …" directive, surface
   //    an OFFER (never auto-act): "never" on a thumbs-down → offer force-gate now.

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,
+};