@vinkius-core/mcp-fusion 2.6.0 → 2.7.0

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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vinkius-core/mcp-fusion",
-    "version": "2.6.0",
+    "version": "2.7.0",
     "description": "MVA (Model-View-Agent) framework for the Model Context Protocol. Structured perception packages with Presenters, cognitive guardrails, self-healing errors, action consolidation, and tRPC-style type safety — so AI agents perceive and act on your data deterministically.",
     "type": "module",
     "main": "dist/index.js",
@@ -13,6 +13,38 @@
         "./client": {
             "import": "./dist/client/index.js",
             "types": "./dist/client/index.d.ts"
+        },
+        "./ui": {
+            "import": "./dist/presenter/ui.js",
+            "types": "./dist/presenter/ui.d.ts"
+        },
+        "./presenter": {
+            "import": "./dist/presenter/index.js",
+            "types": "./dist/presenter/index.d.ts"
+        },
+        "./prompt": {
+            "import": "./dist/prompt/index.js",
+            "types": "./dist/prompt/index.d.ts"
+        },
+        "./state-sync": {
+            "import": "./dist/state-sync/index.js",
+            "types": "./dist/state-sync/index.d.ts"
+        },
+        "./observability": {
+            "import": "./dist/observability/index.js",
+            "types": "./dist/observability/index.d.ts"
+        },
+        "./dev": {
+            "import": "./dist/server/DevServer.js",
+            "types": "./dist/server/DevServer.d.ts"
+        },
+        "./schema": {
+            "import": "./dist/core/StandardSchema.js",
+            "types": "./dist/core/StandardSchema.d.ts"
+        },
+        "./testing": {
+            "import": "./dist/testing/MvaMetaSymbol.js",
+            "types": "./dist/testing/MvaMetaSymbol.d.ts"
         }
     },
     "scripts": {
@@ -71,5 +103,10 @@
         "@modelcontextprotocol/sdk": "^1.12.1",
         "zod": "^3.25.1 || ^4.0.0"
     },
+    "peerDependenciesMeta": {
+        "zod": {
+            "optional": true
+        }
+    },
     "license": "Apache-2.0"
 }