capman 0.6.0 → 0.6.2

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

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AA4EvB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiB9B,CAAA;AAID,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKzB,CAAA;AAIF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,mBAAmB,CAQnE;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,mBAAmB,CAQvE"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAgIvB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoB9B,CAAA;AAID,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASzB,CAAA;AAIF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,mBAAmB,CAQnE;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,mBAAmB,CAQvE"}

package/dist/cjs/schema.js

@@ -10,17 +10,22 @@ const CapabilityParamSchema = zod_1.z.object({
     description: zod_1.z.string().min(1, 'param description is required'),
     required: zod_1.z.boolean(),
     source: zod_1.z.enum(['user_query', 'session']),
-    default: zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean()]).optional(),
     pattern: zod_1.z.string().optional(),
-});
+    type: zod_1.z.enum(['string', 'number', 'boolean', 'date', 'email', 'url', 'enum', 'object']).optional(),
+    enum: zod_1.z.array(zod_1.z.string()).optional(),
+    example: zod_1.z.string().optional(),
+}).refine(p => !(p.type === 'enum' && (!p.enum || p.enum.length === 0)), { message: 'enum values required when type is "enum"' });
 // ─── Resolver Schemas ─────────────────────────────────────────────────────────
+const EndpointSchema = zod_1.z.object({
+    method: zod_1.z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']),
+    path: zod_1.z.string().min(1, 'endpoint path is required'),
+    params: zod_1.z.array(zod_1.z.string()).optional(),
+    idempotent: zod_1.z.boolean().optional(),
+    idempotencyKey: zod_1.z.string().optional(),
+});
 const ApiResolverSchema = zod_1.z.object({
     type: zod_1.z.literal('api'),
-    endpoints: zod_1.z.array(zod_1.z.object({
-        method: zod_1.z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
-        path: zod_1.z.string().min(1, 'endpoint path is required'),
-        params: zod_1.z.array(zod_1.z.string()).optional(),
-    })).min(1, 'at least one endpoint is required'),
+    endpoints: zod_1.z.array(EndpointSchema).min(1, 'at least one endpoint is required'),
 });
 const NavResolverSchema = zod_1.z.object({
     type: zod_1.z.literal('nav'),
@@ -30,11 +35,7 @@ const NavResolverSchema = zod_1.z.object({
 const HybridResolverSchema = zod_1.z.object({
     type: zod_1.z.literal('hybrid'),
     api: zod_1.z.object({
-        endpoints: zod_1.z.array(zod_1.z.object({
-            method: zod_1.z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
-            path: zod_1.z.string().min(1),
-            params: zod_1.z.array(zod_1.z.string()).optional(),
-        })).min(1),
+        endpoints: zod_1.z.array(EndpointSchema).min(1),
     }),
     nav: zod_1.z.object({
         destination: zod_1.z.string().min(1),
@@ -51,6 +52,22 @@ const PrivacyScopeSchema = zod_1.z.object({
     level: zod_1.z.enum(['public', 'user_owned', 'admin']),
     note: zod_1.z.string().optional(),
 });
+const LifecycleInfoSchema = zod_1.z.object({
+    status: zod_1.z.enum(['stable', 'beta', 'experimental', 'deprecated']),
+    deprecatedAt: zod_1.z.string().datetime().optional(),
+    sunsetAt: zod_1.z.string().datetime().optional(),
+    successor: zod_1.z.string().optional(),
+    note: zod_1.z.string().optional(),
+});
+const MatchHintSchema = zod_1.z.object({
+    preferredMode: zod_1.z.enum(['cheap', 'balanced', 'accurate']).optional(),
+});
+const CapabilityErrorSchema = zod_1.z.object({
+    code: zod_1.z.string().min(1, 'error code is required'),
+    description: zod_1.z.string().min(1, 'error description is required'),
+    httpStatus: zod_1.z.number().int().min(400).max(599).optional(),
+    retryable: zod_1.z.boolean().optional(),
+});
 // ─── Capability Schema ────────────────────────────────────────────────────────
 const CapabilitySchema = zod_1.z.object({
     id: zod_1.z.string().min(1, 'capability id is required')
@@ -64,24 +81,56 @@ const CapabilitySchema = zod_1.z.object({
     returns: zod_1.z.array(zod_1.z.string()),
     resolver: ResolverSchema,
     privacy: PrivacyScopeSchema,
+    lifecycle: LifecycleInfoSchema.optional(),
+    tags: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+    errors: zod_1.z.array(CapabilityErrorSchema).optional(),
+    matchHint: MatchHintSchema.optional(),
+});
+const ServerSchema = zod_1.z.object({
+    url: zod_1.z.string().url('server url must be a valid URL'),
+    description: zod_1.z.string().optional(),
+    environment: zod_1.z.string().optional(),
+});
+// ─── ManifestInfo Schema ──────────────────────────────────────────────────────
+const ManifestInfoSchema = zod_1.z.object({
+    title: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    version: zod_1.z.string().optional(),
+    homepage: zod_1.z.string().url().optional(),
+    contact: zod_1.z.object({
+        name: zod_1.z.string().optional(),
+        email: zod_1.z.string().email().optional(),
+        url: zod_1.z.string().url().optional(),
+    }).optional(),
+    license: zod_1.z.object({
+        name: zod_1.z.string().min(1, 'license name is required'),
+        url: zod_1.z.string().url().optional(),
+    }).optional(),
 });
 // ─── Config Schema ────────────────────────────────────────────────────────────
 exports.CapmanConfigSchema = zod_1.z.object({
     app: zod_1.z.string().min(1, 'app name is required'),
     baseUrl: zod_1.z.string().url().optional(),
+    info: ManifestInfoSchema.optional(),
+    servers: zod_1.z.array(ServerSchema).optional(),
+    tagRegistry: zod_1.z.record(zod_1.z.object({ description: zod_1.z.string() })).optional(),
     capabilities: zod_1.z.array(CapabilitySchema)
         .min(1, 'at least one capability is required')
         .refine(caps => new Set(caps.map(c => c.id)).size === caps.length, 'capability ids must be unique'),
 }).refine(cfg => {
     const needsBaseUrl = cfg.capabilities.some(c => c.resolver.type === 'api' || c.resolver.type === 'hybrid');
-    return !needsBaseUrl || !!cfg.baseUrl;
+    return !needsBaseUrl || !!cfg.baseUrl || (cfg.servers?.length ?? 0) > 0;
 }, { message: 'baseUrl is required when any capability uses an api or hybrid resolver' });
 // ─── Manifest Schema ──────────────────────────────────────────────────────────
 exports.ManifestSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.string().min(1, 'schemaVersion is required'),
     version: zod_1.z.string(),
     app: zod_1.z.string().min(1),
     generatedAt: zod_1.z.string().datetime(),
     capabilities: zod_1.z.array(CapabilitySchema).min(1),
+    tagRegistry: zod_1.z.record(zod_1.z.object({ description: zod_1.z.string() })).optional(),
+    servers: zod_1.z.array(ServerSchema).optional(),
+    info: ManifestInfoSchema.optional(),
 });
 function validateConfig(config) {
     const result = exports.CapmanConfigSchema.safeParse(config);

package/dist/cjs/schema.js.map

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

package/dist/cjs/types.d.ts

@@ -1,5 +1,6 @@
 export type ResolverType = 'api' | 'nav' | 'hybrid';
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export type ParamType = 'string' | 'number' | 'boolean' | 'date' | 'email' | 'url' | 'enum' | 'object';
 export interface CapabilityParam {
     name: string;
     description: string;
@@ -9,17 +10,49 @@ export interface CapabilityParam {
      * Optional extraction hint. Either a named type or an example template.
      * Named types: 'email' | 'date' | 'orderId' | 'url'
      * Example template: "order {paramName}" — extracts token after "order"
-     * When provided, pattern matching runs before keyword heuristics.
      */
     pattern?: string;
+    /**
+     * Semantic type of the parameter value.
+     * When set, implies a TYPE_PATTERNS match without requiring pattern to be set.
+     * 'email', 'date', 'url' map directly to TYPE_PATTERNS regex.
+     * 'enum' requires the enum field to be set with allowed values.
+     * 'number', 'boolean', 'object' affect coercion in LLM extraction.
+     */
+    type?: ParamType;
+    /**
+     * Allowed values when type === 'enum'.
+     * Extracted values not in this list are rejected and added to missingParams.
+     */
+    enum?: string[];
+    /**
+     * Single concrete example for LLM param prompting.
+     * Helps the LLM understand what a valid value looks like.
+     * e.g. example: "ORD-12345"
+     */
+    example?: string;
+}
+export interface Endpoint {
+    method: HttpMethod;
+    path: string;
+    params?: string[];
+    /**
+     * Whether this endpoint is idempotent — safe to retry on failure.
+     * Defaults: true for GET/HEAD/OPTIONS, false for POST/PUT/PATCH/DELETE.
+     * Set explicitly to override — e.g. `idempotent: true` on a POST
+     * with an idempotency key allows retries without `retryAllMethods: true`.
+     */
+    idempotent?: boolean;
+    /**
+     * Name of the param whose value is sent as the `Idempotency-Key` header.
+     * When set and the param is available, the header is injected automatically.
+     * e.g. idempotencyKey: 'order_id' → `Idempotency-Key: ORD-12345`
+     */
+    idempotencyKey?: string;
 }
 export interface ApiResolver {
     type: 'api';
-    endpoints: Array<{
-        method: HttpMethod;
-        path: string;
-        params?: string[];
-    }>;
+    endpoints: Endpoint[];
 }
 export interface NavResolver {
     type: 'nav';
@@ -36,6 +69,50 @@ export interface PrivacyScope {
     level: 'public' | 'user_owned' | 'admin';
     note?: string;
 }
+export type LifecycleStatus = 'stable' | 'beta' | 'experimental' | 'deprecated';
+export interface LifecycleInfo {
+    status: LifecycleStatus;
+    /** ISO 8601 — when the capability was deprecated */
+    deprecatedAt?: string;
+    /** ISO 8601 — when the capability will stop working */
+    sunsetAt?: string;
+    /** Capability id to use instead of this one */
+    successor?: string;
+    /** Human-readable note for consumers */
+    note?: string;
+}
+/**
+ * Optional embedding provider for semantic similarity matching.
+ * Zero mandatory dependency — only used when passed to EngineOptions.
+ * Implement with any model: OpenAI, local ONNX, Transformers.js, etc.
+ */
+export interface EmbeddingProvider {
+    /** Encode a batch of texts into fixed-length float vectors. */
+    encode(texts: string[]): Promise<number[][]>;
+}
+export interface MatchHint {
+    /**
+     * Advisory preferred matching mode for this capability.
+     * The engine logs when it ignores the hint (e.g. engine is in cheap mode
+     * but capability prefers accurate). Never enforced — library must not
+     * restrict what consumers can do.
+     */
+    preferredMode?: MatchMode;
+}
+export interface CapabilityError {
+    /** Machine-readable error code e.g. "ORDER_NOT_FOUND", "INSUFFICIENT_FUNDS" */
+    code: string;
+    /** Human-readable description for developers */
+    description: string;
+    /** HTTP status code this error maps to */
+    httpStatus?: number;
+    /**
+     * Whether the agent should retry after this error.
+     * true  — transient (503, timeout) — retry is safe
+     * false — permanent (422, 404) — retrying won't help, ask user
+     */
+    retryable?: boolean;
+}
 export interface Capability {
     id: string;
     name: string;
@@ -45,17 +122,82 @@ export interface Capability {
     returns: string[];
     resolver: Resolver;
     privacy: PrivacyScope;
+    /** Lifecycle status — defaults to 'stable' when absent */
+    lifecycle?: LifecycleInfo;
+    /** Tags for grouping and filtering capabilities */
+    tags?: string[];
+    errors?: CapabilityError[];
+    matchHint?: MatchHint;
+}
+export interface ManifestInfo {
+    /** Human-readable title for the app */
+    title?: string;
+    /** Brief description of what the app does */
+    description?: string;
+    /** App's own version — distinct from capman package version */
+    version?: string;
+    /** URL to the app's homepage or documentation */
+    homepage?: string;
+    contact?: {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    license?: {
+        /** SPDX license identifier e.g. "MIT", "Apache-2.0" */
+        name: string;
+        url?: string;
+    };
+}
+export interface Server {
+    url: string;
+    description?: string;
+    /**
+     * Environment this server belongs to.
+     * Engine selects server by matching EngineOptions.environment.
+     * Fallback: first server in array when no environment matches.
+     */
+    environment?: 'production' | 'staging' | 'development' | string;
 }
 export interface Manifest {
+    /**
+     * Manifest format version — independent of the capman package version.
+     * Consumers use this to determine which parser/validator to apply.
+     * "1" = v0.6+ schema (tags, lifecycle, typed params, servers, etc.)
+     */
+    schemaVersion: string;
+    /** capman package version that generated this manifest */
     version: string;
     app: string;
     generatedAt: string;
     capabilities: Capability[];
+    /**
+     * Optional registry of known tags with descriptions.
+     * Used for documentation and validation — not required for tags to work.
+     */
+    tagRegistry?: Record<string, {
+        description: string;
+    }>;
+    /** Optional metadata block for documentation and provenance */
+    info?: ManifestInfo;
+    /**
+     * Server definitions. When present, engine selects baseUrl from this list.
+     * Falls back to EngineOptions.baseUrl if servers is absent or no match found.
+     */
+    servers?: Server[];
 }
 export interface CapmanConfig {
     app: string;
     baseUrl?: string;
     capabilities: Capability[];
+    /** Optional metadata — written to manifest.info */
+    info?: ManifestInfo;
+    /** Optional tag registry — written to manifest.tagRegistry */
+    tagRegistry?: Record<string, {
+        description: string;
+    }>;
+    /** Server definitions — written to manifest.servers */
+    servers?: Server[];
 }
 export interface MatchResult {
     capability: Capability | null;
@@ -74,15 +216,20 @@ export interface ApiCallResult {
     status?: number;
     /** Parsed JSON response body — only present when actually executed */
     data?: unknown;
+    /** Error message — only present on network-level failure (status 0) */
+    error?: string;
 }
 export interface ResolveResult {
     success: boolean;
     resolverType: ResolverType | null;
+    error?: string;
+    /** Structured error from capability.errors[] when httpStatus matches */
+    matchedError?: CapabilityError;
     apiCalls?: ApiCallResult[];
     navTarget?: string;
-    /** Execution time in milliseconds */
+    status?: number;
+    data?: unknown;
     durationMs?: number;
-    error?: string;
 }
 export interface ValidationResult {
     valid: boolean;

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

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

package/dist/cjs/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.5.5";
+export declare const VERSION = "0.6.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.5.5';
+exports.VERSION = '0.6.1';
 //# sourceMappingURL=version.js.map

package/dist/esm/cache.d.ts

@@ -31,10 +31,19 @@ export declare class FileCache implements CacheStore {
     private store;
     private loadPromise;
     private saveQueue;
+    private dirty;
+    private saveTimer;
     constructor(filePath?: string);
     private load;
     private _doLoad;
     private save;
+    /**
+     * Debounced save — batches evictions and rapid writes into a single disk flush.
+     * Prevents a flurry of full-file writes when many TTL-expired entries are read
+     * in quick succession (e.g. after a server restart with a stale cache file).
+     * Mirrors the scheduleSave() pattern in FileLearningStore.
+     */
+    private scheduleSave;
     private _doSave;
     get(key: string, ttlMs?: number): Promise<CacheEntry | null>;
     set(key: string, result: MatchResult): Promise<void>;

package/dist/esm/cache.js

@@ -73,6 +73,8 @@ export class FileCache {
         this.store = new Map();
         this.loadPromise = null;
         this.saveQueue = Promise.resolve();
+        this.dirty = false;
+        this.saveTimer = null;
         const cwd = process.cwd();
         const resolved = path.resolve(cwd, filePath);
         const allowedPrefix = cwd === '/' ? '/' : cwd + path.sep;
@@ -102,12 +104,20 @@ export class FileCache {
                 // e.g. "Show me articles" and "show me articles" collapse to the same key.
                 const normalized = new Map();
                 for (const [k, v] of Object.entries(parsed)) {
-                    // Structured keys (cap:/query: prefix from buildCacheKey) are already
-                    // canonical — normalizeQuery strips their colons and equals signs.
-                    const storeKey = (k.startsWith('cap:') || k.startsWith('query:'))
-                        ? k
-                        : normalizeQuery(k);
-                    normalized.set(storeKey, v);
+                    // Validate entry structure before accepting — a corrupted entry
+                    // (null result, missing cachedAt) would cause runtime errors deep
+                    // in the engine when capability fields are accessed.
+                    if (v !== null && typeof v === 'object' &&
+                        'result' in v && v.result !== null &&
+                        typeof v.cachedAt === 'string') {
+                        const storeKey = (k.startsWith('cap:') || k.startsWith('query:'))
+                            ? k
+                            : normalizeQuery(k);
+                        normalized.set(storeKey, v);
+                    }
+                    else {
+                        logger.warn(`File cache: skipping invalid entry for key "${k}"`);
+                    }
                 }
                 this.store = normalized;
                 logger.debug(`File cache loaded: ${this.store.size} entries`);
@@ -128,6 +138,24 @@ export class FileCache {
         this.saveQueue = this.saveQueue.then(() => this._doSave());
         return this.saveQueue;
     }
+    /**
+     * Debounced save — batches evictions and rapid writes into a single disk flush.
+     * Prevents a flurry of full-file writes when many TTL-expired entries are read
+     * in quick succession (e.g. after a server restart with a stale cache file).
+     * Mirrors the scheduleSave() pattern in FileLearningStore.
+     */
+    scheduleSave(urgencyMs = 5_000) {
+        this.dirty = true;
+        if (!this.saveTimer) {
+            this.saveTimer = setTimeout(() => {
+                this.saveTimer = null;
+                if (this.dirty) {
+                    this.dirty = false;
+                    this.save();
+                }
+            }, urgencyMs);
+        }
+    }
     async _doSave() {
         try {
             const dir = path.dirname(this.filePath);
@@ -147,7 +175,9 @@ export class FileCache {
             return null;
         if (ttlMs && Date.now() - new Date(entry.cachedAt).getTime() > ttlMs) {
             this.store.delete(key);
-            await this.save(); // eviction must be persisted
+            // Batch the eviction write — immediate save() on every expired read causes
+            // a full file rewrite per request during cold-start with a stale cache.
+            this.scheduleSave();
             logger.debug(`Cache entry expired (file): "${key}"`);
             return null;
         }

package/dist/esm/concurrent.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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>;
+}

package/dist/esm/concurrent.js

@@ -0,0 +1,66 @@
+/**
+ * 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 { CapmanEngine } from './engine';
+export 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 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();
+    }
+}