@vivero/stoma 0.1.0-rc.10

package/dist/protocol-2fD3DJrL.d.ts

@@ -0,0 +1,725 @@
+import { MiddlewareHandler, Context } from 'hono';
+import { TraceReporter } from './policies/sdk/trace.js';
+import { DebugLogger } from '@vivero/stoma-core';
+
+/**
+ * Policy type system - the building blocks of gateway pipelines.
+ *
+ * A {@link Policy} is a named middleware with priority ordering and
+ * optional protocol-agnostic evaluation. Policies are composed into
+ * pipelines at the global and route level, merged by name (route-level
+ * wins), and sorted by priority ascending.
+ *
+ * The HTTP runtime uses {@link Policy.handler} (Hono middleware).
+ * Non-HTTP runtimes (ext_proc, WebSocket) use {@link Policy.evaluate}.
+ *
+ * The {@link PolicyContext} provides request metadata (ID, timing, debug)
+ * to policies at runtime via `getGatewayContext(c)`.
+ *
+ * @module policy-types
+ */
+
+/**
+ * A Policy is a named middleware with priority ordering and optional
+ * protocol-agnostic evaluation.
+ *
+ * - {@link handler} - HTTP runtime entry point (Hono middleware).
+ *   Used by {@link createGateway}.
+ * - {@link evaluate} - Protocol-agnostic entry point. Used by non-HTTP
+ *   runtimes (ext_proc, WebSocket) to invoke the policy without Hono.
+ * - {@link phases} - Which processing phases this policy participates in.
+ *   Used by phase-based runtimes to skip irrelevant policies.
+ * - {@link httpOnly} - Set to `true` for policies that can ONLY work with
+ *   the HTTP protocol and don't make sense for ext_proc or WebSocket.
+ */
+interface Policy {
+    /** Unique policy name (e.g. "jwt-auth", "rate-limit") */
+    name: string;
+    /** The Hono middleware handler - HTTP runtime entry point. */
+    handler: MiddlewareHandler;
+    /** Policy priority - lower numbers execute first. Default: 100. */
+    priority?: number;
+    /**
+     * Protocol-agnostic evaluation entry point.
+     *
+     * Used by non-HTTP runtimes (ext_proc, WebSocket) to invoke this
+     * policy without Hono. The HTTP runtime ({@link createGateway}) uses
+     * {@link handler} directly and ignores this field.
+     *
+     * Policies that implement `evaluate` work across all runtimes.
+     * Policies that only implement `handler` are HTTP-only.
+     */
+    evaluate?: PolicyEvaluator;
+    /**
+     * Processing phases this policy participates in.
+     *
+     * Used by phase-based runtimes (ext_proc) to skip policies that don't
+     * apply to the current processing phase. For example, a JWT auth policy
+     * only needs `"request-headers"`, while a response transform policy
+     * needs `"response-headers"` and `"response-body"`.
+     *
+     * Default: `["request-headers"]` (most policies only inspect request headers).
+     */
+    phases?: ProcessingPhase[];
+    /**
+     * Set to `true` for policies that only work with the HTTP protocol.
+     *
+     * These policies rely on HTTP-specific concepts (Request/Response objects,
+     * specific headers, HTTP status codes, etc.) and cannot be meaningfully
+     * evaluated in other protocols like ext_proc or WebSocket.
+     *
+     * Examples:
+     * - `cors` - uses HTTP-specific `Access-Control-*` headers
+     * - `ssl-enforce` - HTTP-only protocol concept
+     * - `proxy` - HTTP-to-HTTP forwarding
+     * - `mock` - returns HTTP Response objects
+     *
+     * Tooling can use this flag to:
+     * - Skip these policies when generating docs for non-HTTP runtimes
+     * - Warn if an HTTP-only policy is used in a non-HTTP gateway config
+     */
+    httpOnly?: true;
+}
+/** Base configuration shared by all policies */
+interface PolicyConfig {
+    /** Skip this policy when condition returns true */
+    skip?: (c: unknown) => boolean | Promise<boolean>;
+}
+/** Context available to policies during execution */
+interface PolicyContext {
+    /** Unique request ID for tracing */
+    requestId: string;
+    /** Timestamp when the request entered the gateway */
+    startTime: number;
+    /** Gateway name */
+    gatewayName: string;
+    /** Matched route path pattern */
+    routePath: string;
+    /** W3C Trace Context - 32-hex trace ID (propagated or generated). */
+    traceId: string;
+    /** W3C Trace Context - 16-hex span ID for this gateway request. */
+    spanId: string;
+    /**
+     * Get a debug logger for the given namespace.
+     * Returns a no-op when debug is disabled (zero overhead).
+     *
+     * @example
+     * ```ts
+     * const ctx = getGatewayContext(c);
+     * const debug = ctx?.debug("stoma:policy:cache");
+     * debug?.("HIT", cacheKey);
+     * ```
+     */
+    debug: (namespace: string) => DebugLogger;
+    /** Runtime adapter providing store implementations and runtime-specific capabilities. */
+    adapter?: GatewayAdapter;
+}
+
+/**
+ * Circuit breaker policy - protect upstream services from cascading failures.
+ *
+ * Implements the three-state circuit breaker pattern (closed / open / half-open)
+ * with pluggable state storage via {@link CircuitBreakerStore}.
+ *
+ * @module circuit-breaker
+ */
+
+/** The three states of the circuit breaker state machine. */
+type CircuitState = "closed" | "open" | "half-open";
+/** Point-in-time snapshot of a circuit's state and counters. */
+interface CircuitBreakerSnapshot {
+    /** Current circuit state. */
+    state: CircuitState;
+    /** Number of consecutive failures since last reset. */
+    failureCount: number;
+    /** Number of successful probes in half-open state. */
+    successCount: number;
+    /** Epoch ms of the most recent failure. `0` if no failures recorded. */
+    lastFailureTime: number;
+    /** Epoch ms of the most recent state transition. */
+    lastStateChange: number;
+}
+/**
+ * Pluggable storage backend for circuit breaker state.
+ *
+ * Implement this interface to store circuit state in Durable Objects,
+ * KV, or any shared datastore for multi-instance deployments.
+ */
+interface CircuitBreakerStore {
+    /** Read the current snapshot for a circuit key. */
+    getState(key: string): Promise<CircuitBreakerSnapshot>;
+    /** Record a successful request and return the updated snapshot. */
+    recordSuccess(key: string): Promise<CircuitBreakerSnapshot>;
+    /** Record a failed request and return the updated snapshot. */
+    recordFailure(key: string): Promise<CircuitBreakerSnapshot>;
+    /** Transition the circuit to a new state and return the updated snapshot. */
+    transition(key: string, to: CircuitState): Promise<CircuitBreakerSnapshot>;
+    /** Fully reset a circuit, removing all state. */
+    reset(key: string): Promise<void>;
+    /** Optional cleanup - release timers, close connections, etc. */
+    destroy?(): void;
+}
+declare class InMemoryCircuitBreakerStore implements CircuitBreakerStore {
+    private circuits;
+    private getOrCreate;
+    getState(key: string): Promise<CircuitBreakerSnapshot>;
+    recordSuccess(key: string): Promise<CircuitBreakerSnapshot>;
+    recordFailure(key: string): Promise<CircuitBreakerSnapshot>;
+    transition(key: string, to: CircuitState): Promise<CircuitBreakerSnapshot>;
+    reset(key: string): Promise<void>;
+    /** Remove all circuits (for testing) */
+    clear(): void;
+    /** Release all state. */
+    destroy(): void;
+}
+interface CircuitBreakerConfig extends PolicyConfig {
+    /** Number of failures before opening the circuit. Default: 5. */
+    failureThreshold?: number;
+    /** Time in ms before transitioning from open → half-open. Default: 30000. */
+    resetTimeoutMs?: number;
+    /** Max concurrent probes allowed in half-open state. Default: 1. */
+    halfOpenMax?: number;
+    /** Status codes considered failures. Default: [500, 502, 503, 504]. */
+    failureOn?: number[];
+    /** Storage backend. Default: InMemoryCircuitBreakerStore. */
+    store?: CircuitBreakerStore;
+    /** Key extractor. Default: request URL pathname. */
+    key?: (c: Context) => string;
+    /** HTTP status code when the circuit is open. Default: 503. */
+    openStatusCode?: number;
+    /**
+     * Callback invoked on every state transition.
+     *
+     * Called via `safeCall` so errors are swallowed - a failing callback
+     * never blocks traffic. Useful for metrics, logging, or alerting.
+     *
+     * @param key - The circuit key that transitioned.
+     * @param from - The previous circuit state.
+     * @param to - The new circuit state.
+     */
+    onStateChange?: (key: string, from: CircuitState, to: CircuitState) => void | Promise<void>;
+}
+/**
+ * Protect upstream services by breaking the circuit on repeated failures.
+ *
+ * Implements the three-state circuit breaker pattern:
+ * - **Closed** - requests flow normally; failures are counted.
+ * - **Open** - requests are immediately rejected with 503; a `Retry-After` header is set.
+ * - **Half-open** - a limited number of probe requests are allowed through to test recovery.
+ *
+ * State transitions: `closed → open` when failures reach the threshold,
+ * `open → half-open` after the reset timeout, `half-open → closed` on
+ * probe success or `half-open → open` on probe failure.
+ *
+ * @param config - Failure threshold, reset timeout, and storage backend.
+ * @returns A {@link Policy} at priority 30.
+ *
+ * @example
+ * ```ts
+ * // Open after 5 failures, retry after 30s
+ * circuitBreaker();
+ *
+ * // Tighter threshold with custom store
+ * circuitBreaker({
+ *   failureThreshold: 3,
+ *   resetTimeoutMs: 10_000,
+ *   failureOn: [500, 502, 503],
+ *   store: new InMemoryCircuitBreakerStore(),
+ * });
+ *
+ * // With state change notifications
+ * circuitBreaker({
+ *   failureThreshold: 5,
+ *   onStateChange: (key, from, to) => {
+ *     console.log(`Circuit ${key}: ${from} -> ${to}`);
+ *   },
+ * });
+ * ```
+ */
+declare function circuitBreaker(config?: CircuitBreakerConfig): Policy;
+
+/**
+ * Response caching policy with pluggable storage backends.
+ *
+ * @module cache
+ */
+
+/** Pluggable cache storage backend */
+interface CacheStore {
+    /** Retrieve a cached response by key. Returns null on miss. */
+    get(key: string): Promise<Response | null>;
+    /** Store a response under key with a TTL in seconds. */
+    put(key: string, response: Response, ttlSeconds: number): Promise<void>;
+    /** Delete a cached entry. Returns true if something was removed. */
+    delete(key: string): Promise<boolean>;
+    /** Optional cleanup - clear expired entries, release resources. */
+    destroy?(): void;
+}
+/** Options for the in-memory cache store. */
+interface InMemoryCacheStoreOptions {
+    /** Maximum number of cached entries. When exceeded, the oldest entry is evicted (LRU). */
+    maxEntries?: number;
+}
+declare class InMemoryCacheStore implements CacheStore {
+    private entries;
+    private maxEntries;
+    constructor(options?: InMemoryCacheStoreOptions);
+    get(key: string): Promise<Response | null>;
+    put(key: string, response: Response, ttlSeconds: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Remove all entries (for testing) */
+    clear(): void;
+    /** Current number of entries (for testing/inspection) */
+    get size(): number;
+    /** Release all cached entries. */
+    destroy(): void;
+}
+interface CacheConfig extends PolicyConfig {
+    /** Cache TTL in seconds. Default: 300. */
+    ttlSeconds?: number;
+    /** HTTP methods to cache. Default: ["GET"]. Case-insensitive. */
+    methods?: string[];
+    /** Custom cache key builder. Supports async for body-based keys. Default: method + url (+ body hash for POST/PUT/PATCH). */
+    cacheKeyFn?: (c: Context) => string | Promise<string>;
+    /** Only cache responses with these status codes. When set, responses with other statuses are not cached (5xx is always excluded regardless). */
+    cacheableStatuses?: number[];
+    /** Vary cache key on these request headers. */
+    varyHeaders?: string[];
+    /** Storage backend. Default: InMemoryCacheStore. */
+    store?: CacheStore;
+    /** Respect upstream Cache-Control directives. Default: true. */
+    respectCacheControl?: boolean;
+    /** Response header name for cache status (HIT/MISS/BYPASS/SKIP). Default: `"x-cache"`. */
+    cacheStatusHeader?: string;
+    /** Cache-Control directives that trigger a bypass. Matched at the directive level, not substring. Default: `["no-store", "no-cache"]`. */
+    bypassDirectives?: string[];
+}
+/**
+ * Cache upstream responses to reduce latency and load.
+ *
+ * Sets a cache status header on **every** response:
+ * - `HIT` - served from cache
+ * - `MISS` - fetched from upstream, now cached
+ * - `BYPASS` - upstream Cache-Control directive prevented caching
+ * - `SKIP` - not eligible for caching (wrong method or server error status)
+ *
+ * Server error responses (5xx) are never cached. Store failures degrade
+ * gracefully via {@link safeCall} - a broken cache store never crashes the
+ * request.
+ *
+ * For methods with a request body (POST, PUT, PATCH), the default cache key
+ * includes a SHA-256 hash of the body to prevent key collisions across
+ * different payloads.
+ *
+ * @param config - Cache TTL, storage backend, and key strategy. All fields optional.
+ * @returns A {@link Policy} at priority 40.
+ *
+ * @example
+ * ```ts
+ * // Simple 5-minute in-memory cache for GET requests
+ * cache({ ttlSeconds: 300 });
+ *
+ * // Cache with Vary on Accept-Language and custom store
+ * cache({
+ *   ttlSeconds: 600,
+ *   varyHeaders: ["accept-language"],
+ *   store: new CacheApiCacheStore(caches.default),
+ * });
+ * ```
+ */
+declare function cache(config?: CacheConfig): Policy;
+
+interface RateLimitConfig extends PolicyConfig {
+    /** Maximum requests per window */
+    max: number;
+    /** Time window in seconds. Default: 60. */
+    windowSeconds?: number;
+    /** Key extractor - determines the rate limit bucket. Default: client IP. */
+    keyBy?: (c: Context) => string | Promise<string>;
+    /** Storage backend for counters */
+    store?: RateLimitStore;
+    /** Response status code when limited. Default: 429. */
+    statusCode?: number;
+    /** Custom response body when limited */
+    message?: string;
+    /** Ordered list of headers to inspect for the client IP (when `keyBy` is not set). Default: `["cf-connecting-ip", "x-forwarded-for"]`. */
+    ipHeaders?: string[];
+}
+/** Pluggable storage backend for rate limit counters */
+interface RateLimitStore {
+    /** Increment the counter for a key, returning the new count and TTL */
+    increment(key: string, windowSeconds: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    /** Optional: cleanup resources (like intervals) used by the store */
+    destroy?(): void;
+}
+/** Default in-memory rate limit store */
+interface InMemoryRateLimitStoreOptions {
+    /** Maximum number of unique keys to prevent memory exhaustion. Default: 100000. */
+    maxKeys?: number;
+    /** Cleanup interval in ms for expired entries. Default: 60000. */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Default in-memory rate limit store backed by a `Map`.
+ *
+ * The store is bounded by `maxKeys` (default 100,000) to prevent unbounded
+ * memory growth from unique rate-limit keys. When the store reaches capacity
+ * and no expired entries can be evicted, it **fails closed** - returning
+ * `MAX_SAFE_INTEGER` as the count to trigger rate limiting. This is an
+ * intentional security design: memory safety takes priority over availability.
+ *
+ * Note the distinction between store-level and policy-level failure modes:
+ * - **Store at capacity** (this class): fail-closed - reject the request
+ * - **Store throws/times out** (policy handler via `safeCall`): fail-open - allow the request
+ */
+declare class InMemoryRateLimitStore implements RateLimitStore {
+    private counters;
+    private cleanupInterval;
+    /** Maximum number of unique keys to prevent memory exhaustion */
+    private maxKeys;
+    private cleanupIntervalMs;
+    constructor(options?: InMemoryRateLimitStoreOptions | number);
+    /** Start the periodic cleanup interval on first use (Workers-safe). */
+    private ensureCleanupInterval;
+    /**
+     * Increment the counter for a key within the given time window.
+     *
+     * When the store reaches `maxKeys` capacity and no expired entries can
+     * be evicted, returns `{ count: MAX_SAFE_INTEGER, resetAt }` to trigger
+     * rate limiting (fail-closed). This prevents unbounded memory growth at
+     * the cost of potentially rejecting legitimate requests - an intentional
+     * security trade-off where memory safety takes priority over availability.
+     */
+    increment(key: string, windowSeconds: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    private cleanup;
+    /** Stop the cleanup interval (for testing) */
+    destroy(): void;
+    /** Reset all counters (for testing) */
+    reset(): void;
+}
+/**
+ * Rate limit requests with pluggable storage backends.
+ *
+ * Defaults to client IP extraction via `CF-Connecting-IP` or `X-Forwarded-For`.
+ * Sets standard `X-RateLimit-*` response headers on every request and
+ * throws a 429 when the limit is exceeded.
+ *
+ * @param config - Rate limit settings. `max` is required; other fields have sensible defaults.
+ * @returns A {@link Policy} at priority 20 (runs after auth).
+ *
+ * @example
+ * ```ts
+ * // 100 requests per minute per IP (in-memory)
+ * rateLimit({ max: 100 });
+ *
+ * // Custom key + Cloudflare KV store
+ * rateLimit({
+ *   max: 50,
+ *   windowSeconds: 300,
+ *   keyBy: (c) => c.req.header("x-user-id") ?? "anonymous",
+ *   store: new KVRateLimitStore(env.RATE_LIMIT_KV),
+ * });
+ * ```
+ */
+declare const rateLimit: (config: RateLimitConfig) => Policy;
+
+/** Bag of optional store implementations and runtime capabilities for a given runtime. */
+interface GatewayAdapter {
+    rateLimitStore?: RateLimitStore;
+    circuitBreakerStore?: CircuitBreakerStore;
+    cacheStore?: CacheStore;
+    /** Schedule background work that outlives the response (e.g. Cloudflare `executionCtx.waitUntil`). */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /** Dispatch a request to a named service binding or sidecar. */
+    dispatchBinding?: (service: string, request: Request) => Promise<Response>;
+}
+
+/**
+ * Protocol-agnostic types for multi-runtime policy evaluation.
+ *
+ * These types define the contract between policy logic and protocol runtimes.
+ * The HTTP runtime (Hono-based) uses {@link Policy.handler} directly.
+ * Non-HTTP runtimes (ext_proc, WebSocket) use {@link Policy.evaluate}.
+ *
+ * **Architecture:**
+ * ```
+ *                    ┌─────────────────────────────┐
+ *                    │      Policy Definitions      │
+ *                    │  name, priority, evaluate()  │
+ *                    │    (protocol-agnostic)       │
+ *                    └──────────┬──────────────────┘
+ *                               │
+ *              ┌────────────────┼────────────────┐
+ *              │                │                │
+ *    ┌─────────▼──────┐ ┌──────▼──────┐ ┌──────▼───────┐
+ *    │  HTTP Runtime   │ │  ext_proc   │ │  WebSocket   │
+ *    │  (Hono-based)   │ │  (gRPC)     │ │  Runtime     │
+ *    │ createGateway() │ │             │ │              │
+ *    └────────────────┘ └─────────────┘ └──────────────┘
+ * ```
+ *
+ * Hono powers the HTTP runtime. Other runtimes (ext_proc via gRPC,
+ * WebSocket) are peer implementations - same policy definitions,
+ * different wire protocols.
+ *
+ * @module protocol
+ */
+
+/**
+ * Lifecycle phases a policy can participate in.
+ *
+ * Maps to:
+ * - **HTTP**: `request-headers` → `request-body` → `response-headers` → `response-body`
+ *   (trailers are N/A for HTTP/1.1; available in HTTP/2)
+ * - **ext_proc**: All 6 phases - Envoy sends each as a `ProcessingRequest`
+ * - **WebSocket**: `request-headers` (upgrade) → `request-body` (per-message)
+ */
+type ProcessingPhase = "request-headers" | "request-body" | "request-trailers" | "response-headers" | "response-body" | "response-trailers";
+/** Identifies the protocol runtime invoking a policy. */
+type ProtocolType = "http" | "grpc" | "websocket";
+/**
+ * Protocol-agnostic view of what's being processed.
+ *
+ * Constructed by each runtime from its native message type:
+ * - HTTP runtime builds it from Hono's `Context`
+ * - ext_proc runtime builds it from gRPC `ProcessingRequest`
+ * - WebSocket runtime builds it from the upgrade request or message frame
+ */
+interface PolicyInput {
+    /** Current processing phase. */
+    phase: ProcessingPhase;
+    /**
+     * Request method or action.
+     *
+     * - HTTP: `"GET"`, `"POST"`, etc.
+     * - gRPC: Full method name, e.g. `"users.UserService/GetUser"`
+     */
+    method: string;
+    /**
+     * Request path or resource identifier.
+     *
+     * - HTTP: URL path, e.g. `"/users/123"`
+     * - gRPC: Service path, e.g. `"/users.UserService/GetUser"`
+     */
+    path: string;
+    /**
+     * Headers (HTTP) or metadata (gRPC).
+     *
+     * Treat as read-only - express modifications via
+     * {@link PolicyResult} mutations, not by mutating this object.
+     */
+    headers: Headers;
+    /**
+     * Client IP address, extracted by the runtime from protocol-specific
+     * sources (e.g. `CF-Connecting-IP`, `X-Forwarded-For`, gRPC peer address).
+     */
+    clientIp?: string;
+    /**
+     * Message body, present only during body phases.
+     *
+     * May be the full buffered body or a streaming chunk, depending on
+     * the runtime's buffering mode.
+     */
+    body?: ArrayBuffer | string;
+    /**
+     * Trailers, present only during trailer phases.
+     *
+     * Relevant for gRPC (which uses trailers for status codes and error
+     * details) and HTTP/2.
+     */
+    trailers?: Headers;
+    /**
+     * Cross-policy attribute bag.
+     *
+     * Policies read attributes set by upstream policies and set
+     * attributes for downstream policies via {@link AttributeMutation}.
+     * Runtime-populated attributes use the `runtime.*` namespace
+     * (e.g. `runtime.matched_route`, `runtime.upstream_name`).
+     */
+    attributes: Map<string, unknown>;
+    /** The protocol runtime that constructed this input. */
+    protocol: ProtocolType;
+}
+/**
+ * The outcome of a policy evaluation. Discriminated on `action`.
+ *
+ * - `"continue"` - Allow processing to continue, optionally with mutations.
+ * - `"reject"` - Reject with a structured error response.
+ * - `"immediate-response"` - Short-circuit with a complete non-error response.
+ */
+type PolicyResult = PolicyContinue | PolicyReject | PolicyImmediateResponse;
+/**
+ * Allow processing to continue, optionally with mutations.
+ *
+ * Equivalent to `await next()` in HTTP middleware, or ext_proc
+ * `CommonResponse` with header/body mutations.
+ */
+interface PolicyContinue {
+    action: "continue";
+    /** Mutations to apply before continuing to the next policy or upstream. */
+    mutations?: Mutation[];
+}
+/**
+ * Reject the request with a structured error.
+ *
+ * Equivalent to `throw new GatewayError(...)` in HTTP middleware, or
+ * ext_proc `ImmediateResponse` with an error status code.
+ */
+interface PolicyReject {
+    action: "reject";
+    /** HTTP status code (or gRPC status equivalent). */
+    status: number;
+    /** Machine-readable error code (e.g. `"rate_limited"`, `"unauthorized"`). */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Additional headers to include on the error response. */
+    headers?: Record<string, string>;
+}
+/**
+ * Short-circuit with a complete non-error response.
+ *
+ * Used for cache hits, mock responses, redirects - cases where the
+ * policy provides the full response and upstream should not be called.
+ *
+ * Equivalent to returning a `Response` without calling `next()` in
+ * HTTP middleware, or ext_proc `ImmediateResponse` with a success status.
+ */
+interface PolicyImmediateResponse {
+    action: "immediate-response";
+    /** HTTP status code for the response. */
+    status: number;
+    /** Response headers. */
+    headers?: Record<string, string>;
+    /** Response body. */
+    body?: string | ArrayBuffer;
+}
+/**
+ * A discrete modification to apply to the request or response.
+ * Discriminated on `type`.
+ *
+ * Designed to map cleanly to ext_proc `HeaderMutation`, `BodyMutation`,
+ * and Envoy dynamic metadata.
+ */
+type Mutation = HeaderMutation | BodyMutation | StatusMutation | AttributeMutation;
+/** Add, remove, or append a header value. */
+interface HeaderMutation {
+    type: "header";
+    /** `"set"` replaces, `"remove"` deletes, `"append"` adds without replacing. */
+    op: "set" | "remove" | "append";
+    /** Header name (case-insensitive). */
+    name: string;
+    /** Header value. Required for `"set"` and `"append"`, ignored for `"remove"`. */
+    value?: string;
+}
+/** Replace or clear the message body. */
+interface BodyMutation {
+    type: "body";
+    /** `"replace"` substitutes the body, `"clear"` removes it entirely. */
+    op: "replace" | "clear";
+    /** New body content. Required for `"replace"`, ignored for `"clear"`. */
+    content?: string | ArrayBuffer;
+}
+/**
+ * Modify the response status code.
+ *
+ * Only meaningful during response processing phases. Ignored during
+ * request phases.
+ */
+interface StatusMutation {
+    type: "status";
+    /** New HTTP status code. */
+    code: number;
+}
+/**
+ * Set a cross-policy attribute.
+ *
+ * Downstream policies see this value in {@link PolicyInput.attributes}.
+ * In ext_proc, this maps to Envoy dynamic metadata.
+ */
+interface AttributeMutation {
+    type: "attribute";
+    /** Attribute key. Use namespaced keys (e.g. `"auth.user_id"`) to avoid collisions. */
+    key: string;
+    /** Attribute value. */
+    value: unknown;
+}
+/**
+ * Runtime-facing evaluation context provided to policy evaluators.
+ *
+ * This is the base context without typed config - runtimes construct
+ * this from their native request representation. The policy SDK
+ * ({@link definePolicy}) extends this with a typed `config` field
+ * via `PolicyEvalHandlerContext`.
+ */
+interface PolicyEvalContext {
+    /** Debug logger pre-namespaced to `stoma:policy:{name}`. Always callable. */
+    debug: DebugLogger;
+    /** Trace reporter - always callable, no-op when tracing is not active. */
+    trace: TraceReporter;
+    /** Unique request ID for correlation. */
+    requestId: string;
+    /** W3C trace ID (32-hex). */
+    traceId: string;
+    /** Runtime adapter (stores, waitUntil, etc.). */
+    adapter?: GatewayAdapter;
+}
+/**
+ * Protocol-agnostic policy evaluation entry point.
+ *
+ * Implement this on a {@link Policy} to make it work across all runtimes
+ * (HTTP, ext_proc, WebSocket). The HTTP runtime uses {@link Policy.handler}
+ * directly - `evaluate` is consumed by non-HTTP runtimes.
+ *
+ * Runtimes call `onRequest` for request-phase processing and `onResponse`
+ * for response-phase processing. A policy can implement one or both.
+ *
+ * @example
+ * ```ts
+ * // Protocol-agnostic JWT verification
+ * const evaluator: PolicyEvaluator = {
+ *   onRequest: async (input, ctx) => {
+ *     const auth = input.headers.get("authorization");
+ *     if (!auth) return { action: "reject", status: 401, code: "unauthorized", message: "Missing token" };
+ *     // ... verify token ...
+ *     return { action: "continue", mutations: [
+ *       { type: "header", op: "set", name: "x-user-id", value: claims.sub },
+ *     ]};
+ *   },
+ * };
+ * ```
+ */
+/**
+ * Current `evaluate` coverage across policy categories:
+ * - auth: 6/9 (jwt-auth, api-key-auth, basic-auth, oauth2, rbac, jws)
+ * - traffic: 5/13 (rate-limit, ip-filter, cache, geo-ip-filter, ssl-enforce)
+ * - transform: 5/7 (cors, assign-attributes, assign-content, request-transform, response-transform)
+ * - observability: 0/4
+ * - resilience: 0/4
+ *
+ * Total: 16/38 policies have evaluate support. The remaining policies
+ * will gain evaluate implementations as non-HTTP runtimes (ext_proc, WebSocket)
+ * are built out. See PLAN.md Phase 5 for the ext_proc roadmap.
+ */
+interface PolicyEvaluator {
+    /**
+     * Evaluate during request processing phases.
+     *
+     * Called for: `request-headers`, `request-body`, `request-trailers`.
+     */
+    onRequest?: (input: PolicyInput, ctx: PolicyEvalContext) => Promise<PolicyResult>;
+    /**
+     * Evaluate during response processing phases.
+     *
+     * Called for: `response-headers`, `response-body`, `response-trailers`.
+     */
+    onResponse?: (input: PolicyInput, ctx: PolicyEvalContext) => Promise<PolicyResult>;
+}
+
+export { type AttributeMutation as A, type BodyMutation as B, type CacheStore as C, type GatewayAdapter as G, type HeaderMutation as H, InMemoryCacheStore as I, type Mutation as M, type Policy as P, type RateLimitStore as R, type StatusMutation as S, type CircuitBreakerSnapshot as a, type CircuitBreakerStore as b, type CircuitState as c, type InMemoryCacheStoreOptions as d, InMemoryCircuitBreakerStore as e, type InMemoryRateLimitStoreOptions as f, type PolicyConfig as g, type PolicyContext as h, type PolicyContinue as i, type PolicyEvalContext as j, type PolicyEvaluator as k, type PolicyImmediateResponse as l, type PolicyInput as m, type PolicyReject as n, type PolicyResult as o, type ProcessingPhase as p, type ProtocolType as q, cache as r, circuitBreaker as s, rateLimit as t, type CacheConfig as u, type CircuitBreakerConfig as v, InMemoryRateLimitStore as w, type RateLimitConfig as x };