theokit 0.12.0 → 0.13.0

package/dist/index-B40qUSrQ.d.ts

@@ -0,0 +1,575 @@
+import { a as TheoErrorCode, T as TheoErrorEnvelope } from './error-envelope-BsNzzAV5.js';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { P as PluginContext } from './plugin-types-DNJGxr4Z.js';
+import { P as PluginRunner } from './plugin-runner-BGBkzgi0.js';
+import { J as JobBackend } from './job-backend-CgC8Xf33.js';
+import { L as LoadModule, S as ServerRouteNode } from './match-CfbEFRG4.js';
+import { c as CsrfMode, D as DisallowedConfig } from './csrf-BBrEZSBW.js';
+import { z } from 'zod';
+
+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>;
+
+/**
+ * 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>;
+
+/**
+ * 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>>;
+}, z.core.$strip>;
+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>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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>;
+
+/**
+ * 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;
+/**
+ * T5a.2 Phase B slice 5/6 — Web-Standards CORS handler.
+ *
+ * Mirror of `createCorsHandler(config): CorsHandler` for the Web `Request`
+ * shape. Same `CorsConfig`, same `matchesOrigin` logic (pure helper
+ * already), same security guarantees (echo matched origin only — never
+ * `'*'` when credentials enabled; EC-8 fail-closed on callback throw).
+ *
+ * Signature differences vs the IncomingMessage pair:
+ *   - `handlePreflightRequest(request, config): Response | null` — returns
+ *     `Response` when this is a CORS preflight; `null` when not. Caller
+ *     short-circuits accordingly (same control-flow semantic as boolean).
+ *   - `applyCorsHeaders(request, target, config): void` — mutates a
+ *     `Headers` instance in place. Caller passes the headers they're
+ *     building for their Response.
+ */
+interface CorsWebHandler {
+    handlePreflightRequest(request: Request): Response | null;
+    applyCorsHeaders(request: Request, target: Headers): void;
+}
+declare function createCorsWebHandler(config: CorsConfig): CorsWebHandler;
+
+/**
+ * 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;
+/**
+ * T5a.2 Phase C slice 1/2 — Web-Standards-shaped traceId resolver.
+ *
+ * Mirror of `extractTraceId(req: IncomingMessage)` for the Web `Request`
+ * shape. Same precedence (`traceparent` → `x-request-id` → generated
+ * UUID). Uses `request.headers.get(name)` (native Web `Headers` API)
+ * instead of the Node indexer.
+ *
+ * **Multi-value note:** Web `Headers` collapses repeated headers into a
+ * single comma-separated string at parse. The IncomingMessage path's
+ * `pickHeader` "first non-empty value" semantic is naturally satisfied
+ * because there's no array to pick from on the Web side — `.get()`
+ * returns the comma-joined value, which for `traceparent` / `x-request-id`
+ * is treated as a single string anyway (both headers are conventionally
+ * single-valued).
+ */
+declare function extractTraceIdFromRequest(request: Request): string;
+
+/**
+ * `TheoError` — envelope-emitting `Error` subclass per plan
+ * g5-error-envelope-cross-layer v1.0 § Phase 1 / T1.2.
+ *
+ * Mirrors trpc's TRPCError ergonomic pattern (referencia:
+ * trpc/packages/server/src/unstable-core-do-not-import/error/TRPCError.ts:65-87)
+ * adapted for theokit's hybrid envelope model (blueprint Form 4).
+ *
+ * Per ADR D5: `meta.stack` is auto-stripped in non-dev builds when serialized
+ * via `toJSON()` — defense against accidental stack leak to clients (encore
+ * `json:"-"` analog).
+ *
+ * Lives in `core/contracts/` per architecture.md v3 invariant #3.
+ */
+
+/**
+ * Constructor options. `code` and `message` are required; `cause` follows TC39
+ * proposal-error-cause; `meta` and `ext` are opt-in per blueprint ADR D2.
+ */
+interface TheoErrorOptions<TExt = unknown> {
+    readonly code: TheoErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly meta?: Record<string, unknown>;
+    readonly ext?: TExt;
+}
+/**
+ * `TheoError` — envelope-emitting Error subclass. Use this anywhere in
+ * `theokit/server`, route handlers, or middleware to emit a typed,
+ * cross-layer-compatible error.
+ *
+ * Mirrors TRPCError pattern: `code` is required, `message` defaults to
+ * code if omitted, `cause` chain is preserved via TC39 proposal-error-cause.
+ */
+declare class TheoError<TExt = unknown> extends Error {
+    readonly name = "TheoError";
+    readonly code: TheoErrorCode;
+    readonly meta?: Record<string, unknown>;
+    readonly ext?: TExt;
+    constructor(opts: TheoErrorOptions<TExt>);
+    /**
+     * The canonical envelope view of this error. Use when crossing the wire
+     * boundary or feeding telemetry — exposes the shape consumers can rely on
+     * without depending on the class identity.
+     */
+    get envelope(): TheoErrorEnvelope<TExt>;
+    /**
+     * JSON serialization — emits envelope shape only (no name/stack class
+     * internals). Per ADR D5, `meta.stack` is auto-stripped in non-dev to
+     * prevent accidental leak; other meta keys are preserved.
+     */
+    toJSON(): TheoErrorEnvelope<TExt>;
+}
+/**
+ * Coerce any unknown value into a TheoError envelope.
+ *
+ * - If value is already a TheoError, returns it unchanged (no double-wrap).
+ * - If value is a plain Error, wraps it as `INTERNAL_SERVER_ERROR` with
+ *   `cause` chain preserving the original.
+ * - Other values (string, undefined, object) are coerced safely with a
+ *   meaningful message.
+ *
+ * Use at framework boundaries (route handler catch-all, middleware catch,
+ * SDK egress) to ensure every error crossing the wire carries an envelope.
+ */
+/**
+ * `NotFoundError` — typed 404. A `TheoError` with code `NOT_FOUND`, so it
+ * carries a stable `code` (not a bare status literal) and maps to HTTP 404 via
+ * `envelopeCodeToStatus`. Throw it from a `defineRoute` handler for ergonomic
+ * 404s (M7-1).
+ */
+declare class NotFoundError extends TheoError {
+    constructor(message?: string, meta?: Record<string, unknown>);
+}
+declare function fromUnknown(value: unknown): TheoError;
+
+/**
+ * G5 T2.5 — server-side boundary translation per blueprint ADR D3.
+ *
+ * Translates ad-hoc Error class instances (FileTooLargeError,
+ * AuthRequiredError, RouterConventionError, etc.) into the canonical
+ * `TheoErrorEnvelope` shape at the wire boundary. This is the SINGLE
+ * boundary translation point — class identities stay in place inside the
+ * codebase (no invasive call-site rewrites), but the envelope is what
+ * crosses to clients.
+ *
+ * Pure; no I/O. Lives in `core/contracts/` per architecture.md v3
+ * invariant #3 (canonical home for shared client↔server types). This file
+ * is the EXCEPTION-of-an-exception: it intentionally inspects Error names
+ * by string instead of `instanceof` to avoid `core/contracts/` taking a
+ * dependency on `server/`. The mapping table is small and grep-discoverable.
+ */
+
+/**
+ * Translate any server-side Error instance into a canonical envelope.
+ *
+ * Pass-through behavior:
+ * - `TheoError` instances return their `.envelope` unchanged.
+ * - Plain `Error` with unknown name → `INTERNAL_SERVER_ERROR`.
+ * - Non-Error values → wrapped via `TheoError.fromUnknown` semantics.
+ *
+ * Meta carries the source class `name` plus class-specific fields when an
+ * extractor is registered. This keeps wire-side telemetry useful without
+ * leaking implementation details.
+ */
+declare function serverErrorToEnvelope(value: unknown): TheoErrorEnvelope;
+
+/**
+ * Maps a TheoErrorEnvelope `code` to its canonical HTTP status.
+ *
+ * Single source of truth — previously duplicated in `web-handler.ts` and
+ * `handle-request-error.ts` (architecture-remediation plan T1.2, 2026-06-12).
+ *
+ * Every TheoErrorCode value MUST have an explicit entry here. SDK-domain codes
+ * (AGENT_RUN_ERROR, PROVIDER_KEY_MISSING, BUDGET_EXCEEDED, CREDENTIAL_POOL_EXHAUSTED)
+ * intentionally map to 500 — they represent internal failures, not client errors.
+ */
+declare function envelopeCodeToStatus(code: string): number;
+
+/**
+ * Canonical error handler for HTTP request pipelines (T3.4 of
+ * architecture-review-remediation-plan, PV-9 DRY).
+ *
+ * Replaces the duplicated catch-block logic in `executeRoute` (1 site) and
+ * `executeAction` (1 site, via `handleActionError`). Both code paths now
+ * share this implementation.
+ *
+ * Behavior contract (preserved from previous inline catches):
+ * - Plugin `onError` fires first (swallowed if it throws — never amplify failure).
+ * - `AuthRequiredError` is detected via `instanceof` AND a duck-type shape
+ *   check (`code === 'AUTH_REQUIRED' && status === 401`) — required because
+ *   under Vite dev / vitest the module-loader can produce a duplicate
+ *   AuthRequiredError class identity, breaking `instanceof`.
+ * - `onResponse({ inErrorPath: true })` always fires at the end (swallowed
+ *   if it throws — EC-9).
+ */
+interface HandleRequestErrorCtx {
+    req: IncomingMessage;
+    res: ServerResponse;
+    requestId: string | undefined;
+    pluginRunner: PluginRunner | undefined;
+    buildPluginCtx: (ctxObj: Record<string, unknown>) => PluginContext;
+}
+declare function handleRequestError(err: unknown, c: HandleRequestErrorCtx): Promise<void>;
+/**
+ * T5a.2 Phase G slice 3/N — Web-Standards request error handler.
+ *
+ * Mirror of `handleRequestError(err, c: HandleRequestErrorCtx)` for the
+ * Web `Request` shape. Returns a native `Response` directly instead of
+ * mutating `res`. Same behavioral contract:
+ *
+ *   1. Auth-error detection via `instanceof AuthRequiredError` PLUS a
+ *      duck-type fallback (`code === 'AUTH_REQUIRED' && status === 401`)
+ *      — needed because Vite dev / vitest can produce duplicate class
+ *      identities, breaking `instanceof`.
+ *   2. Envelope-shaped JSON body using `serverErrorToEnvelope` (G5 D3
+ *      boundary translation).
+ *   3. Status code derived from envelope.code via `envelopeCodeToStatus`
+ *      mirror (already implemented inline in web-handler.ts; this slice
+ *      uses the same mapping table).
+ *
+ * **Difference vs IncomingMessage path:** the Web path's plugin runner
+ * orchestration lives in `executeWebRequest`'s `runWithHooks` /
+ * `runErrorHooks` (Phase G slice 1/N) — `handleWebRequestError` is the
+ * leaf that builds the error Response WITHOUT touching plugin hooks.
+ * Callers compose: `executeWebRequest` (or future Web execute pipeline)
+ * catches a throw, calls `handleWebRequestError(err, { requestId })` to
+ * build the Response, then routes through onError hooks separately.
+ */
+interface HandleWebRequestErrorCtx {
+    requestId?: string;
+}
+declare function handleWebRequestError(err: unknown, ctx?: HandleWebRequestErrorCtx): Promise<Response>;
+
+interface MiddlewareResult {
+    ctx: unknown;
+    aborted: boolean;
+}
+declare function _resetMiddlewareCacheForTests(): void;
+declare function runMiddlewareAndContext(req: IncomingMessage, res: ServerResponse, loadModule: LoadModule, serverDir: string): Promise<MiddlewareResult>;
+
+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;
+/**
+ * T5a.2 Phase B slice 6/6 — pure Set-Cookie serializer. Extracted from
+ * `setCookie(res, ...)` so the IncomingMessage path AND the Web Headers
+ * path can share the cookie attribute composition.
+ *
+ * Returns the canonical `Set-Cookie` header value string (no surrounding
+ * `Set-Cookie:` prefix — caller wraps via `res.setHeader('Set-Cookie', ...)`
+ * or `headers.append('Set-Cookie', ...)`).
+ *
+ * Defaults: `httpOnly: true`, `secure: NODE_ENV === 'production'`,
+ * `sameSite: 'lax'`, `path: '/'`.
+ */
+declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+declare function setCookie(res: ServerResponse, name: string, value: string, options?: CookieOptions): void;
+declare function deleteCookie(res: ServerResponse, name: string, options?: {
+    path?: string;
+}): void;
+/**
+ * T5a.2 Phase B slice 6/6 — Web-Standards cookie getter.
+ *
+ * Mirror of `getCookie(req: IncomingMessage, name)` for the Web `Request`
+ * shape. Consumes `request.headers.get('cookie')` (native `Headers` API)
+ * instead of `req.headers.cookie`. Same parse logic + same malformed
+ * percent-encoding sanity (returns undefined when raw value contains a
+ * lone `%` that didn't decode, preserving the IncomingMessage path's
+ * "treat as unreadable" CR-009 semantics).
+ */
+declare function getCookieFromRequest(request: Request, name: string): string | undefined;
+/**
+ * T5a.2 Phase B slice 6/6 — Web-Standards cookie setter.
+ *
+ * Mirror of `setCookie(res, name, value, options)` for the Web `Headers`
+ * shape. Appends a `Set-Cookie` entry to the caller's `Headers` instance
+ * via `headers.append('Set-Cookie', ...)`. Multiple appends produce
+ * multiple `Set-Cookie` headers per the Web spec; `headers.getSetCookie()`
+ * retrieves them as an array (the one multi-value header the Web API
+ * exposes natively).
+ *
+ * Uses the shared `serializeCookie` pure helper — same defaults and
+ * attribute composition as the IncomingMessage path.
+ */
+declare function appendCookieToHeaders(target: Headers, name: string, value: string, options?: CookieOptions): void;
+/**
+ * T5a.2 Phase B slice 6/6 — Web-Standards cookie deleter.
+ *
+ * Mirror of `deleteCookie(res, name, options)` — emits a Set-Cookie with
+ * `Max-Age=0` so the browser drops the cookie immediately.
+ */
+declare function appendDeleteCookieToHeaders(target: Headers, name: string, options?: {
+    path?: string;
+}): void;
+
+/**
+ * T2.4 — Custom error pages loader.
+ *
+ * Loads optional `.theokit/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 `.theokit/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;
+
+export { serveStaticFile as $, extractTraceId as A, BATCH_PATH as B, type CookieOptions as C, extractTraceIdFromRequest as D, type ExecuteActionOptions as E, fromUnknown as F, getCookie as G, type HandleBatchOptions as H, getCookieFromRequest as I, handleBatchRequest as J, handleRequestError as K, handleWebRequestError as L, MAX_ERROR_HTML_BYTES as M, NotFoundError as N, jsonTransformer as O, loadCustomErrorPages as P, matchesOrigin as Q, parseCookieHeader as R, STRIPPED_HEADERS as S, TRACE_HEADER as T, parseTraceparent as U, resolveTransformer as V, runMiddlewareAndContext as W, sendError as X, sendJson as Y, serializeCookie as Z, _resetMiddlewareCacheForTests as _, type BatchExecuteFn as a, serverErrorToEnvelope as a0, setCookie as a1, superjsonTransformer as a2, BatchPathConflictError as b, type BatchPayload as c, type BatchRequestItem as d, type BatchResponse as e, type BatchResultItem as f, type CorsConfig as g, type CorsHandler as h, type CorsOrigin as i, type CorsWebHandler as j, type CustomErrorPages as k, type ExecuteRouteContext as l, type MiddlewareResult as m, type SendErrorInput as n, type SendErrorOptions as o, TRACE_PARENT_HEADER as p, TheoError as q, type TheoTransformer as r, appendCookieToHeaders as s, appendDeleteCookieToHeaders as t, createCorsHandler as u, createCorsWebHandler as v, deleteCookie as w, envelopeCodeToStatus as x, executeAction as y, executeRoute as z };