agent-working-memory 0.13.1 → 0.14.0

package/src/core/alias-map.ts

@@ -0,0 +1,97 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Project-dialect alias expansion.
+ *
+ * WHAT IT SOLVES
+ * --------------
+ * A memory tagged `topic=azure` whose body says "private plan… P1v3… app
+ * service" but never "azure". Asked for with "azure", it was not in the top 40.
+ * No general model knows that connection — it is local to this project — but it
+ * is recoverable from the store, because memories tagged `azure` share body
+ * vocabulary that the corpus at large does not.
+ *
+ * The map is mined offline (tests/realstore-eval/mine-aliases.ts) and is a plain
+ * JSON artifact: inspectable, cappable, diffable. That mattered immediately —
+ * reading the first mined map showed it had learned
+ * `agent -> discussed, turns, topics, summary`, i.e. session-summary boilerplate
+ * masquerading as dialect, and a hub guardrail was added before any measurement.
+ *
+ * GUARDRAIL 4 — "require at least one ORIGINAL query term" — is implemented by
+ * SCOPE rather than by an extra filter:
+ *
+ *   - alias terms are added ONLY to the BM25 search string, widening what gets
+ *     retrieved;
+ *   - `queryTokens`, which drives textMatch scoring, stays ORIGINAL.
+ *
+ * So a candidate that matches only alias terms enters the pool with a near-zero
+ * textMatch and is filtered by the existing minScore gate, while a candidate
+ * that matches an original term too is scored normally. The alias terms buy
+ * REACH; the original terms still decide RELEVANCE. That is exactly the
+ * separation Codex asked for, and it needs no new gate to enforce.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+let cache: Record<string, string[]> | null = null;
+
+function mapPath(): string {
+  if (process.env.AWM_ALIAS_MAP) return process.env.AWM_ALIAS_MAP;
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, '..', '..', 'data', 'alias-map.json');
+}
+
+/** Load the mined map once. Missing file is not an error — the feature is opt-in. */
+export function aliasMap(): Record<string, string[]> {
+  if (cache) return cache;
+  const p = mapPath();
+  if (!existsSync(p)) { cache = {}; return cache; }
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'));
+    cache = (parsed.map ?? parsed) as Record<string, string[]>;
+  } catch {
+    cache = {};
+  }
+  return cache;
+}
+
+/** Reset the cache — tests only. */
+export function clearAliasCache(): void { cache = null; }
+
+/** Whether alias expansion is enabled. Default OFF. */
+export function aliasEnabled(): boolean {
+  return process.env.AWM_ALIASES === '1';
+}
+
+/** Max alias terms added to a single query, regardless of how many match. */
+export function aliasQueryCap(): number {
+  const v = Number(process.env.AWM_ALIAS_QUERY_CAP ?? 8);
+  return Number.isFinite(v) && v > 0 ? v : 8;
+}
+
+/**
+ * Expand a query with dialect terms for any category word it mentions.
+ * Returns the added terms (never the rewritten query) so the caller decides
+ * which channel sees them — the whole safety property depends on alias terms
+ * reaching BM25 only, not the scoring tokens.
+ */
+export function aliasTermsFor(query: string): string[] {
+  if (!aliasEnabled()) return [];
+  const m = aliasMap();
+  if (Object.keys(m).length === 0) return [];
+  const toks = new Set((query.toLowerCase().match(/[a-z][a-z0-9_.-]{3,}/g) ?? []));
+  const out: string[] = [];
+  const seen = new Set<string>(toks);
+  for (const t of toks) {
+    const aliases = m[t];
+    if (!aliases) continue;
+    for (const a of aliases) {
+      if (seen.has(a)) continue;      // never re-add a term the query already has
+      seen.add(a);
+      out.push(a);
+      if (out.length >= aliasQueryCap()) return out;
+    }
+  }
+  return out;
+}

package/src/core/embeddings.ts

@@ -1,115 +1,172 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Embedding Engine - vector embeddings via the ML worker pool.
- *
- * Default model: bge-small-en-v1.5 (384 dimensions, ~90MB, MTEB retrieval-optimized).
- * Configurable via AWM_EMBED_MODEL env var.
- *
- * AWM 0.8.x: inference dispatches through ml-worker.ts. The worker_threads
- * path was planned but reverted to in-process because onnxruntime-node's
- * native bindings store V8 handles that don't cross isolate boundaries
- * safely — see ml-worker.ts for the full status. The dispatch abstraction
- * is preserved for a future child_process or HTTP sidecar pool.
- * `AWM_ML_INPROCESS=1` is honored as a no-op (in-process is now the default).
- *
- * NOTE: Changing the model invalidates existing embeddings.
- * Set AWM_EMBED_MODEL=Xenova/all-MiniLM-L6-v2 for backward compatibility.
- */
-
-import { pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
-import { dispatchEmbed, registerInProcessHandlers } from './ml-worker.js';
-import { noteModelLoad } from './write-telemetry.js';
-import { ensureModelCacheDir } from './model-cache.js';
-
-const MODEL_ID = process.env.AWM_EMBED_MODEL ?? 'Xenova/bge-small-en-v1.5';
-const DIMENSIONS = parseInt(process.env.AWM_EMBED_DIMS ?? '384', 10);
-const POOLING = (process.env.AWM_EMBED_POOLING ?? 'mean') as 'cls' | 'mean';
-
-// --- In-process fallback (used by tests and crash recovery) ---
-
-let inProcessInstance: FeatureExtractionPipeline | null = null;
-let inProcessInitPromise: Promise<FeatureExtractionPipeline> | null = null;
-
-async function loadInProcess(): Promise<FeatureExtractionPipeline> {
-  if (inProcessInstance) return inProcessInstance;
-  if (inProcessInitPromise) return inProcessInitPromise;
-  const tLoadStart = performance.now();
-  ensureModelCacheDir();
-  inProcessInitPromise = pipeline('feature-extraction', MODEL_ID, { dtype: 'fp32' }).then(pipe => {
-    inProcessInstance = pipe;
-    noteModelLoad(performance.now() - tLoadStart);
-    console.error(`Embedding model loaded in-process: ${MODEL_ID} (${DIMENSIONS}d)`);
-    return pipe;
-  });
-  return inProcessInitPromise;
-}
-
-async function inProcessEmbed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }): Promise<number[][]> {
-  const { texts, pooling, dimensions } = args;
-  if (texts.length === 0) return [];
-  const embedder = await loadInProcess();
-  const result = await embedder(texts, { pooling, normalize: true });
-  const data = result.data as Float32Array;
-  const vectors: number[][] = [];
-  for (let i = 0; i < texts.length; i++) {
-    vectors.push(Array.from(data.slice(i * dimensions, (i + 1) * dimensions)));
-  }
-  return vectors;
-}
-
-// Register the in-process handler with the pool (used in test mode and as fallback)
-registerInProcessHandlers({ embed: inProcessEmbed });
-
-// --- Public API ---
-
-/**
- * Get or initialize the embedding pipeline (singleton).
- * Kept for backwards compat — returns the in-process pipeline only.
- * Most consumers should use embed() / embedBatch() which dispatch
- * to the worker pool by default.
- */
-export async function getEmbedder(): Promise<FeatureExtractionPipeline> {
-  return loadInProcess();
-}
-
-/**
- * Generate an embedding vector for a text string.
- * Dispatches to the worker pool (or in-process fallback).
- */
-export async function embed(text: string): Promise<number[]> {
-  const vectors = await dispatchEmbed({ texts: [text], pooling: POOLING, dimensions: DIMENSIONS });
-  return vectors[0] ?? new Array(DIMENSIONS).fill(0);
-}
-
-/**
- * Generate embeddings for multiple texts in a batch.
- * More efficient than calling embed() in a loop — the worker batches the
- * tokenization + forward pass.
- */
-export async function embedBatch(texts: string[]): Promise<number[][]> {
-  if (texts.length === 0) return [];
-  return dispatchEmbed({ texts, pooling: POOLING, dimensions: DIMENSIONS });
-}
-
-/** Get the current embedding model ID (for version tracking in stored embeddings) */
-export function getModelId(): string {
-  return MODEL_ID;
-}
-
-/**
- * Cosine similarity between two normalized vectors.
- * Since vectors are pre-normalized, this is just the dot product.
- */
-export function cosineSimilarity(a: number[], b: number[]): number {
-  if (a.length !== b.length || a.length === 0) return 0;
-  let dot = 0;
-  for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i];
-  }
-  // Clamp to [-1, 1] to handle floating point drift
-  return Math.max(-1, Math.min(1, dot));
-}
-
-/** Vector dimensions for this model */
-export const EMBEDDING_DIMENSIONS = DIMENSIONS;
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Embedding Engine - vector embeddings via the ML worker pool.
+ *
+ * Default model: bge-small-en-v1.5 (384 dimensions, ~90MB, MTEB retrieval-optimized).
+ * Configurable via AWM_EMBED_MODEL env var.
+ *
+ * AWM 0.8.x: inference dispatches through ml-worker.ts. The worker_threads
+ * path was planned but reverted to in-process because onnxruntime-node's
+ * native bindings store V8 handles that don't cross isolate boundaries
+ * safely — see ml-worker.ts for the full status. The dispatch abstraction
+ * is preserved for a future child_process or HTTP sidecar pool.
+ * `AWM_ML_INPROCESS=1` is honored as a no-op (in-process is now the default).
+ *
+ * NOTE: Changing the model invalidates existing embeddings.
+ * Set AWM_EMBED_MODEL=Xenova/all-MiniLM-L6-v2 for backward compatibility.
+ */
+
+import { pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
+import { dispatchEmbed, registerInProcessHandlers } from './ml-worker.js';
+import { noteModelLoad } from './write-telemetry.js';
+import { ensureModelCacheDir } from './model-cache.js';
+
+const MODEL_ID = process.env.AWM_EMBED_MODEL ?? 'Xenova/bge-small-en-v1.5';
+const DIMENSIONS = parseInt(process.env.AWM_EMBED_DIMS ?? '384', 10);
+const POOLING = (process.env.AWM_EMBED_POOLING ?? 'mean') as 'cls' | 'mean';
+
+// --- In-process fallback (used by tests and crash recovery) ---
+
+let inProcessInstance: FeatureExtractionPipeline | null = null;
+let inProcessInitPromise: Promise<FeatureExtractionPipeline> | null = null;
+
+async function loadInProcess(): Promise<FeatureExtractionPipeline> {
+  if (inProcessInstance) return inProcessInstance;
+  if (inProcessInitPromise) return inProcessInitPromise;
+  const tLoadStart = performance.now();
+  ensureModelCacheDir();
+  inProcessInitPromise = pipeline('feature-extraction', MODEL_ID, { dtype: 'fp32' }).then(pipe => {
+    inProcessInstance = pipe;
+    noteModelLoad(performance.now() - tLoadStart);
+    console.error(`Embedding model loaded in-process: ${MODEL_ID} (${DIMENSIONS}d)`);
+    return pipe;
+  });
+  return inProcessInitPromise;
+}
+
+async function inProcessEmbed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }): Promise<number[][]> {
+  const { texts, pooling, dimensions } = args;
+  if (texts.length === 0) return [];
+  const embedder = await loadInProcess();
+  const result = await embedder(texts, { pooling, normalize: true });
+  const data = result.data as Float32Array;
+  const vectors: number[][] = [];
+  for (let i = 0; i < texts.length; i++) {
+    vectors.push(Array.from(data.slice(i * dimensions, (i + 1) * dimensions)));
+  }
+  return vectors;
+}
+
+// Register the in-process handler with the pool (used in test mode and as fallback)
+registerInProcessHandlers({ embed: inProcessEmbed });
+
+// --- Public API ---
+
+/**
+ * Get or initialize the embedding pipeline (singleton).
+ * Kept for backwards compat — returns the in-process pipeline only.
+ * Most consumers should use embed() / embedBatch() which dispatch
+ * to the worker pool by default.
+ */
+export async function getEmbedder(): Promise<FeatureExtractionPipeline> {
+  return loadInProcess();
+}
+
+/**
+ * Generate an embedding vector for a text string.
+ * Dispatches to the worker pool (or in-process fallback).
+ */
+export async function embed(text: string): Promise<number[]> {
+  const vectors = await dispatchEmbed({ texts: [text], pooling: POOLING, dimensions: DIMENSIONS });
+  return vectors[0] ?? new Array(DIMENSIONS).fill(0);
+}
+
+/**
+ * Generate embeddings for multiple texts in a batch.
+ * More efficient than calling embed() in a loop — the worker batches the
+ * tokenization + forward pass.
+ */
+export async function embedBatch(texts: string[]): Promise<number[][]> {
+  if (texts.length === 0) return [];
+  return dispatchEmbed({ texts, pooling: POOLING, dimensions: DIMENSIONS });
+}
+
+/** Get the current embedding model ID (for version tracking in stored embeddings) */
+export function getModelId(): string {
+  return MODEL_ID;
+}
+
+/**
+ * Dimension-mismatch telemetry.
+ *
+ * A mismatch means the vector channel silently scores 0 for the affected memories —
+ * recall still returns results (BM25 is unaffected) but they are quietly much worse.
+ * That is invisible without this counter, and a half-migrated corpus is the realistic
+ * way it happens: change AWM_EMBED_MODEL without re-embedding, or interrupt a
+ * migration, and the un-migrated rows drop out of vector scoring with no error.
+ */
+let dimMismatchCount = 0;
+let dimMismatchWarned = false;
+let dimMismatchSample: { expected: number; got: number } | null = null;
+
+/** Observed embedding-dimension mismatches. Surfaced by /health and memory_whoami. */
+export function embeddingHealth(): {
+  dimensionMismatches: number;
+  expectedDimensions: number;
+  sample: { expected: number; got: number } | null;
+} {
+  return {
+    dimensionMismatches: dimMismatchCount,
+    expectedDimensions: DIMENSIONS,
+    sample: dimMismatchSample,
+  };
+}
+
+/** Test-only: reset the mismatch counter. */
+export function __resetEmbeddingHealth(): void {
+  dimMismatchCount = 0;
+  dimMismatchWarned = false;
+  dimMismatchSample = null;
+}
+
+/**
+ * Cosine similarity between two normalized vectors.
+ * Since vectors are pre-normalized, this is just the dot product.
+ *
+ * Returns 0 on a dimension mismatch — the maths is undefined otherwise — but COUNTS
+ * it and warns once, because a silent 0 here reads as "these memories are irrelevant"
+ * rather than "this corpus is half-migrated". Deliberately does not throw: this runs
+ * over every candidate on every recall, so throwing would escalate degraded quality
+ * into an outage.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) {
+    // length 0 is a legitimate not-yet-embedded state, not a corpus mismatch
+    if (a.length !== 0 && b.length !== 0) {
+      dimMismatchCount++;
+      if (!dimMismatchSample) dimMismatchSample = { expected: a.length, got: b.length };
+      if (!dimMismatchWarned) {
+        dimMismatchWarned = true;
+        console.error(
+          `[awm] EMBEDDING DIMENSION MISMATCH: ${a.length}d vs ${b.length}d. ` +
+          `Affected memories score 0 on the vector channel and will rank far too low. ` +
+          `This usually means the corpus is half-migrated — re-embed the whole store ` +
+          `or revert AWM_EMBED_MODEL/AWM_EMBED_DIMS. Warning shown once per process; ` +
+          `see embeddingHealth() / GET /health for the running count.`
+        );
+      }
+    }
+    return 0;
+  }
+  if (a.length === 0) return 0;
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+  }
+  // Clamp to [-1, 1] to handle floating point drift
+  return Math.max(-1, Math.min(1, dot));
+}
+
+/** Vector dimensions for this model */
+export const EMBEDDING_DIMENSIONS = DIMENSIONS;

package/src/core/recall-config.ts

@@ -0,0 +1,115 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Effective recall configuration — self-reporting, so a measurement can PROVE
+ * which configuration produced it.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * On 2026-08-23 a benchmark comparison reported "no effect" for a change that
+ * demonstrably worked. The cause was not AWM: two arms shared a port, teardown
+ * left the first server alive, the second arm health-checked the survivor, and
+ * both arms measured the SAME baseline process. Identical inputs, identical
+ * outputs, a confident and completely wrong conclusion.
+ *
+ * Port hygiene fixes that instance. It does not fix the class. The class is:
+ * **nothing verified that the system measured was the system configured.**
+ * The same gap bit the D11 spreading-activation re-test, where the tracer's arm
+ * label omitted `AWM_SPREAD_INHIBIT`, so two materially different arms both
+ * printed `arm=spread` and had to be told apart by diffing output by hand.
+ *
+ * The durable fix is for the running system to state its own effective recall
+ * configuration, so a harness can assert it and fail LOUDLY instead of silently
+ * measuring the wrong thing. Any new recall flag added to RECALL_FLAGS is
+ * automatically covered by every consumer — the eval tracer's arm label, the
+ * `/health` payload, and the benchmark driver's assertion.
+ *
+ * Adding a flag here is the ONLY step required to make it visible everywhere.
+ */
+
+/**
+ * Every environment flag that can change what `activate()` returns.
+ * Keep this list current — an unlisted flag is an invisible experiment.
+ */
+export const RECALL_FLAGS = [
+  // Second-stage reorder (phase 9b)
+  'AWM_RERANK2',
+  'AWM_RERANK2_K',
+  // Cross-encoder passage selection
+  'AWM_RERANK_WINDOW',
+  'AWM_RERANK_TRUNC',
+  'AWM_RERANK_POOL',
+  'AWM_RERANK_TAGS',
+  'AWM_RERANK_TAGS_LEN',
+  // Derived retrieval text (embedding side)
+  'AWM_RETRIEVAL_TEXT',
+  // Project-dialect alias expansion
+  'AWM_ALIASES',
+  'AWM_ALIAS_QUERY_CAP',
+  // Embedding model — changes every stored vector, so it belongs here
+  'AWM_EMBED_MODEL',
+  'AWM_EMBED_DIMS',
+  'AWM_DISABLE_RERANK_SKIP',
+  // Spreading activation (D11 — parked)
+  'AWM_SPREAD',
+  'AWM_SPREAD_INJECT',
+  'AWM_SPREAD_INHIBIT',
+  'AWM_SPREAD_ITERS',
+  'AWM_SPREAD_DAMPING',
+  'AWM_SPREAD_BUDGET',
+  'AWM_SPREAD_BOOST',
+  // Candidate pool / retrieval breadth
+  'AWM_TOPN_MULT',
+  'AWM_BROAD_EDGES',
+  'AWM_ENTITY_FETCH',
+  'AWM_ENTITY_INDEX_FETCH',
+  'AWM_QUERY_BRIDGE',
+  'AWM_AUTOTAG',
+  // Diagnostic escape hatches that alter ranking
+  'AWM_DISABLE_POOL_FILTER',
+  'AWM_DISABLE_EXPANSION_CACHE',
+  'AWM_DISABLE_SLIM_CACHE',
+  'AWM_ABSTAIN_GATE_K',
+] as const;
+
+export type RecallFlag = (typeof RECALL_FLAGS)[number];
+
+/** Only the flags actually set, in declaration order. */
+export function activeRecallConfig(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const k of RECALL_FLAGS) {
+    const v = env[k];
+    if (v !== undefined && v !== '') out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Short, stable, comparable label for the active configuration.
+ * `default` when nothing is set. Sorted so it never depends on declaration
+ * order or on how the process was launched.
+ */
+export function recallConfigFingerprint(env: NodeJS.ProcessEnv = process.env): string {
+  const active = activeRecallConfig(env);
+  const keys = Object.keys(active).sort();
+  if (keys.length === 0) return 'default';
+  return keys.map(k => `${k.replace(/^AWM_/, '').toLowerCase()}=${active[k]}`).join(',');
+}
+
+/**
+ * Assert the running configuration contains the expected flag values.
+ * Returns the mismatches; empty array means the system is configured as
+ * intended. Harnesses should treat a non-empty result as fatal — it means the
+ * thing being measured is not the thing that was configured.
+ */
+export function diffRecallConfig(
+  expected: Record<string, string>,
+  env: NodeJS.ProcessEnv = process.env,
+): Array<{ flag: string; expected: string; actual: string | undefined }> {
+  const active = activeRecallConfig(env);
+  const bad: Array<{ flag: string; expected: string; actual: string | undefined }> = [];
+  for (const [flag, want] of Object.entries(expected)) {
+    if (active[flag] !== want) bad.push({ flag, expected: want, actual: active[flag] });
+  }
+  return bad;
+}

package/src/core/rerank-window.ts

@@ -0,0 +1,158 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Passage selection for cross-encoder reranking.
+ *
+ * THE PROBLEM
+ * -----------
+ * Reranking truncates each passage to a fixed prefix (historically the first
+ * 400 chars). That truncation exists for a real reason: cross-encoders pad to
+ * the longest passage in the batch, so one 5,000-char memory in a 40-item pool
+ * drags every passage to ~512 tokens and costs 3-4x. The reranker is already
+ * ~90% of warm recall latency, so "just send everything" is not available.
+ *
+ * But a PREFIX is the wrong 400 chars. Measured on the live 29.8k store:
+ *   - canonical memories median 1,965 chars, 98.7% exceed 400
+ *   - the reranker cannot see 78.8% of each canonical memory's vocabulary
+ *   - 99.9% of long canonical memories carry identifiers only past char 400
+ * And measured on tests/longmem-eval: moving the answer from char 150 to char
+ * 700 takes success@1 from 100% to 0%, with the gold's cross-encoder score
+ * collapsing 0.986 -> 0.000 while its BM25 score barely moves. The memory stays
+ * retrievable and stops being rankable.
+ *
+ * THE FIX
+ * -------
+ * Spend the same character budget on the window that actually contains the
+ * query's terms, instead of on whatever happens to be at the top of the memory.
+ * Cost is unchanged — same budget, same batch padding, same inference — so this
+ * buys ranking quality without buying latency.
+ *
+ * The concept line is always kept: it is short, it is the memory's title, and
+ * it is what a human wrote to summarise the thing.
+ */
+
+/** Cheap tokenizer for locating query terms inside a passage. */
+function terms(query: string): string[] {
+  const raw = query.toLowerCase().match(/[a-z0-9_][a-z0-9_.\-]{1,}/g) ?? [];
+  const STOP = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'what', 'where', 'when',
+    'which', 'does', 'did', 'was', 'were', 'are', 'is', 'be', 'to', 'of', 'in',
+    'on', 'at', 'by', 'it', 'as', 'do', 'how', 'why', 'a', 'an', 'or',
+  ]);
+  return Array.from(new Set(raw.filter(t => t.length >= 3 && !STOP.has(t))));
+}
+
+/**
+ * Choose the `budget`-char window of `content` densest in query terms.
+ * Returns the head of the content when nothing matches — the old behaviour,
+ * which is the right fallback: with no query signal there is no reason to
+ * prefer any other part of the memory.
+ */
+export function densestWindow(content: string, query: string, budget: number): string {
+  if (content.length <= budget) return content;
+
+  const toks = terms(query);
+  if (toks.length === 0) return content.slice(0, budget);
+
+  const lower = content.toLowerCase();
+  const hits: number[] = [];
+  for (const t of toks) {
+    let from = 0;
+    for (;;) {
+      const i = lower.indexOf(t, from);
+      if (i < 0) break;
+      hits.push(i);
+      from = i + t.length;
+    }
+  }
+  if (hits.length === 0) return content.slice(0, budget);
+  hits.sort((a, b) => a - b);
+
+  // Slide a window anchored slightly before each hit; keep the one covering most.
+  let bestStart = 0;
+  let bestCount = -1;
+  for (let i = 0; i < hits.length; i++) {
+    const start = Math.max(0, hits[i] - Math.floor(budget / 5));
+    let count = 0;
+    for (let j = i; j < hits.length && hits[j] - start < budget; j++) count++;
+    if (count > bestCount) { bestCount = count; bestStart = start; }
+  }
+
+  // Snap to a word boundary so the cross-encoder is not handed a split token.
+  let start = bestStart;
+  if (start > 0) {
+    const sp = content.indexOf(' ', start);
+    if (sp >= 0 && sp - start < 40) start = sp + 1;
+  }
+  const slice = content.slice(start, start + budget);
+  return (start > 0 ? '…' : '') + slice + (start + budget < content.length ? '…' : '');
+}
+
+/**
+ * Build the passage handed to the cross-encoder for one candidate.
+ *
+ * `mode`:
+ *  - `'prefix'` (default) — legacy behaviour, the first `budget` chars.
+ *  - `'query'`  — the `budget`-char window densest in query terms.
+ */
+export function buildRerankPassage(
+  concept: string,
+  content: string,
+  query: string,
+  budget: number,
+  mode: 'prefix' | 'query',
+  tags?: string[],
+): string {
+  const body = mode === 'query'
+    ? densestWindow(content, query, budget)
+    : (content.length > budget ? content.slice(0, budget) : content);
+  // Topical tags, when enabled. The cross-encoder decides final order since
+  // phase 9b, and it cannot see tags at all — measured on the live store, 66.2%
+  // of topical tag terms never appear in the body, so that vocabulary is
+  // invisible to the stage that now decides ranking. Appended (not substituted)
+  // and length-capped so it cannot crowd out the content window.
+  const extra = rerankTagText(tags);
+  return extra ? `${concept}: ${body} ${extra}` : `${concept}: ${body}`;
+}
+
+/** Whether topical tags are appended to the rerank passage. Default OFF. */
+export function rerankTagsEnabled(): boolean {
+  return process.env.AWM_RERANK_TAGS === '1';
+}
+
+/** Character budget for the appended tag text. */
+export function rerankTagBudget(): number {
+  const v = Number(process.env.AWM_RERANK_TAGS_LEN ?? 80);
+  return Number.isFinite(v) && v > 0 ? v : 80;
+}
+
+/**
+ * Render topical tags as plain terms for the cross-encoder.
+ * Only `topic=` / `proj=` / `project=` carry query vocabulary; date/person/
+ * ticket tags are identifiers the body usually already contains, and adding
+ * them would spend the budget without adding reachable words.
+ */
+export function rerankTagText(tags?: string[]): string {
+  if (!rerankTagsEnabled() || !tags || tags.length === 0) return '';
+  const words = new Set<string>();
+  for (const t of tags) {
+    const m = /^(?:topic|proj|project)=(.+)$/i.exec(t);
+    if (!m) continue;
+    for (const w of m[1].toLowerCase().split(/[-_\s]+/)) {
+      if (w.length > 2) words.add(w);
+    }
+  }
+  if (words.size === 0) return '';
+  return `[${[...words].join(' ').slice(0, rerankTagBudget())}]`;
+}
+
+/** Character budget for a rerank passage. */
+export function rerankTruncation(): number {
+  const v = Number(process.env.AWM_RERANK_TRUNC ?? 400);
+  return Number.isFinite(v) && v > 0 ? v : 400;
+}
+
+/** Passage selection mode. Default `prefix` preserves shipped behaviour. */
+export function rerankWindowMode(): 'prefix' | 'query' {
+  return process.env.AWM_RERANK_WINDOW === 'query' ? 'query' : 'prefix';
+}