@vurb/core 3.2.0

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

@@ -0,0 +1,33 @@
+/**
+ * ResponseDecorator — Causal Invalidation Signal Injection
+ *
+ * Pure function. Single responsibility: prepend a `[System: ...]`
+ * content block to a tool call result when causal invalidation
+ * is triggered.
+ *
+ * The system block goes at **index 0** — a deliberate design choice:
+ * it survives response truncation and appears before the developer's
+ * payload, maximizing LLM attention.
+ *
+ * @example
+ * ```
+ * Before: [{ type: 'text', text: '{"ok": true}' }]
+ * After:  [
+ *   { type: 'text', text: '<cache_invalidation cause="sprints.update" domains="sprints.*" />' },
+ *   { type: 'text', text: '{"ok": true}' },
+ * ]
+ * ```
+ *
+ * @module
+ */
+import type { ToolResponse } from '../core/response.js';
+/**
+ * Prepend a System invalidation content block to a tool call response.
+ *
+ * @param result    - The original tool call result (developer's response)
+ * @param patterns  - Domain patterns that were invalidated (e.g. `['sprints.*']`)
+ * @param causedBy  - The tool name that caused the invalidation
+ * @returns A new result with the System block at index 0
+ */
+export declare function decorateResponse(result: ToolResponse, patterns: readonly string[], causedBy: string): ToolResponse;
+//# sourceMappingURL=ResponseDecorator.d.ts.map

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

@@ -0,0 +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;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

@@ -0,0 +1,20 @@
+import { escapeXmlAttr } from '../core/response.js';
+/**
+ * Prepend a System invalidation content block to a tool call response.
+ *
+ * @param result    - The original tool call result (developer's response)
+ * @param patterns  - Domain patterns that were invalidated (e.g. `['sprints.*']`)
+ * @param causedBy  - The tool name that caused the invalidation
+ * @returns A new result with the System block at index 0
+ */
+export function decorateResponse(result, patterns, causedBy) {
+    const domains = patterns.join(', ');
+    return {
+        ...result,
+        content: [
+            { type: 'text', text: `<cache_invalidation cause="${escapeXmlAttr(causedBy)}" domains="${escapeXmlAttr(domains)}" />` },
+            ...result.content,
+        ],
+    };
+}
+//# sourceMappingURL=ResponseDecorator.js.map

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

@@ -0,0 +1 @@
+{"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/StateSyncBuilder.d.ts

@@ -0,0 +1,77 @@
+import { type CacheDirective, type InvalidationEvent, type ResourceNotification } from './types.js';
+import { StateSyncLayer } from './StateSyncLayer.js';
+/**
+ * Nested builder for configuring a single State Sync policy.
+ */
+export declare class PolicyBuilder {
+    private _cacheControl?;
+    private _invalidates;
+    /**
+     * Mark matching tools as immutable (safe to cache forever).
+     * Use for reference data: countries, currencies, ICD-10 codes.
+     */
+    cached(): this;
+    /**
+     * Mark matching tools as volatile (never cache).
+     * Use for dynamic data that changes on every call.
+     */
+    stale(): this;
+    /**
+     * Declare which glob patterns are invalidated when these tools succeed.
+     */
+    invalidates(...patterns: string[]): this;
+    /** @internal */
+    build(): {
+        cacheControl?: CacheDirective;
+        invalidates?: string[];
+    };
+}
+/**
+ * Fluent builder for centralized State Sync configuration.
+ *
+ * Typically accessed via `f.stateSync()` in the `initVurb` instance.
+ */
+export declare class StateSyncBuilder {
+    private _policies;
+    private _defaults;
+    private _onInvalidation?;
+    private _notificationSink?;
+    private _cachedLayer?;
+    /**
+     * Set global default cache-control directives.
+     *
+     * Only cache-control directives are valid for defaults.
+     * Invalidation patterns are NOT allowed here — use `.policy()` instead.
+     */
+    defaults(fn: (p: Omit<PolicyBuilder, 'invalidates'>) => void): this;
+    /**
+     * Add a scoped policy for matching tools using a fluent nested builder.
+     *
+     * @param match - Tool name or glob pattern (e.g. 'users.*', 'billing.create')
+     * @param fn - Callback to configure the policy
+     *
+     * @example
+     * ```typescript
+     * .policy('billing.*', p => p.noStore().invalidates('billing.*'))
+     * ```
+     */
+    policy(match: string, fn: (p: PolicyBuilder) => void): this;
+    /**
+     * Set a hook for observability when invalidations occur.
+     */
+    onInvalidation(fn: (event: InvalidationEvent) => void): this;
+    /**
+     * Set the notification sink for protocol-level resource updates.
+     */
+    notificationSink(fn: (notification: ResourceNotification) => void | Promise<void>): this;
+    /**
+     * Build the StateSyncLayer instance.
+     */
+    build(): StateSyncLayer;
+    /**
+     * Shortcut for build() to align with other builders.
+     * Bug #114 fix: cache the result so `sync.layer === sync.layer` is true.
+     */
+    get layer(): StateSyncLayer;
+}
+//# sourceMappingURL=StateSyncBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StateSyncBuilder.d.ts","sourceRoot":"","sources":["../../src/state-sync/StateSyncBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACrH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,aAAa,CAAC,CAAiB;IACvC,OAAO,CAAC,YAAY,CAAgB;IAEpC;;;OAGG;IACH,MAAM,IAAI,IAAI;IAKd;;;OAGG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAKxC,gBAAgB;IAChB,KAAK;uBAC8B,cAAc;sBAAgB,MAAM,EAAE;;CAK5E;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,eAAe,CAAC,CAAqC;IAC7D,OAAO,CAAC,iBAAiB,CAAC,CAA+D;IACzF,OAAO,CAAC,YAAY,CAAC,CAA6B;IAElD;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,KAAK,IAAI,GAAG,IAAI;IAqBnE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAQ3D;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAM5D;;OAEG;IACH,gBAAgB,CAAC,EAAE,EAAE,CAAC,YAAY,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAMxF;;OAEG;IACH,KAAK,IAAI,cAAc;IAevB;;;OAGG;IACH,IAAI,KAAK,mBAAiD;CAC7D"}

package/dist/state-sync/StateSyncBuilder.js

@@ -0,0 +1,129 @@
+import {} from './types.js';
+import { StateSyncLayer } from './StateSyncLayer.js';
+/**
+ * Nested builder for configuring a single State Sync policy.
+ */
+export class PolicyBuilder {
+    _cacheControl;
+    _invalidates = [];
+    /**
+     * Mark matching tools as immutable (safe to cache forever).
+     * Use for reference data: countries, currencies, ICD-10 codes.
+     */
+    cached() {
+        this._cacheControl = 'immutable';
+        return this;
+    }
+    /**
+     * Mark matching tools as volatile (never cache).
+     * Use for dynamic data that changes on every call.
+     */
+    stale() {
+        this._cacheControl = 'no-store';
+        return this;
+    }
+    /**
+     * Declare which glob patterns are invalidated when these tools succeed.
+     */
+    invalidates(...patterns) {
+        this._invalidates = [...this._invalidates, ...patterns];
+        return this;
+    }
+    /** @internal */
+    build() {
+        const result = {};
+        if (this._cacheControl)
+            result.cacheControl = this._cacheControl;
+        if (this._invalidates.length > 0)
+            result.invalidates = this._invalidates;
+        return result;
+    }
+}
+/**
+ * Fluent builder for centralized State Sync configuration.
+ *
+ * Typically accessed via `f.stateSync()` in the `initVurb` instance.
+ */
+export class StateSyncBuilder {
+    _policies = [];
+    _defaults = {};
+    _onInvalidation;
+    _notificationSink;
+    _cachedLayer; // Bug #114 fix
+    /**
+     * Set global default cache-control directives.
+     *
+     * Only cache-control directives are valid for defaults.
+     * Invalidation patterns are NOT allowed here — use `.policy()` instead.
+     */
+    defaults(fn) {
+        const builder = new PolicyBuilder();
+        fn(builder);
+        const built = builder.build();
+        // Runtime guard: invalidates() is hidden by Omit<> at compile time
+        // but still callable at runtime — catch this mistake early.
+        if (built.invalidates && built.invalidates.length > 0) {
+            throw new Error('StateSyncBuilder.defaults(): invalidates() is not allowed in defaults. ' +
+                'Use .policy(match, p => p.invalidates(...)) for scoped invalidation.');
+        }
+        if (built.cacheControl) {
+            this._defaults.cacheControl = built.cacheControl;
+        }
+        this._cachedLayer = undefined;
+        return this;
+    }
+    /**
+     * Add a scoped policy for matching tools using a fluent nested builder.
+     *
+     * @param match - Tool name or glob pattern (e.g. 'users.*', 'billing.create')
+     * @param fn - Callback to configure the policy
+     *
+     * @example
+     * ```typescript
+     * .policy('billing.*', p => p.noStore().invalidates('billing.*'))
+     * ```
+     */
+    policy(match, fn) {
+        const builder = new PolicyBuilder();
+        fn(builder);
+        this._policies.push({ match, ...builder.build() });
+        this._cachedLayer = undefined;
+        return this;
+    }
+    /**
+     * Set a hook for observability when invalidations occur.
+     */
+    onInvalidation(fn) {
+        this._onInvalidation = fn;
+        this._cachedLayer = undefined;
+        return this;
+    }
+    /**
+     * Set the notification sink for protocol-level resource updates.
+     */
+    notificationSink(fn) {
+        this._notificationSink = fn;
+        this._cachedLayer = undefined;
+        return this;
+    }
+    /**
+     * Build the StateSyncLayer instance.
+     */
+    build() {
+        const config = {
+            policies: this._policies,
+            defaults: this._defaults,
+        };
+        if (this._onInvalidation)
+            config.onInvalidation = this._onInvalidation;
+        if (this._notificationSink)
+            config.notificationSink = this._notificationSink;
+        return new StateSyncLayer(config);
+    }
+    /**
+     * Shortcut for build() to align with other builders.
+     * Bug #114 fix: cache the result so `sync.layer === sync.layer` is true.
+     */
+    get layer() { return this._cachedLayer ??= this.build(); }
+}
+//# sourceMappingURL=StateSyncBuilder.js.map

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

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

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

@@ -0,0 +1,107 @@
+/**
+ * StateSyncLayer — Protocol Interception Orchestrator
+ *
+ * Thin orchestration layer that ties together the PolicyEngine,
+ * DescriptionDecorator, CausalEngine, and ResponseDecorator into
+ * a single, minimal interface consumed by {@link ServerAttachment}.
+ *
+ * This is **not** a middleware — it operates at the protocol layer,
+ * intercepting `tools/list` and `tools/call` responses to inject
+ * cache-control signals that prevent LLM Temporal Blindness and
+ * Causal State Drift.
+ *
+ * Performance: tool description decoration is cached — the regex +
+ * string concatenation + object spread only runs ONCE per unique
+ * tool name, not per `tools/list` request.
+ *
+ * @example
+ * ```typescript
+ * // Created internally by ServerAttachment when stateSync is configured.
+ * // Not typically instantiated directly — use AttachOptions instead.
+ *
+ * registry.attachToServer(server, {
+ *     stateSync: {
+ *         defaults: { cacheControl: 'no-store' },
+ *         policies: [
+ *             { match: 'sprints.update', invalidates: ['sprints.*'] },
+ *             { match: 'countries.*',    cacheControl: 'immutable' },
+ *         ],
+ *     },
+ * });
+ * ```
+ *
+ * @see {@link StateSyncConfig} for configuration options
+ * @see {@link PolicyEngine} for the resolution strategy
+ *
+ * @module
+ */
+import { type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+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.
+     *
+     * Since tool descriptions are stable between `tools/list` calls,
+     * we cache the decorated version per tool name. This avoids
+     * re-running the regex match, string concatenation, and object spread
+     * 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 — tool definitions are immutable
+     * after registration, so the name alone is sufficient.
+     * Cache hit rate approaches 100%.
+     */
+    private readonly _decoratedToolCache;
+    /**
+     * Construct a StateSyncLayer from user configuration.
+     *
+     * Eagerly validates all policies and defaults at construction time.
+     * If any policy is invalid, construction fails immediately with
+     * a descriptive error.
+     *
+     * @param config - State sync configuration (policies + optional defaults)
+     * @throws {Error} If any policy or default is invalid
+     */
+    constructor(config: StateSyncConfig);
+    /**
+     * Decorate all tool descriptions with their resolved Cache-Control directives.
+     *
+     * Called during `tools/list` to append `[Cache-Control: X]` to each tool's
+     * description. Tools without a matching policy (and no defaults) are
+     * returned unchanged.
+     *
+     * Uses per-tool caching to avoid redundant decoration on repeated calls.
+     *
+     * @param tools - Original MCP tool definitions from the registry
+     * @returns Decorated tool definitions (cached shallow copies where modified)
+     */
+    decorateTools(tools: McpTool[]): McpTool[];
+    /**
+     * Decorate a tool call response with causal invalidation signals.
+     *
+     * Called after every `tools/call` execution. If the tool's policy has
+     * `invalidates` patterns and the call succeeded (`isError !== true`),
+     * prepends a `[System: Cache invalidated for X — caused by Y]` block
+     * at content index 0.
+     *
+     * @param toolName - The name of the tool that was called
+     * @param result   - The tool call result from the handler
+     * @returns Decorated result (with System block) or unchanged result
+     */
+    decorateResult(toolName: string, result: ToolResponse): ToolResponse;
+    /**
+     * Return a cached decorated tool, or compute and cache it.
+     *
+     * Cache invalidation: tool definitions are immutable after registration
+     * in Vurb's ToolRegistry (builders produce new objects each time,
+     * but the content is stable). For safety, we use the tool name as
+     * the cache key — if the same tool name produces different descriptions
+     * across calls (which shouldn't happen), the first decoration wins.
+     */
+    private _decorateToolCached;
+}
+//# sourceMappingURL=StateSyncLayer.d.ts.map

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

@@ -0,0 +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,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

@@ -0,0 +1,158 @@
+/**
+ * StateSyncLayer — Protocol Interception Orchestrator
+ *
+ * Thin orchestration layer that ties together the PolicyEngine,
+ * DescriptionDecorator, CausalEngine, and ResponseDecorator into
+ * a single, minimal interface consumed by {@link ServerAttachment}.
+ *
+ * This is **not** a middleware — it operates at the protocol layer,
+ * intercepting `tools/list` and `tools/call` responses to inject
+ * cache-control signals that prevent LLM Temporal Blindness and
+ * Causal State Drift.
+ *
+ * Performance: tool description decoration is cached — the regex +
+ * string concatenation + object spread only runs ONCE per unique
+ * tool name, not per `tools/list` request.
+ *
+ * @example
+ * ```typescript
+ * // Created internally by ServerAttachment when stateSync is configured.
+ * // Not typically instantiated directly — use AttachOptions instead.
+ *
+ * registry.attachToServer(server, {
+ *     stateSync: {
+ *         defaults: { cacheControl: 'no-store' },
+ *         policies: [
+ *             { match: 'sprints.update', invalidates: ['sprints.*'] },
+ *             { match: 'countries.*',    cacheControl: 'immutable' },
+ *         ],
+ *     },
+ * });
+ * ```
+ *
+ * @see {@link StateSyncConfig} for configuration options
+ * @see {@link PolicyEngine} for the resolution strategy
+ *
+ * @module
+ */
+import {} from '@modelcontextprotocol/sdk/types.js';
+import { PolicyEngine } from './PolicyEngine.js';
+import { decorateDescription } from './DescriptionDecorator.js';
+import { resolveInvalidations } from './CausalEngine.js';
+import { decorateResponse } from './ResponseDecorator.js';
+export class StateSyncLayer {
+    _engine;
+    _onInvalidation;
+    _notificationSink;
+    /**
+     * Per-tool-name cache of decorated McpTool objects.
+     *
+     * Since tool descriptions are stable between `tools/list` calls,
+     * we cache the decorated version per tool name. This avoids
+     * re-running the regex match, string concatenation, and object spread
+     * 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 — tool definitions are immutable
+     * after registration, so the name alone is sufficient.
+     * Cache hit rate approaches 100%.
+     */
+    _decoratedToolCache = new Map();
+    /**
+     * Construct a StateSyncLayer from user configuration.
+     *
+     * Eagerly validates all policies and defaults at construction time.
+     * If any policy is invalid, construction fails immediately with
+     * a descriptive error.
+     *
+     * @param config - State sync configuration (policies + optional defaults)
+     * @throws {Error} If any policy or default is invalid
+     */
+    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.
+     *
+     * Called during `tools/list` to append `[Cache-Control: X]` to each tool's
+     * description. Tools without a matching policy (and no defaults) are
+     * returned unchanged.
+     *
+     * Uses per-tool caching to avoid redundant decoration on repeated calls.
+     *
+     * @param tools - Original MCP tool definitions from the registry
+     * @returns Decorated tool definitions (cached shallow copies where modified)
+     */
+    decorateTools(tools) {
+        return tools.map(tool => this._decorateToolCached(tool));
+    }
+    /**
+     * Decorate a tool call response with causal invalidation signals.
+     *
+     * Called after every `tools/call` execution. If the tool's policy has
+     * `invalidates` patterns and the call succeeded (`isError !== true`),
+     * prepends a `[System: Cache invalidated for X — caused by Y]` block
+     * at content index 0.
+     *
+     * @param toolName - The name of the tool that was called
+     * @param result   - The tool call result from the handler
+     * @returns Decorated result (with System block) or unchanged result
+     */
+    decorateResult(toolName, result) {
+        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: `vurb://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;
+    }
+    // ── Private ──────────────────────────────────────────
+    /**
+     * Return a cached decorated tool, or compute and cache it.
+     *
+     * Cache invalidation: tool definitions are immutable after registration
+     * in Vurb's ToolRegistry (builders produce new objects each time,
+     * but the content is stable). For safety, we use the tool name as
+     * the cache key — if the same tool name produces different descriptions
+     * across calls (which shouldn't happen), the first decoration wins.
+     */
+    _decorateToolCached(tool) {
+        const cached = this._decoratedToolCache.get(tool.name);
+        if (cached)
+            return cached;
+        const decorated = decorateDescription(tool, this._engine.resolve(tool.name));
+        this._decoratedToolCache.set(tool.name, decorated);
+        return decorated;
+    }
+}
+//# sourceMappingURL=StateSyncLayer.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,27 @@
+/**
+ * State Sync — Public API
+ *
+ * Epistemic cache-control layer for MCP tool routing.
+ * Prevents LLM Temporal Blindness and Causal State Drift via
+ * RFC 7234 semantics and coarse-grained causal domain invalidation.
+ *
+ * **Consumer API:**
+ * - {@link StateSyncConfig} — Configuration type (passed to `attachToServer`)
+ * - {@link StateSyncLayer} — Orchestrator (used internally by ServerAttachment)
+ *
+ * Pure functions and PolicyEngine are exported for advanced use cases
+ * (custom pipelines, testing) but are not needed for standard usage.
+ *
+ * @see {@link StateSyncLayer} for the orchestration facade
+ * @see {@link StateSyncConfig} for configuration options
+ *
+ * @module
+ */
+export { StateSyncLayer } from './StateSyncLayer.js';
+export { StateSyncBuilder, PolicyBuilder } from './StateSyncBuilder.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

@@ -0,0 +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;AACrD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGxE,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

@@ -0,0 +1,27 @@
+/**
+ * State Sync — Public API
+ *
+ * Epistemic cache-control layer for MCP tool routing.
+ * Prevents LLM Temporal Blindness and Causal State Drift via
+ * RFC 7234 semantics and coarse-grained causal domain invalidation.
+ *
+ * **Consumer API:**
+ * - {@link StateSyncConfig} — Configuration type (passed to `attachToServer`)
+ * - {@link StateSyncLayer} — Orchestrator (used internally by ServerAttachment)
+ *
+ * Pure functions and PolicyEngine are exported for advanced use cases
+ * (custom pipelines, testing) but are not needed for standard usage.
+ *
+ * @see {@link StateSyncLayer} for the orchestration facade
+ * @see {@link StateSyncConfig} for configuration options
+ *
+ * @module
+ */
+// ── Orchestrator (primary export) ────────────────────────
+export { StateSyncLayer } from './StateSyncLayer.js';
+export { StateSyncBuilder, PolicyBuilder } from './StateSyncBuilder.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

@@ -0,0 +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;AACrD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAYxE,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"}