@vinkius-core/mcp-fusion 2.6.0 → 2.8.0

package/dist/server/autoDiscover.d.ts

@@ -0,0 +1,63 @@
+/** Duck-typed ToolBuilder — avoids circular imports */
+interface ToolBuilderLike {
+    getName(): string;
+    buildToolDefinition?(): unknown;
+}
+/** Duck-typed ToolRegistry — avoids circular imports */
+interface ToolRegistryLike {
+    register(builder: ToolBuilderLike): void;
+}
+/**
+ * Options for `autoDiscover()`.
+ */
+export interface AutoDiscoverOptions {
+    /**
+     * Regex pattern to filter files. Only files matching this pattern
+     * are imported. Default: matches `.ts`, `.js`, `.mjs`, `.mts` files,
+     * excluding `.test.`, `.spec.`, and `.d.ts` files.
+     */
+    pattern?: RegExp;
+    /**
+     * Whether to recurse into subdirectories.
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * Module resolution style:
+     * - `'esm'` — Uses dynamic `import()` (default for ESM projects)
+     * - `'cjs'` — Uses `require()` (for CommonJS projects)
+     *
+     * @default 'esm'
+     */
+    loader?: 'esm' | 'cjs';
+    /**
+     * Custom export resolver. When provided, this function is called
+     * with the module's exports and must return the tool builder(s).
+     *
+     * Default behavior: looks for `default` export or named `tool` export.
+     */
+    resolve?: (mod: Record<string, unknown>) => ToolBuilderLike | ToolBuilderLike[] | undefined;
+}
+/**
+ * Scan a directory and auto-register all discovered tool builders.
+ *
+ * Eliminates the need for a central `index.ts` that manually imports
+ * and registers every tool. New tools are automatically picked up
+ * when they are dropped into the scanned directory.
+ *
+ * @param registry - A ToolRegistry instance to register discovered tools
+ * @param dir - Path to the tools directory (absolute or relative to CWD)
+ * @param options - Discovery options (pattern, recursive, loader, resolve)
+ * @returns Array of discovered file paths (for logging/debugging)
+ * @throws If the directory does not exist or is not readable
+ *
+ * @example
+ * ```typescript
+ * const registry = new ToolRegistry<AppContext>();
+ * const files = await autoDiscover(registry, './src/tools');
+ * console.log(`Discovered ${files.length} tool files`);
+ * ```
+ */
+export declare function autoDiscover(registry: ToolRegistryLike, dir: string, options?: AutoDiscoverOptions): Promise<string[]>;
+export {};
+//# sourceMappingURL=autoDiscover.d.ts.map

package/dist/server/autoDiscover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoDiscover.d.ts","sourceRoot":"","sources":["../../src/server/autoDiscover.ts"],"names":[],"mappings":"AAkDA,uDAAuD;AACvD,UAAU,eAAe;IACrB,OAAO,IAAI,MAAM,CAAC;IAClB,mBAAmB,CAAC,IAAI,OAAO,CAAC;CACnC;AAED,wDAAwD;AACxD,UAAU,gBAAgB;IACtB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAEvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,eAAe,GAAG,eAAe,EAAE,GAAG,SAAS,CAAC;CAC/F;AAmED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAC9B,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC,MAAM,EAAE,CAAC,CA6CnB"}

package/dist/server/autoDiscover.js

@@ -0,0 +1,157 @@
+/**
+ * File-Based Routing — Auto-Discovery of Tools via Directory Structure
+ *
+ * Scans a directory at startup and auto-registers tools based on the
+ * file-system naming convention:
+ *
+ * ```
+ * src/tools/
+ * ├── billing/
+ * │   ├── get_invoice.ts  → billing.get_invoice
+ * │   └── pay.ts          → billing.pay
+ * └── users/
+ *     ├── list.ts         → users.list
+ *     └── ban.ts          → users.ban
+ * ```
+ *
+ * Each file must export a `GroupedToolBuilder` (via `defineTool()`,
+ * `createTool()`, `f.tool()`, etc.) as the **default export** or
+ * a named export called `tool`.
+ *
+ * **Benefits:**
+ * - Zero code orchestration — no central `index.ts` with 50 imports
+ * - Git-friendly — reduced merge conflicts (no shared import file)
+ * - Instant onboarding — "drop a file → it's a tool"
+ *
+ * @example
+ * ```typescript
+ * import { autoDiscover, ToolRegistry } from '@vinkius-core/mcp-fusion';
+ *
+ * const registry = new ToolRegistry<AppContext>();
+ *
+ * // Scan src/tools/ and register everything
+ * await autoDiscover(registry, './src/tools');
+ *
+ * // Or with options
+ * await autoDiscover(registry, './src/tools', {
+ *   pattern: /\.tool\.ts$/,     // only files ending in .tool.ts
+ *   recursive: true,            // scan subdirectories (default: true)
+ *   separator: '.',             // directory separator for tool names
+ * });
+ * ```
+ *
+ * @module
+ */
+import { promises as fs } from 'node:fs';
+import { join, resolve, relative, basename, extname, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// ── Internal ─────────────────────────────────────────────
+const DEFAULT_PATTERN = /\.(ts|js|mjs|mts)$/;
+const EXCLUDED_PATTERN = /\.(test|spec|d)\./;
+/**
+ * Walk a directory tree and collect file paths matching the filter.
+ * @internal
+ */
+async function walkDir(dir, pattern, recursive) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory() && recursive) {
+            const nested = await walkDir(fullPath, pattern, recursive);
+            files.push(...nested);
+        }
+        else if (entry.isFile() && pattern.test(entry.name) && !EXCLUDED_PATTERN.test(entry.name)) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+/**
+ * Check if a value looks like a ToolBuilder (duck typing).
+ * @internal
+ */
+function isToolBuilder(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.getName === 'function');
+}
+/**
+ * Default export resolver: check default → tool → any exported builder.
+ * @internal
+ */
+function defaultResolver(mod) {
+    // Priority 1: default export
+    const defaultExport = mod['default'];
+    if (isToolBuilder(defaultExport))
+        return defaultExport;
+    // Priority 2: named `tool` export
+    const toolExport = mod['tool'];
+    if (isToolBuilder(toolExport))
+        return toolExport;
+    // Priority 3: collect all exported builders
+    const builders = [];
+    for (const value of Object.values(mod)) {
+        if (isToolBuilder(value)) {
+            builders.push(value);
+        }
+    }
+    return builders.length > 0 ? builders : undefined;
+}
+// ── Public API ───────────────────────────────────────────
+/**
+ * Scan a directory and auto-register all discovered tool builders.
+ *
+ * Eliminates the need for a central `index.ts` that manually imports
+ * and registers every tool. New tools are automatically picked up
+ * when they are dropped into the scanned directory.
+ *
+ * @param registry - A ToolRegistry instance to register discovered tools
+ * @param dir - Path to the tools directory (absolute or relative to CWD)
+ * @param options - Discovery options (pattern, recursive, loader, resolve)
+ * @returns Array of discovered file paths (for logging/debugging)
+ * @throws If the directory does not exist or is not readable
+ *
+ * @example
+ * ```typescript
+ * const registry = new ToolRegistry<AppContext>();
+ * const files = await autoDiscover(registry, './src/tools');
+ * console.log(`Discovered ${files.length} tool files`);
+ * ```
+ */
+export async function autoDiscover(registry, dir, options = {}) {
+    const { pattern = DEFAULT_PATTERN, recursive = true, loader = 'esm', resolve: customResolve, } = options;
+    const absoluteDir = resolve(dir);
+    const files = await walkDir(absoluteDir, pattern, recursive);
+    const discoveredFiles = [];
+    for (const filePath of files) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let mod;
+            if (loader === 'cjs') {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                mod = require(filePath);
+            }
+            else {
+                const fileUrl = pathToFileURL(filePath).href;
+                mod = await import(fileUrl);
+            }
+            const resolver = customResolve ?? defaultResolver;
+            const result = resolver(mod);
+            if (!result)
+                continue;
+            const builders = Array.isArray(result) ? result : [result];
+            for (const builder of builders) {
+                registry.register(builder);
+            }
+            discoveredFiles.push(filePath);
+        }
+        catch {
+            // Skip files that fail to import (syntax errors, missing deps, etc.)
+            // In production, this should be logged via the observability layer
+            continue;
+        }
+    }
+    return discoveredFiles;
+}
+//# sourceMappingURL=autoDiscover.js.map

package/dist/server/autoDiscover.js.map

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

package/dist/server/index.d.ts

@@ -3,4 +3,8 @@ export { resolveServer } from './ServerResolver.js';
 export { attachToServer, type AttachOptions, type DetachFn, type RegistryDelegate, } from './ServerAttachment.js';
 export type { ToolExposition, ExpositionConfig } from '../exposition/index.js';
 export { compileExposition, type FlatRoute, type ExpositionResult } from '../exposition/index.js';
+export { autoDiscover } from './autoDiscover.js';
+export type { AutoDiscoverOptions } from './autoDiscover.js';
+export { createDevServer } from './DevServer.js';
+export type { DevServerConfig, DevServer } from './DevServer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACH,cAAc,EACd,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,GAC3D,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACH,cAAc,EACd,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,GAC3D,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAGlG,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/server/index.js

@@ -2,4 +2,8 @@
 export { resolveServer } from './ServerResolver.js';
 export { attachToServer, } from './ServerAttachment.js';
 export { compileExposition } from '../exposition/index.js';
+// ── File-Based Routing ───────────────────────────────────
+export { autoDiscover } from './autoDiscover.js';
+// ── Dev Server (HMR) ────────────────────────────────────
+export { createDevServer } from './DevServer.js';
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACH,cAAc,GAEjB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,iBAAiB,EAAyC,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACH,cAAc,GAEjB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,iBAAiB,EAAyC,MAAM,wBAAwB,CAAC;AAElG,4DAA4D;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,2DAA2D;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/state-sync/PolicyValidator.d.ts

@@ -28,4 +28,40 @@ export declare function validatePolicies(policies: readonly SyncPolicy[]): void;
 export declare function validateDefaults(defaults?: {
     readonly cacheControl?: CacheDirective;
 }): void;
+/**
+ * Warning produced when two policies potentially overlap.
+ *
+ * Overlapping policies are not an error (first-match-wins is deterministic),
+ * but they can cause subtle configuration bugs when the user expects a
+ * more-specific policy to fire but a broader one shadows it.
+ *
+ * @example
+ * ```typescript
+ * const warnings = detectOverlaps(policies);
+ * warnings.forEach(w => console.warn(`[StateSync] ${w.message}`));
+ * ```
+ */
+export interface OverlapWarning {
+    /** Human-readable description of the overlap. */
+    readonly message: string;
+    /** Index of the shadowing (earlier) policy. */
+    readonly shadowingIndex: number;
+    /** Index of the shadowed (later) policy. */
+    readonly shadowedIndex: number;
+}
+/**
+ * Detect potentially overlapping glob policies.
+ *
+ * Checks if a broader policy at index `i` could shadow a more-specific
+ * policy at index `j > i`. Uses GlobMatcher to test if the earlier
+ * pattern matches the later pattern's literal segments.
+ *
+ * This is a heuristic: it only catches cases where the later policy's
+ * `match` string (treated as a literal tool name) would match the
+ * earlier policy's glob. It does NOT do full set-intersection analysis.
+ *
+ * @param policies - The policies array to analyze
+ * @returns Array of overlap warnings (empty if no overlaps detected)
+ */
+export declare function detectOverlaps(policies: readonly SyncPolicy[]): readonly OverlapWarning[];
 //# sourceMappingURL=PolicyValidator.d.ts.map

package/dist/state-sync/PolicyValidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PolicyValidator.d.ts","sourceRoot":"","sources":["../../src/state-sync/PolicyValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI7D,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAsC,CAAC;AAiExF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAetE;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,CAAC,EAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAA;CAAE,GACtD,IAAI,CAON"}
+{"version":3,"file":"PolicyValidator.d.ts","sourceRoot":"","sources":["../../src/state-sync/PolicyValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAK7D,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAsC,CAAC;AAiExF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAetE;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,CAAC,EAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAA;CAAE,GACtD,IAAI,CAON;AAID;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,cAAc,EAAE,CAuBzF"}

package/dist/state-sync/PolicyValidator.js

@@ -1,3 +1,4 @@
+import { matchGlob } from './GlobMatcher.js';
 // ── Constants ────────────────────────────────────────────
 /** Valid cache directives — binary vocabulary, no max-age. */
 export const VALID_DIRECTIVES = new Set(['no-store', 'immutable']);
@@ -84,4 +85,38 @@ export function validateDefaults(defaults) {
             `Allowed: "no-store", "immutable".`);
     }
 }
+/**
+ * Detect potentially overlapping glob policies.
+ *
+ * Checks if a broader policy at index `i` could shadow a more-specific
+ * policy at index `j > i`. Uses GlobMatcher to test if the earlier
+ * pattern matches the later pattern's literal segments.
+ *
+ * This is a heuristic: it only catches cases where the later policy's
+ * `match` string (treated as a literal tool name) would match the
+ * earlier policy's glob. It does NOT do full set-intersection analysis.
+ *
+ * @param policies - The policies array to analyze
+ * @returns Array of overlap warnings (empty if no overlaps detected)
+ */
+export function detectOverlaps(policies) {
+    const warnings = [];
+    for (let i = 0; i < policies.length; i++) {
+        for (let j = i + 1; j < policies.length; j++) {
+            const earlier = policies[i].match;
+            const later = policies[j].match;
+            // If the later policy's match pattern (as a literal name)
+            // would be caught by the earlier policy's glob, it's shadowed.
+            if (matchGlob(earlier, later)) {
+                warnings.push({
+                    message: `policy[${i}] (match: "${earlier}") shadows policy[${j}] (match: "${later}"). ` +
+                        `The later policy will never match because first-match-wins applies.`,
+                    shadowingIndex: i,
+                    shadowedIndex: j,
+                });
+            }
+        }
+    }
+    return warnings;
+}
 //# sourceMappingURL=PolicyValidator.js.map

package/dist/state-sync/PolicyValidator.js.map

@@ -1 +1 @@
-{"version":3,"file":"PolicyValidator.js","sourceRoot":"","sources":["../../src/state-sync/PolicyValidator.ts"],"names":[],"mappings":"AAaA,4DAA4D;AAE5D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;AAExF,6DAA6D;AAC7D,MAAM,aAAa,GAAG,4BAA4B,CAAC;AAEnD,4DAA4D;AAE5D;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,OAAe,EAAE,KAAa,EAAE,MAAc;IACnE,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,KAAK,KAAK,8BAA8B,CAAC,CAAC;IACvE,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACX,GAAG,MAAM,KAAK,KAAK,aAAa,OAAO,0BAA0B,GAAG,KAAK;gBACzE,6CAA6C,CAChD,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,SAAiB,EAAE,MAAc;IAC3D,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACX,GAAG,MAAM,2BAA2B,SAAS,KAAK;YAClD,mCAAmC,CACtC,CAAC;IACN,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,sBAAsB,CAAC,WAAoB,EAAE,MAAc;IAChE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,mCAAmC,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,WAAuB,EAAE,CAAC;QAC5C,eAAe,CAAC,OAAO,EAAE,wDAAwD,EAAE,MAAM,CAAC,CAAC;IAC/F,CAAC;AACL,CAAC;AAED,4DAA4D;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA+B;IAC5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;QACvB,MAAM,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC;QAExC,eAAe,CAAC,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QAE5C,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,oBAAoB,CAAC,CAAC,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,sBAAsB,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAClD,CAAC;IACL,CAAC;AACL,CAAC;AAED,4DAA4D;AAE5D;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC5B,QAAqD;IAErD,IAAI,QAAQ,EAAE,YAAY,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CACX,mCAAmC,QAAQ,CAAC,YAAY,gBAAgB;YACxE,mCAAmC,CACtC,CAAC;IACN,CAAC;AACL,CAAC"}
+{"version":3,"file":"PolicyValidator.js","sourceRoot":"","sources":["../../src/state-sync/PolicyValidator.ts"],"names":[],"mappings":"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"}

package/dist/state-sync/ResponseDecorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResponseDecorator.d.ts","sourceRoot":"","sources":["../../src/state-sync/ResponseDecorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,MAAM,GACjB,YAAY,CAUd"}
+{"version":3,"file":"ResponseDecorator.d.ts","sourceRoot":"","sources":["../../src/state-sync/ResponseDecorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,MAAM,GACjB,YAAY,CAUd"}

package/dist/state-sync/ResponseDecorator.js

@@ -1,3 +1,4 @@
+import { escapeXmlAttr } from '../core/response.js';
 /**
  * Prepend a System invalidation content block to a tool call response.
  *
@@ -11,7 +12,7 @@ export function decorateResponse(result, patterns, causedBy) {
     return {
         ...result,
         content: [
-            { type: 'text', text: `<cache_invalidation cause="${causedBy}" domains="${domains}" />` },
+            { type: 'text', text: `<cache_invalidation cause="${escapeXmlAttr(causedBy)}" domains="${escapeXmlAttr(domains)}" />` },
             ...result.content,
         ],
     };

package/dist/state-sync/ResponseDecorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"ResponseDecorator.js","sourceRoot":"","sources":["../../src/state-sync/ResponseDecorator.ts"],"names":[],"mappings":"AAwBA;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC5B,MAAoB,EACpB,QAA2B,EAC3B,QAAgB;IAEhB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEpC,OAAO;QACH,GAAG,MAAM;QACT,OAAO,EAAE;YACL,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,8BAA8B,QAAQ,cAAc,OAAO,MAAM,EAAE;YAClG,GAAG,MAAM,CAAC,OAAO;SACpB;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"ResponseDecorator.js","sourceRoot":"","sources":["../../src/state-sync/ResponseDecorator.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC5B,MAAoB,EACpB,QAA2B,EAC3B,QAAgB;IAEhB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEpC,OAAO;QACH,GAAG,MAAM;QACT,OAAO,EAAE;YACL,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,8BAA8B,aAAa,CAAC,QAAQ,CAAC,cAAc,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE;YAChI,GAAG,MAAM,CAAC,OAAO;SACpB;KACJ,CAAC;AACN,CAAC"}

package/dist/state-sync/StateSyncLayer.d.ts

@@ -40,6 +40,8 @@ import type { ToolResponse } from '../core/response.js';
 import type { StateSyncConfig } from './types.js';
 export declare class StateSyncLayer {
     private readonly _engine;
+    private readonly _onInvalidation?;
+    private readonly _notificationSink?;
     /**
      * Per-tool-name cache of decorated McpTool objects.
      *
@@ -49,10 +51,9 @@ export declare class StateSyncLayer {
      * on every `tools/list` request — which is the hottest path since
      * it runs at the start of every LLM conversation.
      *
-     * The cache key is the tool name + JSON input schema hash to detect
-     * changes in the underlying tool definition. In practice, tool
-     * definitions are immutable after registration, so the cache
-     * hit rate approaches 100%.
+     * The cache key is the tool name — tool definitions are immutable
+     * after registration, so the name alone is sufficient.
+     * Cache hit rate approaches 100%.
      */
     private readonly _decoratedToolCache;
     /**

package/dist/state-sync/StateSyncLayer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StateSyncLayer.d.ts","sourceRoot":"","sources":["../../src/state-sync/StateSyncLayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA8B;IAElE;;;;;;;;;OASG;gBACS,MAAM,EAAE,eAAe;IAInC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAI1C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY;IAapE;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;CAQ9B"}
+{"version":3,"file":"StateSyncLayer.d.ts","sourceRoot":"","sources":["../../src/state-sync/StateSyncLayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAA2C,MAAM,YAAY,CAAC;AAM3F,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAmD;IACpF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAA6E;IAEhH;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA8B;IAElE;;;;;;;;;OASG;gBACS,MAAM,EAAE,eAAe;IAMnC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAI1C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY;IAuCpE;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;CAQ9B"}

package/dist/state-sync/StateSyncLayer.js

@@ -42,6 +42,8 @@ import { resolveInvalidations } from './CausalEngine.js';
 import { decorateResponse } from './ResponseDecorator.js';
 export class StateSyncLayer {
     _engine;
+    _onInvalidation;
+    _notificationSink;
     /**
      * Per-tool-name cache of decorated McpTool objects.
      *
@@ -51,10 +53,9 @@ export class StateSyncLayer {
      * on every `tools/list` request — which is the hottest path since
      * it runs at the start of every LLM conversation.
      *
-     * The cache key is the tool name + JSON input schema hash to detect
-     * changes in the underlying tool definition. In practice, tool
-     * definitions are immutable after registration, so the cache
-     * hit rate approaches 100%.
+     * The cache key is the tool name — tool definitions are immutable
+     * after registration, so the name alone is sufficient.
+     * Cache hit rate approaches 100%.
      */
     _decoratedToolCache = new Map();
     /**
@@ -69,6 +70,8 @@ export class StateSyncLayer {
      */
     constructor(config) {
         this._engine = new PolicyEngine(config.policies, config.defaults);
+        this._onInvalidation = config.onInvalidation;
+        this._notificationSink = config.notificationSink;
     }
     /**
      * Decorate all tool descriptions with their resolved Cache-Control directives.
@@ -101,6 +104,34 @@ export class StateSyncLayer {
         const policy = this._engine.resolve(toolName);
         const invalidations = resolveInvalidations(policy, result.isError ?? false);
         if (invalidations.length > 0) {
+            // Fire observability hook (sync, fire-and-forget)
+            if (this._onInvalidation) {
+                const event = {
+                    causedBy: toolName,
+                    patterns: invalidations,
+                    timestamp: new Date().toISOString(),
+                };
+                try {
+                    this._onInvalidation(event);
+                }
+                catch { /* observer must not break the pipeline */ }
+            }
+            // Emit protocol-level notifications (fire-and-forget, safe for async sinks)
+            if (this._notificationSink) {
+                for (const pattern of invalidations) {
+                    const notification = {
+                        method: 'notifications/resources/updated',
+                        params: { uri: `fusion://stale/${pattern}` },
+                    };
+                    try {
+                        const maybePromise = this._notificationSink(notification);
+                        if (maybePromise instanceof Promise) {
+                            maybePromise.catch(() => { });
+                        }
+                    }
+                    catch { /* swallow sync errors — best-effort */ }
+                }
+            }
             return decorateResponse(result, invalidations, toolName);
         }
         return result;

package/dist/state-sync/StateSyncLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"StateSyncLayer.js","sourceRoot":"","sources":["../../src/state-sync/StateSyncLayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAwB,MAAM,oCAAoC,CAAC;AAG1E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,OAAO,cAAc;IACN,OAAO,CAAe;IAEvC;;;;;;;;;;;;;OAaG;IACc,mBAAmB,GAAG,IAAI,GAAG,EAAmB,CAAC;IAElE;;;;;;;;;OASG;IACH,YAAY,MAAuB;QAC/B,IAAI,CAAC,OAAO,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,KAAgB;QAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAgB,EAAE,MAAoB;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9C,MAAM,aAAa,GAAG,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC;QAE5E,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;QAC7D,CAAC;QAED,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,wDAAwD;IAExD;;;;;;;;OAQG;IACK,mBAAmB,CAAC,IAAa;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7E,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACnD,OAAO,SAAS,CAAC;IACrB,CAAC;CACJ"}
+{"version":3,"file":"StateSyncLayer.js","sourceRoot":"","sources":["../../src/state-sync/StateSyncLayer.ts"],"names":[],"mappings":"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"}

package/dist/state-sync/index.d.ts

@@ -18,7 +18,9 @@
  * @module
  */
 export { StateSyncLayer } from './StateSyncLayer.js';
-export type { CacheDirective, SyncPolicy, StateSyncConfig, ResolvedPolicy, } from './types.js';
+export type { CacheDirective, SyncPolicy, StateSyncConfig, ResolvedPolicy, InvalidationEvent, ResourceNotification, } from './types.js';
 export { PolicyEngine } from './PolicyEngine.js';
 export { matchGlob } from './GlobMatcher.js';
+export { detectOverlaps } from './PolicyValidator.js';
+export type { OverlapWarning } from './PolicyValidator.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/state-sync/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state-sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,YAAY,EACR,cAAc,EACd,UAAU,EACV,eAAe,EACf,cAAc,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state-sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,YAAY,EACR,cAAc,EACd,UAAU,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/state-sync/index.js

@@ -22,4 +22,5 @@ export { StateSyncLayer } from './StateSyncLayer.js';
 // ── Infrastructure (advanced usage) ──────────────────────
 export { PolicyEngine } from './PolicyEngine.js';
 export { matchGlob } from './GlobMatcher.js';
+export { detectOverlaps } from './PolicyValidator.js';
 //# sourceMappingURL=index.js.map

package/dist/state-sync/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state-sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,4DAA4D;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAUrD,4DAA4D;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state-sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,4DAA4D;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAYrD,4DAA4D;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/state-sync/types.d.ts

@@ -96,6 +96,68 @@ export interface StateSyncConfig {
     readonly defaults?: {
         readonly cacheControl?: CacheDirective;
     };
+    /**
+     * Observability hook invoked after each causal invalidation event.
+     *
+     * Use this to log, trace, or count invalidation events without
+     * coupling the state-sync engine to a specific observability backend.
+     *
+     * @example
+     * ```typescript
+     * stateSync: {
+     *     policies: [...],
+     *     onInvalidation: (event) => {
+     *         console.log(`[StateSync] ${event.causedBy} invalidated ${event.patterns.join(', ')}`);
+     *         metrics.increment('statesync.invalidation', { tool: event.causedBy });
+     *     },
+     * }
+     * ```
+     */
+    readonly onInvalidation?: (event: InvalidationEvent) => void;
+    /**
+     * Protocol-level notification sink for MCP resource change events.
+     *
+     * When provided, causal invalidation also emits
+     * `notifications/resources/updated` MCP protocol messages
+     * in addition to the in-band XML signal.
+     *
+     * @example
+     * ```typescript
+     * stateSync: {
+     *     policies: [...],
+     *     notificationSink: async (notification) => {
+     *         await server.sendNotification(notification);
+     *     },
+     * }
+     * ```
+     */
+    readonly notificationSink?: (notification: ResourceNotification) => void | Promise<void>;
+}
+/**
+ * Event emitted when causal invalidation is triggered.
+ *
+ * @see {@link StateSyncConfig.onInvalidation}
+ */
+export interface InvalidationEvent {
+    /** The tool that caused the invalidation (fully qualified name). */
+    readonly causedBy: string;
+    /** Glob patterns that were invalidated. */
+    readonly patterns: readonly string[];
+    /** ISO-8601 timestamp of the event. */
+    readonly timestamp: string;
+}
+/**
+ * MCP protocol notification for resource changes.
+ *
+ * Mirrors the `notifications/resources/updated` JSON-RPC message.
+ *
+ * @see {@link StateSyncConfig.notificationSink}
+ */
+export interface ResourceNotification {
+    readonly method: 'notifications/resources/updated';
+    readonly params: {
+        readonly uri: string;
+    };
 }
 /**
  * Result of resolving a policy for a specific tool name.

package/dist/state-sync/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/state-sync/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAItD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,UAAU;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IAEvC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAEzC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAChB,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;KAC1C,CAAC;CACL;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/state-sync/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAItD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,UAAU;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IAEvC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAEzC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAChB,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;KAC1C,CAAC;IAEF;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAE7D;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5F;AAID;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE;QACb,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACxB,CAAC;CACL;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C"}