agent-working-memory 0.11.0 → 0.12.3

package/dist/core/write-telemetry.js

@@ -0,0 +1,110 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Write-path telemetry (D1, 2026-07-30).
+ *
+ * Purpose: prove the mechanism behind slow writes before building the
+ * serialized write service. Captures, per write:
+ *   - phase wall times (embed / novelty / persist)
+ *   - event-loop lag at write completion (was this process's loop blocked?)
+ *   - whether a consolidation cycle was running IN THIS PROCESS
+ *   - whether SQLITE_BUSY was hit
+ *   - embed-model cold-load duration (first inference)
+ *
+ * Always-on slow-write warning: any write slower than AWM_SLOW_WRITE_MS
+ * (default 250ms; set 0 to disable) emits ONE structured stderr line.
+ * AWM_PROFILE_WRITE=1 continues to log every write as before.
+ *
+ * Design notes: additive module — no existing export changes (MWA vendors
+ * dist internals; nothing here alters existing paths). All timers are
+ * unref'd so they never hold the process open.
+ */
+const SLOW_WRITE_MS = (() => {
+    const v = Number(process.env.AWM_SLOW_WRITE_MS ?? '250');
+    return Number.isFinite(v) ? v : 250;
+})();
+// ---------- Event-loop lag monitor ----------
+const TICK_MS = 500;
+let lastTick = 0;
+let maxLagSinceRead = 0;
+let monitorStarted = false;
+/** Start the loop-lag heartbeat. Idempotent; call once at process boot. */
+export function startLoopLagMonitor() {
+    if (monitorStarted)
+        return;
+    monitorStarted = true;
+    lastTick = performance.now();
+    const t = setInterval(() => {
+        const now = performance.now();
+        const lag = now - lastTick - TICK_MS;
+        if (lag > maxLagSinceRead)
+            maxLagSinceRead = lag;
+        lastTick = now;
+    }, TICK_MS);
+    if (typeof t.unref === 'function')
+        t.unref();
+}
+/**
+ * Max observed loop lag (ms beyond the expected tick) since the last read.
+ * Reading resets the max. A large value means this process's event loop was
+ * blocked (in-process ML, consolidation, sync SQL) during the window.
+ */
+export function readMaxLoopLag() {
+    const v = maxLagSinceRead;
+    maxLagSinceRead = 0;
+    return Math.max(0, Math.round(v));
+}
+// ---------- In-process consolidation state ----------
+let consolidationActive = false;
+let consolidationAgent = null;
+let consolidationStartedAt = 0;
+export function setConsolidationActive(active, agentId) {
+    consolidationActive = active;
+    consolidationAgent = active ? (agentId ?? null) : null;
+    consolidationStartedAt = active ? performance.now() : 0;
+}
+export function getConsolidationState() {
+    return {
+        active: consolidationActive,
+        agentId: consolidationAgent,
+        runningMs: consolidationActive ? Math.round(performance.now() - consolidationStartedAt) : 0,
+    };
+}
+// ---------- Model cold-load record ----------
+let modelColdLoadMs = null;
+export function noteModelLoad(ms) {
+    if (modelColdLoadMs === null) {
+        modelColdLoadMs = Math.round(ms);
+        process.stderr.write(`[awm] embed model cold load: ${modelColdLoadMs}ms\n`);
+    }
+}
+export function getModelColdLoadMs() {
+    return modelColdLoadMs;
+}
+/**
+ * Report a completed write. Emits one structured stderr line when the write
+ * exceeded the slow threshold (always-on) — including loop lag and in-process
+ * consolidation state, the two signals that distinguish "DB lock wait" from
+ * "my own event loop was blocked".
+ */
+export function reportWrite(t) {
+    if (SLOW_WRITE_MS <= 0)
+        return;
+    if (t.totalMs < SLOW_WRITE_MS)
+        return;
+    const consol = getConsolidationState();
+    const parts = [
+        `[awm] SLOW WRITE ${Math.round(t.totalMs)}ms`,
+        `agent=${t.agentId}`,
+        `action=${t.action}`,
+        `embed=${Math.round(t.embedMs)}ms`,
+        `novelty=${Math.round(t.noveltyMs)}ms`,
+        `persist=${Math.round(t.persistMs)}ms`,
+        `loopLagMax=${readMaxLoopLag()}ms`,
+        `consolidating=${consol.active ? `yes(${consol.agentId ?? '?'},${consol.runningMs}ms)` : 'no'}`,
+        `busy=${t.busyHit ? 'yes' : 'no'}`,
+        modelColdLoadMs !== null ? `modelColdLoad=${modelColdLoadMs}ms` : 'modelColdLoad=none',
+    ];
+    process.stderr.write(parts.join(' ') + '\n');
+}
+//# sourceMappingURL=write-telemetry.js.map

package/dist/core/write-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-telemetry.js","sourceRoot":"","sources":["../../src/core/write-telemetry.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,sCAAsC;AAEtC;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE;IAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,KAAK,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACtC,CAAC,CAAC,EAAE,CAAC;AAEL,+CAA+C;AAE/C,MAAM,OAAO,GAAG,GAAG,CAAC;AACpB,IAAI,QAAQ,GAAG,CAAC,CAAC;AACjB,IAAI,eAAe,GAAG,CAAC,CAAC;AACxB,IAAI,cAAc,GAAG,KAAK,CAAC;AAE3B,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB;IACjC,IAAI,cAAc;QAAE,OAAO;IAC3B,cAAc,GAAG,IAAI,CAAC;IACtB,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE;QACzB,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,GAAG,GAAG,QAAQ,GAAG,OAAO,CAAC;QACrC,IAAI,GAAG,GAAG,eAAe;YAAE,eAAe,GAAG,GAAG,CAAC;QACjD,QAAQ,GAAG,GAAG,CAAC;IACjB,CAAC,EAAE,OAAO,CAAC,CAAC;IACZ,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,UAAU;QAAE,CAAC,CAAC,KAAK,EAAE,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,CAAC,GAAG,eAAe,CAAC;IAC1B,eAAe,GAAG,CAAC,CAAC;IACpB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,uDAAuD;AAEvD,IAAI,mBAAmB,GAAG,KAAK,CAAC;AAChC,IAAI,kBAAkB,GAAkB,IAAI,CAAC;AAC7C,IAAI,sBAAsB,GAAG,CAAC,CAAC;AAE/B,MAAM,UAAU,sBAAsB,CAAC,MAAe,EAAE,OAAgB;IACtE,mBAAmB,GAAG,MAAM,CAAC;IAC7B,kBAAkB,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvD,sBAAsB,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,MAAM,EAAE,mBAAmB;QAC3B,OAAO,EAAE,kBAAkB;QAC3B,SAAS,EAAE,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;KAC5F,CAAC;AACJ,CAAC;AAED,+CAA+C;AAE/C,IAAI,eAAe,GAAkB,IAAI,CAAC;AAE1C,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,eAAe,MAAM,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,eAAe,CAAC;AACzB,CAAC;AAcD;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,CAAe;IACzC,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO;IAC/B,IAAI,CAAC,CAAC,OAAO,GAAG,aAAa;QAAE,OAAO;IACtC,MAAM,MAAM,GAAG,qBAAqB,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG;QACZ,oBAAoB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI;QAC7C,SAAS,CAAC,CAAC,OAAO,EAAE;QACpB,UAAU,CAAC,CAAC,MAAM,EAAE;QACpB,SAAS,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI;QAClC,WAAW,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI;QACtC,WAAW,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI;QACtC,cAAc,cAAc,EAAE,IAAI;QAClC,iBAAiB,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,OAAO,IAAI,GAAG,IAAI,MAAM,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;QAC/F,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;QAClC,eAAe,KAAK,IAAI,CAAC,CAAC,CAAC,iBAAiB,eAAe,IAAI,CAAC,CAAC,CAAC,oBAAoB;KACvF,CAAC;IACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AAC/C,CAAC"}

package/dist/engine/activation.d.ts

@@ -1,18 +1,28 @@
 /**
  * Activation Pipeline — the core retrieval engine.
  *
- * 10-phase cognitive retrieval pipeline:
- *   0. Query expansion (flan-t5-small synonym generation)
- *   1. Vector embedding (MiniLM 384d)
- *   2. Parallel retrieval (FTS5/BM25 + vector pool)
- *   3. Scoring (BM25, Jaccard, z-score vector, entity-bridge boost)
- *   4. Rocchio pseudo-relevance feedback (expand + re-search BM25)
- *   5. ACT-R temporal decay
- *   6. Hebbian boost (co-activation strength)
- *   7. Composite scoring with confidence gating
- *   8. Beam search graph walk (depth 2, hop penalty)
- *   9. Cross-encoder reranking (ms-marco-MiniLM, adaptive blend)
- *  10. Abstention gate
+ * Cognitive retrieval pipeline — phases as shipped (D4 honesty pass 2026-07-30;
+ * default-OFF phases are marked, since operators tune from this header):
+ *   -1. Coreference expansion (conditional: query contains pronouns)
+ *   0. Query expansion (flan-t5-small; caller-gated, MCP default ON)
+ *   1. Vector embedding (bge-small 384d)
+ *   2. Parallel retrieval (dual FTS5/BM25 + native vector top-K)
+ *   3. Per-candidate scoring (BM25, Jaccard, cosine floor, ACT-R decay,
+ *      Hebbian boost, confidence gate — computed together in phase 3b)
+ *   3.5 Rocchio pseudo-relevance feedback (conditional on BM25 signal)
+ *   3.7 Entity-bridge boost (default ON; AWM_DISABLE_ENTITY_BRIDGE=1)
+ *   3.5  Entity-index candidate injection (DEFAULT OFF; AWM_ENTITY_INDEX_FETCH=1 —
+ *        D11 2026-07-30: D9 inverted-index lookup of query-named entities; injected
+ *        candidates get no boost but a guaranteed rerank audition)
+ *   3.75 Query-conditioned entity bridge (DEFAULT OFF; AWM_QUERY_BRIDGE=1)
+ *   4/5 Spreading-activation graph walk (DEFAULT OFF; AWM_SPREAD=1 — parked
+ *       after displacing-gold regressions; see design-proposals D11)
+ *   6. Filter + sort into rerank pool (wide pool since 0.9.0)
+ *   7. Cross-encoder rerank (ms-marco; clear-winner skip unless
+ *      AWM_DISABLE_RERANK_SKIP=1)
+ *   8. Multi-channel OOD detection + agreement gate; supersession penalty;
+ *      abstention enforced only when caller passes require_confidence
+ *   9. Final sort, granularity, confidence attach
  *
  * Logs activation events for eval metrics.
  */

package/dist/engine/activation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../../src/engine/activation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAA6C,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAKtG,OAAO,KAAK,EACF,gBAAgB,EAAE,eAAe,EAC1C,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAoIvE,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;gBAEnC,KAAK,EAAE,WAAW;IAM9B;;OAEG;IACG,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAg2BnE;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAKnC;YAEY,SAAS;IA+FvB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;YACW,gBAAgB;IA4I9B;;;;OAIG;IACG,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBhF,OAAO,CAAC,OAAO;CAchB"}
+{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../../src/engine/activation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EAA6C,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAKtG,OAAO,KAAK,EACF,gBAAgB,EAAE,eAAe,EAC1C,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAoIvE,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;gBAEnC,KAAK,EAAE,WAAW;IAM9B;;OAEG;IACG,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA66BnE;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAKnC;YAEY,SAAS;IA+FvB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;YACW,gBAAgB;IAwJ9B;;;;OAIG;IACG,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBhF,OAAO,CAAC,OAAO;CAchB"}

package/dist/engine/activation.js

@@ -3,18 +3,28 @@
 /**
  * Activation Pipeline — the core retrieval engine.
  *
- * 10-phase cognitive retrieval pipeline:
- *   0. Query expansion (flan-t5-small synonym generation)
- *   1. Vector embedding (MiniLM 384d)
- *   2. Parallel retrieval (FTS5/BM25 + vector pool)
- *   3. Scoring (BM25, Jaccard, z-score vector, entity-bridge boost)
- *   4. Rocchio pseudo-relevance feedback (expand + re-search BM25)
- *   5. ACT-R temporal decay
- *   6. Hebbian boost (co-activation strength)
- *   7. Composite scoring with confidence gating
- *   8. Beam search graph walk (depth 2, hop penalty)
- *   9. Cross-encoder reranking (ms-marco-MiniLM, adaptive blend)
- *  10. Abstention gate
+ * Cognitive retrieval pipeline — phases as shipped (D4 honesty pass 2026-07-30;
+ * default-OFF phases are marked, since operators tune from this header):
+ *   -1. Coreference expansion (conditional: query contains pronouns)
+ *   0. Query expansion (flan-t5-small; caller-gated, MCP default ON)
+ *   1. Vector embedding (bge-small 384d)
+ *   2. Parallel retrieval (dual FTS5/BM25 + native vector top-K)
+ *   3. Per-candidate scoring (BM25, Jaccard, cosine floor, ACT-R decay,
+ *      Hebbian boost, confidence gate — computed together in phase 3b)
+ *   3.5 Rocchio pseudo-relevance feedback (conditional on BM25 signal)
+ *   3.7 Entity-bridge boost (default ON; AWM_DISABLE_ENTITY_BRIDGE=1)
+ *   3.5  Entity-index candidate injection (DEFAULT OFF; AWM_ENTITY_INDEX_FETCH=1 —
+ *        D11 2026-07-30: D9 inverted-index lookup of query-named entities; injected
+ *        candidates get no boost but a guaranteed rerank audition)
+ *   3.75 Query-conditioned entity bridge (DEFAULT OFF; AWM_QUERY_BRIDGE=1)
+ *   4/5 Spreading-activation graph walk (DEFAULT OFF; AWM_SPREAD=1 — parked
+ *       after displacing-gold regressions; see design-proposals D11)
+ *   6. Filter + sort into rerank pool (wide pool since 0.9.0)
+ *   7. Cross-encoder rerank (ms-marco; clear-winner skip unless
+ *      AWM_DISABLE_RERANK_SKIP=1)
+ *   8. Multi-channel OOD detection + agreement gate; supersession penalty;
+ *      abstention enforced only when caller passes require_confidence
+ *   9. Final sort, granularity, confidence attach
  *
  * Logs activation events for eval metrics.
  */
@@ -255,7 +265,12 @@ export class ActivationEngine {
         // its slim cache + JS cosine (same as before but encapsulated). Z-score
         // normalization is replaced with a mode-adaptive raw-cosine floor —
         // simpler, faster, model-tuned for BGE-small embeddings.
-        const VECTOR_TOP_K = Math.max(50, limit * 5);
+        // D4 (2026-07-30): AWM_DISABLE_POOL_FILTER=1 was documented since 0.7.x but
+        // never implemented after the 0.8.x native-vector refactor absorbed the
+        // pool pre-filter. Honor its documented semantics: score ALL active
+        // candidates (no top-K cut, no similarity floor).
+        const POOL_FILTER_DISABLED = process.env.AWM_DISABLE_POOL_FILTER === '1';
+        const VECTOR_TOP_K = POOL_FILTER_DISABLED ? Number.MAX_SAFE_INTEGER : Math.max(50, limit * 5);
         // Tokenize query once (used by scoring)
         const queryTokens = tokenize(query.context);
         // Phase 3a: native vector search across agents — top-K by cosine.
@@ -271,9 +286,9 @@ export class ActivationEngine {
         // entirely. The vectorMatch scoring floor (0.50 targeted / 0.35 exploratory)
         // still suppresses low-confidence matches in the final score.
         // Env override: AWM_SIM_CANDIDATE_FLOOR_TARGETED, AWM_SIM_CANDIDATE_FLOOR_EXPLORATORY.
-        const SIM_CANDIDATE_FLOOR = adaptive.zScoreGate > 0.5
+        const SIM_CANDIDATE_FLOOR = POOL_FILTER_DISABLED ? -1 : (adaptive.zScoreGate > 0.5
             ? Number(process.env.AWM_SIM_CANDIDATE_FLOOR_TARGETED ?? 0.40)
-            : Number(process.env.AWM_SIM_CANDIDATE_FLOOR_EXPLORATORY ?? 0.30);
+            : Number(process.env.AWM_SIM_CANDIDATE_FLOOR_EXPLORATORY ?? 0.30));
         const rawCosineSims = new Map();
         const vectorHits = [];
         if (queryEmbedding) {
@@ -376,6 +391,75 @@ export class ActivationEngine {
                 catch { /* best-effort: entity fetch never breaks recall */ }
             }
         }
+        // ── D11 (2026-07-30): ENTITY-INDEX CANDIDATE INJECTION (default-OFF, AWM_ENTITY_INDEX_FETCH=1) ──
+        // The D9 inverted index resolves query-NAMED entities ("Seetha", "ticket 18999") to every
+        // engram indexed under them — deterministic exact lookup, immune to embedding/BM25 vocabulary
+        // mismatch. Injected candidates get NO score boost; instead they are GUARANTEED a rerank
+        // audition (exempt from the topN cut, the minScore pool filter, the rerank-pool slice, and
+        // the rerank-skip heuristic) and the cross-encoder alone decides whether they surface.
+        // This is the guarded successor to AWM_ENTITY_FETCH above, whose failure mode was measured:
+        // injected gold entered the pool but was cut before the reranker ever scored it. Bounded
+        // (AWM_ENTITY_INDEX_CAP, default 12) so the audition costs at most one extra rerank batch.
+        const injectedIds = new Set();
+        if (process.env.AWM_ENTITY_INDEX_FETCH === '1') {
+            try {
+                const IDX_CAP = Number(process.env.AWM_ENTITY_INDEX_CAP ?? 12);
+                const IDX_QSTOP = new Set(['what', 'who', 'when', 'where', 'why', 'how', 'which', 'whose',
+                    'the', 'this', 'that', 'and', 'but', 'for', 'did', 'does', 'is', 'are', 'was', 'were',
+                    'tell', 'about', 'they', 'them', 'write', 'reply', 'list', 'please', 'remember', 'confirm']);
+                const terms = new Set();
+                for (const m of query.context.matchAll(/\b[A-Z][A-Za-z]{2,}\b/g)) {
+                    const w = m[0].toLowerCase();
+                    if (!IDX_QSTOP.has(w))
+                        terms.add(w);
+                }
+                for (const m of query.context.matchAll(/\b\d{4,}\b/g))
+                    terms.add(m[0]); // bare ids: tickets, members, events
+                let added = 0;
+                for (const term of Array.from(terms).slice(0, 4)) {
+                    if (added >= IDX_CAP)
+                        break;
+                    const entities = await this.store.searchEntities(term, 6);
+                    for (const entity of entities) {
+                        if (added >= IDX_CAP)
+                            break;
+                        for (const agentId of agentIds) {
+                            if (added >= IDX_CAP)
+                                break;
+                            for (const id of await this.store.getEngramIdsByEntity(entity, agentId)) {
+                                if (added >= IDX_CAP)
+                                    break;
+                                if (injectedIds.has(id))
+                                    continue;
+                                // Already a candidate via BM25/vector? Still VOUCH for it: a weak in-pool
+                                // candidate the index confirms would otherwise die at the minScore/topN
+                                // cuts unguarded. The audition guarantee is about the index match, not
+                                // about how the candidate entered the pool.
+                                const inPool = candidateMap.get(id);
+                                if (inPool) {
+                                    if (inPool.stage === 'active' && !inPool.retracted && !inPool.supersededBy) {
+                                        injectedIds.add(id);
+                                        added++;
+                                    }
+                                    continue;
+                                }
+                                const n = await this.store.getEngram(id);
+                                if (!n || n.stage !== 'active' || n.retracted || n.supersededBy)
+                                    continue;
+                                if (query.memoryType && n.memoryType !== query.memoryType)
+                                    continue;
+                                candidateMap.set(id, n);
+                                injectedIds.add(id);
+                                added++;
+                            }
+                        }
+                    }
+                }
+                if (added > 0)
+                    candidates = Array.from(candidateMap.values());
+            }
+            catch { /* index injection never breaks recall */ }
+        }
         if (candidates.length === 0)
             return [];
         // Phase 3b: Score each candidate with per-phase breakdown
@@ -692,6 +776,14 @@ export class ActivationEngine {
         // Tunable via AWM_TOPN_MULT.
         const topNMult = Number(process.env.AWM_TOPN_MULT ?? 8);
         const topN = sorted.slice(0, limit * topNMult);
+        // D11 guard 1/4: injected entity-index candidates ride into the graph/rerank stages even
+        // when their (boost-free) composite fell below the topN cut.
+        if (injectedIds.size > 0) {
+            for (const item of sorted.slice(limit * topNMult)) {
+                if (injectedIds.has(item.engram.id))
+                    topN.push(item);
+            }
+        }
         if (process.env.AWM_SPREAD === '1' && query.spread !== false) {
             await this.spreadActivation(topN);
         }
@@ -699,8 +791,9 @@ export class ActivationEngine {
             await this.graphWalk(topN, 2, adaptive.hopPenalty, adaptive.beamWidth);
         }
         // Phase 6: Initial filter and sort for re-ranking pool
+        // (D11 guard 2/4: injected entity-index candidates are exempt from the minScore floor.)
         const pool = topN
-            .filter(r => r.score >= minScore)
+            .filter(r => r.score >= minScore || injectedIds.has(r.engram.id))
             .sort((a, b) => b.score - a.score);
         // Phase 7: Cross-encoder re-ranking — scores (query, passage) pairs directly
         // Widens the pool to find relevant results that keyword matching missed.
@@ -713,6 +806,13 @@ export class ActivationEngine {
         // the reranker does discrimination on a wide pool. Tunable via AWM_RERANK_POOL.
         const rerankPoolSize = Number(process.env.AWM_RERANK_POOL ?? Math.max(limit * 4, 40));
         const rerankPool = pool.slice(0, rerankPoolSize);
+        // D11 guard 3/4: injected entity-index candidates always reach the cross-encoder.
+        if (injectedIds.size > 0) {
+            for (const item of pool.slice(rerankPoolSize)) {
+                if (injectedIds.has(item.engram.id))
+                    rerankPool.push(item);
+            }
+        }
         // Reranker skip heuristic (0.7.10+): if BM25 already has a clear winner with
         // strong absolute score AND a meaningful gap to the runner-up, the cross-encoder
         // is unlikely to change the top result. Skipping saves ~300ms of wall-clock per
@@ -726,7 +826,9 @@ export class ActivationEngine {
         // Ambiguous queries (close BM25 scores, weak top-1, large pool) still go through
         // the reranker. Disable this heuristic via AWM_DISABLE_RERANK_SKIP=1.
         let rerankSkipped = false;
-        if (useReranker && rerankPool.length >= 2 && process.env.AWM_DISABLE_RERANK_SKIP !== '1') {
+        // (D11 guard 4/4: never skip the reranker when entity-index candidates were injected —
+        // the audition IS the rerank; skipping would return them unjudged or drop them.)
+        if (useReranker && rerankPool.length >= 2 && injectedIds.size === 0 && process.env.AWM_DISABLE_RERANK_SKIP !== '1') {
             const top1 = rerankPool[0];
             const top2 = rerankPool[1];
             const t1Text = top1.phaseScores.textMatch;
@@ -1186,6 +1288,20 @@ export class ActivationEngine {
                     inflow.set(v, (inflow.get(v) ?? 0) + au * share);
                 }
             }
+            // D11: SYNAPSE-style lateral inhibition (divisive normalization) — competing
+            // receivers suppress each other WITHIN an iteration: a node keeps its inflow in
+            // proportion to how much of the iteration's total it earned, so a few strongly-
+            // reached nodes stay strong while diffuse spread mass is crushed. This is the
+            // published fix for the displacing-gold regression that parked AWM_SPREAD.
+            // λ=0 (default) disables; enable for the re-test with AWM_SPREAD_INHIBIT=0.3.
+            const INHIBIT = Number(process.env.AWM_SPREAD_INHIBIT ?? 0);
+            if (INHIBIT > 0 && inflow.size > 1) {
+                let total = 0;
+                for (const f of inflow.values())
+                    total += f;
+                for (const [v, f] of inflow)
+                    inflow.set(v, f * (f / (f + INHIBIT * (total - f))));
+            }
             for (const [v, f] of inflow)
                 graphActivation.set(v, (graphActivation.get(v) ?? 0) + f);
             // Restart (PPR): blend propagated inflow with the original seed vector.