@vinkius-core/mcp-fusion 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.11.0] - 2026-02-23
+
+### 📄 Stateless Cursor Pagination for Prompts
+
+**MCP Fusion** now provides O(1) memory, cryptographic cursor-based pagination for `prompts/list`. Instead of loading thousands of prompts into memory or sending large payloads to MCP clients, the framework emits pages using an RFC-compliant cursor algorithm powered by the native Web Crypto API.
+
+### Added
+
+- **`PromptRegistry.configurePagination({ pageSize })`:** Enables stateless pagination. By default, pagination is disabled (all prompts returned).
+- **`CursorCodec` module:** Implements a robust encoded cursor utilizing native `globalThis.crypto.subtle`. Zero external crypto dependencies.
+- **Server integration:** Automatically extracts the `cursor` param from the `prompts/list` MCP request, decodes it, applies filters, and generates the `nextCursor` transparently.
+- **Tamper resistance:** Adulterated cursors fallback gracefully to the first page without crashing the server.
+- **Progress Notifications Integration:** Full E2E testing of `ProgressSink` mapping to `notifications/progress`. Generator handlers firing `yield progress()` map seamlessly without overhead.
+- **Cooperative Cancellation Integration:** Full E2E testing of `AbortSignal` interception causing runaway generators and chains to abort instantly.
+
+## [1.10.0] - 2026-02-23
+
+### Hydration Timeout Sandbox — Graceful Degradation for Prompt Hydration
+
+**MCP Fusion** now protects prompt handlers from slow/failing external data sources via the **Hydration Timeout Sandbox**. When a handler fetches data from Jira, Stripe, databases, or any external source and the call hangs, the framework enforces a strict deadline, unblocks the UI immediately, and returns a structured SYSTEM ALERT.
+
+### Added
+
+- **`HydrationSandbox` module** (`src/prompt/HydrationSandbox.ts`): Core timeout mechanism using `Promise.race`. Wraps handler execution with a strict deadline and catches both timeouts and handler errors, converting them to graceful `<hydration_alert>` XML-structured messages.
+- **`hydrationTimeout` config** on `definePrompt()`: Per-prompt deadline in milliseconds. Example: `definePrompt('briefing', { hydrationTimeout: 3000, handler: ... })`.
+- **`setDefaultHydrationTimeout(ms)`** on `PromptRegistry`: Global safety net for ALL prompts. Individual prompt timeouts override the registry default.
+- **Three-scenario coverage**: Handler completes → normal result. Handler exceeds deadline → TIMEOUT alert. Handler throws → ERROR alert. The UI ALWAYS unblocks.
+- **Timer cleanup**: `clearTimeout` via `finally` block — no resource leaks, no dangling timers keeping Node.js alive.
+- **Zero overhead**: When no timeout is configured, no timer is created, no `Promise.race` wrapping — the handler runs directly.
+- **Interceptor composition**: Prompt Interceptors still execute after a timeout, ensuring compliance headers and tenant context are always injected.
+- **`getHydrationTimeout()`** on `PromptBuilder` interface: Read the configured timeout for introspection and testing.
+- **17 new tests**: Unit tests covering timeout, early completion, error-as-degradation, timer cleanup, non-Error throws, plus integration tests for per-prompt config, registry defaults, override precedence, backward compatibility, and interceptor composition after timeout.
+
+### Design Influences
+
+- Go's `context.WithDeadline` (structured cancellation)
+- gRPC deadline propagation (strict, per-RPC)
+- Resilience4j TimeLimiter (JVM circuit breaker pattern)
+
 ## [1.9.0] - 2026-02-23
 
 ### Intent Mutex (Anti-Race Condition)

package/README.md

@@ -1,40 +1,49 @@
 <div align="center">
-  <h1>⚡️ **MCP Fusion**</h1>
-  <p><b>The MVA (Model-View-Agent) framework for the Model Context Protocol.</b></p>
-  <p>Structured perception for AI agents — validated data, domain rules, UI blocks, and action affordances in every response.</p>
-  
+  <h1>⚡️ MCP Fusion</h1>
+  <p>MVA (Model-View-Agent) framework for the Model Context Protocol.</p>
+
   [![npm version](https://img.shields.io/npm/v/@vinkius-core/mcp-fusion.svg?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@vinkius-core/mcp-fusion)
   [![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
   [![MCP SDK](https://img.shields.io/badge/MCP-Standard-purple.svg?style=flat-square)](https://modelcontextprotocol.io/)
   [![License](https://img.shields.io/badge/License-Apache_2.0-green.svg?style=flat-square)](LICENSE)
 </div>
 
-<br/>
-
-**[Documentation](https://vinkius-labs.github.io/mcp-fusion/)** · **[API Reference](https://vinkius-labs.github.io/mcp-fusion/api-reference)** · **[Examples](https://vinkius-labs.github.io/mcp-fusion/examples)**
-
-```bash
-npm install @vinkius-core/mcp-fusion zod
-```
+<p align="center">
+  <a href="https://vinkius-labs.github.io/mcp-fusion/">Documentation</a> · 
+  <a href="https://vinkius-labs.github.io/mcp-fusion/quickstart">Quickstart</a> ·
+  <a href="https://vinkius-labs.github.io/mcp-fusion/api-reference">API Reference</a> ·
+  <a href="https://vinkius-labs.github.io/mcp-fusion/examples">Examples</a> ·
+  <a href="https://vinkius-labs.github.io/mcp-fusion/cost-and-hallucination">Why MCP Fusion</a>
+</p>
 
 ---
 
 ## Overview
 
-**MCP Fusion** introduces the **MVA (Model-View-Agent)** pattern — a Presenter layer between your data and the AI agent. Instead of passing raw JSON through `JSON.stringify()`, every response is a **structured perception package**: validated data, domain rules, rendered charts, action affordances, and cognitive guardrails.
+**MCP Fusion** adds an MVA Presenter layer between your data and the AI agent. The Presenter validates data through a Zod schema, strips undeclared fields, attaches just-in-time domain rules, renders UI blocks server-side, and suggests next actions — all before the response reaches the network.
 
 ```text
 Model (Zod Schema) → View (Presenter) → Agent (LLM)
    validates            perceives          acts
 ```
 
-The Presenter is defined once per domain entity. Every tool that returns that entity uses the same Presenter. The agent receives consistent, validated, contextually-rich data across your entire API surface.
+The Presenter is domain-level, not tool-level. Define `InvoicePresenter` once — every tool that returns invoices uses it. Same validation, same rules, same UI, same affordances.
 
----
+## Installation
+
+```bash
+npm install @vinkius-core/mcp-fusion zod
+```
+
+**MCP Fusion** has a required peer dependency on `@modelcontextprotocol/sdk` and `zod`:
+
+```bash
+npm install @modelcontextprotocol/sdk @vinkius-core/mcp-fusion zod
+```
 
-## Presenter
+## Quick Start
 
-The View layer in MVA. Defines how an entity is perceived by the agent — schema validation, system rules, UI blocks, cognitive guardrails, and action affordances.
+### 1. Define a Presenter
 
 ```typescript
 import { createPresenter, ui } from '@vinkius-core/mcp-fusion';
@@ -46,12 +55,7 @@ export const InvoicePresenter = createPresenter('Invoice')
         amount_cents: z.number(),
         status: z.enum(['paid', 'pending', 'overdue']),
     }))
-    .systemRules((invoice, ctx) => [
-        'CRITICAL: amount_cents is in CENTS. Divide by 100 before display.',
-        ctx?.user?.role !== 'admin'
-            ? 'RESTRICTED: Do not reveal exact totals to non-admin users.'
-            : null,
-    ])
+    .systemRules(['CRITICAL: amount_cents is in CENTS. Divide by 100 before display.'])
     .uiBlocks((invoice) => [
         ui.echarts({
             series: [{ type: 'gauge', data: [{ value: invoice.amount_cents / 100 }] }],
@@ -67,32 +71,7 @@ export const InvoicePresenter = createPresenter('Invoice')
     );
 ```
 
-The agent receives:
-
-```text
-📄 DATA       → Validated through Zod .strict() — undeclared fields rejected
-📋 RULES      → "amount_cents is in CENTS. Divide by 100."
-📊 UI BLOCKS  → ECharts gauge rendered server-side
-⚠️ GUARDRAIL  → "50 shown, 250 hidden. Use filters."
-🔗 AFFORDANCE → "→ billing.pay: Process payment"
-```
-
-Presenters compose via `.embed()` — child Presenter rules, UI blocks, and suggestions merge automatically:
-
-```typescript
-const InvoicePresenter = createPresenter('Invoice')
-    .schema(invoiceSchema)
-    .embed('client', ClientPresenter)
-    .embed('payment_method', PaymentMethodPresenter);
-```
-
----
-
-## Tool Definition
-
-Two APIs, identical output. `defineTool()` uses JSON shorthand (no Zod imports). `createTool()` uses full Zod schemas.
-
-### `defineTool()` — JSON-First
+### 2. Define a Tool
 
 ```typescript
 import { defineTool } from '@vinkius-core/mcp-fusion';
@@ -129,39 +108,56 @@ const billing = defineTool<AppContext>('billing', {
 });
 ```
 
-### `createTool()` — Full Zod
+### 3. Attach to Server
 
 ```typescript
-import { createTool } from '@vinkius-core/mcp-fusion';
-
-const billing = createTool<AppContext>('billing')
-    .description('Billing operations')
-    .commonSchema(z.object({ workspace_id: z.string() }))
-    .action({
-        name: 'get_invoice',
-        readOnly: true,
-        returns: InvoicePresenter,
-        schema: z.object({ id: z.string() }),
-        handler: async (ctx, args) =>
-            await ctx.db.invoices.findUnique({ where: { id: args.id } }),
-    });
-```
+import { ToolRegistry } from '@vinkius-core/mcp-fusion';
 
-### Action Consolidation
+const tools = new ToolRegistry<AppContext>();
+tools.register(billing);
+
+tools.attachToServer(server, {
+    contextFactory: (extra) => createAppContext(extra),
+});
+```
 
-Multiple actions register as a single MCP tool with a discriminator field. The agent sees one well-structured tool instead of 50 individual registrations:
+The handler returns raw data. The framework does the rest:
 
 ```text
-billing — Billing operations
-  Action: get_invoice | create_invoice | void_invoice
-  - 'get_invoice': Requires: workspace_id, id. READ-ONLY
-  - 'create_invoice': Requires: workspace_id, client_id, amount, currency
-  - 'void_invoice': Requires: workspace_id, id ⚠️ DESTRUCTIVE
+📄 DATA       → Zod-validated. Undeclared fields stripped.
+📋 RULES      → "amount_cents is in CENTS. Divide by 100."
+📊 UI         → ECharts gauge config — server-rendered, deterministic.
+⚠️ GUARDRAIL  → "50 shown, 250 hidden. Use filters."
+🔗 AFFORDANCE → "→ billing.pay: Process payment"
 ```
 
-### Hierarchical Groups
+## Features
+
+### Presenter — MVA View Layer
 
-For large APIs (5,000+ operations), nest actions into groups:
+Domain-level perception layer with schema validation, JIT system rules, server-rendered UI blocks, cognitive guardrails, action affordances, and relational composition via `.embed()`.
+
+```typescript
+const InvoicePresenter = createPresenter('Invoice')
+    .schema(invoiceSchema)
+    .systemRules((invoice, ctx) => [
+        'CRITICAL: amount_cents is in CENTS.',
+        ctx?.user?.role !== 'admin' ? 'Mask exact totals.' : null,
+    ])
+    .uiBlocks((inv) => [ui.echarts(chartConfig)])
+    .agentLimit(50, (omitted) => ui.summary(`50 shown, ${omitted} hidden.`))
+    .suggestActions((inv) => inv.status === 'pending'
+        ? [{ tool: 'billing.pay', reason: 'Process payment' }]
+        : []
+    )
+    .embed('client', ClientPresenter);
+```
+
+→ [Presenter docs](https://vinkius-labs.github.io/mcp-fusion/presenter) · [Anatomy](https://vinkius-labs.github.io/mcp-fusion/mva/presenter-anatomy) · [Context Tree-Shaking](https://vinkius-labs.github.io/mcp-fusion/mva/context-tree-shaking)
+
+### Action Consolidation & Hierarchical Groups
+
+50 actions → 5 tools. A discriminator enum routes to the correct action. Groups nest arbitrarily with `.group()`.
 
 ```typescript
 createTool<AppContext>('platform')
@@ -176,26 +172,18 @@ createTool<AppContext>('platform')
 // Discriminator values: users.list | users.ban | billing.refund
 ```
 
----
+→ [Building Tools](https://vinkius-labs.github.io/mcp-fusion/building-tools) · [Routing](https://vinkius-labs.github.io/mcp-fusion/routing) · [Tool Exposition](https://vinkius-labs.github.io/mcp-fusion/tool-exposition)
 
-## Prompt Engine
+### Prompt Engine
 
-Full MCP `prompts/list` + `prompts/get` implementation. Prompt arguments are **flat primitives only** (string, number, boolean, enum) — MCP clients render them as forms.
+Full MCP `prompts/list` + `prompts/get` with `PromptMessage.fromView()` — decomposes a Presenter view into XML-tagged prompt messages. Same source of truth as tool responses, zero duplication.
 
 ```typescript
-import { definePrompt, PromptMessage } from '@vinkius-core/mcp-fusion';
-
 const AuditPrompt = definePrompt<AppContext>('financial_audit', {
-    title: 'Financial Audit',
-    description: 'Run a compliance audit on an invoice.',
-    args: {
-        invoiceId: 'string',
-        depth: { enum: ['quick', 'thorough'] as const },
-    } as const,
+    args: { invoiceId: 'string', depth: { enum: ['quick', 'thorough'] as const } } as const,
     middleware: [requireAuth, requireRole('auditor')],
     handler: async (ctx, { invoiceId, depth }) => {
         const invoice = await ctx.db.invoices.get(invoiceId);
-
         return {
             messages: [
                 PromptMessage.system('You are a Senior Financial Auditor.'),
@@ -207,50 +195,27 @@ const AuditPrompt = definePrompt<AppContext>('financial_audit', {
 });
 ```
 
-### `PromptMessage.fromView()`
-
-Decomposes a `ResponseBuilder` (from `Presenter.make()`) into XML-tagged prompt messages. Rules, data, UI blocks, and action suggestions from the Presenter are extracted into semantically separated blocks — same source of truth as the Tool response, zero duplication:
-
-```text
-Presenter.make(data, ctx) → ResponseBuilder
-    │
-    ├─ <domain_rules>    → system role  │ Presenter's systemRules()
-    ├─ <dataset>         → user role    │ Validated JSON
-    ├─ <visual_context>  → user role    │ UI blocks (ECharts, Mermaid, tables)
-    └─ <system_guidance> → system role  │ Hints + HATEOAS action suggestions
-```
-
----
+→ [Prompt Engine docs](https://vinkius-labs.github.io/mcp-fusion/prompts)
 
-## Middleware
+### Middleware
 
 tRPC-style context derivation with pre-compiled chains:
 
 ```typescript
-import { defineMiddleware } from '@vinkius-core/mcp-fusion';
-
 const requireAuth = defineMiddleware(async (ctx: { token: string }) => {
     const user = await db.getUser(ctx.token);
     if (!user) throw new Error('Unauthorized');
-    return { user };  // ← merged into ctx, TS infers { user: User }
-});
-
-// Apply globally or per-action
-defineTool<AppContext>('projects', {
-    middleware: [requireAuth, requireRole('editor')],
-    actions: { ... },
+    return { user };  // merged into ctx, TS infers { user: User }
 });
 ```
 
----
+→ [Middleware docs](https://vinkius-labs.github.io/mcp-fusion/middleware)
 
-## Error Handling
+### Self-Healing Errors
 
-Structured errors with recovery instructions. The agent receives the error code, a suggestion, and a list of valid actions to try:
+Structured errors with recovery instructions and suggested actions:
 
 ```typescript
-import { toolError } from '@vinkius-core/mcp-fusion';
-
 return toolError('ProjectNotFound', {
     message: `Project '${id}' does not exist.`,
     suggestion: 'Call projects.list first to get valid IDs.',
@@ -258,19 +223,13 @@ return toolError('ProjectNotFound', {
 });
 ```
 
-```xml
-<tool_error code="ProjectNotFound">
-<message>Project 'xyz' does not exist.</message>
-<recovery>Call projects.list first to get valid IDs.</recovery>
-<available_actions>projects.list</available_actions>
-</tool_error>
-```
+Zod `.strict()` on all input schemas — hallucinated parameters rejected with per-field correction prompts.
 
----
+→ [Error Handling docs](https://vinkius-labs.github.io/mcp-fusion/error-handling) · [Cognitive Guardrails](https://vinkius-labs.github.io/mcp-fusion/mva/cognitive-guardrails)
 
-## Type-Safe Client
+### Type-Safe Client
 
-End-to-end type inference from server to client — autocomplete for action names and typed arguments:
+End-to-end type inference from server to client:
 
 ```typescript
 import { createFusionClient } from '@vinkius-core/mcp-fusion/client';
@@ -278,31 +237,17 @@ import type { AppRouter } from './server';
 
 const client = createFusionClient<AppRouter>(transport);
 const result = await client.execute('billing.get_invoice', { workspace_id: 'ws_1', id: 'inv_42' });
-//                                   ^^^^^^^^^^^^^^^^^^^^    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-//                                   autocomplete            typed args
 ```
 
----
-
-## Registry & Server Integration
-
-```typescript
-import { ToolRegistry, PromptRegistry } from '@vinkius-core/mcp-fusion';
+→ [FusionClient docs](https://vinkius-labs.github.io/mcp-fusion/fusion-client)
 
-const tools = new ToolRegistry<AppContext>();
-tools.register(billing);
-tools.register(projects);
+### State Sync
 
-const prompts = new PromptRegistry<AppContext>();
-prompts.register(AuditPrompt);
-prompts.register(SummarizePrompt);
+RFC 7234-inspired cache-control signals. Causal invalidation after mutations:
 
-// Attach to MCP server (works with Server and McpServer — duck-typed)
+```typescript
 tools.attachToServer(server, {
-    contextFactory: (extra) => createAppContext(extra),
-    filter: { tags: ['public'] },              // Tag-based context gating
-    toolExposition: 'flat',                     // 'flat' or 'grouped' wire format
-    stateSync: {                                // RFC 7234-inspired cache signals
+    stateSync: {
         defaults: { cacheControl: 'no-store' },
         policies: [
             { match: 'sprints.update', invalidates: ['sprints.*'] },
@@ -310,96 +255,83 @@ tools.attachToServer(server, {
         ],
     },
 });
-
-prompts.attachToServer(server, {
-    contextFactory: (extra) => createAppContext(extra),
-});
 ```
 
----
+→ [State Sync docs](https://vinkius-labs.github.io/mcp-fusion/state-sync)
 
-## Streaming Progress
+### Observability & Tracing
 
-Generator handlers yield progress events — automatically forwarded as MCP `notifications/progress` when the client provides a `progressToken`:
+Zero-overhead typed event system. OpenTelemetry-compatible tracing with structural subtyping:
 
 ```typescript
-handler: async function* (ctx, args) {
-    yield progress(10, 'Cloning repository...');
-    yield progress(50, 'Building AST...');
-    yield progress(90, 'Running analysis...');
-    return success(analysisResult);
-}
+billing.debug(createDebugObserver());
+tools.enableDebug(createDebugObserver((event) => opentelemetry.addEvent(event.type, event)));
+tools.enableTracing(tracer);
 ```
 
----
+→ [Observability](https://vinkius-labs.github.io/mcp-fusion/observability) · [Tracing](https://vinkius-labs.github.io/mcp-fusion/tracing)
 
-## Observability
+### Runtime Guards
 
-Zero-overhead typed event system. Debug observers attach per-tool or globally:
+Concurrency bulkhead, timeout enforcement, and circuit breakers per-tool:
 
-```typescript
-import { createDebugObserver } from '@vinkius-core/mcp-fusion';
+→ [Runtime Guards docs](https://vinkius-labs.github.io/mcp-fusion/runtime-guards)
 
-// Per-tool
-billing.debug(createDebugObserver());
-
-// Global — propagates to all registered tools
-tools.enableDebug(createDebugObserver((event) => {
-    opentelemetry.addEvent(event.type, event);
-}));
-```
+### Streaming Progress
 
-OpenTelemetry-compatible tracing with structural subtyping (no `@opentelemetry/api` dependency required):
+Generator handlers yield progress events — automatically forwarded as MCP `notifications/progress`:
 
 ```typescript
-tools.enableTracing(tracer);
-// Spans: mcp.tool, mcp.action, mcp.durationMs, mcp.isError, mcp.tags
+handler: async function* (ctx, args) {
+    yield progress(10, 'Cloning repository...');
+    yield progress(50, 'Building AST...');
+    yield progress(90, 'Running analysis...');
+    return success(analysisResult);
+}
 ```
 
----
-
-## Capability Matrix
+## All Capabilities
 
 | Capability | Mechanism |
 |---|---|
-| **Presenter** | Domain-level View layer — `.schema()`, `.systemRules()`, `.uiBlocks()`, `.suggestActions()`, `.embed()` |
-| **Cognitive Guardrails** | `.agentLimit(max, onTruncate)` — truncates arrays, injects filter guidance |
+| **Presenter** | `.schema()`, `.systemRules()`, `.uiBlocks()`, `.suggestActions()`, `.embed()` |
+| **Cognitive Guardrails** | `.agentLimit(max, onTruncate)` — truncation + filter guidance |
 | **Action Consolidation** | Multiple actions → single MCP tool with discriminator enum |
 | **Hierarchical Groups** | `.group()` — namespace 5,000+ actions as `module.action` |
-| **Prompt Engine** | `definePrompt()` with flat schema constraint, middleware, lifecycle sync |
-| **MVA-Driven Prompts** | `PromptMessage.fromView()` — Presenter → XML-tagged prompt messages |
+| **Prompt Engine** | `definePrompt()` with flat schema, middleware, `PromptMessage.fromView()` |
 | **Context Derivation** | `defineMiddleware()` — tRPC-style typed context merging |
 | **Self-Healing Errors** | `toolError()` — structured recovery with action suggestions |
+| **Strict Validation** | Zod `.merge().strict()` — unknown fields rejected with actionable errors |
 | **Type-Safe Client** | `createFusionClient<T>()` — full inference from server to client |
 | **Streaming Progress** | `yield progress()` → MCP `notifications/progress` |
-| **State Sync** | RFC 7234 cache-control signals — `invalidates`, `no-store`, `immutable` |
-| **Tool Exposition** | `'flat'` or `'grouped'` wire format — same handlers, different topology |
+| **State Sync** | RFC 7234 cache-control — `invalidates`, `no-store`, `immutable` |
+| **Tool Exposition** | `'flat'` or `'grouped'` wire format |
 | **Tag Filtering** | RBAC context gating — `{ tags: ['core'] }` / `{ exclude: ['internal'] }` |
 | **Observability** | Zero-overhead debug observers + OpenTelemetry-compatible tracing |
+| **Runtime Guards** | Concurrency bulkhead, timeout enforcement, circuit breakers |
 | **TOON Encoding** | Token-Optimized Object Notation — ~40% fewer tokens |
-| **Validation** | Zod `.merge().strict()` — unknown fields rejected with actionable errors |
 | **Introspection** | Runtime metadata via `fusion://manifest.json` MCP resource |
-| **Immutability** | `Object.freeze()` after `buildToolDefinition()` — no post-registration mutation |
-
----
+| **Immutability** | `Object.freeze()` after `buildToolDefinition()` |
 
 ## Documentation
 
+Full documentation available at **[vinkius-labs.github.io/mcp-fusion](https://vinkius-labs.github.io/mcp-fusion/)**.
+
 | Guide | |
 |---|---|
-| **[MVA Architecture](https://vinkius-labs.github.io/mcp-fusion/mva-pattern)** | The MVA pattern — why and how |
-| **[Quickstart](https://vinkius-labs.github.io/mcp-fusion/quickstart)** | Build a Fusion server from zero |
-| **[Presenter](https://vinkius-labs.github.io/mcp-fusion/presenter)** | Schema, rules, UI blocks, affordances, composition |
-| **[Prompt Engine](https://vinkius-labs.github.io/mcp-fusion/prompts)** | `definePrompt()`, `PromptMessage.fromView()`, registry |
-| **[Middleware](https://vinkius-labs.github.io/mcp-fusion/middleware)** | Context derivation, authentication, chains |
-| **[State Sync](https://vinkius-labs.github.io/mcp-fusion/state-sync)** | Cache-control signals, causal invalidation |
-| **[Observability](https://vinkius-labs.github.io/mcp-fusion/observability)** | Debug observers, tracing |
-| **[Tool Exposition](https://vinkius-labs.github.io/mcp-fusion/tool-exposition)** | Flat vs grouped wire strategies |
-| **[Cookbook](https://vinkius-labs.github.io/mcp-fusion/examples)** | Real-world patterns |
-| **[API Reference](https://vinkius-labs.github.io/mcp-fusion/api-reference)** | Complete typings |
-| **[Cost & Hallucination](https://vinkius-labs.github.io/mcp-fusion/cost-and-hallucination)** | Token reduction analysis |
-
----
+| [MVA Architecture](https://vinkius-labs.github.io/mcp-fusion/mva-pattern) | The MVA pattern and manifesto |
+| [Quickstart](https://vinkius-labs.github.io/mcp-fusion/quickstart) | Build a Fusion server from zero |
+| [Presenter](https://vinkius-labs.github.io/mcp-fusion/presenter) | Schema, rules, UI blocks, affordances, composition |
+| [Prompt Engine](https://vinkius-labs.github.io/mcp-fusion/prompts) | `definePrompt()`, `PromptMessage.fromView()`, registry |
+| [Context Tree-Shaking](https://vinkius-labs.github.io/mcp-fusion/mva/context-tree-shaking) | JIT rules vs global system prompts |
+| [Cognitive Guardrails](https://vinkius-labs.github.io/mcp-fusion/mva/cognitive-guardrails) | Truncation, strict validation, self-healing |
+| [Cost & Hallucination](https://vinkius-labs.github.io/mcp-fusion/cost-and-hallucination) | Token reduction analysis |
+| [Middleware](https://vinkius-labs.github.io/mcp-fusion/middleware) | Context derivation, authentication |
+| [State Sync](https://vinkius-labs.github.io/mcp-fusion/state-sync) | Cache-control signals, causal invalidation |
+| [Runtime Guards](https://vinkius-labs.github.io/mcp-fusion/runtime-guards) | Concurrency, timeouts, circuit breakers |
+| [Observability](https://vinkius-labs.github.io/mcp-fusion/observability) | Debug observers, tracing |
+| [Cookbook](https://vinkius-labs.github.io/mcp-fusion/examples) | Real-world patterns |
+| [API Reference](https://vinkius-labs.github.io/mcp-fusion/api-reference) | Complete typings |
 
 ## Requirements
 

package/dist/prompt/CursorCodec.d.ts

@@ -0,0 +1,40 @@
+export interface CursorPayload {
+    after: string;
+}
+export type CursorMode = 'signed' | 'encrypted';
+export interface CursorCodecOptions {
+    /**
+     * 'signed' (default): HMAC signature appended to base64 payload. Payload is visible but tamper-proof.
+     * 'encrypted': AES-GCM encryption. Payload is completely hidden and tamper-proof.
+     */
+    mode?: CursorMode;
+    /**
+     * Optional 32-byte secret key.
+     * If not provided, a random ephemeral key is generated per process.
+     */
+    secret?: string;
+}
+/**
+ * Stateless Cryptographic Cursor for pagination using Web Crypto API.
+ *
+ * Works in Node >= 18, Deno, Bun, and Cloudflare Workers.
+ */
+export declare class CursorCodec {
+    private readonly _mode;
+    private readonly _secretBytes;
+    private _hmacKey?;
+    private _aesKey?;
+    constructor(options?: CursorCodecOptions);
+    private getHmacKey;
+    private getAesKey;
+    /**
+     * Asynchronously encodes a payload into a URL-safe cursor string.
+     */
+    encode(payload: CursorPayload): Promise<string>;
+    /**
+     * Asynchronously decodes and verifies a cursor string back into its payload.
+     * Returns undefined if the cursor is invalid, tampered with, or from a different process/key.
+     */
+    decode(cursor: string): Promise<CursorPayload | undefined>;
+}
+//# sourceMappingURL=CursorCodec.d.ts.map

package/dist/prompt/CursorCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CursorCodec.d.ts","sourceRoot":"","sources":["../../src/prompt/CursorCodec.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAwBD;;;;GAIG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,CAAY;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAY;gBAEhB,OAAO,CAAC,EAAE,kBAAkB;YAe1B,UAAU;YAaV,SAAS;IAavB;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BrD;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;CAmDnE"}