capman 0.5.5 → 0.6.1

package/dist/esm/engine.js

@@ -1,4 +1,4 @@
-import { match as _match, matchWithLLM as _matchWithLLM, resolverToIntent, extractParams, STOPWORDS, LLMParseError } from './matcher';
+import { match as _match, matchWithLLM as _matchWithLLM, resolverToIntent, extractParams, LLMParseError, tokenize, buildBM25Index, sanitizeForPrompt, calibrateCeiling as _calibrateCeiling } from './matcher';
 import { resolve as _resolve, checkPrivacy } from './resolver';
 import { MemoryLearningStore } from './learning';
 import { logger } from './logger';
@@ -17,6 +17,7 @@ export class CapmanEngine {
         this.mode = options.mode ?? 'balanced';
         this.llm = options.llm;
         this.baseUrl = options.baseUrl;
+        this.environment = options.environment;
         this.auth = options.auth;
         this.headers = options.headers;
         this.threshold = options.threshold ?? 50;
@@ -27,6 +28,12 @@ export class CapmanEngine {
         this.llmCircuitBreakerResetMs = options.llmCircuitBreakerResetMs ?? 60_000;
         this.fuzzyMatch = options.fuzzyMatch ?? false;
         this.fuzzyThreshold = options.fuzzyThreshold ?? 0.4;
+        this.bm25K1 = options.bm25K1 ?? 1.5;
+        this.bm25B = options.bm25B ?? 0.75;
+        this.bm25Index = buildBM25Index(options.manifest.capabilities);
+        this.bm25Ceiling = this.calibrateBM25Ceiling();
+        this.marginAwareLLM = options.marginAwareLLM ?? false;
+        this.adaptiveMargin = options.adaptiveMarginOverride ?? this.calibrateAdaptiveMargin();
         // Cache — default MemoryCache (no filesystem writes), or disabled with false
         // Use FileCache or ComboCache explicitly for persistence across restarts
         this.cache = options.cache === false
@@ -90,12 +97,16 @@ export class CapmanEngine {
                     resolvedVia: 'cache',
                     totalMs: Date.now() - start,
                 };
+                const { verdict: cacheVerdict, margin: cacheMargin } = this.computeVerdict(matchWithFreshParams);
                 const result = {
                     match: matchWithFreshParams,
                     resolution,
                     resolvedVia: 'cache',
                     durationMs: Date.now() - start,
                     trace,
+                    verdict: cacheVerdict,
+                    margin: cacheMargin,
+                    missingParams: undefined
                 };
                 await this.recordLearning(query, matchWithFreshParams, 'cache');
                 return result;
@@ -114,6 +125,7 @@ export class CapmanEngine {
         // ── Step 2.5: Apply learning boost ───────────────────────────────────────
         matchResult = await this.applyBoostToMatchResult(query, matchResult, resolvedVia);
         // ── Step 3: Privacy check ────────────────────────────────────────────────
+        let privacyFailed = false;
         if (matchResult.capability) {
             const privacyError = checkPrivacy(matchResult.capability, this.auth);
             steps.push({
@@ -122,8 +134,30 @@ export class CapmanEngine {
                 durationMs: 0,
                 detail: privacyError ?? `level: ${matchResult.capability.privacy.level}`,
             });
+            // Warn on deprecated or sunset capabilities — never silently fail
+            this.checkCapabilityLifecycle(matchResult.capability);
+            // Log when engine mode differs from capability's preferred mode
+            this.checkMatchHint(matchResult.capability);
+            // Short-circuit: if privacy fails, skip disambiguation to avoid burning an LLM
+            // call on a request that _resolve() will block anyway. privacyFailed propagates
+            // to Step 4a so the mode guard check is clean and explicit.
+            if (privacyError)
+                privacyFailed = true;
         }
-        // ── Step 4: Resolve ──────────────────────────────────────────────────────
+        // ── Step 4a: Compute verdict + optional margin-aware LLM disambiguation ──
+        let { verdict, margin } = this.computeVerdict(matchResult);
+        if (verdict === 'marginal' &&
+            this.marginAwareLLM &&
+            this.llm &&
+            !privacyFailed &&
+            (this.mode === 'balanced' || this.mode === 'accurate')) {
+            matchResult = await this.disambiguateLLM(query, matchResult, steps);
+            // Recompute verdict after disambiguation
+            const recomputed = this.computeVerdict(matchResult);
+            verdict = recomputed.verdict;
+            margin = recomputed.margin;
+        }
+        // ── Step 4b: Resolve ──────────────────────────────────────────────────────
         const resolveStart = Date.now();
         const resolution = await _resolve(matchResult, matchResult.extractedParams, this.resolveOptions(overrides));
         steps.push({
@@ -145,6 +179,68 @@ export class CapmanEngine {
             await this.cache.set(capKey, matchResult);
             // capKey always starts with 'cap:' — structurally distinct from queryKey
         }
+        // ── Step 5b: Compute missingParams ───────────────────────────────────────
+        // Spec: LLM attempts extraction first when available. missingParams is last resort.
+        let missingParams;
+        if (matchResult.capability && resolvedVia !== 'llm') {
+            const cap = matchResult.capability;
+            const unresolved = cap.params.filter(p => p.source === 'user_query' && p.required
+                && matchResult.extractedParams[p.name] === null);
+            if (unresolved.length > 0 && this.llm && this.mode !== 'cheap') {
+                // LLM available — attempt targeted param extraction before declaring incomplete
+                const skipReason = this.checkLLMAllowed();
+                if (!skipReason) {
+                    try {
+                        const paramExtractionStart = Date.now();
+                        const paramDescriptions = unresolved
+                            .map(p => `- ${p.name}: ${p.description}`)
+                            .join('\n');
+                        const paramPrompt = `Extract the following parameters from this user query.\n` +
+                            `Query: ${JSON.stringify({ user_query: query })}\n\n` +
+                            `Parameters to extract:\n${paramDescriptions}\n\n` +
+                            `Respond ONLY with valid JSON: { "params": { "<name>": "<value or null>" } }`;
+                        const raw = await this.llm(paramPrompt);
+                        const clean = raw.replace(/```json|```/g, '').trim();
+                        const parsed = JSON.parse(clean);
+                        this.recordLLMSuccess();
+                        steps.push({
+                            type: 'llm_match',
+                            status: 'pass',
+                            durationMs: Date.now() - paramExtractionStart,
+                            detail: `param extraction: ${unresolved.map(p => p.name).join(', ')}`,
+                        });
+                        // Merge LLM-extracted values — validate type before accepting
+                        for (const p of unresolved) {
+                            const val = parsed?.params?.[p.name];
+                            if (val && typeof val === 'string' && val.trim().length > 0) {
+                                matchResult.extractedParams[p.name] = val.trim();
+                            }
+                        }
+                    }
+                    catch (err) {
+                        const isParseError = err instanceof SyntaxError;
+                        if (isParseError) {
+                            // JSON parse failure: refund the rate-limit slot but don't open circuit breaker
+                            // The llm is reachable - the response format was just bad
+                            this.llmCallsThisMinute = Math.max(0, this.llmCallsThisMinute - 1);
+                        }
+                        else {
+                            // Hard failure (timeout, network): refund slot and increment fail counter
+                            this.recordLLMFailure();
+                        }
+                        logger.warn(`LLM param extraction failed: ${err instanceof Error ? err.message : String(err)}`);
+                        // fall through to missingParams below
+                    }
+                }
+            }
+            // After LLM attempt (or if skipped/unavailable), report what's still missing
+            const stillMissing = cap.params
+                .filter(p => p.source === 'user_query' && p.required
+                && matchResult.extractedParams[p.name] === null)
+                .map(p => p.name);
+            if (stillMissing.length > 0)
+                missingParams = stillMissing;
+        }
         // ── Step 6: Build reasoning array ────────────────────────────────────────
         const reasoning = [];
         if (matchResult.candidates.length) {
@@ -189,6 +285,9 @@ export class CapmanEngine {
             resolvedVia,
             durationMs: Date.now() - start,
             trace,
+            verdict,
+            margin,
+            missingParams,
         };
     }
     /**
@@ -216,6 +315,20 @@ export class CapmanEngine {
             await this.cache.clear();
     }
     checkManifestVersion(manifest) {
+        // ── Schema version check ─────────────────────────────────────────────────
+        // schemaVersion tracks manifest format — "1" for v0.6+.
+        // Manifests without schemaVersion are pre-v0.6 — warn but allow.
+        const CURRENT_SCHEMA_VERSION = '1';
+        if (!manifest.schemaVersion) {
+            console.warn(`[capman] Manifest is missing schemaVersion — it was generated with capman < 0.6. ` +
+                `Regenerate with: npx capman generate`);
+        }
+        else if (manifest.schemaVersion !== CURRENT_SCHEMA_VERSION) {
+            console.warn(`[capman] Manifest schemaVersion "${manifest.schemaVersion}" differs from ` +
+                `engine's expected "${CURRENT_SCHEMA_VERSION}". ` +
+                `Regenerate with: npx capman generate`);
+        }
+        // ── Package version check ────────────────────────────────────────────────
         if (!manifest.version)
             return;
         const SEMVER_RE = /^\d+\.\d+\.\d+$/;
@@ -223,8 +336,8 @@ export class CapmanEngine {
             const [mMaj, mMin] = manifest.version.split('.').map(Number);
             const [eMaj, eMin] = VERSION.split('.').map(Number);
             if (mMaj !== eMaj || mMin !== eMin) {
-                console.warn(`[capman] Manifest version "${manifest.version}" was generated with a ` +
-                    `different engine version than "${VERSION}". This is usually fine across patch versions. ` +
+                console.warn(`[capman] Manifest was generated with capman "${manifest.version}" ` +
+                    `but engine is "${VERSION}". This is usually fine across patch versions. ` +
                     `If you experience unexpected matching issues, regenerate with: npx capman generate`);
             }
         }
@@ -233,6 +346,42 @@ export class CapmanEngine {
                 `to engine version "${VERSION}" — version strings are not valid semver.`);
         }
     }
+    checkCapabilityLifecycle(capability) {
+        const lc = capability.lifecycle;
+        if (!lc || lc.status === 'stable' || lc.status === 'beta' || lc.status === 'experimental') {
+            if (lc?.status === 'beta') {
+                logger.warn(`Capability "${capability.id}" is in beta — behavior may change`);
+            }
+            if (lc?.status === 'experimental') {
+                logger.warn(`Capability "${capability.id}" is experimental — use with caution`);
+            }
+            return;
+        }
+        if (lc.status === 'deprecated') {
+            const sunsetPassed = lc.sunsetAt && new Date(lc.sunsetAt) < new Date();
+            if (sunsetPassed) {
+                // Sunset date has passed — strongest warning
+                console.warn(`[capman] ⚠️  Capability "${capability.id}" passed its sunset date (${lc.sunsetAt}). ` +
+                    `It may be removed in a future version.` +
+                    (lc.successor ? ` Use "${lc.successor}" instead.` : '') +
+                    (lc.note ? ` Note: ${lc.note}` : ''));
+            }
+            else {
+                logger.warn(`Capability "${capability.id}" is deprecated.` +
+                    (lc.sunsetAt ? ` Sunset: ${lc.sunsetAt}.` : '') +
+                    (lc.successor ? ` Use "${lc.successor}" instead.` : '') +
+                    (lc.note ? ` Note: ${lc.note}` : ''));
+            }
+        }
+    }
+    checkMatchHint(capability) {
+        const hint = capability.matchHint?.preferredMode;
+        if (!hint || hint === this.mode)
+            return;
+        // Advisory only — log but never enforce
+        logger.warn(`Capability "${capability.id}" prefers mode "${hint}" but engine is in "${this.mode}" mode. ` +
+            `Set mode: '${hint}' in EngineOptions to honor this hint.`);
+    }
     /**
      * Replaces the active manifest without creating a new engine instance.
      * Useful for hot-reloading manifests in long-running servers without
@@ -248,11 +397,12 @@ export class CapmanEngine {
     async loadManifest(manifest) {
         this.checkManifestVersion(manifest);
         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 —
+        // server selection updates automatically after loadManifest()
         await this.clearCache();
-        // Note: LLM rate limiter state (llmCallsThisMinute, llmConsecutiveFails,
-        // llmCircuitOpenAt) is intentionally preserved across manifest reloads.
-        // The LLM provider has not changed, so circuit breaker state remains valid.
-        // If you need a clean rate limiter state, create a new CapmanEngine instance.
     }
     /**
      * Explain what would happen for a query — without executing it.
@@ -291,7 +441,8 @@ export class CapmanEngine {
         // ── Apply learning boost (same as ask()) ─────────────────────────────────
         matchResult = await this.applyBoostToMatchResult(query, matchResult, resolvedVia);
         // ── Build candidate explanations ─────────────────────────────────────────
-        const qWordSet = new Set(query.toLowerCase().split(/\W+/).filter(Boolean));
+        const qTokens = tokenize(query);
+        const qWordSet = new Set(qTokens);
         const candidates = matchResult.candidates
             .sort((a, b) => b.score - a.score)
             .map(c => {
@@ -305,8 +456,8 @@ export class CapmanEngine {
             }
             else if (c.score >= 50) {
                 const matchedWords = (cap?.examples ?? [])
-                    .flatMap(e => e.toLowerCase().split(/\s+/))
-                    .filter(w => qWordSet.has(w) && w.length > 2);
+                    .flatMap(e => tokenize(e))
+                    .filter(w => qWordSet.has(w));
                 const unique = [...new Set(matchedWords)].slice(0, 3);
                 explanation = unique.length
                     ? `Matched keywords: ${unique.join(', ')} (${c.score}%)`
@@ -496,6 +647,10 @@ export class CapmanEngine {
         const fuzzyOpts = {
             fuzzyMatch: this.fuzzyMatch,
             fuzzyThreshold: this.fuzzyThreshold,
+            bm25Index: this.bm25Index,
+            bm25Ceiling: this.bm25Ceiling,
+            bm25K1: this.bm25K1,
+            bm25B: this.bm25B,
         };
         switch (this.mode) {
             case 'cheap': {
@@ -604,7 +759,11 @@ export class CapmanEngine {
                 break;
             }
         }
-        return { matchResult: matchResult, resolvedVia };
+        if (matchResult === undefined) {
+            const exhaustive = this.mode;
+            throw new Error(`_runMatch: unhandled MatchMode "${exhaustive}"`);
+        }
+        return { matchResult, resolvedVia };
     }
     /**
      * Applies learning boost to a MatchResult and returns the updated result.
@@ -663,7 +822,7 @@ export class CapmanEngine {
         const stats = await this.learning.getStats();
         if (!stats || Object.keys(stats.index).length === 0)
             return candidates;
-        const qWords = query.toLowerCase().split(/\W+/).filter(w => w.length > 2 && !STOPWORDS.has(w));
+        const qWords = tokenize(query);
         if (qWords.length === 0)
             return candidates;
         return candidates.map(candidate => {
@@ -689,10 +848,26 @@ export class CapmanEngine {
             };
         });
     }
+    /**
+     * Resolves the effective baseUrl from manifest.servers[] or EngineOptions.baseUrl.
+     * Priority: environment-matched server > first server > explicit baseUrl > undefined
+     */
+    resolveBaseUrl() {
+        const servers = this.manifest.servers;
+        if (!servers?.length)
+            return this.baseUrl;
+        if (this.environment) {
+            const match = servers.find(s => s.environment === this.environment);
+            if (match)
+                return match.url.replace(/\/$/, '');
+        }
+        // Fallback to first server
+        return servers[0].url.replace(/\/$/, '');
+    }
     // ── Private helpers ────────────────────────────────────────────────────────
     resolveOptions(overrides = {}) {
         return {
-            baseUrl: this.baseUrl,
+            baseUrl: this.resolveBaseUrl(),
             auth: this.auth,
             headers: this.headers,
             ...overrides,
@@ -711,6 +886,131 @@ export class CapmanEngine {
             timestamp: new Date().toISOString(),
         });
     }
+    calibrateBM25Ceiling() {
+        return _calibrateCeiling(this.manifest.capabilities, this.bm25Index, this.bm25K1, this.bm25B);
+    }
+    /**
+     * Calibrates the adaptive margin threshold from the manifest's own score
+     * distribution. Runs each capability's first example against all other
+     * capabilities to find the typical inter-capability score spread.
+     * Dense overlapping vocabulary → lower margin (harder to separate).
+     * Sparse vocabulary → higher margin (easier to separate).
+     *
+     * Complexity: O(capabilities²) — runs at constructor time and on loadManifest().
+     * For manifests with ≤100 capabilities this is negligible (<10ms).
+     * For very large manifests (500+ capabilities), consider passing
+     * `adaptiveMarginOverride` to skip calibration.
+     */
+    calibrateAdaptiveMargin() {
+        if (this.manifest.capabilities.length < 2)
+            return 20;
+        const margins = [];
+        const fuzzyOpts = {
+            fuzzyMatch: false, // calibration uses keyword only — deterministic
+            bm25Index: this.bm25Index,
+            bm25Ceiling: this.bm25Ceiling,
+            bm25K1: this.bm25K1,
+            bm25B: this.bm25B,
+        };
+        for (const cap of this.manifest.capabilities) {
+            if (!cap.examples?.length)
+                continue;
+            // Use all examples and take the maximum margin — same rationale as
+            // calibrateBM25Ceiling(): a weak first example skews the calibration.
+            for (const example of cap.examples) {
+                const result = _match(example, this.manifest, fuzzyOpts);
+                const sorted = [...result.candidates].sort((a, b) => b.score - a.score);
+                if (sorted.length >= 2) {
+                    margins.push(sorted[0].score - sorted[1].score);
+                }
+            }
+        }
+        if (margins.length === 0)
+            return 20;
+        // Use 25th percentile of margins as the threshold — manifests where
+        // capabilities are naturally close together get a tighter threshold
+        margins.sort((a, b) => a - b);
+        const p25 = margins[Math.floor(margins.length * 0.25)];
+        return Math.max(10, Math.min(30, Math.round(p25 * 0.6)));
+    }
+    computeVerdict(matchResult) {
+        if (!matchResult.capability)
+            return { verdict: 'uncertain', margin: 0 };
+        const sorted = [...matchResult.candidates].sort((a, b) => b.score - a.score);
+        const best = sorted[0]?.score ?? 0;
+        const second = sorted[1]?.score ?? 0;
+        const margin = best - second;
+        if (best < 60)
+            return { verdict: 'uncertain', margin };
+        if (margin < this.adaptiveMargin)
+            return { verdict: 'marginal', margin };
+        return { verdict: 'clear', margin };
+    }
+    /**
+       * Targeted disambiguation between top-2 candidates.
+       * Sends ~200 tokens instead of full manifest (~4000 tokens) — 93% cost reduction.
+       * Returns updated matchResult with LLM-preferred winner, or original on failure.
+       */
+    async disambiguateLLM(query, matchResult, steps) {
+        if (!this.llm)
+            return matchResult;
+        const sorted = [...matchResult.candidates]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 2);
+        if (sorted.length < 2)
+            return matchResult;
+        const capA = this.manifest.capabilities.find(c => c.id === sorted[0].capabilityId);
+        const capB = this.manifest.capabilities.find(c => c.id === sorted[1].capabilityId);
+        if (!capA || !capB)
+            return matchResult;
+        const skipReason = this.checkLLMAllowed();
+        if (skipReason) {
+            logger.warn(`Disambiguation LLM skipped — ${skipReason}`);
+            steps.push({ type: 'llm_match', status: 'skip', durationMs: 0, detail: `disambiguation skipped: ${skipReason}` });
+            return matchResult;
+        }
+        const prompt = `Two capabilities are close matches for this query. Pick the best one.
+
+  Query: ${JSON.stringify({ user_query: query })}
+
+  Option A: ${capA.id} — ${sanitizeForPrompt(capA.description, 150)}
+  Option B: ${capB.id} — ${sanitizeForPrompt(capB.description, 150)}
+
+  Respond ONLY with valid JSON:
+  { "winner": "<capability_id>", "confidence": <0-100>, "reasoning": "<one sentence>" }`;
+        const t = Date.now();
+        try {
+            const raw = await this.llm(prompt);
+            const clean = raw.replace(/```json|```/g, '').trim();
+            const parsed = JSON.parse(clean);
+            this.recordLLMSuccess();
+            const winner = this.manifest.capabilities.find(c => c.id === parsed.winner);
+            if (!winner) {
+                steps.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t, detail: 'disambiguation returned unknown id' });
+                return matchResult;
+            }
+            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `disambiguation: ${winner.id} (${parsed.confidence}%)` });
+            const confidence = typeof parsed.confidence === 'number' && !isNaN(parsed.confidence)
+                ? Math.min(100, Math.max(0, Math.round(parsed.confidence)))
+                : matchResult.confidence; // fallback to original if LLM returned bad value
+            return {
+                ...matchResult,
+                capability: winner,
+                confidence,
+                intent: resolverToIntent(winner),
+                extractedParams: extractParams(query, winner),
+                candidates: matchResult.candidates.map(c => ({ ...c, matched: c.capabilityId === winner.id })),
+                reasoning: parsed.reasoning ?? `Disambiguated to "${winner.id}"`,
+            };
+        }
+        catch (err) {
+            const isParseError = err instanceof LLMParseError;
+            if (!isParseError)
+                this.recordLLMFailure();
+            steps.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t, detail: String(err) });
+            return matchResult;
+        }
+    }
 }
 /** Maximum allowed query length in characters. Queries exceeding this throw RangeError. */
 CapmanEngine.MAX_QUERY_LENGTH = 1000;

package/dist/esm/generator.js

@@ -5,10 +5,14 @@ import { validateConfig, validateManifest } from './schema';
 import { logger } from './logger';
 export function generate(config) {
     return {
+        schemaVersion: '1',
         version: VERSION,
         app: config.app,
         generatedAt: new Date().toISOString(),
-        capabilities: config.capabilities.map(cap => ({ ...cap, params: [...cap.params] })),
+        capabilities: config.capabilities.map(cap => ({ ...cap })),
+        ...(config.info ? { info: config.info } : {}),
+        ...(config.tagRegistry ? { tagRegistry: config.tagRegistry } : {}),
+        ...(config.servers ? { servers: config.servers } : {}),
     };
 }
 export function loadConfig(configPath) {
@@ -33,6 +37,10 @@ export function loadConfig(configPath) {
             // Use a CJS config file or convert with: module.exports = { ... }
             // Full ESM config support is planned for v0.5.
             try {
+                // Bust the module cache before loading — require() caches by resolved path,
+                // so a second call without this returns the stale version from the first call.
+                // This matters in watch mode and test suites that change config between calls.
+                delete require.cache[require.resolve(resolved)];
                 const mod = require(resolved);
                 raw = mod.default ?? mod;
             }
@@ -80,7 +88,12 @@ export function writeManifest(manifest, outputPath = 'manifest.json') {
         throw new Error(`writeManifest: output path "${outputPath}" resolves outside the working directory.\n` +
             `Resolved: ${resolved}\nAllowed:  ${cwd}`);
     }
-    fs.writeFileSync(resolved, JSON.stringify(manifest, null, 2));
+    // Write atomically via tmp → rename — same pattern used by FileCache and
+    // FileLearningStore. A crash or SIGKILL mid-write leaves the .tmp file, not
+    // a truncated manifest.json, so the next readManifest() can still parse it.
+    const tmp = `${resolved}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+    fs.renameSync(tmp, resolved);
     return resolved;
 }
 export function readManifest(manifestPath = 'manifest.json') {
@@ -122,14 +135,23 @@ export function validate(manifest) {
     return { valid: errors.length === 0, errors, warnings };
 }
 export function generateStarterConfig() {
-    return `// capman.config.js 
-// Define what your app can do for AI agents.
-// Replace the examples below with your own app's capabilities.
+    return `// capman.config.js
+// Auto-generated starter config — edit before use
 
 module.exports = {
-  app: 'your-app-name',
+  app: 'my-app',
   baseUrl: 'https://api.your-app.com',
 
+  // Optional metadata block — used for documentation and provenance
+  info: {
+    title:       'My App',
+    description: 'Brief description of what this app does',
+    version:     '1.0.0',
+    homepage:    'https://your-app.com',
+    contact:     { name: 'Your Name', email: 'you@your-app.com' },
+    license:     { name: 'MIT' },
+  },
+
   capabilities: [
     {
       id: 'get_resource',

package/dist/esm/index.d.ts

@@ -1,10 +1,12 @@
 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, } 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, } from './types';
 export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
 export { match, matchWithLLM, extractParams, } from './matcher';
 export { LLMParseError } from './matcher';
 export type { LLMMatcherOptions } from './matcher';
+export { TYPE_PATTERNS } from './matcher';
+export { filterByTags } from './matcher';
 export { resolve } from './resolver';
 export type { ResolveOptions, AuthContext } from './resolver';
 export { CapmanEngine } from './engine';

package/dist/esm/index.js

@@ -2,6 +2,8 @@ export { setLogLevel } from './logger';
 export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
 export { match, matchWithLLM, extractParams, } from './matcher';
 export { LLMParseError } from './matcher';
+export { TYPE_PATTERNS } from './matcher';
+export { filterByTags } from './matcher';
 export { resolve } from './resolver';
 // ─── Engine (recommended API) ─────────────────────────────────────────────────
 export { CapmanEngine } from './engine';

package/dist/esm/learning.d.ts

@@ -6,6 +6,13 @@ export interface LearningEntry {
     extractedParams: Record<string, string | null>;
     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.
+     */
+    weight?: number;
 }
 export interface KeywordStats {
     /** keyword → Map of capabilityId → hit count */