labre-mcp 0.1.0

package/dist/lib/degradation/index.d.mts

@@ -0,0 +1,9 @@
+export type { Degradable, DegradationEvent, DegradationSeverity, HealthCheck, HealthCheckOutcome, } from './types.mjs';
+export { registerHealthCheck, hasHealthCheck, listHealthChecks, clearRegistry, runHealthCheck, runAllHealthChecks, } from './registry.mjs';
+export { DegradationCollector } from './collector.mjs';
+export { tryDegrade, tryDegradeAmbient } from './with-degradation.mjs';
+export type { TryDegradeOptions } from './with-degradation.mjs';
+export { withMcpDegradation } from './mcp-wrapper.mjs';
+export type { McpHandler, WithMcpDegradationOptions } from './mcp-wrapper.mjs';
+export { getCurrentCollector, runWithCollector, withCollector } from './context.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/lib/degradation/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/lib/degradation/index.mts"],"names":[],"mappings":"AAYA,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/lib/degradation/index.mjs

@@ -0,0 +1,17 @@
+// fallow-ignore-file unused-export
+// fallow-ignore-file unused-types
+// This barrel is the documented public API of the degradation framework
+// (mémoire feedback_mcp_degradable.md). Symbols are exposed even when
+// internal callers reach the sub-modules directly — keep the surface
+// stable so external consumers depend on a single entry point.
+//
+// Public surface of the degradation framework.
+//
+// Importers should reach for this barrel rather than the individual files,
+// e.g. `import { withMcpDegradation, tryDegrade } from '../../lib/degradation/index.mjs';`.
+export { registerHealthCheck, hasHealthCheck, listHealthChecks, clearRegistry, runHealthCheck, runAllHealthChecks, } from './registry.mjs';
+export { DegradationCollector } from './collector.mjs';
+export { tryDegrade, tryDegradeAmbient } from './with-degradation.mjs';
+export { withMcpDegradation } from './mcp-wrapper.mjs';
+export { getCurrentCollector, runWithCollector, withCollector } from './context.mjs';
+//# sourceMappingURL=index.mjs.map

package/dist/lib/degradation/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../../src/lib/degradation/index.mts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,kCAAkC;AAClC,wEAAwE;AACxE,sEAAsE;AACtE,qEAAqE;AACrE,+DAA+D;AAC/D,EAAE;AACF,+CAA+C;AAC/C,EAAE;AACF,2EAA2E;AAC3E,4FAA4F;AAU5F,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/lib/degradation/mcp-wrapper.d.mts

@@ -0,0 +1,27 @@
+import type { Degradable } from './types.mjs';
+import { DegradationCollector } from './collector.mjs';
+export interface WithMcpDegradationOptions {
+    /**
+     * Subset of registered health-check sources to run as a pre-flight before
+     * the handler executes. Failures are seeded into the collector so the
+     * handler sees them when deciding fallback paths.
+     *
+     * Pass `'all'` to run every registered health check. Default: no preflight.
+     */
+    preflight?: string[] | 'all';
+}
+export type McpHandler<TResult> = (collector: DegradationCollector) => Promise<TResult> | TResult;
+/**
+ * Wrap an MCP tool handler with the standard degradation envelope.
+ *
+ * Every MCP handler in `src/mcp/`, `src/work-on-evolution/`, or
+ * `src/work-on-value-chain/` should be invoked through this helper so the
+ * client always receives a `Degradable<T>` shape and silent fallbacks
+ * become visible via `degradationEvents`.
+ *
+ * The handler may throw — the throw propagates to the MCP server, which
+ * wraps it as a JSON-RPC error. `Degradable` is for partial degradations
+ * where the tool still returns a usable result.
+ */
+export declare function withMcpDegradation<TResult>(toolName: string, handler: McpHandler<TResult>, options?: WithMcpDegradationOptions): Promise<Degradable<TResult>>;
+//# sourceMappingURL=mcp-wrapper.d.mts.map

package/dist/lib/degradation/mcp-wrapper.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-wrapper.d.mts","sourceRoot":"","sources":["../../../src/lib/degradation/mcp-wrapper.mts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAIvD,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;CAC9B;AAED,MAAM,MAAM,UAAU,CAAC,OAAO,IAAI,CAAC,SAAS,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,EAC5B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAQ9B"}

package/dist/lib/degradation/mcp-wrapper.mjs

@@ -0,0 +1,45 @@
+// `withMcpDegradation` — the standard wrapper every MCP tool handler MUST
+// use. It creates a per-invocation collector, seeds it with any boot-time
+// health-check failures relevant to the tool, executes the handler, and
+// returns the result wrapped in the `Degradable<T>` envelope.
+//
+// See docs/technical/degradation.md for the convention.
+import { DegradationCollector } from './collector.mjs';
+import { runHealthCheck, listHealthChecks } from './registry.mjs';
+import { withCollector } from './context.mjs';
+/**
+ * Wrap an MCP tool handler with the standard degradation envelope.
+ *
+ * Every MCP handler in `src/mcp/`, `src/work-on-evolution/`, or
+ * `src/work-on-value-chain/` should be invoked through this helper so the
+ * client always receives a `Degradable<T>` shape and silent fallbacks
+ * become visible via `degradationEvents`.
+ *
+ * The handler may throw — the throw propagates to the MCP server, which
+ * wraps it as a JSON-RPC error. `Degradable` is for partial degradations
+ * where the tool still returns a usable result.
+ */
+export async function withMcpDegradation(toolName, handler, options = {}) {
+    const collector = new DegradationCollector(toolName);
+    await runPreflight(collector, options.preflight);
+    // Make the collector available via AsyncLocalStorage so code deep in the
+    // call tree (strategies, loaders, ...) can record events without having
+    // to accept it as an explicit parameter.
+    const result = await withCollector(collector, () => handler(collector));
+    return collector.wrap(result);
+}
+async function runPreflight(collector, preflight) {
+    if (!preflight)
+        return;
+    const sources = preflight === 'all' ? listHealthChecks() : preflight;
+    const events = await Promise.all(sources.map((s) => runHealthCheck(s)));
+    for (const event of events) {
+        if (event !== null)
+            collector.record(stripTimestamp(event));
+    }
+}
+function stripTimestamp(event) {
+    const { at: _at, ...rest } = event;
+    return rest;
+}
+//# sourceMappingURL=mcp-wrapper.mjs.map

package/dist/lib/degradation/mcp-wrapper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-wrapper.mjs","sourceRoot":"","sources":["../../../src/lib/degradation/mcp-wrapper.mts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,8DAA8D;AAC9D,EAAE;AACF,wDAAwD;AAGxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAe9C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAA4B,EAC5B,UAAqC,EAAE;IAEvC,MAAM,SAAS,GAAG,IAAI,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACrD,MAAM,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,yEAAyE;IACzE,wEAAwE;IACxE,yCAAyC;IACzC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IACxE,OAAO,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,SAA+B,EAC/B,SAAuC;IAEvC,IAAI,CAAC,SAAS;QAAE,OAAO;IAEvB,MAAM,OAAO,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAuB;IAC7C,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/lib/degradation/registry.d.mts

@@ -0,0 +1,32 @@
+import type { DegradationEvent, HealthCheck } from './types.mjs';
+/**
+ * Register a health check under a stable source identifier.
+ *
+ * Re-registering an existing source overwrites the previous check —
+ * intended for tests; production code should register each source once
+ * at boot.
+ */
+export declare function registerHealthCheck(source: string, check: HealthCheck): void;
+/** True if a check has been registered for this source. */
+export declare function hasHealthCheck(source: string): boolean;
+/** Names of every registered source, in insertion order. */
+export declare function listHealthChecks(): string[];
+/** Reset the registry — exposed for tests; not part of the public API. */
+export declare function clearRegistry(): void;
+/**
+ * Run a single health check by source name.
+ *
+ * Returns `null` when the dependency is ready. Returns a `DegradationEvent`
+ * (`severity: 'warning'`, `recoverable: false`) when the dependency is not
+ * ready or the check itself threw. Unknown sources also return a warning
+ * event so misconfigured callers do not silently no-op.
+ */
+export declare function runHealthCheck(source: string): Promise<DegradationEvent | null>;
+/**
+ * Run every registered health check in parallel and return the failing ones.
+ *
+ * Successful checks contribute nothing to the returned array; the result is
+ * an empty array when every dependency is ready.
+ */
+export declare function runAllHealthChecks(): Promise<DegradationEvent[]>;
+//# sourceMappingURL=registry.d.mts.map

package/dist/lib/degradation/registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.mts","sourceRoot":"","sources":["../../../src/lib/degradation/registry.mts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EAEZ,MAAM,aAAa,CAAC;AAKrB;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAE5E;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAerF;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAItE"}

package/dist/lib/degradation/registry.mjs

@@ -0,0 +1,79 @@
+// Health-check registry for external dependencies.
+//
+// Tools register one health check per external dependency at boot
+// (see src/mcp/mcp-server.mts). At runtime the MCP wrapper consults
+// the registry to surface dependencies that are already known to be
+// down before any request reaches the inner pipeline.
+//
+// The registry is process-global and append-only; tests reset it via
+// `clearRegistry()`.
+import { toErrorMessage } from '../errors.mjs';
+const registry = new Map();
+/**
+ * Register a health check under a stable source identifier.
+ *
+ * Re-registering an existing source overwrites the previous check —
+ * intended for tests; production code should register each source once
+ * at boot.
+ */
+export function registerHealthCheck(source, check) {
+    registry.set(source, check);
+}
+/** True if a check has been registered for this source. */
+export function hasHealthCheck(source) {
+    return registry.has(source);
+}
+/** Names of every registered source, in insertion order. */
+export function listHealthChecks() {
+    return Array.from(registry.keys());
+}
+/** Reset the registry — exposed for tests; not part of the public API. */
+export function clearRegistry() {
+    registry.clear();
+}
+/**
+ * Run a single health check by source name.
+ *
+ * Returns `null` when the dependency is ready. Returns a `DegradationEvent`
+ * (`severity: 'warning'`, `recoverable: false`) when the dependency is not
+ * ready or the check itself threw. Unknown sources also return a warning
+ * event so misconfigured callers do not silently no-op.
+ */
+export async function runHealthCheck(source) {
+    const check = registry.get(source);
+    if (!check) {
+        return makeEvent(source, `no health check registered for "${source}"`, undefined);
+    }
+    let outcome;
+    try {
+        outcome = await check();
+    }
+    catch (err) {
+        return makeEvent(source, `health check threw: ${toErrorMessage(err)}`, { error: toErrorMessage(err) });
+    }
+    if (outcome.ready)
+        return null;
+    return makeEvent(source, outcome.reason ?? `${source} not ready`, outcome.detail);
+}
+/**
+ * Run every registered health check in parallel and return the failing ones.
+ *
+ * Successful checks contribute nothing to the returned array; the result is
+ * an empty array when every dependency is ready.
+ */
+export async function runAllHealthChecks() {
+    const sources = Array.from(registry.keys());
+    const results = await Promise.all(sources.map((s) => runHealthCheck(s)));
+    return results.filter((e) => e !== null);
+}
+function makeEvent(source, reason, detail) {
+    return {
+        source,
+        reason,
+        severity: 'warning',
+        recoverable: false,
+        detail,
+        at: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=registry.mjs.map

package/dist/lib/degradation/registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.mjs","sourceRoot":"","sources":["../../../src/lib/degradation/registry.mts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,kEAAkE;AAClE,oEAAoE;AACpE,oEAAoE;AACpE,sDAAsD;AACtD,EAAE;AACF,qEAAqE;AACrE,qBAAqB;AAOrB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,KAAkB;IACpE,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,aAAa;IAC3B,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAc;IACjD,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC,MAAM,EAAE,mCAAmC,MAAM,GAAG,EAAE,SAAS,CAAC,CAAC;IACpF,CAAC;IAED,IAAI,OAA2B,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,KAAK,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,SAAS,CAAC,MAAM,EAAE,uBAAuB,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzG,CAAC;IAED,IAAI,OAAO,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,GAAG,MAAM,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;AACpF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAyB,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,SAAS,CAAC,MAAc,EAAE,MAAc,EAAE,MAAe;IAChE,OAAO;QACL,MAAM;QACN,MAAM;QACN,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,KAAK;QAClB,MAAM;QACN,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAC7B,CAAC;AACJ,CAAC"}

package/dist/lib/degradation/types.d.mts

@@ -0,0 +1,41 @@
+export type DegradationSeverity = 'info' | 'warning' | 'error';
+/**
+ * A single degradation observation captured during a tool invocation.
+ *
+ * Sources are short stable identifiers like 'bigquery', 'cpc-mapper',
+ * 'web-search', 'llm:claude', 'llm:opencode'. They appear in MCP log
+ * notifications and in the serialized result.
+ */
+export interface DegradationEvent {
+    source: string;
+    reason: string;
+    severity: DegradationSeverity;
+    recoverable: boolean;
+    detail?: unknown;
+    at: string;
+}
+/**
+ * Standard envelope returned by every MCP tool handler.
+ *
+ * `result` is the tool's normal payload (possibly built from fallback values).
+ * `degraded` is true as soon as at least one warning/error event was recorded.
+ * `degradationEvents` lists every event in capture order for client display.
+ */
+export interface Degradable<T> {
+    result: T;
+    degraded: boolean;
+    degradationEvents: DegradationEvent[];
+}
+/**
+ * Outcome shape returned by a registered health check.
+ *
+ * `ready: true` means the dependency is usable. `reason`/`detail` describe
+ * the failure mode when not ready (missing env vars, auth error, etc.).
+ */
+export interface HealthCheckOutcome {
+    ready: boolean;
+    reason?: string;
+    detail?: unknown;
+}
+export type HealthCheck = () => Promise<HealthCheckOutcome> | HealthCheckOutcome;
+//# sourceMappingURL=types.d.mts.map

package/dist/lib/degradation/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../../src/lib/degradation/types.mts"],"names":[],"mappings":"AASA,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,OAAO,CAAC;IAClB,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC"}

package/dist/lib/degradation/types.mjs

@@ -0,0 +1,10 @@
+// Degradation framework — shared types
+//
+// `Degradable<T>` is the standard envelope that wraps every MCP tool result
+// when an external dependency (LLM, BigQuery, web search, ...) misbehaves
+// without forcing a hard failure. The framework lets tools keep returning
+// a valid result while making the partial-failure visible to the client.
+//
+// See docs/technical/degradation.md for the full convention.
+export {};
+//# sourceMappingURL=types.mjs.map

package/dist/lib/degradation/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../../../src/lib/degradation/types.mts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,0EAA0E;AAC1E,yEAAyE;AACzE,EAAE;AACF,6DAA6D"}

package/dist/lib/degradation/with-degradation.d.mts

@@ -0,0 +1,34 @@
+import type { DegradationSeverity } from './types.mjs';
+import { DegradationCollector } from './collector.mjs';
+export interface TryDegradeOptions {
+    recoverable?: boolean;
+    severity?: DegradationSeverity;
+}
+/**
+ * Execute `fn`. If it throws (or rejects), record the error on `collector`
+ * under `source` and return `fallback` instead.
+ *
+ * The fallback is returned as-is — the caller is responsible for choosing
+ * a value that keeps the surrounding pipeline valid (empty arrays, neutral
+ * scores, stub objects, ...).
+ *
+ * @example
+ *   const patentData = await tryDegrade(
+ *     collector, 'bigquery',
+ *     () => createPatentSource().fetchByCpc(cpcCodes),
+ *     { totalPatents: 0, patents: [] },
+ *   );
+ */
+export declare function tryDegrade<T>(collector: DegradationCollector, source: string, fn: () => Promise<T> | T, fallback: T, opts?: TryDegradeOptions): Promise<T>;
+/**
+ * Same as `tryDegrade` but uses the ambient collector (set by
+ * `withMcpDegradation` via AsyncLocalStorage). When no ambient collector
+ * exists — typically a unit test or CLI script invocation — the failure
+ * is silently swallowed and the fallback is returned.
+ *
+ * Use this from inside MCP-invoked code paths (strategies, loaders,
+ * routers) where threading a collector through every signature would be
+ * noise.
+ */
+export declare function tryDegradeAmbient<T>(source: string, fn: () => Promise<T> | T, fallback: T, opts?: TryDegradeOptions): Promise<T>;
+//# sourceMappingURL=with-degradation.d.mts.map

package/dist/lib/degradation/with-degradation.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-degradation.d.mts","sourceRoot":"","sources":["../../../src/lib/degradation/with-degradation.mts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGvD,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,SAAS,EAAE,oBAAoB,EAC/B,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,QAAQ,EAAE,CAAC,EACX,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,QAAQ,EAAE,CAAC,EACX,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAUZ"}

package/dist/lib/degradation/with-degradation.mjs

@@ -0,0 +1,51 @@
+// `tryDegrade` — functional helper that replaces silent `try/catch {}`
+// blocks around external calls. On success it returns the value; on failure
+// it records a degradation event on the collector and returns the fallback.
+import { getCurrentCollector } from './context.mjs';
+/**
+ * Execute `fn`. If it throws (or rejects), record the error on `collector`
+ * under `source` and return `fallback` instead.
+ *
+ * The fallback is returned as-is — the caller is responsible for choosing
+ * a value that keeps the surrounding pipeline valid (empty arrays, neutral
+ * scores, stub objects, ...).
+ *
+ * @example
+ *   const patentData = await tryDegrade(
+ *     collector, 'bigquery',
+ *     () => createPatentSource().fetchByCpc(cpcCodes),
+ *     { totalPatents: 0, patents: [] },
+ *   );
+ */
+export async function tryDegrade(collector, source, fn, fallback, opts = {}) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        collector.recordError(source, err, opts);
+        return fallback;
+    }
+}
+/**
+ * Same as `tryDegrade` but uses the ambient collector (set by
+ * `withMcpDegradation` via AsyncLocalStorage). When no ambient collector
+ * exists — typically a unit test or CLI script invocation — the failure
+ * is silently swallowed and the fallback is returned.
+ *
+ * Use this from inside MCP-invoked code paths (strategies, loaders,
+ * routers) where threading a collector through every signature would be
+ * noise.
+ */
+export async function tryDegradeAmbient(source, fn, fallback, opts = {}) {
+    const collector = getCurrentCollector();
+    if (!collector) {
+        try {
+            return await fn();
+        }
+        catch {
+            return fallback;
+        }
+    }
+    return tryDegrade(collector, source, fn, fallback, opts);
+}
+//# sourceMappingURL=with-degradation.mjs.map

package/dist/lib/degradation/with-degradation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-degradation.mjs","sourceRoot":"","sources":["../../../src/lib/degradation/with-degradation.mts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,4EAA4E;AAC5E,4EAA4E;AAI5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAOpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,SAA+B,EAC/B,MAAc,EACd,EAAwB,EACxB,QAAW,EACX,OAA0B,EAAE;IAE5B,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QACzC,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,EAAwB,EACxB,QAAW,EACX,OAA0B,EAAE;IAE5B,MAAM,SAAS,GAAG,mBAAmB,EAAE,CAAC;IACxC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AAC3D,CAAC"}

package/dist/lib/errors.d.mts

@@ -0,0 +1,10 @@
+/**
+ * Extract a human-readable message from an unknown caught value.
+ * Falls back to String(e) for non-Error throws (e.g. thrown strings).
+ */
+export declare function toErrorMessage(e: unknown): string;
+/** True if `e` is an Error (or Error-shaped) and its `.code` matches. */
+export declare function isErrorCode(e: unknown, code: string): boolean;
+/** Extract a `.code` field from a caught value, or undefined. */
+export declare function errorCode(e: unknown): string | undefined;
+//# sourceMappingURL=errors.d.mts.map

package/dist/lib/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","sourceRoot":"","sources":["../../src/lib/errors.mts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAQjD;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAG7D;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIxD"}

package/dist/lib/errors.mjs

@@ -0,0 +1,33 @@
+// Error narrowing helpers for `catch (e: unknown)` under strict TS.
+//
+// In strict mode, `catch (e)` types `e` as `unknown`, so `e.message` is a
+// type error. These helpers narrow once and return safe primitives.
+/**
+ * Extract a human-readable message from an unknown caught value.
+ * Falls back to String(e) for non-Error throws (e.g. thrown strings).
+ */
+export function toErrorMessage(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === 'string')
+        return e;
+    if (e !== null && typeof e === 'object' && 'message' in e) {
+        const m = e.message;
+        return typeof m === 'string' ? m : String(m);
+    }
+    return String(e);
+}
+/** True if `e` is an Error (or Error-shaped) and its `.code` matches. */
+export function isErrorCode(e, code) {
+    if (e === null || typeof e !== 'object')
+        return false;
+    return e.code === code;
+}
+/** Extract a `.code` field from a caught value, or undefined. */
+export function errorCode(e) {
+    if (e === null || typeof e !== 'object')
+        return undefined;
+    const c = e.code;
+    return typeof c === 'string' ? c : undefined;
+}
+//# sourceMappingURL=errors.mjs.map

package/dist/lib/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","sourceRoot":"","sources":["../../src/lib/errors.mts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,EAAE;AACF,0EAA0E;AAC1E,oEAAoE;AAEpE;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,CAAU;IACvC,IAAI,CAAC,YAAY,KAAK;QAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IACzC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,CAAC,GAAI,CAA2B,CAAC,OAAO,CAAC;QAC/C,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,WAAW,CAAC,CAAU,EAAE,IAAY;IAClD,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,OAAQ,CAAwB,CAAC,IAAI,KAAK,IAAI,CAAC;AACjD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC1D,MAAM,CAAC,GAAI,CAAwB,CAAC,IAAI,CAAC;IACzC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC"}

package/dist/lib/known-dictionaries.d.mts

@@ -0,0 +1,38 @@
+export declare const KNOWN_SOLUTIONS: Map<string, {
+    canonical: string;
+    vendor: string;
+    category: string;
+}>;
+export declare const KNOWN_CAPABILITIES: Map<string, {
+    canonical: string;
+    nature: string;
+}>;
+/**
+ * Solution naming patterns (indicate branded/concrete products):
+ * - PascalCase or camelCase branded names (e.g. "OpenShift", "GitHub")
+ * - Names with version numbers (e.g. "React 18", "Python 3.12")
+ * - Names with company prefix (e.g. "Google BigQuery", "Amazon S3")
+ * - Proper nouns with trademark symbols
+ * - Single capitalized words that look like brands (e.g. "Docker", "Kafka")
+ * - Names containing registered/trademark symbols
+ */
+export declare const SOLUTION_PATTERNS: {
+    pattern: RegExp;
+    weight: number;
+    reason: string;
+}[];
+/**
+ * Capability naming patterns (indicate abstract activities/concepts):
+ * - Verb phrases (e.g. "manage customer relationships")
+ * - Gerund phrases (e.g. "container orchestration")
+ * - Abstract noun phrases (e.g. "identity management")
+ * - "how to" prefixes (practice nature)
+ * - Phrases describing what, not which brand
+ */
+export declare const CAPABILITY_PATTERNS: {
+    pattern: RegExp;
+    weight: number;
+    reason: string;
+}[];
+export declare const COMMON_ENGLISH_WORDS: Set<string>;
+//# sourceMappingURL=known-dictionaries.d.mts.map

package/dist/lib/known-dictionaries.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"known-dictionaries.d.mts","sourceRoot":"","sources":["../../src/lib/known-dictionaries.mts"],"names":[],"mappings":"AAaA,eAAO,MAAM,eAAe;;;;EAuJ1B,CAAC;AAOH,eAAO,MAAM,kBAAkB;;;EA0E7B,CAAC;AAOH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;GAiB7B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;;;;GAiB/B,CAAC;AAOF,eAAO,MAAM,oBAAoB,aAqC/B,CAAC"}