theokit 0.12.0 → 0.13.0

package/dist/server/index.d.ts

@@ -0,0 +1,848 @@
+import { RouteConfig } from './define/index.js';
+export { ActionAccept, ActionConfig, AgentEndpointConfig, AgentEndpointHandlerArgs, ChannelHandler, CustomTool, DefineAgentToolSpec, MiddlewareHandler, WebChannelHandler, defineAction, defineAgentEndpoint, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel, uiMessageStreamResponse } 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 { H as HEALTH_PATH, a as HealthRouteConfig, b as READY_PATH, c as ReadyRouteConfig, d as ReservedResponse, R as ReservedRoutes, e as defineHealthRoute, f as defineReadyRoute, s as serveReservedRoute } from '../health-route-C0hk64_U.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, N as NotFoundError, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoError, r as TheoTransformer, _ as _resetMiddlewareCacheForTests, s as appendCookieToHeaders, t as appendDeleteCookieToHeaders, u as createCorsHandler, v as createCorsWebHandler, w as deleteCookie, x as envelopeCodeToStatus, y as executeAction, z as executeRoute, A as extractTraceId, D as extractTraceIdFromRequest, F as fromUnknown, G as getCookie, I as getCookieFromRequest, J as handleBatchRequest, K as handleRequestError, L as handleWebRequestError, O as jsonTransformer, P as loadCustomErrorPages, Q as matchesOrigin, R as parseCookieHeader, U as parseTraceparent, V as resolveTransformer, W as runMiddlewareAndContext, X as sendError, Y as sendJson, Z as serializeCookie, $ as serveStaticFile, a0 as serverErrorToEnvelope, a1 as setCookie, a2 as superjsonTransformer } from '../index-B40qUSrQ.js';
+export { ActionNode, ActionScanError, LoadedManifest, ManifestAction, ManifestAgent, 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 '../match-CfbEFRG4.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, f as AgentRunErrorCode, c as AgentThinkingEvent, d as AgentToolCallEvent, e as AgentToolResultEvent } from '../agent-events-DosDXkSV.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';
+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-BpH6ivDY.js';
+import 'ai';
+import 'vite';
+
+/**
+ * Action protocol — cross-boundary contract for `defineAction` + `useAction`.
+ *
+ * Per plan g3-server-actions-and-useaction v1.2 § Phase 0 / T0.1, ADRs D1 (encoding)
+ * + D6 (full dot-notation path) + D7 (PII mask) — types and runtime referenced
+ * by server (`server/http/action-execute.ts`, `server/define/define-action.ts`)
+ * and client (`@theokit/react/useAction`, `vite-plugin/actions-virtual-module`).
+ *
+ * Lives in `core/contracts/` per architecture.md v3.1 exception — cross-module
+ * deep imports ALLOWED for this file. Core depends on NOTHING intra-monorepo;
+ * `extractUniversalIssues` is implemented INLINE (NOT imported from `@theokit/sdk`)
+ * to honor dep-cruiser `core-depends-on-nothing` invariant (EC-1 absorbed).
+ *
+ * Field-key convention (D6 + EC-13): dot-notation full path. Nested objects use
+ * `'user.address.zip'`; array indices use `'items.0.name'` (NOT bracket
+ * `'items[0].name'`). Root-level errors (path = []) use empty string `''`
+ * (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
+ * (more semantic for input-shape mismatch). PAYLOAD_TOO_LARGE → 413 covers EC-3
+ * (response-side size limit; request-side reuses standard 413).
+ */
+type ActionErrorCode = 'VALIDATION_ERROR' | 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'CONTENT_TOO_LARGE' | 'PAYLOAD_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'TOO_MANY_REQUESTS' | 'INTERNAL_SERVER_ERROR';
+/**
+ * Universal zod issue shape covering BOTH v3 (`z.ZodIssue`) and v4 (`$ZodIssue`).
+ * Duck-typed minimum surface: `{path, message}`. Implemented per EC-1 absorbed —
+ * consumers chain may ship either zod major; constructor accepts `unknown` and
+ * normalizes via `extractUniversalIssues`.
+ */
+interface UniversalZodIssue {
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+    readonly code?: string;
+}
+/**
+ * `ActionError` — general server-side action failure. Discriminator `type` is
+ * literal `'TheoActionError'`; used by `ActionError.fromJson` to distinguish
+ * from `ActionInputError`.
+ */
+declare class ActionError extends Error {
+    readonly type: 'TheoActionError' | 'TheoActionInputError';
+    readonly code: ActionErrorCode;
+    readonly status: number;
+    constructor(params: {
+        code: ActionErrorCode;
+        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;
+    /**
+     * Parse a serialized error JSON back into the typed class hierarchy.
+     * Distinguishes `TheoActionInputError` (with `issues` array) from
+     * `TheoActionError` via the `type` discriminator. Falls back to
+     * `INTERNAL_SERVER_ERROR` for malformed bodies (non-object, missing
+     * `type`, unknown `code`).
+     */
+    static fromJson(body: unknown): ActionError;
+}
+/**
+ * `ActionInputError` — validation failure with field-level mapping.
+ *
+ * `fields` is auto-derived from `issues`: for each issue, key = full
+ * dot-notation path (`'user.address.zip'`; root-level `path:[]` → `''`;
+ * array indices as numeric segments → `'items.0.name'`). Multiple messages
+ * for the same key accumulate; duplicate (path, message) tuples are deduped.
+ */
+declare class ActionInputError extends ActionError {
+    readonly type: "TheoActionInputError";
+    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
+ * `UniversalZodIssue[]` (EC-1 absorbed). Duck-typed on `{path, message}` —
+ * does NOT import zod types (`core/contracts/` depends on no intra-monorepo
+ * + zod is consumer-controlled across the boundary).
+ *
+ * Silently skips entries missing required fields or shape mismatches; returns
+ * empty array on non-array input.
+ */
+declare function extractUniversalIssues(raw: unknown): UniversalZodIssue[];
+/**
+ * Type guard for `ActionError` (and its subclass `ActionInputError`). True
+ * iff the value is an instance of `ActionError`. Use `isInputError` to
+ * narrow specifically to validation failures.
+ */
+declare function isActionError(value: unknown): value is ActionError;
+/**
+ * Type guard narrowing to `ActionInputError`. Requires `instanceof` check
+ * (not duck-typing on `type`) to prevent attacker-controlled JSON from
+ * being mistaken for a real error instance.
+ */
+declare function isInputError(value: unknown): value is ActionInputError;
+/**
+ * `ActionResult<TData, TError>` — discriminated union returned by client-side
+ * action invocation. Either `{data, error: undefined}` (success) or
+ * `{data: undefined, error}` (failure). Mirrors Astro `SafeResult` shape.
+ */
+type ActionResult<TData = unknown, TError extends ActionError = ActionError> = {
+    data: TData;
+    error: undefined;
+} | {
+    data: undefined;
+    error: TError;
+};
+/**
+ * `SerializedActionResult` — wire-shape emitted by `serializeActionResult`
+ * in `server/http/serialize-action-result.ts` (T1.3). Discriminator `type`
+ * distinguishes data (devalue-encoded), error (JSON), and empty (204) cases.
+ */
+type SerializedActionResult = {
+    type: 'data';
+    status: number;
+    contentType: 'application/json+devalue';
+    body: string;
+} | {
+    type: 'error';
+    status: number;
+    contentType: 'application/json';
+    body: string;
+} | {
+    type: 'empty';
+    status: 204;
+};
+/**
+ * `ActionManifestEntry` — per-action metadata emitted by `action-scan.ts`
+ * (T1.4) into `.theokit/actions-manifest.json`. Consumed by virtual module
+ * `@theo/actions` (T3.1) and G4 devtools "Actions" tab (T5.1).
+ */
+interface ActionManifestEntry {
+    readonly name: string;
+    readonly filePath: string;
+    readonly urlPath: string;
+    readonly accept: 'form' | 'json';
+    readonly hasInput: boolean;
+}
+
+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: '.theokit/openapi.json'). */
+    specFilePath?: string;
+    /** Page title (default: 'API Reference'). */
+    pageTitle?: string;
+    /** Scalar CDN URL (default: jsdelivr). Must be HTTPS. */
+    cdnUrl?: string;
+}
+/**
+ * Creates a request handler that serves OpenAPI docs.
+ * Returns `null` for non-matching requests (passthrough).
+ */
+declare function createOpenApiHandler(opts?: OpenApiDocsOptions): (request: Request) => Response | null;
+
+/**
+ * A cached value persisted by a CacheStorageAdapter.
+ *
+ * For function caches: `status`/`headers` carry no semantics (use 200 + []).
+ * For route caches: `status` + `headers` reproduce the original Response.
+ *
+ * `body` is always a serialized payload (string or binary). The caller
+ * (engine + middleware) owns serialization/deserialization.
+ */
+interface CacheEntry {
+    body: string | Uint8Array;
+    status: number;
+    headers: [string, string][];
+    /** epoch ms when written */
+    storedAt: number;
+    /** seconds; validity window from storedAt */
+    maxAge: number;
+    /** seconds; stale window after maxAge expires */
+    swr: number;
+    /** accumulated tags (user + path-derived) */
+    tags: string[];
+    /** header names that affect the key (informational; key already includes them) */
+    vary?: string[];
+    /** explicit version stamp; mismatch bypasses cache */
+    cacheVersion?: string;
+}
+/**
+ * Hot-path storage contract — every request hits these 4 methods.
+ *
+ * ISP split (T4.4 of architecture-review-remediation-plan, PV-8): an adapter
+ * author implementing a Redis/D1/KV backend can implement ONLY this surface
+ * (admin methods are optional via `CacheStoreAdmin`).
+ *
+ * Invariants:
+ * - `get(key)` returns `undefined` if missing — never throws.
+ * - `set(key, entry)` is idempotent (last write wins).
+ * - `delete(key)` is idempotent (returns false if missing, never throws).
+ * - `deleteByTag(tag)` removes ALL entries carrying the tag and returns the count.
+ * - Tag index invariant: `get(key)?.tags.includes(tag)` ↔ `deleteByTag(tag)` removes `key`.
+ *
+ * Complexity (in-memory reference impl):
+ * - get/set/delete: O(1) amortized.
+ * - deleteByTag: O(matched-keys) via reverse index.
+ */
+interface CacheStore {
+    readonly name: string;
+    get(key: string): Promise<CacheEntry | undefined>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Fan-out invalidation by tag. Returns # entries removed. */
+    deleteByTag(tag: string): Promise<number>;
+}
+/**
+ * Admin surface — used by tests, devtools, debug introspection.
+ *
+ * Optional for third-party adapters. Engine guards admin calls with `typeof`
+ * checks so a hot-only adapter works correctly in production.
+ */
+interface CacheStoreAdmin {
+    size(): Promise<number>;
+    clear(): Promise<void>;
+    keys(prefix?: string): AsyncIterableIterator<string>;
+}
+/**
+ * Full storage backend contract — Hot path + Admin combined.
+ *
+ * The framework's `InMemoryCacheAdapter` implements both. Public type
+ * `CacheStorageAdapter = CacheStore & Partial<CacheStoreAdmin>` (backward
+ * compatible: existing implementations declaring all 7 methods continue to
+ * satisfy the type; new minimal implementations may omit admin).
+ */
+type CacheStorageAdapter = CacheStore & Partial<CacheStoreAdmin>;
+
+type CacheStatus = 'hit' | 'stale' | 'miss';
+interface CacheEngineOptions {
+    storage: CacheStorageAdapter;
+    defaults?: {
+        maxAge?: number;
+        swr?: number;
+        cacheVersion?: string;
+    };
+    onError?: (err: unknown, ctx: {
+        phase: 'get' | 'set' | 'revalidate';
+        key: string;
+    }) => void;
+}
+interface GetOrComputeOptions<T> {
+    maxAge: number;
+    swr?: number;
+    tags?: string[];
+    cacheVersion?: string;
+    transform?: (raw: T) => T;
+    validate?: (raw: T) => boolean;
+    /**
+     * When `true`, the value is returned but NOT written to cache.
+     * Used by route middleware to bypass cache for uncacheable responses
+     * (Set-Cookie, oversized body, status >= 400 with cacheErrors=false).
+     */
+    skipCacheWhen?: (raw: T) => boolean;
+}
+interface CacheEngine {
+    getOrCompute<T>(key: string, fn: () => Promise<T>, opts: GetOrComputeOptions<T>): Promise<{
+        value: T;
+        status: CacheStatus;
+    }>;
+    /**
+     * Public canonical cache read (T4.2 of architecture-review-remediation-plan,
+     * PV-5 DRY consolidation). Returns the parsed value + status (`hit` | `stale`)
+     * for callers that DON'T want to bind a loader function (e.g., HTTP route
+     * middleware that may want to bypass on miss instead of running a loader).
+     *
+     * Returns undefined when:
+     * - Entry not present in storage
+     * - `opts.cacheVersion` mismatch with entry
+     * - Body is not a JSON string (parse failed)
+     * - `opts.validate` returns false (or throws — caller's onError invoked)
+     * - Entry is fully expired (past maxAge + swr)
+     */
+    tryReadCached<T>(key: string, opts: {
+        cacheVersion?: string;
+        validate?: (v: T) => boolean;
+    }): Promise<{
+        value: T;
+        status: 'hit' | 'stale';
+    } | undefined>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+    invalidate(key: string): Promise<boolean>;
+    invalidateTag(tag: string): Promise<number>;
+    revalidatePath(path: string, type?: 'layout' | 'page'): Promise<number>;
+    /** Storage adapter passthrough (read-only access for diagnostics). */
+    readonly storage: CacheStorageAdapter;
+}
+/**
+ * Build a cache engine wrapping a storage adapter.
+ *
+ * Implements:
+ * - SWR (fresh / stale / expired branching) — Astro `memory-provider.ts:423`-style.
+ * - In-flight dedupe via `Map<key, Promise>` — Next.js `pendingRevalidates` pattern.
+ * - Tag-based invalidation via adapter's deleteByTag.
+ * - Path-as-tag encoding (revalidatePath sugar) — Next.js `revalidate.ts:105`.
+ *
+ * EC-8: Math.max(0, age) guards clock skew.
+ * EC-9: validate callback wrapped in try/catch.
+ * EC-10: loader returning undefined skips cache write + warns once.
+ *
+ * NOTE on max-lines-per-function disable below: createCacheEngine is a factory
+ * closure that owns the in-flight/bg/warned maps. Splitting would force the
+ * helpers across modules and re-introduce the shared mutable state through
+ * parameter lists.
+ */
+declare function createCacheEngine(opts: CacheEngineOptions): CacheEngine;
+
+interface DefineCachedFunctionOptions<TArgs extends unknown[], TReturn> {
+    /** Required cache namespace; appears in keys as "fn:${name}:..." */
+    name: string;
+    /** seconds; defaults to DEFAULT_MAX_AGE (1) */
+    maxAge?: number;
+    /** seconds; stale-while-revalidate window */
+    swr?: number;
+    /** Custom key derivation from args. Default: JSON.stringify(args). */
+    getKey?: (...args: TArgs) => string;
+    /** Static or dynamic tags. */
+    tags?: string[] | ((...args: TArgs) => string[]);
+    /** Version stamp; bump to invalidate all entries under this name. */
+    cacheVersion?: string;
+    /** Transform returned value before caching. */
+    transform?: (raw: TReturn) => TReturn;
+    /** Skip cache if validate returns false (treats existing entry as miss). */
+    validate?: (raw: TReturn) => boolean;
+    /** Called on any error in the cache pipeline. */
+    onError?: (err: unknown, ctx: {
+        args: TArgs;
+    }) => void;
+}
+type CachedFunction<TArgs extends unknown[], TReturn> = ((...args: TArgs) => Promise<TReturn>) & {
+    /** Bust the cache entry for these specific args. */
+    invalidate: (...args: TArgs) => Promise<void>;
+};
+/**
+ * Wrap an async function with cache semantics.
+ * Returns a callable that memoizes by `(name + args)` and exposes `.invalidate(args)`.
+ *
+ * The engine is supplied by the caller (avoids module-level singleton coupling
+ * during testing; framework wiring provides it in production).
+ */
+declare function defineCachedFunction<TArgs extends unknown[], TReturn>(engine: CacheEngine, fn: (...args: TArgs) => TReturn | Promise<TReturn>, opts: DefineCachedFunctionOptions<TArgs, TReturn>): CachedFunction<TArgs, TReturn>;
+
+/** Default 10 MB cap per cached route entry (EC-3). */
+declare const DEFAULT_MAX_ENTRY_SIZE: number;
+interface RouteCacheOptions {
+    maxAge?: number;
+    swr?: number;
+    tags?: string[];
+    varies?: string[];
+    getKey?: (req: Request) => string | Promise<string>;
+    bypassWhen?: (req: Request) => boolean | Promise<boolean>;
+    cacheVersion?: string;
+    cacheErrors?: boolean;
+    methods?: string[];
+    cacheable?: (response: Response) => boolean;
+    /** Max body bytes (EC-3); default DEFAULT_MAX_ENTRY_SIZE. */
+    maxEntrySize?: number;
+}
+interface CachedRouteConfig<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown> extends Omit<RouteConfig<TQuery, TBody, TParams, TCtx>, 'handler'> {
+    cache: RouteCacheOptions;
+    handler: (ctx: {
+        query: z.infer<TQuery>;
+        body: z.infer<TBody>;
+        params: z.infer<TParams>;
+        request: Request;
+        ctx: TCtx;
+    }) => unknown;
+}
+/**
+ * Wrap a `RouteConfig` with cache-aware handler logic.
+ *
+ * Architecture: wraps the user `handler` so cache lookup happens AT
+ * handler-invocation time, AFTER router middleware (auth/csrf/etc) ran.
+ * This structurally satisfies EC-4 (cache-after-auth) without modifying
+ * the router internals.
+ *
+ * Algorithm per request:
+ * 1. Method check + bypassWhen + maxAge=0 → call handler raw
+ * 2. Derive key (path + sortedQuery + varies, prefix by method)
+ * 3. Cache lookup → HIT/STALE return cached Response
+ * 4. Miss → run handler, check cacheability (Set-Cookie / status / size / SSE / streaming)
+ * 5. Cacheable → write entry + return Response with X-Theo-Cache: MISS (dev)
+ * 6. Not cacheable → return original Response unchanged
+ *
+ * Concurrent dedupe is INTENTIONALLY NOT used for routes — Response objects
+ * cannot be safely shared across concurrent callers (body is single-use stream).
+ * Each request that misses runs the handler independently.
+ */
+declare function defineCachedRoute<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown>(engine: CacheEngine, config: CachedRouteConfig<TQuery, TBody, TParams, TCtx>): RouteConfig<TQuery, TBody, TParams, TCtx, Response>;
+
+interface RevalidateResult {
+    deleted: number;
+}
+/**
+ * Invalidate all cache entries carrying the given tag.
+ * Safe to call from any context (route handler, action, webhook).
+ *
+ * `opts.expire` accepted for API compatibility with Next.js; at MVP we delete
+ * immediately (no SWR-with-expire semantics). A non-zero value emits one warn.
+ */
+declare function revalidateTag(tag: string, opts?: {
+    expire?: number;
+}): Promise<RevalidateResult>;
+/**
+ * Immediate invalidation (no SWR), Server-Action-safe.
+ * Same semantics as revalidateTag at MVP; kept as separate name for
+ * call-site clarity ("I want fresh data NOW").
+ */
+declare function updateTag(tag: string): Promise<RevalidateResult>;
+/**
+ * Invalidate cached entries for a route path.
+ * Sugar over `revalidateTag('_THEO_T_/${path}/${type?}')`.
+ */
+declare function revalidatePath(path: string, opts?: {
+    type?: 'layout' | 'page';
+    expire?: number;
+}): Promise<RevalidateResult>;
+
+interface InMemoryCacheAdapterOptions {
+    /** Maximum number of entries before LRU eviction. Default 1000. */
+    maxEntries?: number;
+}
+/**
+ * In-memory cache adapter with LRU eviction + reverse tag index.
+ *
+ * Uses Map insertion-order for O(1) LRU (Astro LRUMap pattern).
+ * Reverse index `tagIndex: Map<tag, Set<key>>` makes deleteByTag O(matched-keys).
+ *
+ * Invariants:
+ * - `entries.size <= maxEntries` post-set.
+ * - `tagIndex[tag].has(key)` ↔ `entries.get(key)?.tags.includes(tag)`.
+ *
+ * eslint-disable @typescript-eslint/require-await — the CacheStorageAdapter
+ * interface is intentionally async so Redis/file/external adapters fit. The
+ * in-memory variant returns immediately but keeps the async signature to
+ * satisfy the contract.
+ */
+declare class InMemoryCacheAdapter implements CacheStorageAdapter {
+    #private;
+    readonly name = "memory";
+    constructor(opts?: InMemoryCacheAdapterOptions);
+    get(key: string): Promise<CacheEntry | undefined>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    deleteByTag(tag: string): Promise<number>;
+    size(): Promise<number>;
+    clear(): Promise<void>;
+    keys(prefix?: string): AsyncIterableIterator<string>;
+}
+
+interface NormalizedCacheConfig {
+    enabled: boolean;
+    storage: 'memory' | CacheStorageAdapter;
+    maxEntries: number;
+    defaults: {
+        maxAge: number;
+        swr?: number;
+        cacheErrors: boolean;
+    };
+}
+/**
+ * Initialize the singleton cache engine for this process.
+ * Throws if called twice; tests should call `_resetCacheEngine()` between.
+ */
+declare function initCacheEngine(config: NormalizedCacheConfig, hooks?: Pick<CacheEngineOptions, 'onError'>): CacheEngine;
+/**
+ * Resolve the singleton cache engine.
+ * Throws a clear error if not initialized — usually means the framework
+ * bootstrap missed calling initCacheEngine, or cache.enabled is false.
+ */
+declare function getCacheEngine(): CacheEngine;
+/**
+ * Test-only: clear the singleton so the next test can re-init.
+ * Production code MUST NOT call this.
+ */
+declare function _resetCacheEngine(): void;
+
+interface RouteRule {
+    maxAge?: number;
+    swr?: number;
+    tags?: string[];
+}
+type RouteRules = Record<string, RouteRule>;
+interface CompiledRouteRule {
+    matcher: (path: string) => boolean;
+    rule: RouteRule;
+    /** Original glob pattern (for debugging). */
+    pattern: string;
+}
+/**
+ * Compile route-rule glob patterns into matcher functions.
+ * First-match-wins semantics (preserves insertion order).
+ *
+ * EC-5: picomatch is a direct production dependency (see plan T7.2).
+ */
+declare function compileRouteRules(rules: RouteRules): CompiledRouteRule[];
+/**
+ * Resolve the first matching rule for `path`, or `undefined` if none match.
+ */
+declare function resolveRouteRule(path: string, compiled: CompiledRouteRule[]): RouteRule | undefined;
+
+interface CacheControlInput {
+    /** seconds; 0 forces no-cache */
+    maxAge: number;
+    /** stale-while-revalidate window in seconds; 0 or undefined omits directive */
+    swr?: number;
+    /** emit `private,` prefix (skips shared CDN caching) */
+    isPrivate?: boolean;
+}
+/**
+ * Build a canonical Cache-Control header value.
+ *
+ * `maxAge === 0` always yields the strict no-cache directive regardless
+ * of `swr` or `isPrivate` — defensive default.
+ *
+ * EC-13: pure function intentional — caller is responsible for input
+ * validation (see validateMaxAge / validateExpire in validation.ts).
+ */
+declare function getCacheControlHeader(input: CacheControlInput): string;
+
+/**
+ * Default tracking/analytics query parameters excluded from cache keys.
+ * Mirrors Astro's DEFAULT_EXCLUDED_PARAMS list (memory-provider.ts:117).
+ * Set as exact-match (not glob) for KISS + zero-dep.
+ */
+declare const DEFAULT_EXCLUDED_QUERY_PARAMS: string[];
+interface KeyDerivationOptions {
+    /** Total override — when provided, bypasses all internal logic. */
+    getKey?: (req: Request) => string | Promise<string>;
+    /** Exact-match query param names to drop. Defaults to DEFAULT_EXCLUDED_QUERY_PARAMS. */
+    excludeQuery?: string[];
+    /** Whether to sort query params alphabetically. Defaults to true. */
+    sortQuery?: boolean;
+    /** Header names whose values are appended as `\0name=value` suffix. */
+    varies?: string[];
+    /** Namespace prefix (e.g., route name). */
+    prefix?: string;
+}
+/**
+ * Derive a deterministic cache key from a Request.
+ *
+ * Default behaviour: `${prefix?}${protocol}//${lower(host)}${path}${?sortedFilteredQuery}` + Vary suffix.
+ * `\0` separator chosen because it cannot appear in URLs or HTTP header values.
+ *
+ * EC-6: malformed URL on getKey path is caller's responsibility.
+ * EC-7: enforces getKey returns string.
+ */
+declare function deriveKey(req: Request, opts?: KeyDerivationOptions): Promise<string>;
+
+interface ValidationResult<T> {
+    valid: T[];
+    dropped: {
+        value: unknown;
+        reason: string;
+    }[];
+}
+/**
+ * Validate an array of cache tags.
+ * Drops invalid entries (type / length / reserved-prefix / overflow) with warn log.
+ * NEVER throws on runtime input — caller-facing safety.
+ *
+ * EC-1: defensive guard for non-array input (e.g., undefined from optional chain).
+ */
+declare function validateTags(tags: unknown, description: string): ValidationResult<string>;
+/**
+ * Validate a `maxAge` value in seconds.
+ * Throws on invalid input (config-time validation).
+ * Returns DEFAULT_MAX_AGE when undefined.
+ */
+declare function validateMaxAge(maxAge: unknown, description: string): number;
+/**
+ * Validate an `expire` value in seconds, optionally cross-checked against `revalidate`.
+ * Throws on invalid input (config-time validation).
+ */
+declare function validateExpire(expire: unknown, revalidate: number | undefined, description: string): number | undefined;
+
+/**
+ * Single source of truth for cache subsystem constants.
+ * Limits mirror Next.js (NEXT_CACHE_TAG_MAX_LENGTH / NEXT_CACHE_TAG_MAX_ITEMS)
+ * — see reference doc §3.2 and ADR D6 of caching-and-revalidation-plan.md.
+ */
+declare const CACHE_TAG_MAX_LENGTH = 256;
+declare const CACHE_TAG_MAX_ITEMS = 128;
+declare const THEO_T_PREFIX = "_THEO_T_";
+declare const DEFAULT_MAX_AGE = 1;
+declare const DEFAULT_SWR_MULTIPLIER = 60;
+
+interface UploadedFile {
+    fieldname: string;
+    filename: string;
+    encoding: string;
+    mimeType: string;
+    buffer: Buffer;
+    size: number;
+}
+interface ParsedBody {
+    fields: Record<string, string>;
+    files: UploadedFile[];
+    json?: unknown;
+}
+interface BodyParserOptions {
+    maxFileSize?: number;
+    maxFiles?: number;
+    maxFieldSize?: number;
+}
+declare class FileTooLargeError extends Error {
+    readonly truncatedFilenames: string[];
+    readonly maxFileSize: number;
+    readonly code = "FILE_TOO_LARGE";
+    readonly status = 413;
+    constructor(message: string, truncatedFilenames: string[], maxFileSize: number);
+}
+declare function parseRequestBody(req: IncomingMessage, options?: BodyParserOptions): Promise<ParsedBody>;
+
+interface SerializedResponse {
+    json: unknown;
+    meta?: unknown;
+}
+/**
+ * Serialize data using superjson for rich type support (Date, Map, Set, BigInt, etc.)
+ */
+declare function serializeResponse(data: unknown): SerializedResponse;
+/**
+ * Deserialize data that was serialized with superjson.
+ */
+declare function deserializeResponse(serialized: SerializedResponse): unknown;
+
+/**
+ * T3.2 — Web-Standards middleware runner for the `executeWebRequest` path.
+ *
+ * The Node request path (`http/execute.ts`) runs middleware via
+ * `runMiddlewareAndContext`, which is coupled to Node `req`/`res`. Per G8
+ * (Web Standards over Node APIs) the Web path needs a `Request`-shaped runner;
+ * this is it. Extracted to a sibling so `web-handler.ts` stays under its LoC
+ * budget (G6).
+ *
+ * Ordering invariant (EC-3): the caller runs the CSRF gate BEFORE invoking this
+ * runner, mirroring the Node path (CSRF stage precedes user middleware).
+ *
+ * NOTE (D4 / EC-12): this is its own middleware contract — `(request, context)`.
+ * Full semantic parity with the Node `defineMiddleware` contract is part of the
+ * deferred Node→Web pipeline convergence, not this slice.
+ */
+/** A Web-path middleware: mutate `context`, or return a `Response` to short-circuit. */
+type WebMiddleware = (request: Request, context: Record<string, unknown>) => Promise<Response | undefined> | Response | undefined | void;
+
+/**
+ * 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';
+    /**
+     * T3.1 — route params resolved upstream by `matchRoute` (e.g. `{ id: '42' }`
+     * for `/users/:id`). Threaded to the handler's `params` input and validated
+     * against `config.params` (Zod) when declared. Defaults to `{}` — callers
+     * that don't supply params keep the prior behavior (additive, backward-compat).
+     */
+    params?: Record<string, string>;
+    /**
+     * T3.2 — Web-Standards middleware chain. Runs in order AFTER the CSRF gate
+     * (EC-3) and BEFORE the handler. A middleware returning a `Response`
+     * short-circuits (handler not reached); mutating `context` passes data to
+     * the handler. Omitted → zero overhead (handler runs directly).
+     */
+    middleware?: readonly WebMiddleware[];
+    /**
+     * 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).
+ *
+ * The shape mirrors Next.js's `LoadedEnvFiles` (`next-env/index.ts:114`).
+ */
+interface LoadEnvOptions {
+    /** Project root. Default: `process.cwd()` */
+    cwd?: string;
+    /** Mode (`development` | `production` | `test`). Default: `process.env.NODE_ENV ?? 'development'` */
+    mode?: string;
+    /** Bypass module-level cache. Default: `false` */
+    forceReload?: boolean;
+}
+interface LoadEnvResult {
+    /** Map of all keys that were APPLIED to process.env by this call. */
+    loaded: Record<string, string>;
+    /** Absolute paths of files that were actually read, in priority order (top wins). */
+    loadedFromFiles: string[];
+}
+
+/**
+ * `loadEnv()` — auto-loads `.env` files into `process.env` for server code.
+ *
+ * Implements the Next.js `loadEnvConfig` algorithm
+ * (`referencias/next.js/packages/next-env/index.ts:114-180`) with TheoKit
+ * adaptations:
+ *
+ * - EC-1: 1MB file-size cap (anti-OOM, anti-supply-chain).
+ * - EC-2: `_resetEnvCache()` test-only side-door.
+ * - EC-8: `dotenv-expand` circular-ref safe (lib-provided).
+ * - EC-13: log when `.env` is a symlink (transparency).
+ * - D6: real `process.env` wins over `.env`-file values.
+ * - NODE_ENV stash: `.env`-set NODE_ENV NEVER overrides the real
+ *   `process.env.NODE_ENV`. Stashed in `__THEOKIT_USER_NODE_ENV` instead.
+ */
+
+/** Test-only side-door for EC-2 — clear the module-level cache between vitest test files. */
+declare function _resetEnvCache(): void;
+declare function loadEnv(options?: LoadEnvOptions): LoadEnvResult;
+
+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 };