theokit 0.4.0-beta.0 → 0.5.0

package/dist/server/index.d.ts

@@ -1,969 +1,38 @@
-import { z } from 'zod';
-import { A as AgentEvent, a as AgentErrorEvent } from '../agent-events-B3KNV9ER.js';
-export { b as AgentMessageEvent, e as AgentRunErrorCode, c as AgentToolCallEvent, d as AgentToolResultEvent } from '../agent-events-B3KNV9ER.js';
-import { IncomingMessage, ServerResponse } from 'node:http';
-import { J as JobBackend } from '../index-li83Swxa.js';
-export { D as DuplicateContextKeyError, a as DuplicateJobNameError, E as EnqueueOptions, I as InMemoryJobBackend, b as InMemoryJobBackendOptions, c as JOB_MANIFEST_SCHEMA_VERSION, d as JobContext, e as JobDefinition, f as JobEnqueueInput, g as JobLease, h as JobManifest, i as JobManifestEntry, j as JobNode, k as JobOptions, l as JobRegistry, m as JobRunner, N as NonRetryableError, O as Outbox, n as OutboxFlushOptions, P as PostgresFactory, o as PostgresJobBackend, p as PostgresJobBackendOptions, Q as QueueClient, R as RedisFactory, S as StorageManager, _ as __resetSingletonForTests, q as buildJobManifest, r as createJobRunner, s as createOutbox, t as createOutboxDispatcher, u as createQueueClient, v as defineJob, w as getStorageManager, x as scanJobs, y as writeJobManifest } from '../index-li83Swxa.js';
-import { ViteDevServer } from 'vite';
-export { AuthRequiredError, BackupCode, BackupCodeOptions, OidcMetadata, PkceChallenge, SessionConfig, SessionManager, SessionMeta, ThrottleOptions, ThrottleState, TotpAlgorithm, TotpOptions, TotpUriOptions, VerifyTotpOptions, _resetKeyCacheForTests, assertProductionSecret, checkThrottle, clearOidcCache, createSessionManager, decrypt, discoverOidcProvider, encrypt, generateBackupCodes, generateNonce, generateOAuthState, generatePkceChallenge, generateTotp, generateTotpSecret, pkceChallengeFromVerifier, recordAttempt, requireAuth, rotateIfNeeded, totpUri, verifyBackupCode, verifyOAuthState, verifyTotp } from './auth/index.js';
+import { RouteConfig } from './define/index.js';
+export { ActionAccept, ActionConfig, AgentEndpointConfig, AgentEndpointHandlerArgs, ChannelHandler, CustomTool, DefineAgentToolSpec, MiddlewareHandler, WebChannelHandler, defineAction, defineAgentEndpoint, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel } from './define/index.js';
+export { W as WebSocketHandler, a as WebSocketHandlerWeb, b as WebSocketLike, d as defineWebSocket, c as defineWebSocketWeb } from '../define-websocket-CdK94O-D.js';
+export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoTransformer, _ as _resetMiddlewareCacheForTests, r as appendCookieToHeaders, s as appendDeleteCookieToHeaders, t as createCorsHandler, u as createCorsWebHandler, v as deleteCookie, w as executeAction, x as executeRoute, y as extractTraceId, z as extractTraceIdFromRequest, A as getCookie, D as getCookieFromRequest, F as handleBatchRequest, G as jsonTransformer, I as loadCustomErrorPages, J as matchesOrigin, K as parseCookieHeader, L as parseTraceparent, N as resolveTransformer, O as runMiddlewareAndContext, P as sendError, Q as sendJson, R as serializeCookie, U as serveStaticFile, V as setCookie, W as superjsonTransformer } from '../index-DWWEdFh5.js';
+export { ActionNode, ActionScanError, LoadedManifest, ManifestAction, ManifestRoute, ManifestWebSocket, TheoManifest, WebSocketRouteNode, generateManifest, loadManifest, scanMiddlewares, scanServerActions, scanServerActionsEnriched, scanServerRoutes, scanWebSocketRoutes, writeManifest } from './scan/index.js';
+export { L as LoadModule, S as ServerRouteNode, c as compilePattern, a as createProductionLoader, b as createViteLoader, m as matchRoute } from '../module-loader-Cfz7dgCP.js';
+import { T as TheoErrorEnvelope, a as TheoErrorCode, V as ValidationFieldsExt } from '../error-envelope-BsNzzAV5.js';
+export { AgentRunLike, AgentRunResult, AgentRunStreamMessage, ConversationHistoryArgs, ConversationHistoryResult, ConversationStorageLike, SdkAgent, SdkAgentOptions, SdkRunLike, createConversationHistory, errorToEvent, streamAgentRun } from './agent/index.js';
+export { a as AgentErrorEvent, A as AgentEvent, b as AgentMessageEvent, e as AgentRunErrorCode, c as AgentToolCallEvent, d as AgentToolResultEvent } from '../agent-events-B3KNV9ER.js';
+export { AuthRequiredError, BackupCode, BackupCodeOptions, OidcMetadata, PkceChallenge, SessionConfig, SessionManager, SessionManagerWeb, SessionMeta, ThrottleOptions, ThrottleState, TotpAlgorithm, TotpOptions, TotpUriOptions, VerifyTotpOptions, _resetKeyCacheForTests, assertProductionSecret, checkThrottle, clearOidcCache, createSessionManager, createSessionManagerWeb, decrypt, discoverOidcProvider, encrypt, generateBackupCodes, generateNonce, generateOAuthState, generatePkceChallenge, generateTotp, generateTotpSecret, pkceChallengeFromVerifier, recordAttempt, requireAuth, rotateIfNeeded, rotateIfNeededWeb, totpUri, verifyBackupCode, verifyOAuthState, verifyTotp } from './auth/index.js';
 export { InMemoryUsageStorage, ToolHookEvent, ToolUsageRecord, TrackAgentRunInput, TrackAgentRunOptions, TrackAgentToolsHooks, TrackAgentToolsOptions, UsageQuery, UsageRecord, UsageResult, UsageStorageAdapter, trackAgentRun, trackAgentTools } from './cost/index.js';
 export { CRON_MANIFEST_SCHEMA_VERSION, CronConcurrencyPolicy, CronContext, CronDefinition, CronManifest, CronManifestEntry, CronNode, CronOptions, CronScheduler, DuplicateCronNameError, ExistingConfigUnparseableError, buildCronManifest, convertToAwsCron, createCronScheduler, defineCron, scanCrons, translateCronToAws, translateCronToCloudflare, translateCronToDeno, translateCronToVercel, validateCronSchedule, writeCronManifest } from './cron/index.js';
-import { R as RateLimitConfig, a as RateLimitResult, C as CsrfReadinessStore } from '../schema-CjVly9c_.js';
-export { b as CsrfReadinessRouteSummary, c as CsrfReadinessSummary, d as CsrfWarnRecord, e as ServiceDefinition, S as ServicesConfig, f as ServicesConfigInput, g as ServicesConfigOutput, h as createRateLimiter } from '../schema-CjVly9c_.js';
-import { R as RateLimitStore } from '../rate-limit-store-BEJnhWdw.js';
-export { I as InMemoryStore, a as RateLimitState } from '../rate-limit-store-BEJnhWdw.js';
-export { G as GenericFactory, P as PoolLike, a as PostgresDatabaseConfig, R as RedisLike, b as RedisServerConfig, S as ServerConfig, c as StorageAdapter, d as StorageConfig, T as TlsConfig } from '../storage-types-DtIVejC1.js';
-
-/**
- * core/contracts/route-config.ts
- *
- * Canonical home for `RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>` —
- * the contract shape consumed by `defineRoute()` (server) and
- * `defineCachedRoute()` (cache).
- *
- * Moved here in T2.2 of architecture-cleanup so `cache → core/contracts`
- * is the legal edge (replacing the prior `cache → server` violation).
- *
- * GAP-4 (plan v1.1): the 5-arity generic shape `<TQuery, TBody, TParams, TCtx, TResponse>`
- * MUST be preserved byte-by-byte. Type tests assert this in
- * `tests/unit/route-config-generic-arity.test.ts`.
- */
-
-interface RouteConfig<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown> {
-    query?: TQuery;
-    body?: TBody;
-    params?: TParams;
-    status?: number;
-    /**
-     * Opt out of CSRF enforcement for this route. Use for endpoints that
-     * legitimately receive third-party POSTs (Stripe webhooks, GitHub
-     * webhooks, OAuth callbacks). Defaults to enforced per `config.security.csrf`.
-     *
-     * Setting `csrf: false` only disables the per-route check — it does NOT
-     * disable the global mode setting for other routes.
-     */
-    csrf?: false;
-    handler: (ctx: {
-        query: z.infer<TQuery>;
-        body: z.infer<TBody>;
-        params: z.infer<TParams>;
-        request: Request;
-        ctx: TCtx;
-    }) => TResponse | Promise<TResponse>;
-}
-
-/**
- * Define a typed HTTP route.
- * Identity function — provides type inference for route handlers.
- */
-declare function defineRoute<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown>(config: RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>): RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>;
-
-/**
- * Action wire-protocol accept mode per plan g3-server-actions-and-useaction
- * v1.2 ADR D1. Default behavior (when omitted) is `'json'`. `'form'` opts the
- * action into FormData multipart parsing for progressive-enhancement forms;
- * the runtime in `server/http/action-execute.ts` will coerce FormData entries
- * against the `input` schema via `formDataToObject` (Astro pattern).
- */
-type ActionAccept = 'form' | 'json';
-interface ActionConfig<TInput extends z.ZodType, TCtx = unknown> {
-    /**
-     * Zod input schema. Required: every action declares its input contract via
-     * Zod (architecture rule: zod-is-SSOT). The shape becomes the handler's
-     * typed `input` parameter via `z.infer<TInput>`.
-     */
-    input: TInput;
-    /**
-     * Wire-protocol accept mode. Defaults to `'json'` when omitted. Setting
-     * `'form'` switches the runtime to FormData multipart parsing — the input
-     * schema MUST be `z.object(...)` so field-by-field coercion can drive
-     * boolean string / number / array coercion (Astro pattern).
-     */
-    accept?: ActionAccept;
-    handler: (ctx: {
-        input: z.infer<TInput>;
-        ctx: TCtx;
-    }) => unknown;
-}
-/**
- * Define a typed server action.
- *
- * Identity function — provides type inference for action handlers. The
- * runtime that consumes the config (validation + invocation + serialization)
- * lives in `server/http/action-execute.ts`.
- *
- * Per plan g3-server-actions-and-useaction v1.2 § Phase 1 / T1.2: the new
- * `accept?: 'form' | 'json'` field is the only contract change vs the
- * pre-G3 identity. Existing callsites (`defineAction({input, handler})`)
- * continue to compile — `accept` is opt-in.
- */
-declare function defineAction<TInput extends z.ZodType, TCtx = unknown>(config: ActionConfig<TInput, TCtx>): ActionConfig<TInput, TCtx>;
-
-type MiddlewareHandler = (request: Request, next: (request: Request) => Promise<Response>) => Response | Promise<Response>;
-/**
- * Define a middleware handler.
- * Identity function — provides type annotation for middleware.
- */
-declare function defineMiddleware(handler: MiddlewareHandler): MiddlewareHandler;
-
-/**
- * T5.1 — defineAgentEndpoint
- *
- * Sugar over defineRoute (ADR D4). Accepts an async generator that yields
- * AgentEvents and produces a RouteConfig whose handler returns a Response
- * streaming Server-Sent Events (SSE).
- *
- * Wire format: `data: <JSON>\n\n` per event. Standards-compliant.
- *
- * The generator may throw — the wrapper catches and emits a final
- * `{ type: 'error', message }` event before closing the stream.
- *
- * The wrapper observes `request.signal` (EC-7) — when aborted, the
- * underlying generator is told to `return()` and the stream closes
- * promptly.
- *
- * Note (EC-12, Out of Scope): SSE backpressure (slow consumer) is not
- * handled here. For high-frequency token streaming consider a different
- * transport (WS) or a buffer policy. This MVP enqueues each event
- * immediately.
- */
-interface AgentEndpointHandlerArgs<TCtx = unknown, TBody = unknown> {
-    query: undefined;
-    body: TBody;
-    params: undefined;
-    request: Request;
-    ctx: TCtx;
-    /**
-     * Mutable headers bag that the wrapper merges into the SSE response BEFORE
-     * the stream starts. Used by `createConversationHistory` to issue a
-     * conversation-id cookie on first request. Append entries via
-     * `cookieHeaders.append('set-cookie', '<cookie-string>')`.
-     *
-     * Cookies appended AFTER the first yield are NOT applied — the response
-     * headers commit when the wrapper constructs the Response, before the
-     * async generator runs. This is per HTTP semantics, not a wrapper choice.
-     */
-    cookieHeaders: Headers;
-    /**
-     * Phase 3 (Production-Readiness #5) — request abort signal.
-     *
-     * Fires when the SSE client disconnects (browser closes tab, abort fetch,
-     * etc.). Thread this to `agent.send(msg, { signal })` so the SDK cancels
-     * the in-flight provider call — STOPS TOKENS FROM CHARGING for output
-     * the user will never receive.
-     *
-     * EC-1 (MUST FIX): the signal is derived via duck-type detection
-     * (`'aborted' in r.signal && typeof r.signal.addEventListener === 'function'`)
-     * to survive cross-realm scenarios (Node 18 polyfills, undici, Edge
-     * runtimes with their own AbortSignal globals). `instanceof AbortSignal`
-     * would fail in those cases.
-     */
-    signal: AbortSignal;
-}
-interface AgentEndpointConfig<TCtx = unknown, TBody = unknown> {
-    handler: (args: AgentEndpointHandlerArgs<TCtx, TBody>) => AsyncGenerator<AgentEvent, void, unknown>;
-}
-declare function defineAgentEndpoint<TBody = unknown, TCtx = unknown>(config: AgentEndpointConfig<TCtx, TBody>): RouteConfig<z.ZodUndefined, z.ZodUndefined, z.ZodUndefined, TCtx, Response>;
-
-/**
- * Item #4 — `defineAgentTool`
- *
- * Sugar over the `@theokit/sdk` `CustomTool` contract. Takes a Zod 3 schema +
- * handler and produces a structurally-compatible `CustomTool` that
- * `Agent.create({ tools: [...] })` accepts.
- *
- * Why not delegate to SDK's `defineTool`?
- *   SDK's `defineTool` calls `z.toJSONSchema(...)` which only exists on Zod 4
- *   (at root) or `zod/v4` (Zod 3.25+ subpath). TheoKit pins Zod 3 framework-
- *   wide. Bumping to Zod 4 is a major breaking change touching every primitive
- *   — out of scope for this item. Instead, we convert the Zod schema to JSON
- *   Schema 7 with `zod-to-json-schema` (Zod 3 native, MIT, zero transitive
- *   deps, 3M weekly DLs) and build the `CustomTool` object directly. See ADR
- *   D1 in `docs/plans/item-4-define-agent-tool-plan.md`.
- *
- * Handler error propagation:
- *   `defineAgentTool` parses the input via the Zod schema BEFORE calling the
- *   user handler. Invalid input throws a `ZodError`, which the SDK's tool-
- *   dispatcher (or the `streamAgentRun` adapter) sees as a tool failure and
- *   surfaces as an `error` AgentEvent on the SSE wire (ADR D3).
- */
-/**
- * Local mirror of the SDK's `CustomTool` interface. We don't `import type`
- * from `@theokit/sdk` because the SDK is an optional peer (consumers who
- * never call `defineAgentTool` shouldn't need it installed). The shape is
- * the wire contract; any structurally-matching object is accepted by
- * `Agent.create({ tools })`.
- *
- * @public
- */
-interface CustomTool {
-    name: string;
-    description: string;
-    inputSchema: Record<string, unknown>;
-    handler: (input: Record<string, unknown>) => string | Promise<string>;
-}
-/**
- * Spec accepted by {@link defineAgentTool}. `inputSchema` is a Zod 3 schema
- * rooted in `z.object(...)`. The `handler` argument type is inferred via
- * `z.infer<T>`.
- *
- * @public
- */
-interface DefineAgentToolSpec<T extends z.ZodType> {
-    /** Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`. */
-    name: string;
-    /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */
-    description: string;
-    /** Zod schema describing the input. Must be `z.object(...)` at the root. */
-    inputSchema: T;
-    /** Handler invoked with the parsed input. */
-    handler: (input: z.infer<T>) => string | Promise<string>;
-}
-/**
- * Build a {@link CustomTool} from a Zod 3 schema + handler.
- *
- * Behavior:
- * - Validates `name` matches the LLM tool-name regex.
- * - Requires `inputSchema` to be a `ZodObject` (Anthropic + SDK contract).
- * - Warns (not throws) if `description` is empty — empty descriptions
- *   degrade LLM tool selection.
- * - Converts the Zod schema to JSON Schema 7 inline (no `$ref`s — LLMs handle
- *   inline schemas more reliably).
- * - Strips the top-level `$schema` field (Anthropic rejects schemas with
- *   `$schema` at root in some provider modes).
- * - Wraps the handler to parse the input via the Zod schema BEFORE invoking
- *   the user code — bad LLM-supplied input throws `ZodError`, which the SDK
- *   converts to `tool_result(isError)`.
- *
- * @public
- */
-declare function defineAgentTool<T extends z.ZodType>(spec: DefineAgentToolSpec<T>): CustomTool;
-
-interface WebSocketLike {
-    send(data: string | Buffer): void;
-    close(code?: number, reason?: string): void;
-}
-interface WebSocketHandler {
-    onOpen?: (ws: WebSocketLike, req: IncomingMessage) => void;
-    onMessage?: (ws: WebSocketLike, data: string | Buffer) => void;
-    onClose?: (ws: WebSocketLike, code: number, reason: Buffer) => void;
-    onError?: (ws: WebSocketLike, error: Error) => void;
-}
-/**
- * Define a WebSocket endpoint handler.
- * Identity function — provides type inference for WebSocket handlers.
- */
-declare function defineWebSocket(handler: WebSocketHandler): WebSocketHandler;
-
-interface ChannelHandler<TMessage = unknown> {
-    onSubscribe?: (ws: WebSocketLike, room: string, req: IncomingMessage) => void;
-    onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void;
-    onUnsubscribe?: (ws: WebSocketLike, room: string) => void;
-}
-/**
- * Define a channel handler for WebSocket rooms.
- * Identity function — provides type inference for channel handlers.
- */
-declare function defineChannel<TMessage = unknown>(handler: ChannelHandler<TMessage>): ChannelHandler<TMessage>;
-
-interface PluginContext {
-    request: IncomingMessage;
-    response: ServerResponse;
-    ctx: Record<string, unknown>;
-    requestId: string;
-}
-interface PluginErrorContext extends PluginContext {
-    error: unknown;
-}
-interface RunHookOptions {
-    inErrorPath?: boolean;
-}
-interface HookResult {
-    shortCircuited: boolean;
-}
-type OnRequestHook = (ctx: PluginContext) => void | Promise<void>;
-type PreHandlerHook = (ctx: PluginContext) => void | Promise<void>;
-type OnResponseHook = (ctx: PluginContext) => void | Promise<void>;
-type OnErrorHook = (ctx: PluginErrorContext) => void | Promise<void>;
-type HookName = 'onRequest' | 'preHandler' | 'onResponse' | 'onError';
-type HookByName<K extends HookName> = K extends 'onError' ? OnErrorHook : K extends 'onRequest' ? OnRequestHook : K extends 'preHandler' ? PreHandlerHook : K extends 'onResponse' ? OnResponseHook : never;
-interface TheoApp {
-    addHook<K extends HookName>(name: K, fn: HookByName<K>): void;
-    decorateRequest<T>(key: string, value: T): void;
-}
-interface TheoPlugin {
-    name: string;
-    register(app: TheoApp): void | Promise<void>;
-}
-/**
- * Identity function for plugin authors. Provides auto-completion + type
- * inference at the call site (TanStack/Vite/Astro pattern). Pure runtime
- * no-op — returns the input unchanged.
- *
- * @example
- *   import { definePlugin } from 'theokit/server'
- *   export default definePlugin({
- *     name: 'my-plugin',
- *     register(app) {
- *       app.addHook('onRequest', (req) => { ... })
- *     },
- *   })
- *
- * Equivalent to `const p: TheoPlugin = {...}` but more ergonomic. See
- * ADR-0008 (D1 + D6) for the rationale.
- */
-declare function definePlugin(plugin: TheoPlugin): TheoPlugin;
-
-/**
- * Identity function for defining a Theo plugin.
- *
- * **Note:** Prefer `definePlugin` (shorter, canonical name per ADR-0008 D6).
- * Both functions are identical — `defineTheoPlugin` is kept as an alias for
- * existing in-tree consumers without forcing a migration sweep.
- */
-declare function defineTheoPlugin(plugin: TheoPlugin): TheoPlugin;
-
-declare class DuplicatePluginError extends Error {
-    constructor(name: string);
-}
-declare class DuplicateDecorationError extends Error {
-    constructor(key: string, existingPlugin: string, newPlugin: string);
-}
-declare class PluginRunner {
-    private plugins;
-    private onRequestHooks;
-    private preHandlerHooks;
-    private onResponseHooks;
-    private onErrorHooks;
-    private decorations;
-    has(name: string): boolean;
-    register(plugin: TheoPlugin): Promise<void>;
-    applyDecorations(ctx: Record<string, unknown>): void;
-    runOnRequest(ctx: PluginContext): Promise<HookResult>;
-    runPreHandler(ctx: PluginContext): Promise<HookResult>;
-    runOnResponse(ctx: PluginContext, options?: RunHookOptions): Promise<HookResult>;
-    /**
-     * Run all onError hooks. Swallows errors thrown inside hooks themselves to
-     * prevent recursion (an error in an error handler must not trigger onError
-     * again).
-     */
-    runOnError(ctx: PluginContext, error: unknown): Promise<HookResult>;
-    private runHookList;
-}
-
-interface ServerRouteNode {
-    filePath: string;
-    routePath: string;
-    paramNames: string[];
-    pattern: RegExp;
-    /** HTTP methods (uppercase) the route file exports. Optional for backward
-     * compatibility with manifests generated before G1. Empty array means the
-     * file has no HTTP exports (util-only); undefined means "not detected". */
-    methods?: string[];
-}
-declare function compilePattern(routePath: string): {
-    pattern: RegExp;
-    paramNames: string[];
-};
-declare function matchRoute(url: string, routes: ServerRouteNode[]): {
-    route: ServerRouteNode;
-    params: Record<string, string>;
-} | null;
-
-type LoadModule = (path: string) => Promise<Record<string, unknown>>;
-declare function createViteLoader(vite: ViteDevServer): LoadModule;
-declare function createProductionLoader(): LoadModule;
-
-/**
- * T4.1 — Audit logging interface + default JSON stdout sink.
- *
- * Per ADR D4: define the interface; ship a zero-dep default; reserve
- * adapter shapes for Postgres, File, OpenTelemetry, Sentry as follow-up
- * packages. Persistence has heavy deps (`pg`, `better-sqlite3`); we
- * keep core dep-free and let users opt in.
- *
- * Compatibility:
- *   - Node / Bun / Deno / Vercel — console.log is sync, captured.
- *   - Edge runtimes (CF Workers, Vercel Edge) — console.log is captured
- *     but may be rate-limited by the platform. For high-volume edge audit,
- *     implement a custom sink writing to a queue / HTTP endpoint.
- */
-interface AuditEvent {
-    /** Domain-qualified verb. Convention: `<domain>.<verb>` (e.g. csrf.warn, session.rotated). */
-    action: string;
-    /** Who triggered the event. Anonymous = no auth at time of event. */
-    actor?: {
-        type: 'user' | 'system' | 'anonymous';
-        id?: string;
-    };
-    /** What was operated on (optional). */
-    resource?: {
-        type: string;
-        id?: string;
-    };
-    /** Arbitrary event-specific metadata. JSON-serializable. */
-    metadata?: Record<string, unknown>;
-    /** ISO 8601 timestamp. If absent, sink fills in `new Date().toISOString()`. */
-    timestamp?: string;
-    /** Optional trace id (populated by middleware from `x-trace-id`). */
-    traceId?: string;
-}
-interface AuditLogger {
-    log(event: AuditEvent): void | Promise<void>;
-}
-/**
- * Default sink: one JSON line per event to stdout. Sync. Never throws.
- *
- * EC: circular refs / BigInt values fall back to a placeholder line so
- * the event is still observable (action + traceId) without crashing the
- * request lifecycle.
- */
-declare class JsonStdoutSink implements AuditLogger {
-    log(event: AuditEvent): void;
-}
-/**
- * No-op logger. Returned when `config.audit` is unset. Zero overhead;
- * framework wiring sites null-check before calling.
- */
-declare function createNoOpLogger(): AuditLogger;
-/**
- * T4.2 — Safe-emit wrapper. Used by framework wiring sites (csrf.ts,
- * rate-limit.ts, session.ts) so a logger throw NEVER propagates into
- * the request handler.
- */
-declare function safeAudit(logger: AuditLogger | undefined, event: AuditEvent): void;
-
-/**
- * CSRF enforcement mode.
- *
- * - `off`     — skip CSRF entirely. Use only when you have another defense
- *               (e.g. you don't ship session cookies, all auth is bearer).
- * - `warn`    — log a structured warning when the check would fail, but
- *               still serve the request. Default for 0.2.0. Migration mode.
- * - `strict`  — reject failing requests with 403 + code `CSRF_INVALID`.
- *               Will become the default in 0.3.0.
- */
-type CsrfMode = 'off' | 'warn' | 'strict';
-/**
- * Per-request structured logger surface. Only `warn` is used by enforceCsrf;
- * we don't require a full Logger here so callers can pass a mock or the
- * console directly.
- */
-interface CsrfLogger {
-    warn: (payload: CsrfWarnPayload) => void;
-    /** Optional path the request was destined for — used for log correlation. */
-    path?: string;
-}
-/**
- * T5.1 — Rails-inspired per-route escalation.
- *
- * `routes` accepts string (exact match) or RegExp entries. When a request
- * path matches AND the request would otherwise emit a warning, the
- * `behavior` field decides what happens:
- *
- *   - `'warn'`  → normal warn dispatch (no-op vs default)
- *   - `'raise'` → escalate to 403 regardless of global `csrf` mode
- *
- * `'raise'` never downgrades: when global mode is `'off'`, validation is
- * skipped entirely and disallowed dispatch never runs.
- */
-interface DisallowedConfig {
-    routes: (string | RegExp)[];
-    behavior: 'warn' | 'raise';
-}
-/**
- * Test whether `path` matches any of the supplied patterns. String
- * patterns are EXACT (trailing slash matters — use RegExp for tolerance).
- *
- * EC-5: when a RegExp carries the `/g` flag, `.test()` mutates
- * `lastIndex` and the next invocation may miss. We reset `lastIndex`
- * before each test so the matcher is a pure function.
- */
-declare function matchDisallowed(path: string, patterns: readonly (string | RegExp)[]): boolean;
-/**
- * T2.2 — Stable cutover identifier shipped with every csrf.warn payload.
- *
- * Convention borrowed from Vite's `deprecations.ts:74` — a `code` plus a
- * `docsUrl` lets users (a) grep their logs for a single stable identifier
- * to find every csrf.warn line, and (b) click through directly to the
- * migration guide. Strings are exported constants so the analyzer (T2.3)
- * and migration guide can reference the same source of truth.
- */
-declare const CSRF_WARN_CODE: "CSRF_STRICT_CUTOVER";
-declare const CSRF_WARN_DOCS_URL: "https://theokit.dev/upgrade/csrf-strict-cutover";
-interface CsrfWarnPayload {
-    event: 'csrf.warn';
-    method: string;
-    path: string | undefined;
-    reason: string;
-    /**
-     * Stable identifier for the 0.2 → 0.3 CSRF strict cutover. Always
-     * `'CSRF_STRICT_CUTOVER'`. Grep-able from prod logs.
-     */
-    code: string;
-    /**
-     * Link to the section of the migration guide explaining how to clear
-     * this specific warning class.
-     */
-    docsUrl: string;
-}
-declare function validateCsrf(req: IncomingMessage): {
-    valid: true;
-} | {
-    valid: false;
-    reason: string;
-};
-declare function enforceCsrf(req: IncomingMessage, mode: CsrfMode, logger?: CsrfLogger, disallowed?: DisallowedConfig, auditLogger?: AuditLogger): {
-    allow: boolean;
-    reason?: string;
-};
-
-/**
- * T5.2 — pluggable response/request transformer.
- *
- * `superjson` is the default, preserving Date/Map/Set/BigInt/etc.
- * `json` is the lightweight option (plain JSON.stringify/parse).
- * Users can supply a custom object implementing this contract.
- */
-interface TheoTransformer {
-    name: string;
-    serialize: (value: unknown) => string;
-    deserialize: (raw: string) => unknown;
-}
-declare const superjsonTransformer: TheoTransformer;
-declare const jsonTransformer: TheoTransformer;
-declare function resolveTransformer(selector: 'json' | 'superjson' | TheoTransformer): TheoTransformer;
-
-/**
- * server/http/execute-context.ts
- *
- * `ExecuteRouteContext` — the parameter object passed to `executeRoute()`
- * and `executeAction()` per ADR-0016 (T3.1 of architecture-cleanup).
- *
- * Replaces the 12-positional-param signature with a single named-field
- * object, eliminating 3 of 4 eslint-disable comments on `executeRoute`.
- *
- * Location: lives in `server/http/` (not `core/contracts/`) because the
- * shape references server-side types (CsrfMode, JobBackend, PluginRunner,
- * TheoTransformer, ServerRouteNode, LoadModule, DisallowedConfig). Keeping
- * the type here preserves the existing module direction graph — no new
- * `core → server` edges.
- *
- * Consumers within server/ build this object once per request; external
- * callers (router-runner) see the same shape via the `ExecuteRouteContext`
- * named export.
- */
-
-/**
- * The request-execution context. Each request builds one of these and passes
- * it to `executeRoute(ctx)`.
- *
- * All fields are required EXCEPT those with optional `?` markers; defaults
- * are applied inside `executeRoute` via destructure (e.g., `csrfMode = 'strict'`).
- */
-interface ExecuteRouteContext {
-    route: ServerRouteNode;
-    method: string;
-    params: Record<string, string>;
-    req: IncomingMessage;
-    res: ServerResponse;
-    loadModule: LoadModule;
-    serverDir?: string;
-    requestId?: string;
-    pluginRunner?: PluginRunner;
-    transformer?: TheoTransformer;
-    /** Defaults to `'strict'` when omitted. */
-    csrfMode?: CsrfMode;
-    disallowed?: DisallowedConfig;
-    /** When provided, `ctx.queue` auto-injects + outbox lifecycle hooks attach. */
-    jobBackend?: JobBackend;
-}
-
-/**
- * Canonical HTTP response helpers (T5.1 extraction).
- *
- * Moved out of execute.ts so request-pipeline stages (execute-stages.ts,
- * handle-request-error.ts, etc.) can depend on these helpers without
- * creating a cycle through execute.ts.
- *
- * Public surface re-exported from execute.ts for backward compat — every
- * existing caller of `sendError` / `sendJson` continues to work via the
- * `theokit/server` barrel.
- */
-declare function sendJson(res: ServerResponse, data: unknown, status?: number, transformer?: TheoTransformer): void;
-interface SendErrorOptions {
-    custom404Html?: string;
-    custom500Html?: string;
-}
-/**
- * Canonical error response.
- *
- * T6.3 (PV-17): the positional 7-param signature is preserved for backward
- * compat. New call sites should use the options-bag form:
- *
- *   sendError(res, { code, message, status, issues?, requestId?, options? })
- *
- * Both shapes resolve to the same implementation.
- */
-interface SendErrorInput {
-    code: string;
-    message: string;
-    status: number;
-    issues?: unknown[];
-    requestId?: string;
-    options?: SendErrorOptions;
-}
-declare function sendError(res: ServerResponse, input: SendErrorInput): void;
-declare function sendError(res: ServerResponse, code: string, message: string, status: number, issues?: unknown[], requestId?: string, options?: SendErrorOptions): void;
-
-declare function executeRoute(ctx: ExecuteRouteContext): Promise<void>;
-
-interface ExecuteActionOptions {
-    filePath: string;
-    exportName: string;
-    req: IncomingMessage;
-    res: ServerResponse;
-    loadModule: LoadModule;
-    serverDir?: string;
-    requestId?: string;
-    pluginRunner?: PluginRunner;
-    csrfMode?: CsrfMode;
-    disallowed?: DisallowedConfig;
-}
-declare function executeAction(filePath: string, exportName: string, req: IncomingMessage, res: ServerResponse, loadModule: LoadModule, serverDir?: string, requestId?: string, pluginRunner?: PluginRunner, csrfMode?: CsrfMode, disallowed?: DisallowedConfig): Promise<void>;
-
-interface MiddlewareResult {
-    ctx: unknown;
-    aborted: boolean;
-}
-declare function _resetMiddlewareCacheForTests(): void;
-declare function runMiddlewareAndContext(req: IncomingMessage, res: ServerResponse, loadModule: LoadModule, serverDir: string): Promise<MiddlewareResult>;
-
-/**
- * T1.2 — CORS middleware.
- *
- * Single global middleware that runs FIRST in the request pipeline:
- *   CORS preflight → rate limit → CSRF → security headers → handler
- *
- * Preflight (`OPTIONS` with `Access-Control-Request-Method`) is handled
- * by `handlePreflight`, which short-circuits the response with 204 +
- * Access-Control-* headers.
- *
- * Non-preflight requests pass through; `applyHeaders` adds
- * `Access-Control-Allow-Origin` (echoing the request's Origin),
- * `Access-Control-Expose-Headers`, and `Access-Control-Allow-Credentials`.
- *
- * Per ADR D3: preflight responses are deterministic and only the matched
- * origin is echoed back (never `'*'` when credentials are enabled —
- * required by the CORS spec).
- */
-type CorsOrigin = string | RegExp | readonly (string | RegExp)[] | ((origin: string) => boolean);
-interface CorsConfig {
-    origins: CorsOrigin;
-    methods?: readonly ('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD')[];
-    allowedHeaders?: readonly string[];
-    exposedHeaders?: readonly string[];
-    credentials?: boolean;
-    maxAge?: number;
-}
-interface CorsHandler {
-    handlePreflight(req: IncomingMessage, res: ServerResponse): boolean;
-    applyHeaders(req: IncomingMessage, res: ServerResponse): void;
-}
-/**
- * Test whether `origin` is allowed by `allowed`. Pure function — no I/O.
- *
- * EC-8: callback variants that throw are fail-closed (deny). Without
- * this, a transient datastore outage would silently widen CORS during
- * the failure window.
- */
-declare function matchesOrigin(origin: string, allowed: CorsOrigin): boolean;
-declare function createCorsHandler(config: CorsConfig): CorsHandler;
-
-interface CookieOptions {
-    httpOnly?: boolean;
-    secure?: boolean;
-    sameSite?: 'strict' | 'lax' | 'none';
-    maxAge?: number;
-    path?: string;
-    domain?: string;
-}
-/**
- * Parse a `Cookie` header into a Map (RFC 6265 §5.4).
- * - Empty/missing input → empty Map.
- * - Malformed entries (no `=`) skipped silently (defensive).
- * - Duplicate names → last-wins.
- * - Values URL-decoded if possible; raw on decode failure (CR-009 protection).
- *
- * Canonical helper (T3.2 of architecture-review-remediation-plan; PV-4 DRY).
- * Consumed by `getCookie` here AND by `rate-limit/rate-limit-per-route.ts`.
- */
-declare function parseCookieHeader(header: string | undefined): Map<string, string>;
-declare function getCookie(req: IncomingMessage, name: string): string | undefined;
-declare function setCookie(res: ServerResponse, name: string, value: string, options?: CookieOptions): void;
-declare function deleteCookie(res: ServerResponse, name: string, options?: {
-    path?: string;
-}): void;
-
-/**
- * T1.4 — Server-side batch handler.
- *
- * Receives `{ requests: [...] }` POSTed to `/api/__theo_batch__` and returns
- * `{ results: [...] }` with per-item error isolation. EC-2: items cannot
- * override auth/forwarded headers (would be a session-bypass vector).
- */
-
-declare const STRIPPED_HEADERS: readonly ["authorization", "cookie", "x-forwarded-for", "x-forwarded-host", "x-forwarded-proto", "x-real-ip", "host"];
-declare const BATCH_PATH = "/api/__theo_batch__";
-declare class BatchPathConflictError extends Error {
-    constructor(path: string);
-}
-declare const batchRequestSchema: z.ZodObject<{
-    path: z.ZodString;
-    method: z.ZodString;
-    query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    body: z.ZodOptional<z.ZodUnknown>;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    path: string;
-    method: string;
-    headers?: Record<string, string> | undefined;
-    query?: Record<string, unknown> | undefined;
-    body?: unknown;
-}, {
-    path: string;
-    method: string;
-    headers?: Record<string, string> | undefined;
-    query?: Record<string, unknown> | undefined;
-    body?: unknown;
-}>;
-declare const batchPayloadSchema: z.ZodObject<{
-    requests: z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
-        method: z.ZodString;
-        query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        body: z.ZodOptional<z.ZodUnknown>;
-        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    }, "strip", z.ZodTypeAny, {
-        path: string;
-        method: string;
-        headers?: Record<string, string> | undefined;
-        query?: Record<string, unknown> | undefined;
-        body?: unknown;
-    }, {
-        path: string;
-        method: string;
-        headers?: Record<string, string> | undefined;
-        query?: Record<string, unknown> | undefined;
-        body?: unknown;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    requests: {
-        path: string;
-        method: string;
-        headers?: Record<string, string> | undefined;
-        query?: Record<string, unknown> | undefined;
-        body?: unknown;
-    }[];
-}, {
-    requests: {
-        path: string;
-        method: string;
-        headers?: Record<string, string> | undefined;
-        query?: Record<string, unknown> | undefined;
-        body?: unknown;
-    }[];
-}>;
-type BatchRequestItem = z.infer<typeof batchRequestSchema>;
-type BatchPayload = z.infer<typeof batchPayloadSchema>;
-type BatchExecuteFn = (req: BatchRequestItem) => Promise<{
-    data: unknown;
-} | {
-    error: {
-        message: string;
-        code?: string;
-    };
-}>;
-interface HandleBatchOptions {
-    execute: BatchExecuteFn;
-    /** Max number of items per batch. Default 32. */
-    max?: number;
-    /** Outer-request headers that override per-item headers in STRIPPED_HEADERS. */
-    outerHeaders?: Record<string, string>;
-}
-type BatchResultItem = {
-    data: unknown;
-} | {
-    error: {
-        message: string;
-        code?: string;
-    };
-};
-interface BatchResponse {
-    results: BatchResultItem[];
-}
-/**
- * Validate + execute a batch request.
- *
- * CR-028 fix: previously the signature was `payload: BatchPayload`,
- * suggesting the caller had already validated. In reality `api-middleware`
- * passes `JSON.parse(rawBody) as BatchPayload` — an unsafe cast over raw
- * HTTP input. We widen the input type to `unknown` so the type system
- * forces validation, then run Zod once at this single trust boundary.
- */
-declare function handleBatchRequest(payload: unknown, options: HandleBatchOptions): Promise<BatchResponse>;
-
-/**
- * T2.4 — Custom error pages loader.
- *
- * Loads optional `.theo/client/404.html` and `500.html` from disk so adapters
- * (Node, CF, Vercel, Bun, Netlify, AWS Lambda, Deno) can pass them to the
- * shared `sendError` pipeline.
- *
- * EC-9: caps file size at 1MB. Files beyond the limit are skipped with a
- * console.warn and the default JSON error path is used.
- */
-declare const MAX_ERROR_HTML_BYTES = 1048576;
-interface CustomErrorPages {
-    custom404Html?: string;
-    custom500Html?: string;
-}
-/**
- * Load `.theo/client/{404,500}.html` from the given client directory.
- * Returns object with both fields when present; missing pages remain undefined.
- */
-declare function loadCustomErrorPages(clientDir: string): CustomErrorPages;
-
-declare function serveStaticFile(req: IncomingMessage, res: ServerResponse, clientDir: string): boolean;
-
-/**
- * Phase 7 — Observability: traceId propagation (D7).
- *
- * Extract a stable identifier from incoming requests so a single value
- * correlates the client request, every server log line, the response
- * envelope, and any downstream span. Precedence:
- *
- *   1. `traceparent` (W3C Trace Context — `00-{32-hex}-{16-hex}-{flags}`)
- *   2. `x-request-id` (Heroku / GCP / generic proxy header)
- *   3. Generated UUID (fresh per request)
- *
- * UUIDs are accepted as trace identifiers by every major vendor that
- * does not enforce strict 32-hex (Datadog, Honeycomb, Sentry, Logflare,
- * Axiom, etc). We don't need ULIDs to ship this surface.
- */
-declare const TRACE_HEADER = "x-trace-id";
-declare const TRACE_PARENT_HEADER = "traceparent";
-/**
- * Parse a W3C Trace Context `traceparent` header value. Returns the
- * 32-hex trace-id when valid (and not the reserved all-zeros), else
- * `null`.
- */
-declare function parseTraceparent(value: string): string | null;
-/**
- * Resolve the request's traceId following the precedence above.
- */
-declare function extractTraceId(req: IncomingMessage): string;
-
-declare function scanServerRoutes(serverDir: string): ServerRouteNode[];
-
-interface ActionNode {
-    filePath: string;
-    actionPath: string;
-}
-/**
- * Enriched manifest entry per plan g3-server-actions-and-useaction v1.2
- * § Phase 1 / T1.4 + ADR D4. Consumed by virtual module `@theo/actions`
- * (T3.1) and G4 devtools "Actions" tab (T5.1).
- */
-interface ActionManifestEntry$1 {
-    name: string;
-    filePath: string;
-    urlPath: string;
-    accept: 'form' | 'json';
-    hasInput: boolean;
-    /**
-     * P#4 plugin-forms shared-schema convention (per plan p4-plugin-forms v1.1 T1.1).
-     * When present, points to an isomorphic schema file at
-     * `<serverDir>/actions/schemas/<basename>.ts` exporting `export const schema = z.object(...)`.
-     * Virtual module emits `import {schema} from '<schemaFilePath>'` + attaches as
-     * `actions.X.__zodSchema` so client-side <TheoForm> can drive zodResolver.
-     * Undefined when convention not followed (graceful degrade — TheoForm still
-     * works via explicit `schema={...}` prop escape hatch).
-     */
-    schemaFilePath?: string;
-}
-/**
- * EC-2: structured error for scan-time defects (name collision, reserved
- * identifier, etc.). Throw at scan time to fail loud — silent shadowing is
- * a security/correctness footgun.
- */
-declare class ActionScanError extends Error {
-    readonly code: 'NAME_COLLISION' | 'RESERVED_NAME';
-    readonly conflictingPaths: readonly string[];
-    constructor(code: 'NAME_COLLISION' | 'RESERVED_NAME', message: string, conflictingPaths: readonly string[]);
-}
-/**
- * Backward-compatible: original simple-shape scanner used by existing
- * consumers. Preserved verbatim; new consumers should call
- * `scanServerActionsEnriched`.
- */
-declare function scanServerActions(serverDir: string): ActionNode[];
-/**
- * Enriched scan: light AST detection of `accept: 'form'|'json'` + `input:`
- * presence via regex-after-comment-stripping (EC-9). Throws ActionScanError
- * on file/dir name collision (EC-2) or reserved JS identifier names.
- *
- * Output `ActionManifestEntry[]` is sorted by `name` for deterministic
- * `.theo/actions-manifest.json` emission.
- */
-declare function scanServerActionsEnriched(serverDir: string): ActionManifestEntry$1[];
-
-interface WebSocketRouteNode {
-    filePath: string;
-    wsPath: string;
-}
-declare function scanWebSocketRoutes(serverDir: string): WebSocketRouteNode[];
-
-/**
- * Scan the server/middleware/ directory for middleware files.
- * Files are returned sorted alphabetically — use numeric prefixes
- * (e.g. 01-cors.ts, 02-auth.ts) to control execution order.
- *
- * Files starting with '_' or '.' are ignored (helpers, hidden files).
- */
-declare function scanMiddlewares(serverDir: string): string[];
-
-interface ManifestRoute {
-    filePath: string;
-    routePath: string;
-    paramNames: string[];
-    /** HTTP methods (uppercase) the route file exports. Optional — manifests
-     * generated before G1 omit this; loaders treat absence as "unknown". */
-    methods?: string[];
-}
-interface ManifestAction {
-    filePath: string;
-    actionPath: string;
-}
-interface ManifestWebSocket {
-    filePath: string;
-    wsPath: string;
-}
-interface TheoManifest {
-    version: 1;
-    generatedAt: string;
-    routes: ManifestRoute[];
-    actions: ManifestAction[];
-    websockets: ManifestWebSocket[];
-}
-interface LoadedManifest {
-    routes: ServerRouteNode[];
-    actions: ActionNode[];
-    websockets: WebSocketRouteNode[];
-}
-declare function generateManifest(serverDir: string): TheoManifest;
-declare function writeManifest(manifest: TheoManifest, outputDir: string): void;
-declare function loadManifest(distDir: string, serverDir: string): LoadedManifest;
+export { DuplicateContextKeyError, DuplicateJobNameError, EnqueueOptions, InMemoryJobBackend, InMemoryJobBackendOptions, JOB_MANIFEST_SCHEMA_VERSION, JobContext, JobDefinition, JobManifest, JobManifestEntry, JobNode, JobOptions, JobRegistry, JobRunner, Outbox, OutboxFlushOptions, PostgresJobBackend, PostgresJobBackendOptions, QueueClient, buildJobManifest, createJobRunner, createOutbox, createOutboxDispatcher, createQueueClient, defineJob, scanJobs, writeJobManifest } from './jobs/index.js';
+export { J as JobBackend, a as JobEnqueueInput, b as JobLease, N as NonRetryableError } from '../job-backend-CgC8Xf33.js';
+export { ConsoleObservabilityAdapter, LogLevel, LoggerFn, NoopObservabilityAdapter, NoopSpan, ObservabilityAdapter, RequestLog, SpanAttributes, SpanHandle, SpanImpl, StructuredLog, TheoCloudObservabilityAdapter, TheoLogger, _resetWarnOnceForTests, createLogger, createObservabilityPlugin, defineObservabilityAdapter, findSuggestion, levenshtein, logRequest, resolveAdapter, serializeSpansToOtlp, warnOnce } from './observability/index.js';
+export { a as AuditEvent, A as AuditLogger, J as JsonStdoutSink, c as createNoOpLogger, s as safeAudit } from '../audit-log-BQWM5YLG.js';
+export { D as DuplicateDecorationError, a as DuplicatePluginError, P as PluginRunner } from '../plugin-runner-BGBkzgi0.js';
+export { InvalidPluginShapeError, createPluginRunnerFromConfig } from './plugins/index.js';
+export { R as RateLimitConfig, a as RateLimitResult, c as createRateLimiter, b as createRateLimiterWeb } from '../rate-limit-BdNDZ3vt.js';
+export { I as InMemoryStore, a as RateLimitState, R as RateLimitStore } from '../rate-limit-store-BEJnhWdw.js';
+export { DeriveKeyRequestContext, KeyByMode, RouteRateLimitConfig, createRouteRateLimiter, createRouteRateLimiterWeb, deriveKey, deriveKeyFromRequest, matchRoutePattern } from './rate-limit/index.js';
+export { ChannelManager } from './realtime/index.js';
+export { CSP_REPORT_PATH, CSRF_READINESS_PATH, CSRF_READINESS_RESET_PATH, CspMode, CspReportHandlerOptions, CspViolation, DEFAULT_CSP, DEFAULT_PERMISSIONS_POLICY, SecurityEnv, SecurityHeadersConfig, SecurityHeadersOptions, applySecurityHeaders, buildSecurityHeaders, handleCspReport, handleCspReportRequest, handleCsrfReadiness, handleCsrfReadinessRequest, normalizeLegacy, normalizeNew } from './security/index.js';
+export { C as CSRF_WARN_CODE, a as CSRF_WARN_DOCS_URL, b as CsrfLogger, c as CsrfMode, d as CsrfWarnPayload, D as DisallowedConfig, e as enforceCsrf, m as matchDisallowed, v as validateCsrf, f as validateCsrfRequest } from '../csrf-BBrEZSBW.js';
+export { a as CsrfReadinessRouteSummary, C as CsrfReadinessStore, b as CsrfReadinessSummary, c as CsrfWarnRecord } from '../csrf-readiness-store-CjIoub3U.js';
+export { P as PostgresFactory, R as RedisFactory, S as StorageManager, g as getStorageManager } from '../storage-manager-C4jsO0Tp.js';
+export { Db0Database, UnstorageInstance, useDatabase, useUnstorage } from './storage/index.js';
+export { G as GenericFactory, a as PoolLike, P as PostgresDatabaseConfig, c as RedisLike, R as RedisServerConfig, S as ServerConfig, d as StorageAdapter, b as StorageConfig, T as TlsConfig } from '../storage-types-DsDTCPbp.js';
+export { BodyTooLargeError, DEFAULT_MAX_BODY_BYTES, DefineWebhookOptions, RawBodyResult, ReadRawBodyOptions, VerifyFn, VerifyResult, WebhookContext, WebhookDefinition, defineWebhook, dispatchWebhook, readRawBody, timingSafeEqual } from './webhook/index.js';
+import { z } from 'zod';
+import { IncomingMessage } from 'node:http';
+import { W as WebOnRequestHook, b as WebPreHandlerHook, c as WebOnResponseHook, d as WebOnErrorHook } from '../plugin-types-DNJGxr4Z.js';
+export { e as HookName, H as HookResult, O as OnErrorHook, f as OnRequestHook, g as OnResponseHook, P as PluginContext, h as PluginErrorContext, i as PreHandlerHook, R as RunHookOptions, a as TheoApp, T as TheoPlugin, j as definePlugin } from '../plugin-types-DNJGxr4Z.js';
+export { a as ServiceDefinition, S as ServicesConfig, b as ServicesConfigInput, c as ServicesConfigOutput } from '../schema-D3v8VB7o.js';
+import 'vite';
 
 /**
  * Action protocol — cross-boundary contract for `defineAction` + `useAction`.
@@ -984,6 +53,7 @@ declare function loadManifest(distDir: string, serverDir: string): LoadedManifes
  * (EC-7). Consumers needing bracket notation can write a small `dotToBracket`
  * helper in userland.
  */
+
 /**
  * HTTP-status mapping per IANA HTTP Status Code Registry (subset relevant to
  * action surface). VALIDATION_ERROR → 422 is preferred over Astro's BAD_REQUEST/400
@@ -1016,6 +86,20 @@ declare class ActionError extends Error {
         message?: string;
         stack?: string;
     });
+    /**
+     * G5 T2.4 — canonical envelope view of the action error. Maps the G3
+     * ActionErrorCode to a canonical TheoErrorCode (VALIDATION_ERROR ↔
+     * UNPROCESSABLE_ENTITY, CONTENT_TOO_LARGE ↔ PAYLOAD_TOO_LARGE) so consumer
+     * UI / SDK code can switch on the unified envelope.
+     *
+     * Subclasses override to populate `ext` (see `ActionInputError.envelope`).
+     */
+    get envelope(): TheoErrorEnvelope;
+    /**
+     * Translate G3 ActionErrorCode → canonical TheoErrorCode (blueprint
+     * Recommendations § "G3 ActionError becomes inaugural envelope user").
+     */
+    static toTheoErrorCode(code: ActionErrorCode): TheoErrorCode;
     static codeToStatus(code: ActionErrorCode): number;
     static statusToCode(status: number): ActionErrorCode;
     /**
@@ -1040,6 +124,12 @@ declare class ActionInputError extends ActionError {
     readonly issues: readonly UniversalZodIssue[];
     readonly fields: Record<string, string[]>;
     constructor(rawIssues: unknown);
+    /**
+     * G5 T2.4 — envelope view with ValidationFieldsExt populated from .fields.
+     * UI consumers can `switch (env.code)` on `UNPROCESSABLE_ENTITY` and read
+     * `(env.ext as ValidationFieldsExt).fields` for field-level rendering.
+     */
+    get envelope(): TheoErrorEnvelope<ValidationFieldsExt>;
 }
 /**
  * Normalize zod v3 (`z.ZodIssue`) and v4 (`$ZodIssue`) raw issues to
@@ -1107,721 +197,23 @@ interface ActionManifestEntry {
     readonly hasInput: boolean;
 }
 
-/**
- * Item #4 — `streamAgentRun`
- *
- * Adapter that consumes the `@theokit/sdk` `Run.stream()` async generator
- * (SDKMessage variants) and yields TheoKit `AgentEvent`s suitable for SSE
- * via `defineAgentEndpoint`. One line at the consumer side:
- *
- *   ```ts
- *   const run = await agent.send(message)
- *   yield* streamAgentRun(run)
- *   ```
- *
- * Mapping table (SDK → AgentEvent):
- *
- * | SDK message                          | AgentEvent yielded                     |
- * |---|---|
- * | assistant.content[].type==='text'    | { type: 'message', content }           |
- * | assistant.content[].type==='tool_use'| (none — covered by tool_call below)    |
- * | tool_call(status='running')          | { type: 'tool_call', name, args, id }  |
- * | tool_call(status='completed')        | { type: 'tool_result', name, data, id }|
- * | tool_call(status='error')            | { type: 'error', message, id }         |
- * | run.wait() status==='error'          | { type: 'error', message }             |
- * | run.wait() status==='cancelled'      | (none — cancel ≠ error)                |
- * | system / user / thinking / status /  | (none — internal SDK telemetry)        |
- * |   task / request / object_delta      |                                        |
- *
- * Abort semantics: when the consumer calls `generator.return()` on the
- * outer `defineAgentEndpoint` generator, `streamAgentRun` exits the
- * `for await` loop and does NOT call `run.wait()`. Cleanup of in-flight
- * SDK resources is the SDK consumer's responsibility (`run.cancel()`).
- */
-/**
- * Local mirror of the SDK's `Run` interface — only the surfaces we consume.
- * The message contract is minimal (just `{ type: string }`) so the SDK's
- * `SDKMessage` discriminated union IS structurally assignable without any
- * cast at the consumer site (covariant — TS accepts the SDK's typed message
- * as the wider `{ type: string }`). Property access inside `streamAgentRun`
- * narrows via runtime type guards.
- *
- * `import type` from `@theokit/sdk` would couple TheoKit to the SDK at type-
- * resolution time even for consumers who never use the agent surface.
- */
-interface AgentRunLike {
-    stream: () => AsyncIterable<{
-        type: string;
-    }>;
-    wait: () => Promise<AgentRunResult>;
-}
-/**
- * Re-exported as a convenience for test fixtures. Production code typically
- * passes an SDK `Run` directly (structural match via `{ type: string }`).
- */
-type AgentRunStreamMessage = {
-    type: 'assistant';
-    message: {
-        role: 'assistant';
-        content: {
-            type: string;
-            text?: string;
-        }[];
-    };
-} | {
-    type: 'tool_call';
-    name: string;
-    status: 'running' | 'completed' | 'error';
-    args?: unknown;
-    result?: unknown;
-    call_id: string;
-} | {
-    type: string;
-    [k: string]: unknown;
-};
-/** Subset of the SDK `RunResult` we consume. */
-interface AgentRunResult {
-    status: 'finished' | 'error' | 'cancelled';
-    error?: {
-        message: string;
-        code?: string;
-        cause?: unknown;
-    };
-}
-/**
- * Map an SDK error to the AgentErrorEvent shape. Pure function — easy to test.
- *
- * Backward compat (D4): non-AgentRunError throws yield only `message` field
- * (legacy shape); discriminated fields stay `undefined`.
- *
- * Return type is the specific `AgentErrorEvent` (not the union) for ergonomic
- * call-site access — `errorToEvent(err).code` works without narrowing.
- */
-declare function errorToEvent(err: unknown, id?: string): AgentErrorEvent;
-declare function streamAgentRun(run: AgentRunLike): AsyncGenerator<AgentEvent, void, unknown>;
-
-/**
- * Item #5 — `createConversationHistory`
- *
- * Orchestrator that resolves a stable `agentId` from (explicit → session →
- * cookie → fresh UUID), then returns an `@theokit/sdk` `Agent` via
- * `Agent.getOrCreate(agentId, options)`. Conversation turns auto-persist in
- * `<cwd>/.theokit/agents/<agentId>/messages.jsonl` — SDK owns the storage
- * (ADR D1). `MemorySettings` (facts recall layer) is opt-in passthrough via
- * `options.memory` (ADR D2).
- *
- * Security: agentId from cookie/explicit is attacker-controlled. The SDK
- * uses it as a filesystem path component AND we serialize it into Set-Cookie.
- * EC-1 enforces a strict regex `^[a-zA-Z0-9_-]{1,128}$` at every entry point;
- * invalid values fall through (treated as "missing") rather than throw.
- */
-/**
- * Minimum surface of an SDK Agent that consumers care about post-creation.
- * Structural match — any object with `send` + `dispose` of compatible
- * shape works. `send` returns a `SdkRunLike` (a Run-shaped object) that
- * `streamAgentRun` can consume. Permissive `unknown` for now; consumers
- * who want stricter types can cast to the SDK's own types.
- *
- * **T5.2 (architecture-cleanup) — DP-7 decision: KEEP (Opt B).** The 5 duck-typed
- * mirrors below were flagged as "over-engineered" by the 2026-05-27 architecture
- * review. Decision: KEEP them because `@theokit/sdk` is `devDependency` (not
- * required at runtime for consumers that don't use agent features). Removing
- * the mirrors would force a hard runtime dep on the SDK, breaking consumers
- * who build TheoKit apps without the agent layer.
- *
- * @kept Defensive duck-type. Do NOT replace with direct SDK type imports unless
- *   `@theokit/sdk` is promoted from devDependency to dependency. If promoting,
- *   ALSO drop the mirrors (Opt A from the architecture-cleanup plan T5.2).
- */
-interface SdkRunLike {
-    stream: () => AsyncIterable<{
-        type: string;
-    }>;
-    wait: () => Promise<{
-        status: 'finished' | 'error' | 'cancelled';
-        error?: {
-            message: string;
-        };
-    }>;
-}
-interface SdkAgent {
-    send: (message: string, options?: unknown) => Promise<SdkRunLike>;
-    dispose: () => Promise<void>;
-}
-/**
- * Phase 2 — structural duck-type of `@theokit/sdk`'s `ConversationStorageAdapter`.
- *
- * D2 (decoupling): we mirror the SDK's shape locally rather than hard-import
- * the SDK type. This lets consumers pass any object matching the structural
- * contract (own implementation, SDK's `FileSystemConversationStorage`,
- * `InMemoryConversationStorage`, or a Postgres/Redis recipe).
- *
- * EC-5 (SHOULD TEST — sync drift detection): the SDK type MUST be assignable
- * to this interface AND vice-versa. A contract test asserts both directions.
- *
- * `unknown` for the message payload avoids coupling to the SDK's `SDKMessage`
- * shape. Real consumers cast at the call site if they need stricter types.
- */
-interface ConversationStorageLike {
-    getMessages(conversationId: string): Promise<readonly unknown[]>;
-    appendMessage(conversationId: string, message: unknown): Promise<void>;
-    deleteConversation(conversationId: string): Promise<void>;
-    listConversationIds?(opts?: {
-        limit?: number;
-    }): Promise<readonly string[] | undefined>;
-    dispose?(): Promise<void>;
-}
-/**
- * Minimum surface of `AgentOptions` accepted by `Agent.getOrCreate`. Forward-
- * compatible: callers pass whatever the SDK supports (memory, tools, etc.).
- *
- * Phase 2 adds typed `conversationStorage` slot. The index signature still
- * passes everything else opaquely.
- */
-interface SdkAgentOptions {
-    apiKey?: string;
-    model?: {
-        id: string;
-    };
-    tools?: readonly unknown[];
-    memory?: Record<string, unknown>;
-    /**
-     * Phase 2 (Production-Readiness #1) — pluggable conversation persistence.
-     * Default (when omitted): SDK falls back to `FileSystemConversationStorage`.
-     * Required for serverless / multi-host deploys.
-     */
-    conversationStorage?: ConversationStorageLike;
-    [key: string]: unknown;
-}
-interface SdkModule {
-    Agent: {
-        getOrCreate: (agentId: string, options: SdkAgentOptions) => Promise<SdkAgent>;
-    };
-}
-interface ConversationHistoryArgs {
-    /** Request — for reading the conversation cookie. */
-    request: Request | {
-        headers?: {
-            cookie?: string;
-        } | Headers;
-    };
-    /**
-     * Response-like surface that accepts a `Set-Cookie` header. The primitive
-     * appends a Set-Cookie line when issuing a new conversation id. If absent,
-     * the primitive still reads the existing cookie but cannot issue a new
-     * one — useful for read-only contexts.
-     */
-    response?: {
-        headers: Headers;
-    };
-    /** Explicit override — wins over session/cookie/uuid (ADR D3 step 1). */
-    agentId?: string;
-    /** Auth session containing a `conversationId` field — ADR D3 step 2. */
-    session?: {
-        conversationId?: string;
-    } | null;
-    /** SDK AgentOptions forwarded to Agent.getOrCreate. apiKey + model required. */
-    options: SdkAgentOptions;
-    /** Cookie name override. Default: 'theo_conversation'. */
-    cookieName?: string;
-    /** Cookie max-age in seconds. Default + min: 30 days. Non-positive coerced to default (EC-4). */
-    cookieMaxAge?: number;
-}
-interface ConversationHistoryResult {
-    /** The SDK Agent, ready to receive `agent.send(message)`. */
-    agent: SdkAgent;
-    /** The resolved conversation id (useful for logging / debugging). */
-    conversationId: string;
-    /** True when the id was newly generated (no prior cookie / session). */
-    isNew: boolean;
-}
-/** @internal */
-declare function __setSdkForTests(sdk: SdkModule | null): void;
-/** @internal */
-declare function __resetSdkForTests(): void;
-declare function createConversationHistory(args: ConversationHistoryArgs): Promise<ConversationHistoryResult>;
-
-/**
- * Request log primitive (T6.2 of architecture-review-remediation-plan).
- *
- * Split out from `logger.ts` per PV-12 (SRP) — the file previously mixed
- * 3 concerns (factory, warnOnce, request log). This module owns ONLY the
- * `logRequest` flow + the devtools broadcast best-effort forwarder.
- *
- * Public API surface is unchanged — `logger.ts` re-exports `logRequest`
- * + `RequestLog` + `LoggerFn` for backward compat.
- */
-
-interface RequestLog {
-    level: string;
-    method: string;
-    url: string;
-    status: number;
-    duration: number;
-    requestId: string;
-    timestamp: string;
-}
-type LoggerFn = (log: RequestLog) => void;
-declare function logRequest(info: Omit<RequestLog, 'level' | 'timestamp'>, customLogger?: LoggerFn, req?: IncomingMessage): void;
-
-type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
-interface StructuredLog {
-    level: string;
-    msg: string;
-    timestamp: string;
-    [key: string]: unknown;
-}
-interface TheoLogger {
-    debug(msg: string, context?: Record<string, unknown>): void;
-    info(msg: string, context?: Record<string, unknown>): void;
-    warn(msg: string, context?: Record<string, unknown>): void;
-    error(msg: string, context?: Record<string, unknown>): void;
-    child(context: Record<string, unknown>): TheoLogger;
-}
-declare function createLogger(options?: {
-    level?: LogLevel;
-    output?: (log: StructuredLog) => void;
-    context?: Record<string, unknown>;
-}): TheoLogger;
-/**
- * Reset internal state. Test-only export — do not call from production.
- */
-declare function _resetWarnOnceForTests(): void;
-/**
- * Emit a structured warning ONCE per key. Subsequent calls with the same
- * key are suppressed. Used for cutover-style warnings (e.g. CSRF warn)
- * that would otherwise flood logs under load.
- *
- * Convention: key is `<event>:<method>:<path>` — see callers in csrf.ts.
- *
- * EC-2: payload may contain circular references. Wrap `JSON.stringify`
- * in try/catch so a malformed payload doesn't crash the request handler.
- */
-declare function warnOnce(key: string, payload: Record<string, unknown>): void;
-
-declare function levenshtein(a: string, b: string): number;
-declare function findSuggestion(input: string, candidates: string[], maxDistance?: number): string | null;
-
-declare class InvalidPluginShapeError extends Error {
-    constructor(index: number, reason: string);
-}
-/**
- * Build a PluginRunner from a list of plugins typically declared in
- * `theo.config.ts` under the `plugins` field. Returns `undefined` when no
- * plugins are configured so callers can pass `undefined` to `executeRoute`
- * and preserve the zero-overhead path.
- */
-declare function createPluginRunnerFromConfig(plugins: unknown): Promise<PluginRunner | undefined>;
-
-/**
- * T2.2 — Per-route + per-user rate limiting.
- *
- * Layered on top of `rate-limit-store.ts`. The route map allows
- * declarative policies ("strict /api/login, loose everything else")
- * driven by config, not handler-decorated. `keyBy` selects what
- * identifier the limiter buckets on.
- *
- * ADR D2: per-route via path matching, NOT per-handler decorator.
- * Operators can tune policies without touching route definitions.
- */
-type KeyByMode = 'ip' | 'session' | 'user' | ((req: IncomingMessage) => string);
-interface RouteRateLimitConfig {
-    /** Fallback config used when no per-route entry matches. */
-    default?: RateLimitConfig;
-    /** Map of path pattern → config. Exact-string keys (RegExp via API). */
-    routes?: Record<string, RateLimitConfig>;
-    /** Same as `routes` but each entry is a [pattern, config] tuple, RegExp allowed. */
-    routePatterns?: readonly [string | RegExp, RateLimitConfig][];
-    /** Bucket identifier strategy. Default 'ip'. */
-    keyBy?: KeyByMode;
-    /** Cookie name used by keyBy='session'. Defaults to 'theo_session'. */
-    cookieName?: string;
-    /** Optional shared store (for multi-route correlation). Default per-limiter InMemoryStore. */
-    store?: RateLimitStore;
-}
-/**
- * Test whether `path` matches `pattern`. String patterns are compared
- * after trailing-slash normalization (EC-5). RegExp uses `.test` after
- * resetting `lastIndex` (defensive against `/g` flag).
- */
-declare function matchRoutePattern(path: string, pattern: string | RegExp): boolean;
-/**
- * Build the rate-limit bucket key for the request based on `keyBy`.
- *
- * EC-6: session mode reads the configured `cookieName`. With the wrong
- * cookie name (e.g., default 'theo_session' but app uses 'app_session'),
- * we fall back to IP so anonymous users still get rate-limited rather
- * than sharing an empty bucket.
- */
-declare function deriveKey$1(req: IncomingMessage, keyBy: KeyByMode, cookieName: string): string;
-/**
- * Per-route rate limiter factory. Returns a sync checker compatible with
- * the existing api-middleware shape.
- *
- * Backwards-compatibility (ADR D2): a flat `{ windowMs, max }` config is
- * accepted and treated as `default` (no per-route variants).
- */
-declare function createRouteRateLimiter(config: RouteRateLimitConfig | RateLimitConfig): (req: IncomingMessage) => RateLimitResult;
-
-declare class ChannelManager {
-    private rooms;
-    private wsRooms;
-    subscribe(ws: WebSocketLike, room: string): void;
-    unsubscribe(ws: WebSocketLike, room: string): void;
-    broadcast(room: string, data: unknown, exclude?: WebSocketLike): void;
-    broadcastAll(data: unknown): void;
-    getRoomSize(room: string): number;
-    cleanup(ws: WebSocketLike): void;
+interface OpenApiDocsOptions {
+    /** Path to serve Scalar UI (default: '/api/docs'). */
+    docsPath?: string;
+    /** Path to serve the JSON spec (default: '/api/docs/openapi.json'). */
+    openapiJsonPath?: string;
+    /** Path to the spec file on disk (default: '.theo/openapi.json'). */
+    specFilePath?: string;
+    /** Page title (default: 'API Reference'). */
+    pageTitle?: string;
+    /** Scalar CDN URL (default: jsdelivr). Must be HTTPS. */
+    cdnUrl?: string;
 }
-
-/**
- * Phase 6 — Default Security Headers (D4 / EC-2).
- *
- * Per-response security baseline. The framework applies these BEFORE the
- * route handler runs so a handler can still override via `res.setHeader`.
- *
- * EC-2 backward-compatibility: CSP ships in `report-only` mode by default
- * for 0.2.0. Existing apps with inline scripts or third-party CDN scripts
- * keep working but consumers see violation reports via their CSP report
- * collector (or browser DevTools). 0.3.0 will flip the default to
- * `enforce` after a release of visibility.
- */
-/**
- * Default Content-Security-Policy. Conservative-but-not-paralyzing:
- *
- *   - default-src 'self'              — every fetch falls back to same-origin
- *   - script-src 'self'               — T6.1 (0.3.0): `'unsafe-inline'`
- *                                         dropped. The SSR pipeline issues a
- *                                         per-request nonce that REPLACES
- *                                         this directive at runtime
- *                                         (`'nonce-<token>'`). For static /
- *                                         non-SSR contexts where no nonce is
- *                                         available, the policy is strict-
- *                                         no-inline — user inline scripts
- *                                         must be migrated to external
- *                                         `<script src="...">` or threaded
- *                                         through `ctx.nonce`.
- *   - style-src 'self' 'unsafe-inline' — Tailwind + TheoUI use style attrs
- *                                         in animation directives
- *   - img-src 'self' data: blob:      — supports inline data URIs, blobs
- *                                         from canvas exports
- *   - font-src 'self' data:           — Geist fonts inline-base64
- *   - connect-src 'self' ws: wss:     — WebSocket dev HMR + agent streams
- *   - frame-ancestors 'none'          — clickjacking defense
- */
-/**
- * T5.1 — default CSP includes the built-in report endpoint so violations
- * are visible without extra config. Apps that ship a custom `csp` string
- * override the report-uri.
- */
-declare const DEFAULT_CSP: string;
 /**
- * T1.1 — Default Permissions-Policy header (default-deny stance).
- *
- * Disables sensitive Web APIs that the vast majority of apps don't use.
- * Apps that DO need any of these opt in by overriding `permissionsPolicy`
- * in `config.security.headers`.
- *
- * The seven features listed are the most-abused for: tracking
- * (geolocation, accelerometer, gyroscope), spyware (camera, microphone),
- * fraud (payment), and hardware exfiltration (usb).
- *
- * Aligns with Mozilla baseline + OWASP Secure Headers + Lighthouse PWA.
+ * Creates a request handler that serves OpenAPI docs.
+ * Returns `null` for non-matching requests (passthrough).
  */
-declare const DEFAULT_PERMISSIONS_POLICY = "geolocation=(), camera=(), microphone=(), payment=(), usb=(), accelerometer=(), gyroscope=()";
-type CspMode = 'enforce' | 'report-only' | 'off';
-interface SecurityHeadersConfig {
-    /**
-     * Custom CSP policy string. When set, replaces the default verbatim.
-     * Pass `false` to disable CSP entirely (alias for `cspMode: 'off'`).
-     */
-    csp?: string | false;
-    /**
-     * Enforcement mode for CSP. Default `report-only` for 0.2.0 (EC-2).
-     * 0.3.0 will default to `enforce`.
-     */
-    cspMode?: CspMode;
-    /**
-     * Strict-Transport-Security value. Defaults to
-     * `max-age=31536000; includeSubDomains` in production. Pass `false` to
-     * suppress (e.g. internal LANs without TLS).
-     */
-    hsts?: string | false;
-    /** X-Frame-Options. Default DENY. */
-    frameOptions?: 'DENY' | 'SAMEORIGIN';
-    /** X-Content-Type-Options. Default `nosniff`. */
-    contentTypeOptions?: 'nosniff';
-    /** Referrer-Policy. Default `strict-origin-when-cross-origin`. */
-    referrerPolicy?: string;
-    /**
-     * T1.1 — Permissions-Policy directive string. When set, replaces the
-     * default verbatim (no merge — see ADR-EC-12). Pass `false` to disable
-     * the header entirely. Schema-level refinement rejects any string
-     * containing CR/LF (EC-3 — CWE-113 HTTP Response Splitting mitigation).
-     */
-    permissionsPolicy?: string | false;
-}
-interface SecurityEnv {
-    production: boolean;
-}
-/**
- * T4.1 — Per-request options passed by the SSR pipeline.
- *
- * - `nonce`: when set, the framework substitutes the `'unsafe-inline'`
- *   token in `script-src` with `'nonce-<nonce>'`. EC-3 forces
- *   `Cache-Control: private, no-store` so a CDN cannot cache the HTML
- *   (carrying one nonce) and re-serve it with a freshly-generated CSP
- *   header (carrying a different nonce).
- * - `prerender`: when true, the nonce is IGNORED. Prerendered HTML is
- *   generated at build time with no nonce in the script tags; mixing a
- *   runtime nonce in the header would block every script. EC-4.
- */
-interface SecurityHeadersOptions {
-    nonce?: string;
-    prerender?: boolean;
-}
-/**
- * Build the security headers map for a given config + env. Pure function —
- * returned object can be inspected, logged, or applied to a response.
- */
-declare function buildSecurityHeaders(config: SecurityHeadersConfig, env: SecurityEnv, options?: SecurityHeadersOptions): Record<string, string>;
-/**
- * Apply security headers to a Node ServerResponse. Called by the
- * api-middleware before the route handler runs. The handler can override
- * any header via `res.setHeader()` — last write wins by Node convention.
- */
-declare function applySecurityHeaders(res: ServerResponse, config: SecurityHeadersConfig, env: SecurityEnv, options?: SecurityHeadersOptions): void;
-
-/**
- * T5.1 — Built-in CSP report endpoint.
- *
- * Browsers POST violation reports to `report-uri` (legacy `application/csp-report`)
- * or `Reporting API` (`application/reports+json`). Framework auto-registers this
- * endpoint so `cspMode: 'report-only'` is actually useful out of the box.
- *
- * Forwards normalized violations to:
- *   - audit logger (`csp.violation`)
- *   - devtools dispatcher (dev only, for Errors tab)
- *   - optional user hook (Sentry, etc.)
- *
- * EC-2: browser MAY send `{"csp-report": null}`, empty `{}`, or
- * reports+json entries lacking `body`. Handler MUST short-circuit to
- * 204 (valid format, no violation), NEVER crash via null deref.
- */
-declare const CSP_REPORT_PATH = "/__theo/csp-report";
-interface CspViolation {
-    blockedUrl: string;
-    documentUrl: string;
-    violatedDirective: string;
-    effectiveDirective?: string;
-    originalPolicy?: string;
-    disposition?: 'enforce' | 'report';
-    statusCode?: number;
-    sourceFile?: string;
-    lineNumber?: number;
-    columnNumber?: number;
-}
-interface CspReportHandlerOptions {
-    auditLogger?: AuditLogger;
-    devtoolsDispatcher?: {
-        onCspViolation?: (v: CspViolation) => void;
-    };
-    /** Optional user-provided sink (Sentry, custom log router). Errors here are swallowed. */
-    onViolation?: (v: CspViolation) => void;
-}
-declare function normalizeLegacy(raw: Record<string, unknown>): CspViolation;
-/**
- * Map a `reports+json` entry to the internal shape. Returns `null` if
- * the entry lacks a usable `body` object (EC-2).
- */
-declare function normalizeNew(entry: unknown): CspViolation | null;
-declare function handleCspReport(req: IncomingMessage, res: ServerResponse, opts: CspReportHandlerOptions): Promise<void>;
-
-/**
- * T2.2 — `/__theo/csrf-readiness` endpoint.
- *
- *   GET  /__theo/csrf-readiness        → 200 + JSON summary
- *   POST /__theo/csrf-readiness/reset  → 204; clears the store
- *
- * The reset endpoint enforces CSRF (own dog food) — requires
- * `X-Theo-Action: 1` AND a matching Origin header (EC-15). This avoids
- * the endpoint being weaponizable from a cross-origin page when the
- * endpoint is opt-in exposed in production.
- *
- * Mount opt-in: in dev mode, the host wires this in unconditionally. In
- * production, only mount when `config.security.csrfTelemetry.exposeReadinessEndpoint === true`.
- * EC-10 parallel: returns 404 (via boolean false return) when the URL
- * does not match — the caller continues normal request handling.
- */
-
-declare const CSRF_READINESS_PATH = "/__theo/csrf-readiness";
-declare const CSRF_READINESS_RESET_PATH = "/__theo/csrf-readiness/reset";
-declare function handleCsrfReadiness(req: IncomingMessage, res: ServerResponse, store: CsrfReadinessStore): Promise<boolean>;
-
-interface UnstorageInstance<T> {
-    getItem(key: string): Promise<T | null>;
-    setItem(key: string, value: T): Promise<void>;
-    removeItem(key: string): Promise<void>;
-    keys(prefix?: string): Promise<string[]>;
-    hasItem(key: string): Promise<boolean>;
-    clear(prefix?: string): Promise<void>;
-    dispose?(): Promise<void>;
-}
-declare function useUnstorage<T = unknown>(name: string, driver?: unknown): Promise<UnstorageInstance<T>>;
-
-interface Db0Database {
-    exec: (sql: string) => Promise<unknown>;
-    prepare: (sql: string) => unknown;
-    sql: (strings: TemplateStringsArray, ...args: unknown[]) => Promise<unknown>;
-}
-declare function useDatabase(name: string, connector: unknown): Promise<Db0Database>;
-
-/**
- * Constant-time byte comparison.
- *
- * Wraps `node:crypto.timingSafeEqual` when available (Node 6.6+) and falls
- * back to a constant-time XOR loop for runtimes without `node:crypto`
- * (Cloudflare Workers, Deno, Bun edge). Required to defeat timing attacks
- * on webhook signature verification — a naive `===` or `Buffer.equals`
- * would short-circuit on first mismatch byte and leak signature position
- * via wall-clock timing.
- *
- * Web Crypto's `crypto.subtle.verify` would also work, but requires a
- * `CryptoKey` object and is asymmetric (verify a signature against a key).
- * For our case — comparing two pre-computed digests — raw byte equality
- * is the correct primitive.
- *
- * @see https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b
- * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/verify
- */
-/**
- * Returns true iff `a` and `b` have identical bytes. Takes time
- * proportional to `a.length` regardless of where bytes differ.
- *
- * @throws TypeError if either argument is not a Uint8Array.
- */
-declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
-
-/**
- * Read a Web `Request` body as a raw string EXACTLY ONCE and expose it
- * alongside the original request (which remains readable by downstream
- * code). Enforces a configurable `maxBodyBytes` cap to prevent OOM via
- * pathological POST.
- *
- * MUST be called FIRST in the webhook pipeline, before any other code
- * touches the body (`request.text()`, `request.json()`, parsers). Once
- * the body is consumed, `Request.clone()` throws and this function fails.
- *
- * EC-101: default `maxBodyBytes = 1_000_000` (1 MB) covers Stripe
- * (256 KB max), Slack (4 MB but compressed), and is well below Node
- * memory thresholds. GitHub webhooks up to 25 MB MUST opt in
- * (`maxBodyBytes: 25_000_000`).
- *
- * @see https://docs.stripe.com/webhooks/signatures
- * @see https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks
- */
-declare const DEFAULT_MAX_BODY_BYTES = 1000000;
-interface ReadRawBodyOptions {
-    /** Maximum bytes to read before throwing `BodyTooLargeError`. Defaults to 1 MB. */
-    maxBodyBytes?: number;
-}
-interface RawBodyResult {
-    /** UTF-8 decoded body (or empty string when no body present). */
-    rawBody: string;
-    /** The ORIGINAL request, still readable by downstream code. */
-    bodyClone: Request;
-}
-/**
- * Thrown when the request body exceeds `maxBodyBytes`. Carries status
- * 413 (Payload Too Large) and stable code `BODY_TOO_LARGE` so callers
- * can map it to an HTTP response without sniffing the message.
- */
-declare class BodyTooLargeError extends Error {
-    readonly limit: number;
-    readonly actualSeen: number;
-    readonly status = 413;
-    readonly code = "BODY_TOO_LARGE";
-    constructor(limit: number, actualSeen: number);
-}
-declare function readRawBody(request: Request, options?: ReadRawBodyOptions): Promise<RawBodyResult>;
-
-/**
- * Webhook primitive types (R0.5.10).
- *
- * @see docs/adr/0005-webhook-verify-inline-function.md
- */
-type VerifyResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-};
-/**
- * A verify function — pure, async-or-sync. Takes the cloned request
- * (raw body NOT yet consumed by handler), returns ok/notOk + reason.
- *
- * Per ADR-0005, helper factories (`stripe`, `github`, `slack`) return
- * this shape. Users can also write inline `verify: async (req) => ...`
- * for custom providers.
- */
-type VerifyFn = (req: Request) => Promise<VerifyResult> | VerifyResult;
-interface WebhookContext {
-    /** The cloned Request (still readable by user code). */
-    readonly request: Request;
-    /** Raw body bytes as UTF-8 string — already-verified at this point. */
-    readonly rawBody: string;
-    /** W3C trace_id propagated from request. */
-    readonly traceId: string;
-    /** Abort signal triggered by client disconnect or server stop. */
-    readonly signal: AbortSignal;
-}
-interface DefineWebhookOptions {
-    verify: VerifyFn;
-    handler: (ctx: WebhookContext) => unknown;
-    /** Override `readRawBody` body size cap (EC-101). Default 1MB. */
-    maxBodyBytes?: number;
-}
-interface WebhookDefinition {
-    readonly verify: VerifyFn;
-    readonly handler: (ctx: WebhookContext) => unknown;
-    readonly maxBodyBytes?: number;
-    /** Discriminator for runtime dispatch. */
-    readonly __theokit_kind: 'webhook';
-}
-
-/**
- * Declare a webhook handler with first-class signature verification
- * (R0.5.10, ADR-0005). Pure identity helper — returns the definition
- * unchanged for downstream dispatch.
- *
- * @example
- * ```ts
- * // server/webhooks/stripe.ts
- * import { defineWebhook } from 'theokit/server'
- * import { stripe } from 'theokit/server/webhook/providers'
- *
- * export default defineWebhook({
- *   verify: stripe({ secret: process.env.STRIPE_WEBHOOK_SECRET! }),
- *   async handler({ rawBody }) {
- *     const event = JSON.parse(rawBody)
- *     // ...
- *     return new Response('ok')
- *   },
- * })
- * ```
- */
-declare function defineWebhook(opts: DefineWebhookOptions): WebhookDefinition;
-/**
- * Dispatch a webhook request through the definition's verify → handler
- * pipeline. Returns the handler's `Response` (or a wrapped one), or a
- * 401/413 response when verification or body size guards trip.
- *
- * EC-101: enforces `maxBodyBytes` (default 1MB via readRawBody).
- * EC-103: every throw from `verify` (sync or async) is treated as
- * `{ok: false, reason: 'verify threw: <message>'}`. Handler NEVER
- * invoked on verify failure.
- */
-declare function dispatchWebhook(def: WebhookDefinition, request: Request): Promise<Response>;
+declare function createOpenApiHandler(opts?: OpenApiDocsOptions): (request: Request) => Response | null;
 
 /**
  * A cached value persisted by a CacheStorageAdapter.
@@ -2295,6 +687,88 @@ declare function serializeResponse(data: unknown): SerializedResponse;
  */
 declare function deserializeResponse(serialized: SerializedResponse): unknown;
 
+/**
+ * The route module exported by a `server/routes/*.ts` file (after T2.6 G6
+ * router lockdown). Method-named exports map to `defineRoute` results.
+ */
+type WebRouteModule = Partial<Record<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', unknown>>;
+/**
+ * Optional behavior knobs for `executeWebRequest`. Each knob defaults to
+ * the safe "no-op" stance so existing Phase A consumers (T1.2 fixture
+ * tests) keep working unchanged.
+ *
+ * **`csrfMode`** (T5a.2 Phase B slice 1/6) — when set to `'strict'`, the
+ * Web-Standards request gate runs `validateCsrfRequest` BEFORE method
+ * dispatch on state-changing methods (POST/PUT/PATCH/DELETE) and emits a
+ * `403 FORBIDDEN` envelope when the check fails. Default: `'off'` (no
+ * CSRF enforcement) to preserve Phase A backward compat. Production
+ * consumers SHOULD pass `csrfMode: 'strict'`.
+ *
+ * Per the T5a.2 plan v1.0 § Phase B header-only leaves: csrf.ts is the
+ * first leaf to be migrated (slice 1/6); 5 more sibling leaves remain
+ * (csrf-multi-header, csrf-readiness-endpoint, csp-report, cors, cookies).
+ */
+interface ExecuteWebRequestOptions {
+    csrfMode?: 'off' | 'strict';
+    /**
+     * T5a.2 Phase E — body parser strategy.
+     *
+     * - `'inline'` (default): handle `application/json` + `text/*` only.
+     *   Returns the parsed value (object for JSON, string for text). Other
+     *   content-types (e.g., multipart) return `undefined`.
+     * - `'full'`: delegate to `parseWebRequestBody` for multipart support
+     *   + per-file size caps + max-files cap (Web Standards `request.formData()`
+     *   under the hood). Returns a `ParsedWebBody` object:
+     *   `{ json?, fields, files }`. Multipart consumers MUST opt into this
+     *   mode; JSON-only routes pay zero cost staying on `'inline'`.
+     */
+    bodyParser?: 'inline' | 'full';
+    /**
+     * T5a.2 Phase G slice 1/N — plugin lifecycle hooks.
+     *
+     * Adapters (Node, CF Workers, Bun, Deno) wire `WebPluginContext`-shaped
+     * hooks at the executeWebRequest lifecycle. Lifecycle order mirrors the
+     * Fastify / Hono convention:
+     *
+     *   1. CSRF check (when opts.csrfMode === 'strict')
+     *   2. onRequest — earliest, before body parsing. Plugins can short-circuit
+     *      by setting `ctx.response` (handler skipped; subsequent hooks see
+     *      the short-circuit response).
+     *   3. body parse (inline OR full per opts.bodyParser)
+     *   4. preHandler — after body parsed, before handler runs. Same
+     *      short-circuit semantic.
+     *   5. handler invocation
+     *   6. onResponse — after handler returns OR after a hook short-circuit.
+     *      `ctx.response` is populated.
+     *   7. onError — fires if any of (handler, onRequest, preHandler) throws.
+     *      `ctx.response` is the envelope-shaped error response built via
+     *      serverErrorToEnvelope.
+     *
+     * `responseHeaders` is shared across hooks; the final Response merges
+     * them with the handler's Response headers (handler headers win on
+     * conflict; hook headers add new ones). Decorations made via
+     * `ctx.ctx[key] = value` persist across hooks (request-scoped state).
+     *
+     * `hooks: undefined` (default) → no plugin lifecycle, Phase A behavior
+     * preserved. Production consumers wire via the WebPluginRunner facade
+     * (a future Phase G slice).
+     */
+    hooks?: {
+        onRequest?: readonly WebOnRequestHook[];
+        preHandler?: readonly WebPreHandlerHook[];
+        onResponse?: readonly WebOnResponseHook[];
+        onError?: readonly WebOnErrorHook[];
+    };
+    /**
+     * Stable request identifier propagated into hook contexts. Adapters
+     * resolve via traceparent / x-request-id / generated UUID (see
+     * `extractTraceIdFromRequest` from Phase C slice 1/2). Default:
+     * `globalThis.crypto.randomUUID()`.
+     */
+    requestId?: string;
+}
+declare function executeWebRequest(request: Request, routeModule: WebRouteModule, opts?: ExecuteWebRequestOptions): Promise<Response>;
+
 /**
  * Types for `loadEnv()` — env auto-load utility (Phase 1 of
  * docs/plans/framework-zero-config-polish-plan.md).
@@ -2336,4 +810,4 @@ interface LoadEnvResult {
 declare function _resetEnvCache(): void;
 declare function loadEnv(options?: LoadEnvOptions): LoadEnvResult;
 
-export { type ActionAccept, type ActionConfig, ActionError, type ActionErrorCode, ActionInputError, type ActionManifestEntry, type ActionNode, type ActionResult, ActionScanError, type AgentEndpointConfig, type AgentEndpointHandlerArgs, AgentErrorEvent, AgentEvent, type AgentRunLike, type AgentRunResult, type AgentRunStreamMessage, type AuditEvent, type AuditLogger, BATCH_PATH, type BatchExecuteFn, BatchPathConflictError, type BatchPayload, type BatchRequestItem, type BatchResponse, type BatchResultItem, type BodyParserOptions, BodyTooLargeError, DEFAULT_MAX_AGE as CACHE_DEFAULT_MAX_AGE, DEFAULT_MAX_ENTRY_SIZE as CACHE_DEFAULT_MAX_ENTRY_SIZE, DEFAULT_SWR_MULTIPLIER as CACHE_DEFAULT_SWR_MULTIPLIER, CACHE_TAG_MAX_ITEMS, CACHE_TAG_MAX_LENGTH, CSP_REPORT_PATH, CSRF_READINESS_PATH, CSRF_READINESS_RESET_PATH, CSRF_WARN_CODE, CSRF_WARN_DOCS_URL, type CacheControlInput, type CacheEngine, type CacheEngineOptions, type CacheEntry, type CacheStatus, type CacheStorageAdapter, type CacheStore, type CacheStoreAdmin, type ValidationResult as CacheValidationResult, type CachedFunction, type CachedRouteConfig, type ChannelHandler, ChannelManager, type CompiledRouteRule, type ConversationHistoryArgs, type ConversationHistoryResult, type ConversationStorageLike, type CookieOptions, type CorsConfig, type CorsHandler, type CorsOrigin, type CspMode, type CspReportHandlerOptions, type CspViolation, type CsrfLogger, type CsrfMode, CsrfReadinessStore, type CsrfWarnPayload, type CustomErrorPages, type CustomTool, DEFAULT_CSP, DEFAULT_EXCLUDED_QUERY_PARAMS, DEFAULT_MAX_BODY_BYTES, DEFAULT_PERMISSIONS_POLICY, type Db0Database, type DefineAgentToolSpec, type DefineCachedFunctionOptions, type DefineWebhookOptions, type DisallowedConfig, DuplicateDecorationError, DuplicatePluginError, type ExecuteActionOptions, type ExecuteRouteContext, FileTooLargeError, type GetOrComputeOptions, type HandleBatchOptions, type HookName, type HookResult, InMemoryCacheAdapter, type InMemoryCacheAdapterOptions, InvalidPluginShapeError, JobBackend, JsonStdoutSink, type KeyByMode, type KeyDerivationOptions, type LoadEnvOptions, type LoadEnvResult, type LoadModule, type LoadedManifest, type LogLevel, type LoggerFn, MAX_ERROR_HTML_BYTES, type ManifestAction, type ManifestRoute, type ManifestWebSocket, type MiddlewareHandler, type MiddlewareResult, type NormalizedCacheConfig, type OnErrorHook, type OnRequestHook, type OnResponseHook, type ParsedBody, type PluginContext, type PluginErrorContext, PluginRunner, type PreHandlerHook, RateLimitConfig, RateLimitResult, RateLimitStore, type RawBodyResult, type ReadRawBodyOptions, type RequestLog, type RevalidateResult, type RouteCacheOptions, type RouteConfig, type RouteRateLimitConfig, type RouteRule, type RouteRules, type RunHookOptions, STRIPPED_HEADERS, type SdkAgent, type SdkAgentOptions, type SdkRunLike, type SecurityEnv, type SecurityHeadersConfig, type SecurityHeadersOptions, type SendErrorInput, type SendErrorOptions, type SerializedActionResult, type SerializedResponse, type ServerRouteNode, type StructuredLog, THEO_T_PREFIX, TRACE_HEADER, TRACE_PARENT_HEADER, type TheoApp, type TheoLogger, type TheoManifest, type TheoPlugin, type TheoTransformer, type UniversalZodIssue, type UnstorageInstance, type UploadedFile, type VerifyFn, type VerifyResult, type WebSocketHandler, type WebSocketLike, type WebSocketRouteNode, type WebhookContext, type WebhookDefinition, __resetSdkForTests, __setSdkForTests, _resetCacheEngine, _resetEnvCache, _resetMiddlewareCacheForTests, _resetWarnOnceForTests, applySecurityHeaders, buildSecurityHeaders, compilePattern, compileRouteRules, createCacheEngine, createConversationHistory, createCorsHandler, createLogger, createNoOpLogger, createPluginRunnerFromConfig, createProductionLoader, createRouteRateLimiter, createViteLoader, defineAction, defineAgentEndpoint, defineAgentTool, defineCachedFunction, defineCachedRoute, defineChannel, defineMiddleware, definePlugin, defineRoute, defineTheoPlugin, defineWebSocket, defineWebhook, deleteCookie, deriveKey as deriveCacheKey, deriveKey$1 as deriveKey, deserializeResponse, dispatchWebhook, enforceCsrf, errorToEvent, executeAction, executeRoute, extractTraceId, extractUniversalIssues, findSuggestion, generateManifest, getCacheControlHeader, getCacheEngine, getCookie, handleBatchRequest, handleCspReport, handleCsrfReadiness, initCacheEngine, isActionError, isInputError, jsonTransformer, levenshtein, loadCustomErrorPages, loadEnv, loadManifest, logRequest, matchDisallowed, matchRoute, matchRoutePattern, matchesOrigin, normalizeLegacy, normalizeNew, parseCookieHeader, parseRequestBody, parseTraceparent, readRawBody, resolveRouteRule, resolveTransformer, revalidatePath, revalidateTag, runMiddlewareAndContext, safeAudit, scanMiddlewares, scanServerActions, scanServerActionsEnriched, scanServerRoutes, scanWebSocketRoutes, sendError, sendJson, serializeResponse, serveStaticFile, setCookie, streamAgentRun, superjsonTransformer, timingSafeEqual, updateTag, useDatabase, useUnstorage, validateExpire as validateCacheExpire, validateMaxAge as validateCacheMaxAge, validateTags as validateCacheTags, validateCsrf, warnOnce, writeManifest };
+export { ActionError, type ActionErrorCode, ActionInputError, type ActionManifestEntry, type ActionResult, type BodyParserOptions, DEFAULT_MAX_AGE as CACHE_DEFAULT_MAX_AGE, DEFAULT_MAX_ENTRY_SIZE as CACHE_DEFAULT_MAX_ENTRY_SIZE, DEFAULT_SWR_MULTIPLIER as CACHE_DEFAULT_SWR_MULTIPLIER, CACHE_TAG_MAX_ITEMS, CACHE_TAG_MAX_LENGTH, type CacheControlInput, type CacheEngine, type CacheEngineOptions, type CacheEntry, type CacheStatus, type CacheStorageAdapter, type CacheStore, type CacheStoreAdmin, type ValidationResult as CacheValidationResult, type CachedFunction, type CachedRouteConfig, type CompiledRouteRule, DEFAULT_EXCLUDED_QUERY_PARAMS, type DefineCachedFunctionOptions, FileTooLargeError, type GetOrComputeOptions, InMemoryCacheAdapter, type InMemoryCacheAdapterOptions, type KeyDerivationOptions, type LoadEnvOptions, type LoadEnvResult, type NormalizedCacheConfig, type OpenApiDocsOptions, type ParsedBody, type RevalidateResult, type RouteCacheOptions, RouteConfig, type RouteRule, type RouteRules, type SerializedActionResult, type SerializedResponse, THEO_T_PREFIX, type UniversalZodIssue, type UploadedFile, _resetCacheEngine, _resetEnvCache, compileRouteRules, createCacheEngine, createOpenApiHandler, defineCachedFunction, defineCachedRoute, deriveKey as deriveCacheKey, deserializeResponse, executeWebRequest, extractUniversalIssues, getCacheControlHeader, getCacheEngine, initCacheEngine, isActionError, isInputError, loadEnv, parseRequestBody, resolveRouteRule, revalidatePath, revalidateTag, serializeResponse, updateTag, validateExpire as validateCacheExpire, validateMaxAge as validateCacheMaxAge, validateTags as validateCacheTags };