capman 0.6.1 → 0.6.2

package/CODEBASE.md

@@ -169,12 +169,11 @@ Usage analytics and keyword index — incremental, PII-safe.
 
 Key exports:
 - `LearningStore` interface — `record(entry)`, `getStats()`, `getTopCapabilities(limit)`, `getIndex()`, `destroy()`
-- `FileLearningStore` — persists to `.capman/learning.json`, caps at 10,000 entries. Saves debounced (5s) with synchronous flush on process exit via `flushSync()`
-- `MemoryLearningStore` — in-memory only, used in tests
-- `LearningIndex` — internal class shared by both stores. Maintains keyword index and stats counters incrementally. Eliminates ~80 lines of duplication
+- `FileLearningStore(filePath, halfLifeDays)` — persists to `.capman/learning.json`, caps at 10,000 entries. Saves debounced (5s) with synchronous flush on process exit. Migration guard: pre-v0.7 entries without `lastUpdated` use file mtime as fallback
+- `MemoryLearningStore(halfLifeDays)` — in-memory only, used in tests
+- `LearningIndex(halfLifeDays)` — internal class shared by both stores. Maintains keyword index and stats counters incrementally. Time decay applied lazily on `getStats()` read — not on write. `halfLifeDays` must be positive; throws `RangeError` otherwise Eliminates ~80 lines of duplication
 
-`LearningEntry`:
-- `query` — stored as tokenized keywords only, never raw text. PII (emails, names, IDs) stripped before persistence
+- `LearningEntry` — query stored as tokenized keywords only (PII-safe), plus capabilityId, confidence, intent, resolvedVia, timestamp, `lastUpdated` (ms since epoch — used for time decay)
 - `capabilityId`, `confidence`, `intent`, `extractedParams`
 - `resolvedVia: 'keyword' | 'llm' | 'cache'`
 - `timestamp`
@@ -222,6 +221,8 @@ Key exports:
 - `cacheTtlMs` — optional TTL for cache entries in ms (default: no expiry)
 - `maxLLMCallsPerMinute` — rate limit (default: 60). Set to 0 to disable LLM entirely
 - `llmCooldownMs`, `llmCircuitBreakerThreshold`, `llmCircuitBreakerResetMs`
+- `learningHalfLifeDays` — half-life in days for time-decayed learning (default: 30). Only applies when engine creates its own default store
+- `embedding` — optional `EmbeddingProvider` for semantic similarity. Pre-encodes capabilities at construction and after `loadManifest()`. Fused into RRF as third signal. Failures fall back gracefully to BM25+fuzzy
 
 Matching pipeline in `ask()`:
 1. Cache check — return immediately on hit (public capabilities only). Re-extracts params fresh from current query

package/dist/cjs/concurrent.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ConcurrentCapmanEngine — a thin wrapper around CapmanEngine that serialises
+ * ask() and explain() calls via an internal promise queue.
+ *
+ * Use this when sharing a single CapmanEngine instance across concurrent async
+ * request handlers (e.g. a long-lived Express server with balanced/accurate mode).
+ *
+ * Why a promise queue instead of async-mutex:
+ *   - Zero external dependencies — no new package.json entries for consumers
+ *   - Identical serialisation guarantee to a FIFO mutex
+ *   - Simpler audit surface
+ *
+ * Why opt-in, not default:
+ *   - Per-request engine patterns pay zero overhead (recommended for most servers)
+ *   - Cheap mode shared engines pay zero overhead
+ *   - Consumer retains full control over their concurrency model
+ *
+ * @example
+ * // Safe shared engine across concurrent requests
+ * const engine = new ConcurrentCapmanEngine({ manifest, llm, mode: 'balanced' })
+ * app.post('/ask', async (req, res) => {
+ *   const result = await engine.ask(req.body.query)
+ *   res.json(result)
+ * })
+ */
+import { type EngineOptions, type EngineResult } from './engine';
+import type { Manifest } from './types';
+import type { ResolveOptions } from './resolver';
+import type { ExplainResult } from './types';
+export declare class ConcurrentCapmanEngine {
+    private engine;
+    /**
+     * The tail of the promise chain — each new call appends to this.
+     * On rejection, the queue resets to a resolved promise so subsequent
+     * calls are not permanently blocked by a single failure.
+     */
+    private queue;
+    constructor(options: EngineOptions);
+    ask(query: string, overrides?: Partial<ResolveOptions>): Promise<EngineResult>;
+    explain(query: string): Promise<ExplainResult>;
+    /** Swap the manifest. Safe to call outside the queue — triggers cache clear internally. */
+    loadManifest(manifest: Manifest): Promise<void>;
+    /** Returns learning stats or null if learning is disabled. */
+    getStats(): Promise<import("./learning").KeywordStats | null>;
+    /** Returns top-N most frequently matched capabilities. */
+    getTopCapabilities(limit?: number): Promise<{
+        id: string;
+        hits: number;
+    }[]>;
+    /** Clear the cache. */
+    clearCache(): Promise<void>;
+}
+//# sourceMappingURL=concurrent.d.ts.map

package/dist/cjs/concurrent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrent.d.ts","sourceRoot":"","sources":["../../src/concurrent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAA;AAC9E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAc;IAC5B;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAsC;gBAEvC,OAAO,EAAE,aAAa;IAIlC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ9E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAQ9C,2FAA2F;IAC3F,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,8DAA8D;IAC9D,QAAQ;IAIR,0DAA0D;IAC1D,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM;;;;IAIjC,uBAAuB;IACvB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/dist/cjs/concurrent.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * ConcurrentCapmanEngine — a thin wrapper around CapmanEngine that serialises
+ * ask() and explain() calls via an internal promise queue.
+ *
+ * Use this when sharing a single CapmanEngine instance across concurrent async
+ * request handlers (e.g. a long-lived Express server with balanced/accurate mode).
+ *
+ * Why a promise queue instead of async-mutex:
+ *   - Zero external dependencies — no new package.json entries for consumers
+ *   - Identical serialisation guarantee to a FIFO mutex
+ *   - Simpler audit surface
+ *
+ * Why opt-in, not default:
+ *   - Per-request engine patterns pay zero overhead (recommended for most servers)
+ *   - Cheap mode shared engines pay zero overhead
+ *   - Consumer retains full control over their concurrency model
+ *
+ * @example
+ * // Safe shared engine across concurrent requests
+ * const engine = new ConcurrentCapmanEngine({ manifest, llm, mode: 'balanced' })
+ * app.post('/ask', async (req, res) => {
+ *   const result = await engine.ask(req.body.query)
+ *   res.json(result)
+ * })
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConcurrentCapmanEngine = void 0;
+const engine_1 = require("./engine");
+class ConcurrentCapmanEngine {
+    constructor(options) {
+        /**
+         * The tail of the promise chain — each new call appends to this.
+         * On rejection, the queue resets to a resolved promise so subsequent
+         * calls are not permanently blocked by a single failure.
+         */
+        this.queue = Promise.resolve();
+        this.engine = new engine_1.CapmanEngine(options);
+    }
+    ask(query, overrides) {
+        const result = this.queue.then(() => this.engine.ask(query, overrides));
+        // Reset queue tail to resolved on failure — one bad call must not
+        // block all subsequent callers indefinitely.
+        this.queue = result.catch(() => { });
+        return result;
+    }
+    explain(query) {
+        const result = this.queue.then(() => this.engine.explain(query));
+        this.queue = result.catch(() => { });
+        return result;
+    }
+    // ── Delegated methods — safe to call directly, no serialisation needed ──
+    /** Swap the manifest. Safe to call outside the queue — triggers cache clear internally. */
+    loadManifest(manifest) {
+        return this.engine.loadManifest(manifest);
+    }
+    /** Returns learning stats or null if learning is disabled. */
+    getStats() {
+        return this.engine.getStats();
+    }
+    /** Returns top-N most frequently matched capabilities. */
+    getTopCapabilities(limit) {
+        return this.engine.getTopCapabilities(limit);
+    }
+    /** Clear the cache. */
+    clearCache() {
+        return this.engine.clearCache();
+    }
+}
+exports.ConcurrentCapmanEngine = ConcurrentCapmanEngine;
+//# sourceMappingURL=concurrent.js.map

package/dist/cjs/concurrent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrent.js","sourceRoot":"","sources":["../../src/concurrent.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAEH,qCAA8E;AAK9E,MAAa,sBAAsB;IASjC,YAAY,OAAsB;QAPlC;;;;WAIG;QACK,UAAK,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAA;QAGjD,IAAI,CAAC,MAAM,GAAG,IAAI,qBAAY,CAAC,OAAO,CAAC,CAAA;IACzC,CAAC;IAED,GAAG,CAAC,KAAa,EAAE,SAAmC;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAA;QACvE,kEAAkE;QAClE,6CAA6C;QAC7C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACnC,OAAO,MAAM,CAAA;IACf,CAAC;IAED,OAAO,CAAC,KAAa;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA;QAChE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACnC,OAAO,MAAM,CAAA;IACf,CAAC;IAED,2EAA2E;IAE3E,2FAA2F;IAC3F,YAAY,CAAC,QAAkB;QAC7B,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;IAC3C,CAAC;IAED,8DAA8D;IAC9D,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAA;IAC/B,CAAC;IAED,0DAA0D;IAC1D,kBAAkB,CAAC,KAAc;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAC9C,CAAC;IAED,uBAAuB;IACvB,UAAU;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAA;IACjC,CAAC;CACF;AAhDD,wDAgDC"}

package/dist/cjs/engine.d.ts

@@ -3,17 +3,34 @@ import type { LLMMatcherOptions } from './matcher';
 import type { ResolveOptions, AuthContext } from './resolver';
 import type { CacheStore } from './cache';
 import type { LearningStore } from './learning';
+import type { EmbeddingProvider } from './types';
 import type { MatchMode } from './types';
 /**
  * Options for constructing a CapmanEngine instance.
  *
- * ⚠️  CONCURRENCY: CapmanEngine is not safe for sharing across concurrent
- * async request handlers. The LLM rate limiter, circuit breaker, and
- * learning index cache are all instance-level mutable state. In an
- * Express/Fastify/etc. server, either:
- *   (a) Create one engine per request — safest, no shared state
- *   (b) Use a single instance only with cheap mode (no LLM calls)
- *   (c) Add an external mutex around LLM calls if sharing is required
+ * ⚠️  CONCURRENCY: CapmanEngine is NOT safe for sharing a single instance
+ * across concurrent async request handlers in a server environment.
+ *
+ * Node.js is single-threaded — classical data races do not apply. What does
+ * apply is async interleaving: two ask() chains can interleave at await
+ * suspension points. The following hazards are real:
+ *
+ *   - Calling loadManifest() while ask() calls are in-flight: mitigated by
+ *     an optimistic manifestVersion guard — in-flight results skip the cache
+ *     write rather than polluting it with stale data.
+ *   - Sharing one instance across concurrent balanced/accurate LLM calls:
+ *     rate limiter and circuit-breaker state can interleave.
+ *
+ * The following are NOT hazards (synchronous within the event loop):
+ *   - MemoryCache Map mutations
+ *   - LLM counter increments (llmCallsThisMinute++ is atomic in Node.js)
+ *   - statsCounter updates
+ *
+ * Safe patterns:
+ *   (a) One engine per request — safest, zero shared state
+ *   (b) Single shared instance in cheap mode only (no LLM calls)
+ *   (c) ConcurrentCapmanEngine wrapper (v0.8.0) — serialises ask() via
+ *       a zero-dependency promise queue
  *
  * @example
  * // Safe — per-request engine
@@ -87,6 +104,15 @@ export interface EngineOptions {
      * @default 60000
      */
     llmCircuitBreakerResetMs?: number;
+    /**
+     * Half-life in days for time-decayed learning weights.
+     * A learning entry that is exactly this many days old retains 50% of its
+     * original weight. Older entries fade faster; recent ones dominate.
+     * Only applies when the engine creates its own default MemoryLearningStore.
+     * If you pass a custom learning store, configure halfLifeDays on it directly.
+     * @default 30
+     */
+    learningHalfLifeDays?: number;
     /**
      * Enable fuzzy matching using Fuse.js — catches paraphrases, typos,
      * and morphological variants that exact keyword matching misses.
@@ -115,12 +141,43 @@ export interface EngineOptions {
      */
     adaptiveMarginOverride?: number;
     /**
-     * Target environment for server selection from manifest.servers[].
-     * When manifest.servers is present and this matches a server's environment,
-     * that server's URL is used as baseUrl.
-     * Falls back to first server, then EngineOptions.baseUrl if no match.
-     */
+    * Target environment for server selection from manifest.servers[].
+    * When manifest.servers is present and this matches a server's environment,
+    * that server's URL is used as baseUrl.
+    * Falls back to first server, then EngineOptions.baseUrl if no match.
+    */
     environment?: string;
+    /**
+    * Half-life for time-decayed learning in days.
+    * A learning signal that is halfLifeDays old contributes half its original weight.
+    * Only applies when using the engine's default MemoryLearningStore.
+    * For FileLearningStore, pass halfLifeDays directly to its constructor.
+    * @default 30
+    */
+    halfLifeDays?: number;
+    /**
+     * Optional embedding provider for semantic similarity matching.
+     * When provided, capability texts are pre-encoded at construction time
+     * and query embeddings are computed on each ask() call. The embedding
+     * signal is fused with BM25 and fuzzy signals via RRF.
+     *
+     * Zero mandatory dependencies — bring your own provider:
+     *
+     * @example
+     * const engine = new CapmanEngine({
+     *   manifest,
+     *   embedding: {
+     *     async encode(texts: string[]) {
+     *       // call your embedding API here
+     *       return texts.map(t => myEmbedModel.embed(t))
+     *     }
+     *   }
+     * })
+     *
+     * Note: embedding is purely additive — if encode() throws, the engine
+     * falls back to BM25 + fuzzy scoring without interrupting operation.
+     */
+    embedding?: EmbeddingProvider;
 }
 export interface EngineResult {
     match: MatchResult;
@@ -142,6 +199,7 @@ export declare class CapmanEngine {
     /** Maximum allowed query length in characters. Queries exceeding this throw RangeError. */
     static readonly MAX_QUERY_LENGTH = 1000;
     private manifest;
+    private manifestVersion;
     private mode;
     private llm?;
     private cache;
@@ -160,6 +218,10 @@ export declare class CapmanEngine {
     private marginAwareLLM;
     private adaptiveMargin;
     private environment?;
+    private embedding?;
+    private capEmbeddings?;
+    /** Resolves when the post-loadManifest re-encode completes. Awaited by buildEmbeddingScores(). */
+    private pendingEmbedding;
     private maxLLMCallsPerMinute;
     private llmCooldownMs;
     private llmCircuitBreakerThreshold;
@@ -200,6 +262,10 @@ export declare class CapmanEngine {
     clearCache(): Promise<void>;
     private checkManifestVersion;
     private checkCapabilityLifecycle;
+    /** Cosine similarity between two equal-length vectors */
+    private cosineSim;
+    /** Encode query and return cosine similarity scores (0–100) keyed by capability ID */
+    private buildEmbeddingScores;
     private checkMatchHint;
     /**
      * Replaces the active manifest without creating a new engine instance.
@@ -281,6 +347,10 @@ export declare class CapmanEngine {
      * For manifests with ≤100 capabilities this is negligible (<10ms).
      * For very large manifests (500+ capabilities), consider passing
      * `adaptiveMarginOverride` to skip calibration.
+     *
+     * Note: constructor total cost also includes BM25 index build O(capabilities × tokens)
+     * and embedding pre-encoding O(capabilities) if an EmbeddingProvider is configured.
+     * For 100 capabilities with embeddings, expect ~100–500ms depending on provider latency.
      */
     private calibrateAdaptiveMargin;
     private computeVerdict;

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

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/cjs/engine.js

@@ -10,6 +10,9 @@ const version_1 = require("./version");
 // ─── CapmanEngine ─────────────────────────────────────────────────────────────
 class CapmanEngine {
     constructor(options) {
+        this.manifestVersion = 0;
+        /** Resolves when the post-loadManifest re-encode completes. Awaited by buildEmbeddingScores(). */
+        this.pendingEmbedding = null;
         // ── LLM rate limiting state ────────────────────────────────────────────────
         this.llmCallsThisMinute = 0;
         this.llmWindowStart = Date.now();
@@ -46,8 +49,20 @@ class CapmanEngine {
         // Use FileLearningStore explicitly for persistence across restarts
         this.learning = options.learning === false
             ? null
-            : (options.learning ?? new learning_1.MemoryLearningStore());
-        logger_1.logger.info(`CapmanEngine initialized — mode: ${this.mode}, cache: ${this.cache ? 'enabled' : 'disabled'}, learning: ${this.learning ? 'enabled' : 'disabled'}`);
+            : (options.learning ?? new learning_1.MemoryLearningStore(options.learningHalfLifeDays ?? 30));
+        this.embedding = options.embedding;
+        if (this.embedding) {
+            // Pre-encode all capability texts at construction time — one batch call.
+            // Concatenate name + description for richer semantic surface.
+            const texts = this.manifest.capabilities.map(c => `${c.name}: ${c.description}`);
+            this.embedding.encode(texts).then(vecs => {
+                this.capEmbeddings = vecs;
+                logger_1.logger.info('Capability embeddings pre-encoded');
+            }).catch(err => {
+                logger_1.logger.warn(`EmbeddingProvider pre-encode failed — embedding signal disabled: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        logger_1.logger.info(`CapmanEngine initialized — mode: ${this.mode}, cache: ${this.cache ? 'enabled' : 'disabled'}, learning: ${this.learning ? 'enabled' : 'disabled'}, embedding: ${this.embedding ? 'enabled' : 'disabled'}`);
         // ── Manifest version compatibility check ─────────────────────────────────
         this.checkManifestVersion(options.manifest);
     }
@@ -71,6 +86,9 @@ class CapmanEngine {
         }
         const start = Date.now();
         const steps = [];
+        // Capture manifest version at entry — used to guard the cache write.
+        // If loadManifest() is called mid-flight, we skip writing stale results.
+        const manifestVersion = this.manifestVersion;
         // ── Step 1: Check cache ──────────────────────────────────────────────────
         const cacheStart = Date.now();
         if (this.cache) {
@@ -176,11 +194,19 @@ class CapmanEngine {
         //    queries that resolve to the same capability share a cache entry
         if (this.cache && resolution.success && matchResult.capability
             && matchResult.capability.privacy.level === 'public') {
-            const queryKey = (0, cache_1.normalizeQuery)(query);
-            const capKey = (0, cache_1.buildCacheKey)(query, matchResult.capability.id, matchResult.extractedParams);
-            await this.cache.set(queryKey, matchResult);
-            await this.cache.set(capKey, matchResult);
-            // capKey always starts with 'cap:' — structurally distinct from queryKey
+            // Optimistic concurrency guard — skip cache write if manifest was swapped
+            // mid-flight. The result was computed against a now-stale manifest and
+            // must not pollute the cache for the new one.
+            if (this.manifestVersion === manifestVersion) {
+                const queryKey = (0, cache_1.normalizeQuery)(query);
+                const capKey = (0, cache_1.buildCacheKey)(query, matchResult.capability.id, matchResult.extractedParams);
+                await this.cache.set(queryKey, matchResult);
+                await this.cache.set(capKey, matchResult);
+                // capKey always starts with 'cap:' — structurally distinct from queryKey
+            }
+            else {
+                logger_1.logger.warn('loadManifest() called mid-flight — skipping cache write for stale result');
+            }
         }
         // ── Step 5b: Compute missingParams ───────────────────────────────────────
         // Spec: LLM attempts extraction first when available. missingParams is last resort.
@@ -377,6 +403,44 @@ class CapmanEngine {
             }
         }
     }
+    /** Cosine similarity between two equal-length vectors */
+    cosineSim(a, b) {
+        if (a.length !== b.length || a.length === 0) {
+            logger_1.logger.warn(`cosineSim: dimension mismatch (${a.length} vs ${b.length}) — returning 0`);
+            return 0;
+        }
+        let dot = 0, normA = 0, normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denom = Math.sqrt(normA) * Math.sqrt(normB);
+        return denom === 0 ? 0 : dot / denom;
+    }
+    /** Encode query and return cosine similarity scores (0–100) keyed by capability ID */
+    async buildEmbeddingScores(query) {
+        if (!this.embedding || !this.capEmbeddings)
+            return undefined;
+        // Wait for any in-flight re-encode from loadManifest() to finish.
+        // Without this, the first ask() after loadManifest returns uses stale embeddings.
+        if (this.pendingEmbedding)
+            await this.pendingEmbedding;
+        try {
+            const [queryVec] = await this.embedding.encode([query]);
+            const scores = new Map();
+            this.manifest.capabilities.forEach((cap, i) => {
+                const sim = this.cosineSim(queryVec, this.capEmbeddings[i]);
+                // Cosine sim is -1..1; map to 0–100, negatives floored to 0
+                scores.set(cap.id, Math.max(0, Math.round(sim * 100)));
+            });
+            return scores;
+        }
+        catch (err) {
+            logger_1.logger.warn(`Embedding encode failed — skipping embedding signal: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    }
     checkMatchHint(capability) {
         const hint = capability.matchHint?.preferredMode;
         if (!hint || hint === this.mode)
@@ -399,13 +463,31 @@ class CapmanEngine {
      */
     async loadManifest(manifest) {
         this.checkManifestVersion(manifest);
+        // Assign all derived state atomically before any await — an in-flight ask()
+        // must never see a new manifest paired with a stale bm25Index or ceiling.
         this.manifest = manifest;
         this.bm25Index = (0, matcher_1.buildBM25Index)(manifest.capabilities);
         this.bm25Ceiling = this.calibrateBM25Ceiling();
         this.adaptiveMargin = this.calibrateAdaptiveMargin();
-        // resolveBaseUrl() reads from this.manifest.servers on each call —
+        this.manifestVersion++;
         // server selection updates automatically after loadManifest()
         await this.clearCache();
+        // Re-encode capabilities after manifest swap — stale embeddings misalign with new capabilities
+        if (this.embedding) {
+            const texts = manifest.capabilities.map(c => `${c.name}: ${c.description}`);
+            this.pendingEmbedding = this.embedding.encode(texts).then(vecs => {
+                this.capEmbeddings = vecs;
+                this.pendingEmbedding = null;
+                logger_1.logger.info('Capability embeddings re-encoded after manifest reload');
+            }).catch(err => {
+                this.capEmbeddings = undefined;
+                this.pendingEmbedding = null;
+                logger_1.logger.warn(`EmbeddingProvider re-encode failed after loadManifest: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        else {
+            this.pendingEmbedding = null;
+        }
     }
     /**
      * Explain what would happen for a query — without executing it.
@@ -647,13 +729,15 @@ class CapmanEngine {
         let matchResult;
         let resolvedVia = 'keyword';
         // Fuzzy options — never applied in cheap mode
+        const embeddingScores = await this.buildEmbeddingScores(query);
         const fuzzyOpts = {
             fuzzyMatch: this.fuzzyMatch,
             fuzzyThreshold: this.fuzzyThreshold,
             bm25Index: this.bm25Index,
-            bm25Ceiling: this.bm25Ceiling,
             bm25K1: this.bm25K1,
             bm25B: this.bm25B,
+            bm25Ceiling: this.bm25Ceiling,
+            embeddingScores,
         };
         switch (this.mode) {
             case 'cheap': {
@@ -676,20 +760,33 @@ class CapmanEngine {
                     else {
                         const t = Date.now();
                         try {
-                            matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
-                            this.recordLLMSuccess();
-                            resolvedVia = 'llm';
-                            // Merge keyword scores into LLM candidates so boost has real signal for alternatives
-                            const kwResult = (0, matcher_1.match)(query, this.manifest, fuzzyOpts);
-                            matchResult = {
-                                ...matchResult,
-                                candidates: matchResult.candidates.map(c => ({
-                                    ...c,
-                                    score: c.matched
-                                        ? c.score // keep LLM confidence for winner
-                                        : (kwResult.candidates.find(kc => kc.capabilityId === c.capabilityId)?.score ?? 0),
-                                })),
-                            };
+                            const kwResultAccurate = (0, matcher_1.match)(query, this.manifest, fuzzyOpts);
+                            const top3Accurate = kwResultAccurate.candidates
+                                .sort((a, b) => b.score - a.score)
+                                .filter(c => c.score > 0)
+                                .slice(0, 3)
+                                .map(c => this.manifest.capabilities.find(cap => cap.id === c.capabilityId))
+                                .filter(Boolean);
+                            // Skip LLM if no candidates scored above zero — no meaningful top-3 to discriminate
+                            if (top3Accurate.length === 0) {
+                                matchResult = kwResultAccurate;
+                            }
+                            else {
+                                const llmResult = await (0, matcher_1.matchWithLLM)(query, top3Accurate, { llm: this.llm, app: this.manifest.app });
+                                this.recordLLMSuccess();
+                                resolvedVia = 'llm';
+                                // If LLM says OOS but keyword had a match, the correct capability may have
+                                // been rank 4+. Fall back to keyword result rather than returning OOS.
+                                matchResult = llmResult.capability === null ? kwResultAccurate : {
+                                    ...llmResult,
+                                    candidates: llmResult.candidates.map(c => ({
+                                        ...c,
+                                        score: c.matched
+                                            ? c.score
+                                            : (kwResultAccurate.candidates.find(kc => kc.capabilityId === c.capabilityId)?.score ?? 0),
+                                    })),
+                                };
+                            }
                             steps?.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
                         }
                         catch (err) {
@@ -734,19 +831,32 @@ class CapmanEngine {
                         logger_1.logger.debug(`Query escalated to LLM: "${query}"`);
                         const t2 = Date.now();
                         try {
-                            matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
-                            this.recordLLMSuccess();
-                            resolvedVia = 'llm';
-                            // keywordResult already computed above in balanced mode — merge scores
-                            matchResult = {
-                                ...matchResult,
-                                candidates: matchResult.candidates.map(c => ({
-                                    ...c,
-                                    score: c.matched
-                                        ? c.score
-                                        : (keywordResult.candidates.find(kc => kc.capabilityId === c.capabilityId)?.score ?? 0),
-                                })),
-                            };
+                            const top3Balanced = keywordResult.candidates
+                                .sort((a, b) => b.score - a.score)
+                                .filter(c => c.score > 0)
+                                .slice(0, 3)
+                                .map(c => this.manifest.capabilities.find(cap => cap.id === c.capabilityId))
+                                .filter(Boolean);
+                            // Balanced mode only escalates when keyword confidence is low but > 0 —
+                            // top3 should always be non-empty here, but guard anyway
+                            if (top3Balanced.length === 0) {
+                                matchResult = keywordResult;
+                            }
+                            else {
+                                const llmResult = await (0, matcher_1.matchWithLLM)(query, top3Balanced, { llm: this.llm, app: this.manifest.app });
+                                this.recordLLMSuccess();
+                                resolvedVia = 'llm';
+                                // If LLM returns OOS but keyword had a scored candidate, fall back to keyword
+                                matchResult = llmResult.capability === null ? keywordResult : {
+                                    ...llmResult,
+                                    candidates: llmResult.candidates.map(c => ({
+                                        ...c,
+                                        score: c.matched
+                                            ? c.score
+                                            : (keywordResult.candidates.find(kc => kc.capabilityId === c.capabilityId)?.score ?? 0),
+                                    })),
+                                };
+                            }
                             steps?.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
                         }
                         catch (err) {
@@ -837,7 +947,15 @@ class CapmanEngine {
                 const hits = wordIndex[candidate.capabilityId] ?? 0;
                 if (hits > 0) {
                     // Logarithmic boost — diminishing returns after first few hits
-                    boost += Math.min(5, Math.log2(hits + 1) * 2);
+                    const rawBoost = Math.min(5, Math.log2(hits + 1) * 2);
+                    // IDF weighting — common words ("get", "show", "user") appear in many
+                    // capabilities and accumulate learning hits that carry little signal.
+                    // Reuses BM25 df/N so no separate computation is needed.
+                    const df = this.bm25Index.df[word] ?? 0;
+                    const idf = df > 0
+                        ? Math.log((this.bm25Index.N - df + 0.5) / (df + 0.5) + 1)
+                        : 0;
+                    boost += rawBoost * Math.min(1, idf);
                 }
             }
             const cappedBoost = Math.min(15, Math.round(boost));
@@ -903,6 +1021,10 @@ class CapmanEngine {
      * For manifests with ≤100 capabilities this is negligible (<10ms).
      * For very large manifests (500+ capabilities), consider passing
      * `adaptiveMarginOverride` to skip calibration.
+     *
+     * Note: constructor total cost also includes BM25 index build O(capabilities × tokens)
+     * and embedding pre-encoding O(capabilities) if an EmbeddingProvider is configured.
+     * For 100 capabilities with embeddings, expect ~100–500ms depending on provider latency.
      */
     calibrateAdaptiveMargin() {
         if (this.manifest.capabilities.length < 2)