capman 0.4.5 → 0.5.1

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

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAA2C,MAAM,SAAS,CAAA;AAIlG,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,eAAe,EAAE,OAAO,CAAA;IACxB,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA+BD,wBAAsB,OAAO,CAC3B,WAAW,EAAE,WAAW,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAuExB"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAA2C,MAAM,SAAS,CAAA;AAIlG,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,eAAe,EAAE,OAAO,CAAA;IACxB,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAqCD,wBAAsB,OAAO,CAC3B,WAAW,EAAE,WAAW,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA+ExB"}

package/dist/cjs/resolver.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolve = resolve;
 const logger_1 = require("./logger");
+function redactParams(params) {
+    return Object.fromEntries(Object.entries(params).map(([k, v]) => [k, v != null ? '[REDACTED]' : 'null']));
+}
 function checkPrivacy(capability, auth) {
     const level = capability.privacy.level;
     if (level === 'public')
@@ -44,19 +47,25 @@ async function resolve(matchResult, params = {}, options = {}) {
         };
     }
     // ── Session param injection ───────────────────────────────────────────────
-    // Inject auth.userId into any params marked as source: 'session'
+    // Inject auth.userId into params marked as source: 'session'
+    // Session params are only injected if they appear as {template} in the path —
+    // they must never leak into the query string as ?user_id=xyz
     const enrichedParams = { ...params };
     if (options.auth?.userId !== undefined && options.auth.userId !== '') {
+        const resolver = capability.resolver;
+        const pathTemplate = resolver.type === 'api' ? resolver.endpoints.map(e => e.path).join('') :
+            resolver.type === 'hybrid' ? resolver.api.endpoints.map(e => e.path).join('') :
+                resolver.type === 'nav' ? resolver.destination : '';
         for (const param of capability.params) {
-            if (param.source === 'session') {
+            if (param.source === 'session' && pathTemplate.includes(`{${param.name}}`)) {
                 enrichedParams[param.name] = options.auth.userId;
-                logger_1.logger.debug(`Injected session param "${param.name}" = "${options.auth.userId}"`);
+                logger_1.logger.debug(`Injected session param "${param.name}" (value redacted)`);
             }
         }
     }
     const resolver = capability.resolver;
     logger_1.logger.info(`Resolving capability "${capability.id}" via ${resolver.type} resolver`);
-    logger_1.logger.debug(`Params: ${JSON.stringify(params)}`);
+    logger_1.logger.debug(`Params: ${JSON.stringify(redactParams(params))}`);
     logger_1.logger.debug(`Options: baseUrl=${options.baseUrl} dryRun=${options.dryRun}`);
     try {
         switch (resolver.type) {
@@ -172,12 +181,20 @@ async function resolveApi(resolver, params, options) {
         };
     }
 }
+function validateNavParam(key, value) {
+    if (!/^[a-zA-Z0-9_\-]+$/.test(value)) {
+        throw new Error(`Nav param "${key}" contains invalid characters: "${value}". ` +
+            `Only alphanumeric, hyphens, and underscores are allowed.`);
+    }
+}
 function resolveNav(resolver, params) {
     let destination = resolver.destination;
     for (const [key, value] of Object.entries(params)) {
         if (value === null || value === undefined)
             continue;
-        destination = destination.replace(`{${key}}`, encodeURIComponent(String(value)));
+        const str = String(value);
+        validateNavParam(key, str);
+        destination = destination.replace(`{${key}}`, encodeURIComponent(str));
     }
     return { success: true, resolverType: 'nav', navTarget: destination };
 }

package/dist/cjs/resolver.js.map

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

package/dist/cjs/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.4.5";
+export declare const VERSION = "0.5.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/cjs/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Auto-generated by scripts/version.js — do not edit manually
-exports.VERSION = '0.4.5';
+exports.VERSION = '0.5.1';
 //# sourceMappingURL=version.js.map

package/dist/esm/cache.d.ts

@@ -6,7 +6,7 @@ export interface CacheEntry {
     hits: number;
 }
 export interface CacheStore {
-    get(key: string): Promise<CacheEntry | null>;
+    get(key: string, ttlMs?: number): Promise<CacheEntry | null>;
     set(key: string, result: MatchResult): Promise<void>;
     clear(): Promise<void>;
     size(): Promise<number>;
@@ -21,7 +21,7 @@ export declare function normalizeQuery(query: string): string;
 export declare function buildCacheKey(query: string, capabilityId: string | null, extractedParams: Record<string, string | null>): string;
 export declare class MemoryCache implements CacheStore {
     private store;
-    get(key: string): Promise<CacheEntry | null>;
+    get(key: string, ttlMs?: number): Promise<CacheEntry | null>;
     set(key: string, result: MatchResult): Promise<void>;
     clear(): Promise<void>;
     size(): Promise<number>;
@@ -30,10 +30,12 @@ export declare class FileCache implements CacheStore {
     private filePath;
     private store;
     private loaded;
+    private saveQueue;
     constructor(filePath?: string);
     private load;
     private save;
-    get(key: string): Promise<CacheEntry | null>;
+    private _doSave;
+    get(key: string, ttlMs?: number): Promise<CacheEntry | null>;
     set(key: string, result: MatchResult): Promise<void>;
     clear(): Promise<void>;
     size(): Promise<number>;
@@ -42,7 +44,7 @@ export declare class ComboCache implements CacheStore {
     private memory;
     private file;
     constructor(filePath?: string);
-    get(key: string): Promise<CacheEntry | null>;
+    get(key: string, ttlMs?: number): Promise<CacheEntry | null>;
     set(key: string, result: MatchResult): Promise<void>;
     clear(): Promise<void>;
     size(): Promise<number>;

package/dist/esm/cache.js

@@ -27,10 +27,17 @@ export class MemoryCache {
     constructor() {
         this.store = new Map();
     }
-    async get(key) {
+    async get(key, ttlMs) {
         const entry = this.store.get(key);
         if (entry) {
+            if (ttlMs && Date.now() - new Date(entry.cachedAt).getTime() > ttlMs) {
+                this.store.delete(key);
+                logger.debug(`Cache entry expired (memory): "${key}"`);
+                return null;
+            }
             entry.hits++;
+            this.store.delete(key);
+            this.store.set(key, entry);
             logger.debug(`Cache hit (memory): "${key}"`);
             return entry;
         }
@@ -55,10 +62,12 @@ export class MemoryCache {
     async size() { return this.store.size; }
 }
 // ─── File Cache ───────────────────────────────────────────────────────────────
+const FILE_CACHE_MAX = 2048;
 export class FileCache {
     constructor(filePath = '.capman/cache.json') {
         this.store = new Map();
         this.loaded = false;
+        this.saveQueue = Promise.resolve();
         this.filePath = path.resolve(process.cwd(), filePath);
         logger.info(`FileCache initialized — writing to: ${this.filePath}`);
     }
@@ -81,28 +90,47 @@ export class FileCache {
         }
         this.loaded = true;
     }
-    async save() {
+    save() {
+        this.saveQueue = this.saveQueue.then(() => this._doSave());
+        return this.saveQueue;
+    }
+    async _doSave() {
         try {
             const dir = path.dirname(this.filePath);
             await fs.promises.mkdir(dir, { recursive: true });
             await fs.promises.writeFile(this.filePath, JSON.stringify(Object.fromEntries(this.store), null, 2));
         }
-        catch {
-            logger.warn(`Failed to save file cache to ${this.filePath}`);
+        catch (err) {
+            logger.warn(`Failed to save file cache to ${this.filePath}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    async get(key) {
+    async get(key, ttlMs) {
         await this.load();
         const entry = this.store.get(key);
         if (entry) {
+            if (ttlMs && Date.now() - new Date(entry.cachedAt).getTime() > ttlMs) {
+                this.store.delete(key);
+                await this.save();
+                logger.debug(`Cache entry expired (file): "${key}"`);
+                return null;
+            }
             entry.hits++;
+            this.store.delete(key);
+            this.store.set(key, entry);
             logger.debug(`Cache hit (file): "${key}"`);
-            return entry;
+            await this.save();
         }
-        return null;
+        return entry ?? null;
     }
     async set(key, result) {
         await this.load();
+        if (this.store.size >= FILE_CACHE_MAX) {
+            const oldest = this.store.keys().next().value;
+            if (oldest !== undefined) {
+                this.store.delete(oldest);
+                logger.debug(`File cache evicted oldest entry (max size ${FILE_CACHE_MAX} reached)`);
+            }
+        }
         this.store.set(key, {
             query: key,
             result,
@@ -127,14 +155,13 @@ export class ComboCache {
         this.memory = new MemoryCache();
         this.file = new FileCache(filePath);
     }
-    async get(key) {
-        const memHit = await this.memory.get(key);
+    async get(key, ttlMs) {
+        const memHit = await this.memory.get(key, ttlMs);
         if (memHit)
             return memHit;
-        const fileHit = await this.file.get(key);
+        const fileHit = await this.file.get(key, ttlMs);
         if (fileHit) {
             await this.memory.set(key, fileHit.result);
-            logger.debug(`Cache promoted to memory: "${key}"`);
             return fileHit;
         }
         return null;

package/dist/esm/engine.d.ts

@@ -2,8 +2,27 @@ import type { Manifest, MatchResult, ResolveResult, ExecutionTrace, ExplainResul
 import type { LLMMatcherOptions } from './matcher';
 import type { ResolveOptions, AuthContext } from './resolver';
 import type { CacheStore } from './cache';
-import type { LearningStore, KeywordStats } from './learning';
+import type { LearningStore } from './learning';
 import type { MatchMode } from './index';
+/**
+ * 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
+ *
+ * @example
+ * // Safe — per-request engine
+ * app.post('/ask', async (req, res) => {
+ *   const engine = new CapmanEngine({ manifest, llm, mode: 'balanced' })
+ *   const result = await engine.ask(req.body.query)
+ *   res.json(result)
+ * })
+ */
 export interface EngineOptions {
     /** The capability manifest to use */
     manifest: Manifest;
@@ -28,6 +47,19 @@ export interface EngineOptions {
     headers?: Record<string, string>;
     /** Confidence threshold for keyword matcher (default: 50) */
     threshold?: number;
+    /**
+     * Optional TTL for cache entries in milliseconds.
+     * Entries older than this are treated as misses and evicted on read.
+     * Default: no expiry.
+     *
+     * Useful when capabilities are frequently updated or removed — ensures
+     * stale entries don't persist indefinitely after a manifest change.
+     *
+     * @example
+     * // Expire cache entries after 1 hour
+     * new CapmanEngine({ manifest, cacheTtlMs: 60 * 60 * 1000 })
+     */
+    cacheTtlMs?: number;
     /**
      * Maximum LLM calls per minute in balanced/accurate mode.
      * After limit is hit, falls back to keyword result.
@@ -70,12 +102,11 @@ export declare class CapmanEngine {
     private auth?;
     private headers?;
     private threshold;
+    private cacheTtlMs;
     private maxLLMCallsPerMinute;
     private llmCooldownMs;
     private llmCircuitBreakerThreshold;
     private llmCircuitBreakerResetMs;
-    private cachedStats;
-    private statsInvalidated;
     private llmCallsThisMinute;
     private llmWindowStart;
     private llmLastCallAt;
@@ -98,7 +129,7 @@ export declare class CapmanEngine {
      * Get stats from the learning store.
      * Shows which capabilities are most used, LLM vs keyword ratio, cache hit rate.
      */
-    getStats(): Promise<KeywordStats | null>;
+    getStats(): Promise<import("./learning").KeywordStats | null>;
     /**
      * Get the most frequently matched capabilities.
      */
@@ -141,6 +172,17 @@ export declare class CapmanEngine {
      * Records a failed LLM call — may open the circuit breaker.
      */
     private recordLLMFailure;
+    /**
+     * Runs the matching pipeline for a query — shared by ask() and explain().
+     * Handles cheap / balanced / accurate mode dispatch and LLM rate limiting.
+     * Returns the match result and which resolver was used.
+     */
+    private _runMatch;
+    /**
+     * Applies learning boost to a MatchResult and returns the updated result.
+     * Shared by ask() and explain() to avoid logic divergence.
+     */
+    private applyBoostToMatchResult;
     /**
      * Applies learning boost to match candidates based on historical usage.
      * Capabilities that have previously matched similar keywords get a small