capman 0.6.1 → 0.6.2

package/dist/esm/engine.js

@@ -7,6 +7,9 @@ import { VERSION } from './version';
 // ─── CapmanEngine ─────────────────────────────────────────────────────────────
 export 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();
@@ -43,8 +46,20 @@ export class CapmanEngine {
         // Use FileLearningStore explicitly for persistence across restarts
         this.learning = options.learning === false
             ? null
-            : (options.learning ?? new MemoryLearningStore());
-        logger.info(`CapmanEngine initialized — mode: ${this.mode}, cache: ${this.cache ? 'enabled' : 'disabled'}, learning: ${this.learning ? 'enabled' : 'disabled'}`);
+            : (options.learning ?? new 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.info('Capability embeddings pre-encoded');
+            }).catch(err => {
+                logger.warn(`EmbeddingProvider pre-encode failed — embedding signal disabled: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        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);
     }
@@ -68,6 +83,9 @@ export 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) {
@@ -173,11 +191,19 @@ export 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 = normalizeQuery(query);
-            const capKey = 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 = normalizeQuery(query);
+                const capKey = 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.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.
@@ -374,6 +400,44 @@ export class CapmanEngine {
             }
         }
     }
+    /** Cosine similarity between two equal-length vectors */
+    cosineSim(a, b) {
+        if (a.length !== b.length || a.length === 0) {
+            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.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)
@@ -396,13 +460,31 @@ export 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 = 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.info('Capability embeddings re-encoded after manifest reload');
+            }).catch(err => {
+                this.capEmbeddings = undefined;
+                this.pendingEmbedding = null;
+                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.
@@ -644,13 +726,15 @@ export 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': {
@@ -673,20 +757,33 @@ export class CapmanEngine {
                     else {
                         const t = Date.now();
                         try {
-                            matchResult = await _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 = _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 = _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 _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) {
@@ -731,19 +828,32 @@ export class CapmanEngine {
                         logger.debug(`Query escalated to LLM: "${query}"`);
                         const t2 = Date.now();
                         try {
-                            matchResult = await _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 _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) {
@@ -834,7 +944,15 @@ export 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));
@@ -900,6 +1018,10 @@ export 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)

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
 export { setLogLevel } from './logger';
 export type { LogLevel } from './logger';
-export type { Capability, CapabilityParam, CapmanConfig, Manifest, MatchResult, ExecutionTrace, TraceStep, MatchCandidate, ResolveResult, ApiCallResult, ValidationResult, Resolver, ApiResolver, NavResolver, HybridResolver, PrivacyScope, ResolverType, HttpMethod, ExplainResult, ExplainCandidate, ManifestInfo, Server, LifecycleInfo, LifecycleStatus, CapabilityError, Endpoint, ParamType, MatchHint, } from './types';
+export type { Capability, CapabilityParam, CapmanConfig, Manifest, MatchResult, ExecutionTrace, TraceStep, MatchCandidate, ResolveResult, ApiCallResult, ValidationResult, Resolver, ApiResolver, NavResolver, HybridResolver, PrivacyScope, ResolverType, HttpMethod, ExplainResult, ExplainCandidate, ManifestInfo, Server, LifecycleInfo, LifecycleStatus, CapabilityError, Endpoint, ParamType, MatchHint, EmbeddingProvider, } from './types';
 export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
 export { match, matchWithLLM, extractParams, } from './matcher';
 export { LLMParseError } from './matcher';
@@ -10,6 +10,7 @@ export { filterByTags } from './matcher';
 export { resolve } from './resolver';
 export type { ResolveOptions, AuthContext } from './resolver';
 export { CapmanEngine } from './engine';
+export { ConcurrentCapmanEngine } from './concurrent';
 export type { EngineOptions, EngineResult } from './engine';
 export { MemoryCache, FileCache, ComboCache, buildCacheKey, normalizeQuery } from './cache';
 export type { CacheStore, CacheEntry } from './cache';

package/dist/esm/index.js

@@ -7,6 +7,7 @@ export { filterByTags } from './matcher';
 export { resolve } from './resolver';
 // ─── Engine (recommended API) ─────────────────────────────────────────────────
 export { CapmanEngine } from './engine';
+export { ConcurrentCapmanEngine } from './concurrent';
 // ─── Cache ────────────────────────────────────────────────────────────────────
 export { MemoryCache, FileCache, ComboCache, buildCacheKey, normalizeQuery } from './cache';
 // ─── Learning ─────────────────────────────────────────────────────────────────

package/dist/esm/learning.d.ts

@@ -7,12 +7,19 @@ export interface LearningEntry {
     resolvedVia: 'keyword' | 'llm' | 'cache';
     timestamp: string;
     /**
-     * Confidence-derived weight stored at record time (confidence / 100, floor 0.1).
-     * Used by subtract() to reverse the exact contribution made by update(),
-     * preventing index drift when high-confidence entries are pruned.
-     * Optional for backwards-compatibility with persisted entries written before v0.5.5.
-     */
+       * Confidence-derived weight stored at record time (confidence / 100, floor 0.1).
+       * Used by subtract() to reverse the exact contribution made by update(),
+       * preventing index drift when high-confidence entries are pruned.
+       * Optional for backwards-compatibility with persisted entries written before v0.5.5.
+       */
     weight?: number;
+    /**
+     * Unix timestamp (ms) when this entry was last updated.
+     * Used for time-decay — older entries contribute less learning signal.
+     * Optional for backwards-compatibility with persisted entries written before v0.7.0.
+     * Migration: FileLearningStore falls back to file mtime for entries missing this field.
+     */
+    lastUpdated?: number;
 }
 export interface KeywordStats {
     /** keyword → Map of capabilityId → hit count */
@@ -50,7 +57,7 @@ export declare class FileLearningStore implements LearningStore {
     private learningIndex;
     private dirty;
     private saveTimer;
-    constructor(filePath?: string);
+    constructor(filePath?: string, halfLifeDays?: number);
     flushSync(): void;
     /**
      * Removes this store from the exit flush registry and cancels any pending save timer.
@@ -74,6 +81,7 @@ export declare class FileLearningStore implements LearningStore {
 export declare class MemoryLearningStore implements LearningStore {
     private entries;
     private learningIndex;
+    constructor(halfLifeDays?: number);
     record(entry: LearningEntry): Promise<void>;
     getStats(): Promise<KeywordStats>;
     getIndex(): Promise<Record<string, Record<string, number>>>;

package/dist/esm/learning.js

@@ -3,6 +3,15 @@ import * as path from 'path';
 import { logger } from './logger';
 const MAX_LEARNING_ENTRIES = 10_000;
 import { tokenize } from './matcher';
+/**
+ * Exponential decay — older entries contribute less signal.
+ * At exactly halfLifeDays old, a weight of 1.0 decays to 0.5.
+ * At 2× halfLifeDays, it decays to 0.25. And so on.
+ */
+function decayedWeight(weight, lastUpdated, halfLifeDays) {
+    const ageDays = (Date.now() - lastUpdated) / (1000 * 60 * 60 * 24);
+    return weight * Math.pow(0.5, ageDays / halfLifeDays);
+}
 // Module-level registry — tracks all active FileLearningStore instances
 // for process exit flushing. Handlers registered once to avoid accumulation.
 const activeStores = new Set();
@@ -56,11 +65,18 @@ function computeTopCapabilities(entries, limit) {
 // Both FileLearningStore and MemoryLearningStore compose this instead of
 // duplicating the same ~80 lines of index management logic.
 class LearningIndex {
-    constructor() {
+    constructor(halfLifeDays = 30) {
         this.index = {};
+        /** Tracks when each (word, capabilityId) cell was last reinforced — used for decay */
+        this.lastUpdatedIndex = {};
         this.statsCounter = {
             totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0,
         };
+        if (halfLifeDays <= 0) {
+            throw new RangeError(`halfLifeDays must be a positive number — got ${halfLifeDays}. ` +
+                `Use a value in days e.g. 30 (1 month), 7 (1 week).`);
+        }
+        this.halfLifeDays = halfLifeDays;
     }
     update(entry) {
         this.statsCounter.totalQueries++;
@@ -75,15 +91,21 @@ class LearningIndex {
             // more signal than a 51% borderline match. Floor of 0.1 ensures
             // borderline matches still contribute, just proportionally less.
             const weight = Math.max(0.1, entry.confidence / 100);
-            // Store weight on the entry so subtract() can reverse the exact amount.
-            // Without this, subtract() would have to use a hardcoded estimate (0.5)
-            // that causes index drift after pruning high-confidence entries.
+            // Respect a caller-supplied timestamp (historical replay, rebuild()).
+            // For brand-new real-time entries lastUpdated is undefined — default to now.
+            const now = entry.lastUpdated ?? Date.now();
+            // Store weight and timestamp on the entry so subtract() can reverse the
+            // exact amount and migration has an accurate record time.
             entry.weight = weight;
+            entry.lastUpdated = now;
             const words = tokenize(entry.query);
             for (const word of words) {
                 this.index[word] ??= {};
                 this.index[word][entry.capabilityId] =
                     (this.index[word][entry.capabilityId] ?? 0) + weight;
+                // Track when this (word, cap) cell was last reinforced for decay
+                this.lastUpdatedIndex[word] ??= {};
+                this.lastUpdatedIndex[word][entry.capabilityId] = now;
             }
         }
     }
@@ -111,9 +133,11 @@ class LearningIndex {
                 (this.index[word][entry.capabilityId] ?? weight) - weight;
             if (this.index[word][entry.capabilityId] <= 0) {
                 delete this.index[word][entry.capabilityId];
+                delete this.lastUpdatedIndex[word]?.[entry.capabilityId];
             }
             if (Object.keys(this.index[word]).length === 0) {
                 delete this.index[word];
+                delete this.lastUpdatedIndex[word];
             }
         }
     }
@@ -126,10 +150,25 @@ class LearningIndex {
     }
     reset() {
         this.index = {};
+        this.lastUpdatedIndex = {};
         this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
     }
     getStats() {
-        return { ...this.statsCounter, index: structuredClone(this.index) };
+        // Apply time-decay lazily on read. The index stores accumulated weights;
+        // each (word, capId) cell is decayed by how long ago it was last reinforced.
+        // This means recently-used capabilities retain full signal while stale ones fade.
+        const decayed = {};
+        for (const [word, capMap] of Object.entries(this.index)) {
+            for (const [capId, weight] of Object.entries(capMap)) {
+                const lastUpdated = this.lastUpdatedIndex[word]?.[capId] ?? Date.now();
+                const dw = decayedWeight(weight, lastUpdated, this.halfLifeDays);
+                if (dw > 0.001) { // drop negligible signal — avoids ghost entries
+                    decayed[word] ??= {};
+                    decayed[word][capId] = dw;
+                }
+            }
+        }
+        return { ...this.statsCounter, index: decayed };
     }
     getIndex() {
         return structuredClone(this.index);
@@ -137,13 +176,13 @@ class LearningIndex {
 }
 // ─── File Learning Store ──────────────────────────────────────────────────────
 export class FileLearningStore {
-    constructor(filePath = '.capman/learning.json') {
+    constructor(filePath = '.capman/learning.json', halfLifeDays = 30) {
         this.entries = [];
         this.loadPromise = null;
         this.saveQueue = Promise.resolve();
-        this.learningIndex = new LearningIndex();
         this.dirty = false;
         this.saveTimer = null;
+        this.learningIndex = new LearningIndex(halfLifeDays);
         const cwd = process.cwd();
         const resolved = path.resolve(cwd, filePath);
         const allowedPrefix = cwd === '/' ? '/' : cwd + path.sep;
@@ -207,6 +246,17 @@ export class FileLearningStore {
     }
     async _doLoad() {
         try {
+            // Fetch mtime once — used as lastUpdated fallback for pre-v0.7.0 entries.
+            // Conservative: treats all old entries as "last updated when file was written"
+            // rather than "infinitely old", preventing a cliff-edge decay on first upgrade.
+            let fileMtimeMs = Date.now();
+            try {
+                const stat = await fs.promises.stat(this.filePath);
+                fileMtimeMs = stat.mtimeMs;
+            }
+            catch {
+                // File doesn't exist yet or stat failed — Date.now() fallback is safe
+            }
             const raw = await fs.promises.readFile(this.filePath, 'utf-8');
             const parsed = JSON.parse(raw);
             if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && Array.isArray(parsed.entries)) {
@@ -220,7 +270,11 @@ export class FileLearningStore {
                         (entry.capabilityId === null || typeof entry.capabilityId === 'string') &&
                         typeof entry.confidence === 'number' &&
                         typeof entry.resolvedVia === 'string') {
-                        validEntries.push(entry);
+                        // Migration guard: backfill lastUpdated for pre-v0.7.0 entries
+                        validEntries.push({
+                            ...entry,
+                            lastUpdated: entry.lastUpdated ?? fileMtimeMs,
+                        });
                     }
                     else {
                         skipped++;
@@ -326,9 +380,9 @@ export class FileLearningStore {
 }
 // ─── Memory Learning Store (for testing) ─────────────────────────────────────
 export class MemoryLearningStore {
-    constructor() {
+    constructor(halfLifeDays = 30) {
         this.entries = [];
-        this.learningIndex = new LearningIndex();
+        this.learningIndex = new LearningIndex(halfLifeDays);
     }
     async record(entry) {
         const sanitized = {

package/dist/esm/matcher.d.ts

@@ -59,6 +59,14 @@ export declare function scoreCapability(qWordSet: Set<string>, cap: Capability,
  * Input must already be post-stopword and post-stem (use tokenize() first).
  */
 export declare function extractBigrams(tokens: string[]): Set<string>;
+/**
+ * Reciprocal Rank Fusion — fuses multiple ranked lists into a single score map.
+ * k=60 is the standard literature default.
+ */
+export declare function rrf(rankings: Array<Array<{
+    id: string;
+    score: number;
+}>>, k?: number): Map<string, number>;
 /**
  * Returns a sub-manifest containing only capabilities that match ALL provided tags.
  * Capabilities without tags are excluded when tags filter is active.
@@ -108,6 +116,8 @@ export interface MatchOptions {
     bm25K1?: number;
     bm25B?: number;
     bm25Ceiling?: number;
+    /** Pre-computed cosine similarity scores keyed by capability ID (0–100). Engine passes these when an EmbeddingProvider is configured. */
+    embeddingScores?: Map<string, number>;
 }
 /**
  * Calibrates a BM25 normalization ceiling from the manifest.
@@ -117,6 +127,8 @@ export interface MatchOptions {
 export declare function calibrateCeiling(capabilities: Capability[], bm25Index: BM25Index, k1: number, b: number): number;
 export declare function match(query: string, manifest: Manifest, options?: MatchOptions): MatchResult;
 export interface LLMMatcherOptions {
+    /** App name for prompt context — passed from engine, optional for direct callers */
+    app?: string;
     llm: (prompt: string) => Promise<string>;
 }
 /**
@@ -130,4 +142,4 @@ export interface LLMMatcherOptions {
  * wrapper that maps the prompt to a proper system message, keeping user query
  * data in the user turn only.
  */
-export declare function matchWithLLM(query: string, manifest: Manifest, options: LLMMatcherOptions): Promise<MatchResult>;
+export declare function matchWithLLM(query: string, topCandidates: Capability[], options: LLMMatcherOptions): Promise<MatchResult>;