@vurb/core 3.2.0

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

@@ -0,0 +1,174 @@
+/**
+ * State Sync — Type Definitions
+ *
+ * Binary cache vocabulary for LLM temporal awareness.
+ * Uses RFC 7234 semantics deeply embedded in LLM pre-training data.
+ *
+ * There is no `max-age`. LLMs have no clock — time-based expiration
+ * is meaningless inside a context window.
+ *
+ * @see {@link StateSyncConfig} for the public configuration interface
+ * @see {@link https://arxiv.org/abs/2510.23853 | "Your LLM Agents are Temporally Blind"}
+ * @see {@link https://www.preprints.org/manuscript/202601.0910 | "State Drift in Language-Conditioned Autonomous Agents"}
+ *
+ * @module
+ */
+/**
+ * Binary cache directive for tool responses.
+ *
+ * - `'no-store'` — Never reuse cached data. Always re-fetch.
+ *   Use for volatile data: balances, inventory, patient records.
+ *
+ * - `'immutable'` — Safe to cache forever. Data will never change.
+ *   Use for reference data: countries, currencies, ICD-10 codes.
+ *
+ * LLMs have seen `Cache-Control: no-store` millions of times in HTTP docs,
+ * API specs, and developer discussions. The association between `no-store`
+ * and "do not reuse this response" is deeply embedded in model weights.
+ */
+export type CacheDirective = 'no-store' | 'immutable';
+/**
+ * A single policy rule matched by glob pattern.
+ *
+ * Policies control two behaviors:
+ * 1. **Description decoration** — Append `[Cache-Control: X]` to tool descriptions
+ * 2. **Causal invalidation** — After successful mutations, signal which domains are stale
+ *
+ * @example
+ * ```typescript
+ * // Read tools: mark as volatile
+ * { match: 'sprints.get', cacheControl: 'no-store' }
+ *
+ * // Write tools: mark volatile + declare causal invalidations
+ * { match: 'sprints.update', invalidates: ['sprints.*'] }
+ *
+ * // Reference data: safe to cache forever
+ * { match: 'countries.*', cacheControl: 'immutable' }
+ * ```
+ */
+export interface SyncPolicy {
+    /**
+     * Glob pattern to match tool names.
+     *
+     * Uses dot-separated segments with wildcard support:
+     * - `*` matches exactly one segment
+     * - `**` matches zero or more segments
+     *
+     * @example `'sprints.*'`, `'tasks.update'`, `'**'`
+     */
+    readonly match: string;
+    /** Cache directive to apply to matching tools' descriptions. */
+    readonly cacheControl?: CacheDirective;
+    /**
+     * Glob patterns of tools whose cached data is invalidated on success.
+     *
+     * Only triggers when the tool call succeeds (`isError !== true`).
+     * The LLM receives: `[System: Cache invalidated for X — caused by Y]`
+     *
+     * @example `['sprints.*', 'tasks.*']`
+     */
+    readonly invalidates?: readonly string[];
+}
+/**
+ * State Sync configuration.
+ *
+ * Policies are evaluated in declaration order (first match wins).
+ * Defaults apply when no policy matches a tool.
+ *
+ * @example
+ * ```typescript
+ * const stateSync: StateSyncConfig = {
+ *     defaults: { cacheControl: 'no-store' },
+ *     policies: [
+ *         { match: 'sprints.update', invalidates: ['sprints.*'] },
+ *         { match: 'tasks.update',   invalidates: ['tasks.*', 'sprints.*'] },
+ *         { match: 'countries.*',    cacheControl: 'immutable' },
+ *     ],
+ * };
+ *
+ * registry.attachToServer(server, { stateSync });
+ * ```
+ */
+export interface StateSyncConfig {
+    /** Policy rules, evaluated in declaration order (first match wins). */
+    readonly policies: readonly SyncPolicy[];
+    /** Defaults applied when no policy matches a tool. */
+    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.
+ *
+ * Produced by the PolicyEngine after first-match-wins resolution.
+ * Consumed by the description and response decorators.
+ *
+ * @internal
+ */
+export interface ResolvedPolicy {
+    readonly cacheControl?: CacheDirective;
+    readonly invalidates?: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +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;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/dist/state-sync/types.js

@@ -0,0 +1,17 @@
+/**
+ * State Sync — Type Definitions
+ *
+ * Binary cache vocabulary for LLM temporal awareness.
+ * Uses RFC 7234 semantics deeply embedded in LLM pre-training data.
+ *
+ * There is no `max-age`. LLMs have no clock — time-based expiration
+ * is meaningless inside a context window.
+ *
+ * @see {@link StateSyncConfig} for the public configuration interface
+ * @see {@link https://arxiv.org/abs/2510.23853 | "Your LLM Agents are Temporally Blind"}
+ * @see {@link https://www.preprints.org/manuscript/202601.0910 | "State Drift in Language-Conditioned Autonomous Agents"}
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/state-sync/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/testing/MvaMetaSymbol.d.ts

@@ -0,0 +1,45 @@
+/**
+ * MVA Meta Symbol — In-Memory Backdoor for the Testing Package
+ *
+ * A global Symbol attached to every `ToolResponse` produced by
+ * `ResponseBuilder.build()`. Carries the structured MVA layers
+ * (data, systemRules, uiBlocks) as live JS objects.
+ *
+ * **Invisible to the MCP protocol**: `Symbol` keys are ignored by
+ * `JSON.stringify`, so the transport layer never sees this property.
+ * But the VurbTester reads it in RAM for zero-regex assertion.
+ *
+ * @example
+ * ```typescript
+ * import { MVA_META_SYMBOL, type MvaMeta } from 'vurb';
+ *
+ * const response = await registry.routeCall(ctx, 'users', { action: 'list' });
+ * const meta = (response as any)[MVA_META_SYMBOL] as MvaMeta | undefined;
+ * if (meta) {
+ *     console.log(meta.data);        // Validated object (post-Zod)
+ *     console.log(meta.systemRules); // ['Rule 1', 'Rule 2']
+ *     console.log(meta.uiBlocks);    // [{ type: 'echarts', content: '...' }]
+ * }
+ * ```
+ *
+ * @module
+ */
+/**
+ * Global Symbol for attaching MVA metadata to ToolResponse objects.
+ *
+ * Uses `Symbol.for()` to ensure cross-package identity — the testing
+ * package references the same Symbol without importing the core.
+ */
+export declare const MVA_META_SYMBOL: unique symbol;
+/**
+ * Structured MVA metadata attached to ToolResponse via Symbol.
+ */
+export interface MvaMeta {
+    /** Validated data after Egress Firewall (Presenter Zod schema) */
+    readonly data: unknown;
+    /** JIT system rules from Presenter */
+    readonly systemRules: readonly string[];
+    /** SSR UI blocks (echarts, markdown, summary) */
+    readonly uiBlocks: readonly unknown[];
+}
+//# sourceMappingURL=MvaMetaSymbol.d.ts.map

package/dist/testing/MvaMetaSymbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MvaMetaSymbol.d.ts","sourceRoot":"","sources":["../../src/testing/MvaMetaSymbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,eAA8B,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,OAAO;IACpB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACzC"}

package/dist/testing/MvaMetaSymbol.js

@@ -0,0 +1,34 @@
+/**
+ * MVA Meta Symbol — In-Memory Backdoor for the Testing Package
+ *
+ * A global Symbol attached to every `ToolResponse` produced by
+ * `ResponseBuilder.build()`. Carries the structured MVA layers
+ * (data, systemRules, uiBlocks) as live JS objects.
+ *
+ * **Invisible to the MCP protocol**: `Symbol` keys are ignored by
+ * `JSON.stringify`, so the transport layer never sees this property.
+ * But the VurbTester reads it in RAM for zero-regex assertion.
+ *
+ * @example
+ * ```typescript
+ * import { MVA_META_SYMBOL, type MvaMeta } from 'vurb';
+ *
+ * const response = await registry.routeCall(ctx, 'users', { action: 'list' });
+ * const meta = (response as any)[MVA_META_SYMBOL] as MvaMeta | undefined;
+ * if (meta) {
+ *     console.log(meta.data);        // Validated object (post-Zod)
+ *     console.log(meta.systemRules); // ['Rule 1', 'Rule 2']
+ *     console.log(meta.uiBlocks);    // [{ type: 'echarts', content: '...' }]
+ * }
+ * ```
+ *
+ * @module
+ */
+/**
+ * Global Symbol for attaching MVA metadata to ToolResponse objects.
+ *
+ * Uses `Symbol.for()` to ensure cross-package identity — the testing
+ * package references the same Symbol without importing the core.
+ */
+export const MVA_META_SYMBOL = Symbol.for('vurb.mva-meta');
+//# sourceMappingURL=MvaMetaSymbol.js.map

package/dist/testing/MvaMetaSymbol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MvaMetaSymbol.js","sourceRoot":"","sources":["../../src/testing/MvaMetaSymbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,153 @@
+{
+    "name": "@vurb/core",
+    "version": "3.2.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",
+    "types": "dist/index.d.ts",
+    "bin": {
+        "vurb": "./dist/cli/vurb.js"
+    },
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./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"
+        },
+        "./introspection": {
+            "import": "./dist/introspection/index.js",
+            "types": "./dist/introspection/index.d.ts"
+        },
+        "./sandbox": {
+            "import": "./dist/sandbox/index.js",
+            "types": "./dist/sandbox/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "rimraf dist && tsc",
+        "lint": "eslint src/",
+        "lint:fix": "eslint src/ --fix",
+        "test": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "ai",
+        "llm",
+        "tools",
+        "typescript",
+        "framework",
+        "middleware",
+        "zod",
+        "mva",
+        "model-view-agent",
+        "presenter",
+        "guardrails",
+        "agentic",
+        "structured-data",
+        "action-consolidation",
+        "dlp",
+        "compliance",
+        "pii-redaction",
+        "fsm",
+        "state-machine",
+        "anti-hallucination"
+    ],
+    "author": "Renato Marinho",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/vinkius-labs/vurb.ts.git",
+        "directory": "packages/core"
+    },
+    "bugs": {
+        "url": "https://github.com/vinkius-labs/vurb.ts/issues"
+    },
+    "homepage": "https://vurb.vinkius.com/",
+    "files": [
+        "dist",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@toon-format/toon": "^2.1.0",
+        "zod-to-json-schema": "^3.25.1"
+    },
+    "peerDependencies": {
+        "@modelcontextprotocol/sdk": "^1.12.1",
+        "esbuild": "^0.24.0",
+        "fast-json-stringify": "^6.0.0",
+        "fast-redact": "^3.0.0",
+        "isolated-vm": "^5.0.4",
+        "xstate": "^5.0.0",
+        "zod": "^3.25.1 || ^4.0.0"
+    },
+    "peerDependenciesMeta": {
+        "zod": {
+            "optional": true
+        },
+        "isolated-vm": {
+            "optional": true
+        },
+        "esbuild": {
+            "optional": true
+        },
+        "fast-json-stringify": {
+            "optional": true
+        },
+        "fast-redact": {
+            "optional": true
+        },
+        "xstate": {
+            "optional": true
+        }
+    },
+    "license": "Apache-2.0",
+    "devDependencies": {
+        "fast-redact": "^3.5.0",
+        "rimraf": "^6.0.0"
+    }
+}