agent-working-memory 0.13.0 → 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,113 +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';
-
-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();
-  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/model-cache.ts

@@ -0,0 +1,51 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Model cache directory — makes `HF_HOME` (and `AWM_CACHE_DIR`) actually work.
+ *
+ * ROOT CAUSE (found 2026-08-22 investigating flaky model loads in ephemeral Docker
+ * containers): @huggingface/transformers has NO built-in environment-variable support
+ * for its cache location — it reads only `env.cacheDir`, set in code, and nothing else.
+ * Left unset, it defaults to `<install-dir-of-@huggingface/transformers>/.cache/` —
+ * inside node_modules, wiped on every `npm install`/`npm ci`, i.e. every Docker build
+ * and every global upgrade re-downloads all three models from scratch.
+ *
+ * `docs/deployment.md` has instructed `HF_HOME=/data/models` for Railway/Fly/Render
+ * persistence since it was written — that variable was a silent no-op the whole time;
+ * nothing in AWM ever read it. This module makes it real, so existing deployments start
+ * working with ZERO config changes on the user's end. `AWM_CACHE_DIR` (referenced in
+ * docs/architecture.md, also previously fictional) is honored as an AWM-specific
+ * override, and the default is now genuinely persistent for a bare npm install too
+ * (previously it was ephemeral there as well, just less obviously so).
+ *
+ * Precedence: AWM_CACHE_DIR > HF_HOME > <packageRoot>/data/models.
+ *
+ * MUST run before the first `pipeline()` / `AutoTokenizer.from_pretrained()` /
+ * `AutoModel*.from_pretrained()` call in the process — `env.cacheDir` is read at
+ * download/load time, not import time, but there's no reason to risk a race, so every
+ * model-loading module in src/core/ calls `ensureModelCacheDir()` before its first
+ * library call. Idempotent — safe to call from all three.
+ */
+
+import { env } from '@huggingface/transformers';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let configured = false;
+
+function resolvePackageRoot(): string {
+  // This file lives at src/core/model-cache.ts (dev, via tsx) or
+  // dist/core/model-cache.js (built) — either way, two levels up is the package root.
+  const here = dirname(fileURLToPath(import.meta.url));
+  return dirname(dirname(here));
+}
+
+export function ensureModelCacheDir(): string {
+  if (configured) return env.cacheDir!;
+  const dir = process.env.AWM_CACHE_DIR || process.env.HF_HOME || join(resolvePackageRoot(), 'data', 'models');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  env.cacheDir = dir;
+  configured = true;
+  return dir;
+}

package/src/core/query-expander.ts

@@ -17,6 +17,7 @@
 
 import { pipeline, type Text2TextGenerationPipeline } from '@huggingface/transformers';
 import { dispatchExpand, registerInProcessHandlers } from './ml-worker.js';
+import { ensureModelCacheDir } from './model-cache.js';
 
 const MODEL_ID = 'Xenova/flan-t5-small';
 
@@ -28,6 +29,7 @@ let inProcessInitPromise: Promise<Text2TextGenerationPipeline> | null = null;
 async function loadInProcess(): Promise<Text2TextGenerationPipeline> {
   if (inProcessInstance) return inProcessInstance;
   if (inProcessInitPromise) return inProcessInitPromise;
+  ensureModelCacheDir();
   inProcessInitPromise = pipeline('text2text-generation', MODEL_ID, { dtype: 'fp32' }).then(pipe => {
     inProcessInstance = pipe as Text2TextGenerationPipeline;
     console.error(`Query expander loaded in-process: ${MODEL_ID}`);

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