capman 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,95 @@ All notable changes to capman are documented here.
 
 ---
 
+## [0.5.1] — 2026-04-18
+### Fixed
+
+**Critical:**
+- `getStats()` and `getIndex()` now return deep clones of the internal index — callers can no longer corrupt the learning store by mutating the returned object
+- `FileCache` and `FileLearningStore` saves are now serialized through a promise queue — concurrent writes no longer silently drop entries via last-write-wins
+- `clear()` now resets the incremental index and stats counters in both stores — previously left stale boost data after clearing
+
+**High:**
+- Session params (`source: 'session'`) no longer leak into API query strings — only injected when the param name appears as a `{template}` in the path
+- `MemoryCache` and `FileCache` now use LRU eviction — previously used FIFO, evicting frequently-accessed entries ahead of cold ones
+- Tiebreak logic in boost corrected — `b.matched` now correctly preserves original winner on tied scores (was `a.matched`, only worked when winner was first in array)
+- LLM error logging now uses `err.message` instead of `${err}` — prevents potential API key exposure from SDK errors that embed auth headers in error objects
+
+**Medium:**
+- `rebuildIndex()` after pruning replaced with `subtractFromIndex()` — O(pruned × w) instead of O(n × w), avoids full index rebuild at the 10k entry cap
+- `ask()` and `explain()` matching dispatch unified into `_runMatch()` — eliminates 60 lines of duplicated mode-switching logic
+- Fallback param denylist extended — category nouns like `"orders"`, `"data"`, `"results"`, `"items"` no longer produce junk URLs
+- File write errors now include the actual error message in the log — was silently swallowing `ENOSPC`, `EACCES` etc.
+- `loadSpec()` fetch in parser now has a 10s timeout with `AbortController` — previously hung indefinitely on unresponsive URLs
+- Cache entries now support optional TTL via `cacheTtlMs` in `EngineOptions` — stale entries from removed capabilities are expired on read
+- `matchWithLLM` JSDoc documents the manifest injection surface — capability descriptions and examples are verbatim in the LLM prompt
+
+### Tests
+- 82 tests passing
+
+## [0.5.0] — 2026-04-15
+### Added
+- Learning index is now incremental — `record()` updates the index in O(w) per entry instead of rebuilding from scratch on every `getStats()` call. Eliminates O(n) CPU spike on every query under load.
+- `getIndex()` method on both `FileLearningStore` and `MemoryLearningStore` — returns live keyword index directly in O(1)
+- `extractParams` exported from public API — enables direct param extraction without going through `match()`
+- `resolverToIntent()` exported from public API — converts a capability's resolver type to its intent string
+- `STOPWORDS` exported from public API — same set used by matcher and learning index
+
+### Fixed
+
+**Security:**
+- Auth bypass via cache key — non-public capabilities are no longer cached. Previously User A's cached match for a `user_owned` capability could be served to User B before privacy checks ran
+- Arbitrary file write via CLI — `--out` and `--config-out` flags in `capman generate` now validated against working directory. Path traversal attempts exit with a clear error
+- Prompt injection hardening — system instructions now come before user data in `matchWithLLM` prompt, with explicit `USER_QUERY_START/END` delimiters
+
+**Learning system:**
+- Boost feedback loop — learning now records the pre-boost match result, not the post-boost winner
+- Boosted winner no longer gets empty `extractedParams` — params extracted directly via `extractParams()`
+- Cache now stores post-boost result — previously cache/live path could return different capabilities
+- OOS results can no longer be promoted via boost alone — boost skipped when all candidates score 0
+- Tied boost scores now preserve original winner
+- Learning index no longer includes stopwords — words like `"show"`, `"get"`, `"for"` were inflating unrelated scores
+- Boost logic deduplicated — `ask()` and `explain()` share `applyBoostToMatchResult()`
+
+**Security — logs:**
+- PII no longer logged at debug level — param values and `auth.userId` redacted as `[REDACTED]`
+
+**Cache:**
+- `FileCache` now has a 2048-entry cap with oldest-first eviction — previously grew without bound
+
+**Resolver:**
+- Nav params validated against allowlist before substitution — prevents open redirect via encoded path separators
+
+**Matcher:**
+- `JSON.parse` failures no longer trigger the circuit breaker — prefixed `LLM_PARSE_ERROR` and treated separately from network failures
+- Required param fallback rejects generic nouns — only accepts identifier-shaped last words
+
+**Engine:**
+- Version compatibility warning now uses `console.warn` — was using `logger.warn` suppressed by default `'silent'` log level
+- Version warning wording softened — advisory not mandatory
+- Concurrency limitation documented in `EngineOptions` JSDoc and README
+
+### Tests
+- 80 tests passing (up from 73)
+- Boost tests now use `mode: 'balanced'` — previously used `mode: 'cheap'` making them vacuous
+- Nav open redirect test added
+
+---
+
+## [0.4.5] — 2026-04-08
+### Added
+- Learning index wired into keyword matcher — boost up to +15 points for historically matched capabilities
+- Manifest version compatibility check — warns when manifest `major.minor` differs from engine version
+
+### Fixed
+- Dead logger warning condition in `matchWithLLM` corrected
+- Empty string `userId` no longer injected into session params
+- `resolverToIntent()` exported and reused in engine
+- Learning boost skipped in `cheap` mode
+- Boost logic applied consistently in both `ask()` and `explain()`
+
+---
+
 ## [0.4.4] — 2026-04-05
 ### Fixed
 - Rate limit double-counting on LLM failure — `recordLLMFailure()` no longer increments `llmCallsThisMinute` (slot already reserved by `checkLLMAllowed()`)

package/CODEBASE.md

@@ -47,7 +47,7 @@ Key exports:
 - `validateManifest(manifest)` — validates a `Manifest` at read time
 
 Notable rules:
-- `id` must match `/^[a-z][a-z0-9_]*$/` — snake_case only
+- `id` must match `/^[a-z0-9_]+$/` — snake_case only
 - `description` minimum 10 characters
 - Capability IDs must be unique within a manifest
 
@@ -61,35 +61,38 @@ Key exports:
 - `loadConfig(path?)` → `CapmanConfig` — loads `capman.config.js` via `require()`
 - `writeManifest(manifest, path?)` — writes `manifest.json`
 - `readManifest(path?)` → `Manifest` — reads and Zod-validates `manifest.json`
-- `validate(manifest)` → `ValidationResult` — runs Zod + warns on missing examples
-- `generateStarterConfig()` → `string` — returns starter `capman.config.js` content
+- `validate(manifest)` → `ValidationResult`
+- `generateStarterConfig()` → `string`
 - `VERSION` — current version string, auto-generated by `scripts/version.js`
 
+Note: `loadConfig()` uses `require()` internally — CJS config files only. ESM config files (`.mjs` or `"type": "module"`) are not supported. Full ESM config support is planned for v0.6.
+
 ---
 
 ### `src/matcher.ts`
 Intent matching — keyword scoring and LLM-based matching.
 
 Key exports:
-- `match(query, manifest)` → `MatchResult`
-  - Scores every capability against the query
-  - Returns winner + all candidates with scores
-  - Extracts params from the query using keyword heuristics
-  - Returns `out_of_scope` if best score < 50%
-- `matchWithLLM(query, manifest, { llm })` → `MatchResult`
-  - Sends structured prompt to LLM with query as JSON field (prompt injection safe)
-  - Returns matched capability, confidence, intent, extracted params
+- `match(query, manifest)` → `MatchResult` — scores all capabilities, returns winner + all candidates
+- `matchWithLLM(query, manifest, { llm })` → `MatchResult` — LLM-based matching
+  - Query passed as `JSON.stringify({ user_query })` with system instructions before user data
+  - `USER_QUERY_START/END` delimiters separate instructions from user-controlled content
+  - Parse failures throw `LLM_PARSE_ERROR:` prefixed errors — not counted as network failures
   - Errors propagate to caller — no internal try/catch
+- `extractParams(query, capability)` → `Record<string, string | null>` — direct param extraction
+- `resolverToIntent(capability)` → intent string — converts resolver type to intent
+- `STOPWORDS` — set of words filtered from scoring and learning index
 
 Scoring algorithm (weights):
-- Examples match: up to 60 points
+- Examples: best single-example overlap score — up to 60 points (not accumulated across examples)
 - Description match: up to 30 points
 - Name match: up to 10 points
 
 Param extraction:
 - `isIdParam` — single token (e.g. `order_id=1234`)
 - `isNavParam` — single token after nav keywords (`to`, `open`, `show`)
-- Everything else — multi-word joined with `-` (e.g. `product=blue-jacket`)
+- Multi-word — joined with `-` (e.g. `product=blue-jacket`)
+- Required param fallback — only accepts identifier-shaped last word (rejects generic nouns)
 - Optional params stay `null` if no keyword match found
 
 ---
@@ -100,26 +103,23 @@ Capability execution — API calls, navigation, hybrid.
 Key exports:
 - `resolve(matchResult, params, options)` → `ResolveResult`
   - Enforces privacy before executing
-  - Injects `auth.userId` into session params automatically
+  - Injects `auth.userId` into session params (skipped if empty string or undefined)
   - Supports `dryRun: true` — returns call plan without executing
   - Retries with `AbortController` timeout on failure
-  - - Returns `status` and parsed `data` from API response
-  - `null` and `undefined` params are never written into URLs — skipped silently
-  - Nav param values are URL-encoded via `encodeURIComponent` — matches API resolver behavior
+  - Returns `status` and parsed `data` from API response
+  - `null` and `undefined` params never written into URLs
+  - Nav param values URL-encoded via `encodeURIComponent`
+  - Nav params validated against `[a-zA-Z0-9_-]` allowlist — rejects path separators
 
 `ResolveOptions`:
-- `baseUrl` — prepended to all API paths
-- `auth` — `{ isAuthenticated, role, userId }`
-- `dryRun` — skip actual fetch
-- `retries` — retry count on failure (default: 0)
-- `timeoutMs` — abort timeout (default: 5000)
-- `headers` — custom request headers
-- `fetch` — injectable fetch function (used in tests)
+- `baseUrl`, `auth`, `dryRun`, `retries`, `timeoutMs`, `headers`, `fetch`
 
 Privacy enforcement:
 - `public` — always allowed
 - `user_owned` — requires `auth.isAuthenticated === true`
-- `admin` — requires `auth.role === 'admin'`
+- `admin` — requires `auth.isAuthenticated === true` AND `auth.role === 'admin'`
+
+Debug logging: param values and `auth.userId` are redacted as `[REDACTED]` — never logged in plaintext.
 
 ---
 
@@ -129,22 +129,24 @@ Pluggable cache backends.
 Key exports:
 - `CacheStore` interface — `get(key)`, `set(key, result)`, `clear()`, `size()`
 - `MemoryCache` — in-memory Map, 512-entry cap with oldest-first eviction
-- `FileCache` — async `fs.promises` read/write, lazy-loaded on first access
-- `ComboCache` — memory-first with file fallback, promotes file hits to memory
+- `FileCache` — async `fs.promises` read/write, 2048-entry cap with oldest-first eviction
+- `ComboCache` — memory-first with file fallback
 - `normalizeQuery(query)` — lowercase + trim + collapse whitespace → cache key
-- `buildCacheKey(query, capabilityId, params)` — smarter key using capability + params (exported for future post-match cache layer — not currently used by engine)
+- `buildCacheKey(query, capabilityId, params)` — exported for future post-match cache layer (not currently used by engine)
+
+Security: Only `public` capabilities are cached. Non-public (`user_owned`, `admin`) are never cached — prevents auth bypass where one user's cached match is served to another.
 
 Notes:
 - `FileCache` and `ComboCache` are single-instance only — concurrent writers will corrupt
-- For multi-instance deployments, use a Redis adapter (planned v0.5)
+- For multi-instance deployments, use a Redis adapter (planned v0.6)
 
 ---
 
 ### `src/learning.ts`
-Usage analytics and keyword index.
+Usage analytics and keyword index — now incremental.
 
 Key exports:
-- `LearningStore` interface — `record(entry)`, `getStats()`, `getTopCapabilities(limit)`
+- `LearningStore` interface — `record(entry)`, `getStats()`, `getTopCapabilities(limit)`, `getIndex()`
 - `FileLearningStore` — persists to `.capman/learning.json`, caps at 10,000 entries
 - `MemoryLearningStore` — in-memory only, used in tests
 
@@ -154,9 +156,16 @@ Key exports:
 - `timestamp`
 
 `KeywordStats` (from `getStats()`):
-- `index` — `{ word → { capabilityId → hitCount } }` — foundation for adaptive matching
+- `index` — `{ word → { capabilityId → hitCount } }` — used by engine for learning boost
 - `totalQueries`, `llmQueries`, `cacheHits`, `outOfScope`
 
+Performance:
+- Index is maintained incrementally in `record()` — O(w) per entry where w = meaningful words
+- `getStats()` returns cached counters — O(1), no rebuild
+- `getIndex()` returns live index — O(1)
+- Full rebuild only on pruning (when entries exceed 10,000 cap)
+- Stopwords filtered from index — same `STOPWORDS` set as `matcher.ts`
+
 ---
 
 ### `src/engine.ts`
@@ -167,27 +176,31 @@ Key exports:
 - `EngineOptions` — all constructor options
 - `EngineResult` — `{ match, resolution, resolvedVia, durationMs, trace }`
 
+⚠️ **Concurrency:** `CapmanEngine` is not safe for sharing across concurrent async request handlers. The LLM rate limiter, circuit breaker, and learning index cache are instance-level mutable state. Create one engine per request in server deployments, or use `cheap` mode for shared instances.
+
 `CapmanEngine` methods:
-- `ask(query, overrides?)` → `EngineResult` — full pipeline: cache → match → resolve → learn
-- `explain(query)` → `ExplainResult` — match only, no execution, with candidate explanations
+- `ask(query, overrides?)` → `EngineResult` — full pipeline: cache → match → boost → resolve → learn
+- `explain(query)` → `ExplainResult` — match + boost only, no execution, no cache/learning write
 - `getStats()` → `KeywordStats | null`
 - `getTopCapabilities(limit?)` → `Array<{ id, hits }>`
 - `clearCache()`
 
 Matching pipeline in `ask()`:
-1. Cache check — return immediately on hit
+1. Cache check — return immediately on hit (public capabilities only)
 2. Match — `cheap` / `balanced` / `accurate` mode
 3. Privacy check — recorded in trace
-4. Cache set — stores under normalized query key
-5. Resolve — actual API call or nav
-6. Reasoning build — human-readable array
-7. Learning record
+4. Learning boost — up to +15 points for historically matched capabilities (skipped in `cheap` mode, skipped if all candidates score 0)
+5. Cache set — stores post-boost result under normalized query key (public only)
+6. Resolve — actual API call or nav
+7. Reasoning build — human-readable array
+8. Learning record — pre-boost result recorded to prevent feedback loop
 
 LLM rate limiting (all modes respect these):
 - `maxLLMCallsPerMinute` — sliding window (default: 60)
 - `llmCooldownMs` — minimum gap between calls (default: 0)
 - `llmCircuitBreakerThreshold` — failures before circuit opens (default: 3)
 - `llmCircuitBreakerResetMs` — circuit reset time (default: 60,000ms)
+- Parse failures (`LLM_PARSE_ERROR`) do NOT count toward circuit breaker — only network failures do
 
 ---
 
@@ -203,9 +216,7 @@ Key exports:
   - Extracts path/query/body params
   - Generates examples from operation summaries
 
-`ParseResult`:
-- `config` — ready-to-use `CapmanConfig`
-- `stats` — `{ total, skipped, warnings }`
+`ParseResult`: `{ config, stats: { total, skipped, warnings } }`
 
 Supported: OpenAPI 3.x, Swagger 2.x (JSON or YAML)
 
@@ -217,7 +228,8 @@ Minimal logger. Silent by default.
 Key exports:
 - `logger` — singleton with `debug()`, `info()`, `warn()`, `error()`
 - `setLogLevel(level)` — `'silent' | 'error' | 'warn' | 'info' | 'debug'`
-- `LogLevel` type
+
+Note: The manifest version compatibility warning uses `console.warn` directly (not `logger.warn`) so it is always visible regardless of log level.
 
 ---
 
@@ -225,134 +237,58 @@ Key exports:
 Public API surface. Re-exports everything the library exposes.
 
 Notable:
-- `ask(query, manifest, options?)` — convenience function, delegates to `CapmanEngine` internally
+- `ask(query, manifest, options?)` — convenience function, delegates to `CapmanEngine`
   - Marked `@deprecated` — use `CapmanEngine` directly for full features
-- `MatchMode` type — `'cheap' | 'balanced' | 'accurate'`
-- All types, classes, and functions from all modules above
+- `MatchMode` — `'cheap' | 'balanced' | 'accurate'`
+- `extractParams`, `resolverToIntent`, `STOPWORDS` — exported for advanced use cases
 
 ---
 
 ## bin/
 
 ### `bin/capman.js`
-Entry point only. Reads `command` from `process.argv` and routes to the correct module.
-~20 lines. No logic here.
+Entry point only (~20 lines). Routes `command` to the correct module.
 
 ### `bin/lib/shared.js`
-Shared utilities used by all command modules.
+Exports: `args`, `command`, `flags`, `getFlag`, `c`, `log`, `header`, `requireSrc`
 
-Exports:
-- `args`, `command`, `flags` — parsed from `process.argv`
-- `getFlag(name)` — returns value of `--name value` flag
-- `c` — ANSI color codes (`reset`, `bold`, `teal`, `yellow`, `red`, `green`, `gray`)
-- `log` — `{ info, success, warn, error, blank }`
-- `header()` — prints capman version header
-- `requireSrc()` — loads `dist/cjs/index.js`, auto-builds if missing
-
-### `bin/lib/cmd-init.js`
-Creates `capman.config.js` starter file in current directory.
+`getFlag(name)` — exits with error if flag is present but has no value (e.g. `--from` with no path).
 
 ### `bin/lib/cmd-generate.js`
-Three generation paths:
-- `--from <path|url>` → OpenAPI parser → `capman.config.js` + `manifest.json`
-- `--ai` → LLM-assisted generation from plain English description
-- _(no flags)_ → load `capman.config.js` manually → `manifest.json`
-
-Contains `buildAIPrompt(description)` and `callLLM(provider, apiKey, prompt)`.
-Supports `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`.
-
-### `bin/lib/cmd-validate.js`
-Reads `manifest.json`, runs Zod validation, prints errors and warnings.
-Exits with code 1 if invalid.
-
-### `bin/lib/cmd-inspect.js`
-Prints all capabilities in `manifest.json` — name, ID, resolver type, privacy, description, first example.
-
-### `bin/lib/cmd-demo.js`
-Live demo using a hardcoded e-commerce manifest.
-Shows the full **QUERY → MATCH → EXECUTION → RESULT → EXPLANATION** blueprint for 4 sample queries.
-No config or API key required.
-
-### `bin/lib/cmd-run.js`
-Runs a single query against the current `manifest.json`.
-`--debug` flag shows all candidate scores.
-
-### `bin/lib/cmd-explain.js`
-Runs `engine.explain(query)` and prints the full explanation:
-- What matched and why
-- All candidates with per-candidate explanations
-- What would execute (without executing)
-- Whether privacy would block it
+Three generation paths: `--from` (OpenAPI), `--ai` (LLM-assisted), manual.
+Output paths validated via `safeOutputPath()` — rejects traversal outside working directory.
+Contains `buildAIPrompt()` and `callLLM()`.
+
+### `bin/lib/cmd-init.js` — creates `capman.config.js`
+### `bin/lib/cmd-validate.js` — validates `manifest.json`
+### `bin/lib/cmd-inspect.js` — prints all capabilities
+### `bin/lib/cmd-demo.js` — live demo with hardcoded e-commerce manifest
+### `bin/lib/cmd-run.js` — runs a query, `--debug` shows all candidates
+### `bin/lib/cmd-explain.js` — runs `engine.explain()` and prints full breakdown
+### `bin/lib/cmd-help.js` — usage and command list
 
 ---
 
 ## tests/
 
-### `tests/matcher.test.ts`
-14 tests covering:
-- Keyword scoring accuracy
-- Out-of-scope detection
-- Param extraction (single token, multi-word, ID params, nav params)
-- `ask()` matching modes (cheap, balanced, accurate, default)
-
-### `tests/resolver.test.ts`
-18 tests covering:
-- API resolver — dry run, path substitution, query string params
-- Nav resolver — destination building
-- Hybrid resolver — both API and nav
-- No match — graceful failure
-- Privacy enforcement — public, user_owned, admin, session injection
-- Fetch error handling — network error, non-ok status, ok + data
-- Retry behaviour — succeeds after N failures, exhausts retries
-
-### `tests/engine.test.ts`
-26 tests covering:
-- Basic `ask()` — match and resolve
-- Caching — cache hit, cache cleared, ComboCache promotion
-- Learning — records queries, top capabilities, resolvedVia tracking
-- Matching modes — cheap never calls LLM, accurate calls LLM
-- Execution trace — candidates, reasoning, steps, cache hit trace
-- `explain()` — matched, out of scope, candidates with explanations, wouldExecute, blocked, no side effects
-- LLM rate limiting — rate limit, cooldown, circuit breaker, fallback on failure
-
-### `tests/parser.test.ts`
-9 tests covering:
-- Capability extraction from spec
-- Correct IDs from `operationId`
-- Privacy inference from tags and security
-- Path and query param extraction
-- Request body field extraction
-- Base URL extraction
-- Skipping operations with insufficient info
-- Error on missing file
-
----
+### `tests/matcher.test.ts` — 16 tests
+Keyword scoring, OOS detection, param extraction, LLM edge cases (hallucinated ID, undefined reasoning)
 
-## scripts/
+### `tests/resolver.test.ts` — 22 tests
+API/nav/hybrid resolvers, privacy enforcement, session injection, null params, nav open redirect
 
-### `scripts/version.js`
-Prebuild script. Reads `version` from `package.json` and writes:
-```typescript
-// Auto-generated by scripts/version.js — do not edit manually
-export const VERSION = '0.4.2'
-```
-to `src/version.ts`. Runs automatically before every `pnpm run build`.
+### `tests/engine.test.ts` — 33 tests
+`ask()`, `explain()`, caching, learning, matching modes, trace, rate limiting, manifest version check, learning boost
 
-`src/version.ts` is gitignored.
+### `tests/parser.test.ts` — 9 tests
+OpenAPI capability extraction, privacy inference, param extraction, base URL, error handling
 
 ---
 
-## test/ (integration, not in CI)
-
-### `test/conduit.config.js`
-capman config for the RealWorld Conduit app (`conduit.productionready.io`).
-8 capabilities covering all resolver types.
-
-### `test/test-conduit.ts`
-Tests keyword matcher against live Conduit API.
+## scripts/
 
-### `test/test-llm-live.ts`
-Tests `matchWithLLM` and `CapmanEngine` accurate mode against live API using OpenRouter free models.
+### `scripts/version.js`
+Prebuild script. Reads `version` from `package.json` and writes `src/version.ts`. Runs automatically before every build.
 
 ---
 
@@ -360,13 +296,13 @@ Tests `matchWithLLM` and `CapmanEngine` accurate mode against live API using Ope
 
 | File | Purpose |
 |---|---|
-| `tsconfig.json` | CJS build → `dist/cjs/` |
-| `tsconfig.esm.json` | ESM build → `dist/esm/` |
+| `tsconfig.json` | CJS build → `dist/cjs/` with `.d.ts` |
+| `tsconfig.esm.json` | ESM build → `dist/esm/` with `.d.ts` |
 | `package.json` | Version, exports map, scripts, dependencies |
-| `.github/workflows/ci.yml` | Build + test + verify dist on every push |
-| `.gitignore` | Ignores `dist/`, `node_modules/`, `src/version.ts`, `.capman/` |
+| `.github/workflows/ci.yml` | Build + test + verify both dist outputs on every push |
 | `CHANGELOG.md` | All notable changes per version |
 | `CODEBASE.md` | This file |
+| `ROADMAP_v0.5.0.md` | Prioritized fix and feature roadmap |
 
 ---
 
@@ -381,13 +317,15 @@ Developer writes capman.config.js
          ↓
   CapmanEngine.ask("user query")
          ↓
-  cache.ts     → cache hit? return immediately
+  cache.ts       → cache hit? return immediately (public only)
+         ↓
+  matcher.ts     → score all capabilities → pick winner
          ↓
-  matcher.ts   → score all capabilities → pick winner
+  learning.ts    → apply boost (+0 to +15) based on keyword history
          ↓
-  resolver.ts  → enforce privacy → call API or navigate
+  resolver.ts    → enforce privacy → call API or navigate
          ↓
-  learning.ts  → record query + result
+  learning.ts    → record pre-boost match result
          ↓
-  EngineResult → { match, resolution, trace, resolvedVia }
+  EngineResult   → { match, resolution, trace, resolvedVia }
 ```

package/README.md

@@ -66,6 +66,29 @@ console.log(result.resolvedVia)             // 'keyword' | 'llm' | 'cache'
 console.log(result.trace.reasoning)         // ['Matched "check_product_availability" with 100% confidence', ...]
 ```
 
+
+### ⚠️ Concurrency Warning
+
+`CapmanEngine` is **not safe** for sharing across concurrent async request handlers. The LLM rate limiter, circuit breaker, and learning index cache are instance-level mutable state.
+
+In a Node.js server, create one engine per request:
+
+```typescript
+// ✅ Safe
+app.post('/ask', async (req, res) => {
+  const engine = new CapmanEngine({ manifest, llm })
+  const result = await engine.ask(req.body.query)
+  res.json(result)
+})
+
+// ❌ Unsafe under concurrent load
+const engine = new CapmanEngine({ manifest, llm })
+app.post('/ask', async (req, res) => {
+  const result = await engine.ask(req.body.query)  // race condition
+  res.json(result)
+})
+```
+
 **3. See it live**
 
 ```bash

package/bin/lib/cmd-generate.js

@@ -1,7 +1,22 @@
 'use strict'
 
+const path = require('path')
 const fs   = require('fs')
 const { header, log, c, flags, getFlag, requireSrc } = require('./shared')
+// ─── Path safety guard ────────────────────────────────────────────────────────
+
+function safeOutputPath(rawPath, cwd) {
+  const resolved = path.resolve(cwd, rawPath)
+  if (!resolved.startsWith(cwd + path.sep) && resolved !== cwd) {
+    log.error(`Output path "${rawPath}" resolves outside the working directory.`)
+    console.log(`  Resolved: ${resolved}`)
+    console.log(`  Allowed:  ${cwd}`)
+    process.exit(1)
+  }
+  return resolved
+}
+
+
 
 // ─── AI prompt builder ────────────────────────────────────────────────────────
 
@@ -120,11 +135,13 @@ module.exports = async function cmdGenerate() {
   header()
   const { generate, loadConfig, writeManifest, validate, parseOpenAPI } = requireSrc()
 
-  const fromFlag  = getFlag('--from')
+const fromFlag  = getFlag('--from')
   const aiFlag    = flags.includes('--ai')
-  const outPath   = getFlag('--out') ?? 'manifest.json'
-  const configOut = getFlag('--config-out') ?? 'capman.config.js'
+  const cwd       = process.cwd()
+  const outPath   = safeOutputPath(getFlag('--out') ?? 'manifest.json', cwd)
+  const configOut = safeOutputPath(getFlag('--config-out') ?? 'capman.config.js', cwd)
 
+  
   // ── Path 1: OpenAPI parser ───────────────────────────────────────────────
   if (fromFlag) {
     log.info(`Parsing OpenAPI spec: ${fromFlag}`)

package/dist/cjs/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/cjs/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAID,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AAEH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAC7C,MAAM,CAQR;AAMD,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,KAAK,CAAgC;IAEvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAU5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAepD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAC9B;AAID,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,MAAM,CAAQ;gBAEV,QAAQ,SAAuB;YAK7B,IAAI;YAiBJ,IAAI;IAaZ,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAW5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI9B;AAID,qBAAa,UAAW,YAAW,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,IAAI,CAAW;gBAEX,QAAQ,SAAuB;IAKrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAID,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC5D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AAEH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAC7C,MAAM,CAQR;AAOD,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,KAAK,CAAgC;IAEvC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAiB5D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAepD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAC9B;AAMD,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,SAAS,CAA6C;gBAElD,QAAQ,SAAuB;YAK7B,IAAI;IAiBlB,OAAO,CAAC,IAAI;YAKE,OAAO;IAaf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAmB5D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI9B;AAID,qBAAa,UAAW,YAAW,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,IAAI,CAAW;gBAEX,QAAQ,SAAuB;IAKrC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY5D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B"}