@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.160

package/dist/_chunks/logger-CPoQkGK6.js

@@ -0,0 +1,1523 @@
+import { i as assertValidCookieValue, n as assertValidCookieName, r as assertValidCookieOptions, t as require_dist } from "./dist-BA3u1z3W.js";
+import { t as _setGetSearchParamsFn } from "./define-CFmvb4Bt.js";
+import { t as _setGetSegmentParamsFn } from "./define-Bssfp6ot.js";
+import { a as mergePreservedSearchParams, r as validateExternalRedirectUrl, t as assertRelativeRedirectPath } from "./href-validation-CMc5JRls.js";
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/server/als-registry.ts
+/**
+* Centralized AsyncLocalStorage registry for server-side per-request state.
+*
+* ALL ALS instances used by the server framework live here. Individual
+* modules (request-context.ts, tracing.ts, actions.ts, etc.) import from
+* this registry and re-export public accessor functions.
+*
+* Why: ALS instances require singleton semantics — if two copies of the
+* same ALS exist (one from a relative import, one from a barrel import,
+* or the same file re-evaluated by Vite after an HMR invalidation), one
+* module writes to its copy and another reads from an empty copy.
+* Centralizing ALS creation in a single module + anchoring each instance
+* on `globalThis` under a `Symbol.for(...)` key eliminates this class of
+* bug, including the Vite-dev case where module instance split would
+* otherwise hand two copies of this file out of a single evaluation cycle.
+*
+* The `timber-shims` plugin remaps `@timber-js/app/server` to src/ in
+* RSC and SSR environments so import-specifier paths converge here, and
+* the `globalThis[SYMBOL_FOR]` anchor below closes the remaining gap: any
+* second evaluation of this module picks up the ALS the first evaluation
+* already stored rather than instantiating a fresh one. Same pattern the
+* Cloudflare bindings ALS uses in `adapters/cloudflare.ts`.
+*
+* DO NOT create ALS instances outside this file. If you need a new ALS,
+* add it here and import from `./als-registry.js` in the consuming module.
+* Inside this file, always route through `getOrCreateAls(symbol)` — a raw
+* `new AsyncLocalStorage()` reintroduces the instance-split hazard.
+*
+* See design/18-build-system.md §"Module Singleton Strategy" and
+* §"Singleton State Registry". Regression test:
+* `tests/als-registry-singleton.test.ts`.
+*/
+/**
+* Return a process-wide singleton `AsyncLocalStorage` keyed by `symbol`.
+*
+* `Symbol.for(...)` keys live in the cross-realm symbol registry, and
+* `globalThis` is shared across every module evaluation inside the same
+* Node.js process. Together they give a stable anchor that survives
+* re-evaluation of this file — the second evaluation observes the
+* `globalThis[symbol]` slot already populated by the first and hands
+* back the identical ALS instance.
+*/
+function getOrCreateAls(symbol) {
+	const g = globalThis;
+	const existing = g[symbol];
+	if (existing instanceof AsyncLocalStorage) return existing;
+	const created = new AsyncLocalStorage();
+	g[symbol] = created;
+	return created;
+}
+/** @internal — import via request-context.ts public API */
+var requestContextAls = getOrCreateAls(Symbol.for("timber:request-context-als"));
+/** @internal — import via tracing.ts public API */
+var traceAls = getOrCreateAls(Symbol.for("timber:trace-als"));
+/** @internal — import via server-timing.ts public API */
+var timingAls = getOrCreateAls(Symbol.for("timber:timing-als"));
+/** @internal — import via actions.ts public API */
+var revalidationAls = getOrCreateAls(Symbol.for("timber:revalidation-als"));
+/** @internal — import via form-flash.ts public API */
+var formFlashAls = getOrCreateAls(Symbol.for("timber:form-flash-als"));
+/** @internal — import via early-hints-sender.ts public API */
+var earlyHintsSenderAls = getOrCreateAls(Symbol.for("timber:early-hints-sender-als"));
+/** @internal — import via waituntil-bridge.ts public API */
+var waitUntilAls = getOrCreateAls(Symbol.for("timber:wait-until-als"));
+getOrCreateAls(Symbol.for("timber:workers-cache-purge-als"));
+//#endregion
+//#region src/server/tracing.ts
+/**
+* Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
+*
+* getTraceId() is always available in server code (middleware, access, components, actions).
+* Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
+* or a crypto.randomUUID()-derived fallback otherwise.
+*
+* See design/17-logging.md §"trace_id is Always Set"
+*/
+/**
+* Returns the current request's trace ID — always a 32-char lowercase hex string.
+*
+* With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).
+* Without OTEL: crypto.randomUUID() with hyphens stripped.
+*
+* Throws if called outside a request context (no ALS store).
+*/
+function getTraceId() {
+	const store = traceAls.getStore();
+	if (!store) throw new Error("[timber] getTraceId() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
+	return store.traceId;
+}
+/**
+* Returns the current OTEL span ID if available, undefined otherwise.
+*/
+function getSpanId() {
+	return traceAls.getStore()?.spanId;
+}
+/**
+* Generate a 32-char lowercase hex ID from crypto.randomUUID().
+* Same format as OTEL trace IDs — zero-friction upgrade path.
+*/
+function generateTraceId() {
+	return randomUUID().replace(/-/g, "");
+}
+/**
+* Run a callback within a trace context. Used by the pipeline to establish
+* per-request ALS scope.
+*/
+function runWithTraceId(id, fn) {
+	return traceAls.run({ traceId: id }, fn);
+}
+/**
+* Replace the trace ID in the current ALS store. Used when OTEL creates
+* a root span and we want to switch from the UUID fallback to the real
+* OTEL trace ID.
+*/
+function replaceTraceId(newTraceId, newSpanId) {
+	const store = traceAls.getStore();
+	if (store) {
+		store.traceId = newTraceId;
+		store.spanId = newSpanId;
+	}
+}
+/**
+* Update the span ID in the current ALS store. Used when entering a new
+* OTEL span to keep log–trace correlation accurate.
+*/
+function updateSpanId(newSpanId) {
+	const store = traceAls.getStore();
+	if (store) store.spanId = newSpanId;
+}
+/**
+* Get the current trace store, or undefined if outside a request context.
+* Framework-internal — use getTraceId()/getSpanId() in user code.
+*/
+function getTraceStore() {
+	return traceAls.getStore();
+}
+var PLATFORM_TRACER_KEY = Symbol.for("timber:platform-tracer");
+/** The registered native platform tracer, if any. */
+function getPlatformTracer() {
+	return globalThis[PLATFORM_TRACER_KEY];
+}
+/**
+* Attempt to get the @opentelemetry/api tracer. Returns undefined if the
+* package is not installed or no SDK is registered.
+*
+* timber.js depends on @opentelemetry/api as the vendor-neutral interface.
+* The API is a no-op by default — spans are only emitted when the developer
+* initializes an SDK in register().
+*/
+var _otelApi;
+async function getOtelApi() {
+	if (_otelApi === void 0) try {
+		_otelApi = await import("@opentelemetry/api");
+	} catch {
+		_otelApi = null;
+	}
+	return _otelApi;
+}
+/** OTEL tracer instance, lazily created. */
+var _tracer;
+/**
+* Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.
+*/
+async function getTracer() {
+	if (_tracer === void 0) {
+		const api = await getOtelApi();
+		if (api) _tracer = api.trace.getTracer("timber.js");
+		else _tracer = null;
+	}
+	return _tracer;
+}
+/**
+* Run a function within a framework span. Composes two emission channels:
+*
+* - **Native platform span** — when an adapter registered a PlatformTracer
+*   (Cloudflare Workers), the fn is wrapped in platformTracer.enterSpan()
+*   so it appears in the platform's native trace view.
+* - **OTEL span** — when an OTEL SDK is active, the fn also runs inside an
+*   OTEL span (dual emission). No SDK and no platform tracer = zero overhead.
+*
+* Automatically:
+* - Creates the span as a child of the current context
+* - Updates the ALS span ID for log–trace correlation
+* - Ends the span when the function completes
+* - Records exceptions on error (OTEL channel)
+*/
+async function withSpan(name, attributes, fn) {
+	const platformTracer = getPlatformTracer();
+	if (!platformTracer) return runOtelSpan(name, attributes, fn);
+	return platformTracer.enterSpan(name, async (span) => {
+		for (const key of Object.keys(attributes)) span.setAttribute(key, attributes[key]);
+		const store = traceAls.getStore();
+		const prevPlatformSpan = store?.platformSpan;
+		if (store) store.platformSpan = span;
+		try {
+			return await runOtelSpan(name, attributes, fn);
+		} finally {
+			if (store) store.platformSpan = prevPlatformSpan;
+		}
+	});
+}
+/** The OTEL half of withSpan() — no-op passthrough when no SDK is active. */
+async function runOtelSpan(name, attributes, fn) {
+	const tracer = await getTracer();
+	if (!tracer) return fn();
+	const api = await getOtelApi();
+	return tracer.startActiveSpan(name, { attributes }, async (span) => {
+		const prevSpanId = getSpanId();
+		updateSpanId(span.spanContext().spanId);
+		try {
+			const result = await fn();
+			span.setStatus({ code: api.SpanStatusCode.OK });
+			return result;
+		} catch (error) {
+			span.setStatus({ code: api.SpanStatusCode.ERROR });
+			if (error instanceof Error) span.recordException(error);
+			throw error;
+		} finally {
+			span.end();
+			updateSpanId(prevSpanId);
+		}
+	});
+}
+/**
+* Set an attribute on the current active span (if any).
+* Used for setting span attributes after span creation (e.g. timber.result on access spans).
+*/
+async function setSpanAttribute(key, value) {
+	const platformSpan = traceAls.getStore()?.platformSpan;
+	if (platformSpan) platformSpan.setAttribute(key, value);
+	const api = await getOtelApi();
+	if (!api) return;
+	const activeSpan = api.trace.getActiveSpan();
+	if (activeSpan) activeSpan.setAttribute(key, value);
+}
+/**
+* Add a span event to the current active span (if any).
+* Used for timber.cache HIT/MISS events — recorded as span events, not child spans.
+*/
+async function addSpanEvent(name, attributes) {
+	const api = await getOtelApi();
+	if (!api) return;
+	const activeSpan = api.trace.getActiveSpan();
+	if (activeSpan) activeSpan.addEvent(name, attributes);
+}
+/**
+* Fire-and-forget span event — no await, no microtask overhead.
+*
+* Used on the cache hot path where awaiting addSpanEvent creates an
+* unnecessary microtask per cache operation. If OTEL is not loaded yet,
+* the event is silently dropped (acceptable for diagnostics).
+*
+* See TIM-370 for perf motivation.
+*/
+function addSpanEventSync(name, attributes) {
+	if (!_otelApi) return;
+	const activeSpan = _otelApi.trace.getActiveSpan();
+	if (activeSpan) activeSpan.addEvent(name, attributes);
+}
+/**
+* Try to extract the OTEL trace ID from the current active span context.
+* Returns undefined if OTEL is not active or no span exists.
+*/
+async function getOtelTraceId() {
+	const api = await getOtelApi();
+	if (!api) return void 0;
+	const activeSpan = api.trace.getActiveSpan();
+	if (!activeSpan) return void 0;
+	const ctx = activeSpan.spanContext();
+	if (!ctx.traceId || ctx.traceId === "00000000000000000000000000000000") return;
+	return {
+		traceId: ctx.traceId,
+		spanId: ctx.spanId
+	};
+}
+//#endregion
+//#region src/server/debug.ts
+/**
+* Runtime debug flag for timber.js.
+*
+* Two distinct functions for two distinct security levels:
+*
+* ## `isDebug()` — server-side logging only
+*
+* Returns true when timber's debug/warning messages should be written to
+* stderr / the server console. This NEVER affects what is sent to the
+* client (no error details, no timing headers, no stack traces).
+*
+* Active when any of:
+* - `NODE_ENV !== 'production'` (standard dev mode)
+* - `TIMBER_DEBUG` env var is set to a truthy value at runtime
+* - `timber.config.ts` has `debug: true`
+*
+* ## `isDevMode()` — client-visible dev behavior
+*
+* Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything
+* that changes what clients can observe:
+* - Dev error pages with stack traces (fallback-error.ts)
+* - Detailed Server-Timing headers (pipeline.ts)
+* - Error messages in action INTERNAL_ERROR payloads (action-client.ts)
+* - Pipeline error handler wiring (Vite overlay)
+*
+* `isDevMode()` is statically replaced in production builds → the guarded
+* code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.
+*
+* Usage:
+*   In Cloudflare Workers wrangler.toml:
+*     [vars]
+*     TIMBER_DEBUG = "1"
+*
+*   In Node.js:
+*     TIMBER_DEBUG=1 node server.js
+*
+*   In timber.config.ts:
+*     export default { debug: true }
+*
+* See design/13-security.md for the security taxonomy.
+* See design/18-build-system.md for build pipeline details.
+*/
+/**
+* Check if the application is running in development mode.
+*
+* This is the ONLY function that should gate client-visible dev behavior:
+* - Dev error pages with stack traces
+* - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
+* - Error messages in action `INTERNAL_ERROR` payloads
+* - Pipeline error handler wiring (Vite overlay)
+*
+* Returns `process.env.NODE_ENV !== 'production'`, which is statically
+* replaced by the bundler in production builds. Code guarded by this
+* function is tree-shaken to zero bytes in production.
+*
+* TIMBER_DEBUG does NOT enable this — that would leak server internals
+* to clients. Use `isDebug()` for server-side-only logging.
+*/
+function isDevMode() {
+	return process.env.NODE_ENV !== "production";
+}
+/**
+* Config-level debug override. Set via `setDebugFromConfig()` during
+* initialization when timber.config.ts has `debug: true`.
+*/
+var _configDebug = false;
+/**
+* Check if timber debug logging is active (server-side only).
+*
+* Returns true if ANY of these conditions hold:
+* - NODE_ENV is not 'production' (standard dev mode)
+* - TIMBER_DEBUG environment variable is set to a truthy value at runtime
+* - timber.config.ts has `debug: true`
+*
+* This function controls ONLY server-side logging — messages written to
+* stderr or the server console. It NEVER affects client-visible behavior
+* (error pages, response headers, action payloads). For client-visible
+* behavior, use `isDevMode()`.
+*
+* The TIMBER_DEBUG check is deliberately written as a dynamic property
+* access so bundlers cannot statically replace it.
+*/
+function isDebug() {
+	if (process.env.NODE_ENV !== "production") return true;
+	if (_configDebug) return true;
+	return _readTimberDebugEnv();
+}
+/**
+* Read TIMBER_DEBUG from the environment at runtime.
+*
+* Extracted to a separate function to:
+* 1. Prevent bundler inlining (cross-module function calls are not inlined)
+* 2. Handle platforms where `process` may not exist (Cloudflare Workers)
+* 3. Support globalThis.__TIMBER_DEBUG for programmatic control
+*/
+function _readTimberDebugEnv() {
+	if (globalThis.__TIMBER_DEBUG) return true;
+	try {
+		const val = typeof process !== "undefined" && process.env ? process.env["TIMBER_DEBUG"] : void 0;
+		if (val && val !== "0" && val !== "false") return true;
+	} catch {}
+	return false;
+}
+//#endregion
+//#region src/server/error-formatter.ts
+/**
+* Error Formatter — rewrites SSR/RSC error messages to surface user code.
+*
+* When React or Vite throw errors during SSR, stack traces reference
+* vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)
+* and mangled export names (`__vite_ssr_export_default__`). This module
+* rewrites error messages and stack traces to point at user code instead.
+*
+* Dev-only — in production, errors go through the structured logger
+* without formatting.
+*/
+/**
+* Patterns that identify internal Vite/RSC vendor paths in stack traces.
+* These are replaced with human-readable labels.
+*/
+var VENDOR_PATH_PATTERNS = [
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor_react-server-dom[^\s)]+/g,
+		replacement: "<react-server-dom>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor[^\s)]+/g,
+		replacement: "<rsc-vendor>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/[^\s)]+/g,
+		replacement: "<vite-dep>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps\/[^\s)]+/g,
+		replacement: "<vite-dep>"
+	}
+];
+/**
+* Patterns that identify Vite-mangled export names in error messages.
+*/
+var MANGLED_NAME_PATTERNS = [{
+	pattern: /__vite_ssr_export_default__/g,
+	replacement: "<default export>"
+}, {
+	pattern: /__vite_ssr_export_(\w+)__/g,
+	replacement: "<export $1>"
+}];
+/**
+* Rewrite an error's message and stack to replace internal Vite paths
+* and mangled names with human-readable labels.
+*/
+function formatSsrError(error) {
+	if (!(error instanceof Error)) return String(error);
+	let message = error.message;
+	let stack = error.stack ?? "";
+	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) message = message.replace(pattern, replacement);
+	for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) stack = stack.replace(pattern, replacement);
+	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) stack = stack.replace(pattern, replacement);
+	const hint = extractErrorHint(error.message);
+	const parts = [];
+	parts.push(message);
+	if (hint) parts.push(`  → ${hint}`);
+	const userFrames = extractUserFrames(stack);
+	if (userFrames.length > 0) {
+		parts.push("");
+		parts.push("  User code in stack:");
+		for (const frame of userFrames) parts.push(`    ${frame}`);
+	}
+	return parts.join("\n");
+}
+/**
+* Extract a human-readable hint from common React/RSC error messages.
+*
+* React error messages contain useful information but the surrounding
+* context (vendor paths, mangled names) obscures it. This extracts the
+* actionable part as a one-line hint.
+*/
+function extractErrorHint(message) {
+	if (message.match(/Functions cannot be passed directly to Client Components/)) {
+		const propMatch = message.match(/<[^>]*?\s(\w+)=\{function/);
+		if (propMatch) return `Prop "${propMatch[1]}" is a function — mark it "use server" or call it before passing`;
+		return "A function prop was passed to a Client Component — mark it \"use server\" or call it before passing";
+	}
+	if (message.includes("Objects are not valid as a React child")) return "An object was rendered as JSX children — convert to string or extract the value";
+	const nullRefMatch = message.match(/Cannot read propert(?:y|ies) of (undefined|null) \(reading '(\w+)'\)/);
+	if (nullRefMatch) return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;
+	const notFnMatch = message.match(/(\w+) is not a function/);
+	if (notFnMatch) return `"${notFnMatch[1]}" is not a function — check imports and exports`;
+	if (message.includes("Element type is invalid")) return "A component resolved to undefined/null — check default exports and import paths";
+	if (message.includes("Invalid hook call")) return "A hook was called outside of a React component render. If this is a 'use client' component, ensure the directive is at the very top of the file (before any imports) and that @vitejs/plugin-rsc is loaded correctly. Barrel re-exports from non-'use client' files do not propagate the directive.";
+	return null;
+}
+/**
+* Extract stack frames that reference user code (not node_modules,
+* not framework internals).
+*
+* Returns at most 5 frames to keep output concise.
+*/
+function extractUserFrames(stack) {
+	const lines = stack.split("\n");
+	const userFrames = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("at ")) continue;
+		if (trimmed.includes("node_modules") || trimmed.includes("<react-server-dom>") || trimmed.includes("<rsc-vendor>") || trimmed.includes("<vite-dep>") || trimmed.includes("node:internal")) continue;
+		userFrames.push(trimmed);
+		if (userFrames.length >= 5) break;
+	}
+	return userFrames;
+}
+//#endregion
+//#region src/server/default-logger.ts
+/**
+* DefaultLogger — human-readable stderr logging when no custom logger is configured.
+*
+* Ships as the fallback so production deployments always have error visibility,
+* even without an `instrumentation.ts` logger export. Output is one line per
+* event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+*
+* Format:
+*   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+*   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+*   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+*
+* Behavior:
+* - Suppressed entirely in dev mode (dev logging handles all output)
+* - `debug` suppressed unless TIMBER_DEBUG is set
+* - Replaced entirely when a custom logger is set via `setLogger()`
+*
+* See design/17-logging.md §"DefaultLogger"
+*/
+/**
+* Format data fields as `key=value` pairs for human-readable output.
+* - `error` key is serialized via formatSsrError for stack trace cleanup
+* - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+* - Other values are stringified inline
+*/
+function formatDataFields(data) {
+	if (!data) return "";
+	const parts = [];
+	let traceId;
+	for (const [key, value] of Object.entries(data)) {
+		if (key === "trace_id") {
+			traceId = typeof value === "string" ? value : String(value);
+			continue;
+		}
+		if (key === "error") {
+			parts.push(`error=${formatSsrError(value)}`);
+			continue;
+		}
+		if (value === void 0 || value === null) continue;
+		parts.push(`${key}=${value}`);
+	}
+	if (traceId) parts.push(`trace_id=${traceId.slice(0, 8)}`);
+	return parts.length > 0 ? "  " + parts.join("  ") : "";
+}
+/** Pad level string to fixed width for alignment. */
+function padLevel(level) {
+	return level.padEnd(5);
+}
+function createDefaultLogger() {
+	return {
+		error(msg, data) {
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("ERROR")}  ${msg}${fields}\n`);
+		},
+		warn(msg, data) {
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("WARN")}  ${msg}${fields}\n`);
+		},
+		info(msg, data) {
+			if (isDevMode()) return;
+			if (!isDebug()) return;
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("INFO")}  ${msg}${fields}\n`);
+		},
+		debug(msg, data) {
+			if (isDevMode()) return;
+			if (!isDebug()) return;
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("DEBUG")}  ${msg}${fields}\n`);
+		}
+	};
+}
+//#endregion
+//#region src/server/waituntil-bridge.ts
+/**
+* Per-request waitUntil bridge — ALS bridge for platform adapters.
+*
+* The generated entry point (Nitro, Cloudflare) wraps the handler with
+* `runWithWaitUntil`, binding the platform's lifecycle extension function
+* (e.g., h3's `event.waitUntil()` or CF's `ctx.waitUntil()`) for the
+* request duration. The `waitUntil()` primitive reads from this ALS to
+* dispatch background work to the correct platform API.
+*
+* Design doc: design/11-platform.md §"waitUntil()"
+*/
+/**
+* Get the current request's waitUntil function, if available.
+*
+* Returns undefined when no platform adapter has installed a waitUntil
+* handler for the current request (e.g., on platforms that don't support
+* lifecycle extension, or outside a request context).
+*/
+function getWaitUntil() {
+	return waitUntilAls.getStore();
+}
+//#endregion
+//#region src/server/cookie-parsing.ts
+var import_dist = require_dist();
+/**
+* Parse a Cookie header string into a Map of name → value pairs.
+* Follows RFC 6265 §4.2.1: cookies are semicolon-separated key=value pairs.
+*
+* Values are auto-decoded with `decodeURIComponent` so they round-trip
+* losslessly with `getCookies().set()` (which auto-encodes). Malformed
+* `%`-escapes from third-party cookies fall back to the raw byte sequence
+* — the parser must be total over arbitrary inbound headers, including
+* non-conforming values from other servers, browser extensions, etc.
+*/
+function parseCookieHeader(header) {
+	const map = /* @__PURE__ */ new Map();
+	if (!header) return map;
+	const parsed = (0, import_dist.parseCookie)(header);
+	for (const name in parsed) {
+		const value = parsed[name];
+		if (value !== void 0) map.set(name, value);
+	}
+	return map;
+}
+/**
+* Decode a single cookie value with `decodeURIComponent`, falling back to
+* the raw byte sequence if the input contains a malformed `%`-escape.
+*
+* Used by both `parseCookieHeader` (incoming Cookie: header) and the
+* `setRaw` forwarding path (outgoing Set-Cookie from upstream services).
+* Total — never throws.
+*
+* cookie's internal decode has identical semantics but is not exported,
+* so we keep this standalone helper.
+*/
+function safeDecodeCookieValue(raw) {
+	try {
+		return decodeURIComponent(raw);
+	} catch {
+		return raw;
+	}
+}
+/**
+* Serialize a CookieEntry into a Set-Cookie header value.
+*
+* Total — never throws. If the cookie package's serializer rejects
+* the input (e.g. non-integer maxAge, forbidden chars in name/value),
+* falls back to a minimal hand-rolled serialization so the response
+* path is never interrupted by a codec error.
+*/
+function serializeCookieEntry(entry) {
+	try {
+		return (0, import_dist.stringifySetCookie)({
+			name: entry.name,
+			value: entry.value,
+			domain: entry.options.domain,
+			path: entry.options.path,
+			expires: entry.options.expires,
+			maxAge: entry.options.maxAge,
+			httpOnly: entry.options.httpOnly,
+			secure: entry.options.secure,
+			sameSite: entry.options.sameSite,
+			partitioned: entry.options.partitioned
+		}, { encode: (v) => v });
+	} catch {
+		return serializeCookieEntryFallback(entry);
+	}
+}
+function serializeCookieEntryFallback(entry) {
+	const parts = [`${entry.name}=${entry.value}`];
+	const opts = entry.options;
+	if (opts.domain) parts.push(`Domain=${opts.domain}`);
+	if (opts.path) parts.push(`Path=${opts.path}`);
+	if (opts.expires) parts.push(`Expires=${opts.expires.toUTCString()}`);
+	if (opts.maxAge !== void 0) parts.push(`Max-Age=${opts.maxAge}`);
+	if (opts.httpOnly) parts.push("HttpOnly");
+	if (opts.secure) parts.push("Secure");
+	if (opts.sameSite) parts.push(`SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`);
+	if (opts.partitioned) parts.push("Partitioned");
+	return parts.join("; ");
+}
+/**
+* Parse a raw `Set-Cookie` header string into name, value, and options.
+* Handles all standard attributes: Path, Domain, Max-Age, Expires,
+* SameSite, Secure, HttpOnly, Partitioned.
+*
+* Does NOT apply DEFAULT_COOKIE_OPTIONS — the caller decides whether
+* to merge defaults (e.g. `set()` does, but `setRaw()` should preserve
+* the original header's intent).
+*/
+function parseSetCookie(header) {
+	const parsed = (0, import_dist.parseSetCookie)(header, { decode: (v) => v });
+	if (!parsed.name) return null;
+	const options = {};
+	if (parsed.path !== void 0) options.path = parsed.path || "/";
+	if (parsed.domain !== void 0) options.domain = parsed.domain;
+	if (parsed.maxAge !== void 0 && Number.isFinite(parsed.maxAge)) options.maxAge = parsed.maxAge;
+	if (parsed.expires !== void 0) options.expires = parsed.expires;
+	if (parsed.sameSite !== void 0 && parsed.sameSite !== true) {
+		const sameSite = parsed.sameSite.toLowerCase();
+		if (sameSite === "strict" || sameSite === "lax" || sameSite === "none") options.sameSite = sameSite;
+	}
+	if (parsed.secure) options.secure = true;
+	if (parsed.httpOnly) options.httpOnly = true;
+	if (parsed.partitioned) options.partitioned = true;
+	return {
+		name: parsed.name,
+		value: parsed.value ?? "",
+		options
+	};
+}
+//#endregion
+//#region src/server/cookie-context.ts
+/**
+* Cookie Context — per-request cookie API and on-the-wire helpers.
+*
+* Split out of `request-context.ts` (TIM-853) so the cookie subsystem
+* — encoding contract, options grammar, parser, serializer, RYW map,
+* and rerender seed — lives in one file. The headers/scope/params APIs
+* stay in `request-context.ts` and call into this module via the
+* exported helpers.
+*
+* See design/29-cookies.md for the encoding contract and read-your-own-
+* writes semantics. See ONGOING_SECURITY.md H-3 (TIM-868) for the
+* smuggling primitive that the encoding contract closes.
+*/
+/**
+* Returns a cookie accessor for the current request.
+*
+* Available in middleware, access checks, server components, and server actions.
+* Throws if called outside a request context (security principle #2: no global fallback).
+*
+* Read methods (.get, .has, .getAll) are always available and reflect
+* read-your-own-writes from .set() calls in the same request.
+*
+* Mutation methods (.set, .delete, .clear) are only available in mutable
+* contexts (middleware.ts, server actions, route.ts handlers). Calling them
+* in read-only contexts (access.ts, server components) throws.
+*
+* This is the escape hatch for direct cookie jar operations. For typed
+* cookie access, use `defineCookie()` instead.
+*
+* See design/29-cookies.md
+*/
+function getCookieJar() {
+	const store = requestContextAls.getStore();
+	if (!store) throw new Error("[timber] getCookieJar() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
+	if (!store.parsedCookies) store.parsedCookies = parseCookieHeader(store.cookieHeader);
+	const map = store.parsedCookies;
+	return {
+		get(name) {
+			return map.get(name);
+		},
+		has(name) {
+			return map.has(name);
+		},
+		getAll() {
+			return Array.from(map.entries()).map(([name, value]) => ({
+				name,
+				value
+			}));
+		},
+		get size() {
+			return map.size;
+		},
+		set(name, value, options) {
+			assertMutable(store, "set");
+			assertValidCookieName(name);
+			if (typeof value !== "string") throw new Error(`[timber] getCookieJar().set(${JSON.stringify(name)}, …): value must be a string, got ${typeof value}.\n  To store a JSON-serializable value, use defineCookie + jsonCookieCodec:\n\n    import { defineCookie, jsonCookieCodec } from '@timber-js/app/cookies';\n\n    export const ${name}Cookie = defineCookie(${JSON.stringify(name)}, {\n      codec: jsonCookieCodec(),\n    });\n\n    ${name}Cookie.set(value);\n\n  See design/29-cookies.md §"Typed Cookies with Schema Validation".`);
+			const raw = options?.raw === true;
+			const wireValue = raw ? value : encodeURIComponent(value);
+			if (raw) assertValidCookieValue(name, wireValue);
+			if (store.flushed) {
+				if (isDebug()) console.warn(`[timber] warn: getCookieJar().set('${name}') called after response headers were committed.\n  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n  or a route.ts handler.`);
+				return;
+			}
+			const { raw: _raw, ...attributeOptions } = options ?? {};
+			const opts = {
+				...DEFAULT_COOKIE_OPTIONS,
+				...attributeOptions
+			};
+			assertValidCookieOptions(opts);
+			store.cookieJar.set(name, {
+				name,
+				value: wireValue,
+				options: opts
+			});
+			map.set(name, raw ? wireValue : value);
+		},
+		setFromHeaders(headers) {
+			assertMutable(store, "setFromHeaders");
+			if (store.flushed) {
+				console.warn("[timber] warn: getCookieJar().setFromHeaders() called after response headers were committed.\n  The cookies will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n  or a route.ts handler.");
+				return;
+			}
+			for (const raw of headers.getSetCookie()) {
+				const parsed = parseSetCookie(raw);
+				if (parsed) setRaw(store, map, parsed.name, parsed.value, parsed.options);
+			}
+		},
+		delete(name, options) {
+			assertMutable(store, "delete");
+			assertValidCookieName(name);
+			if (store.flushed) {
+				if (isDebug()) console.warn(`[timber] warn: getCookieJar().delete('${name}') called after response headers were committed.\n  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\n  or a route.ts handler.`);
+				return;
+			}
+			const opts = {
+				...DEFAULT_COOKIE_OPTIONS,
+				...options,
+				maxAge: 0,
+				expires: /* @__PURE__ */ new Date(0)
+			};
+			assertValidCookieOptions(opts);
+			store.cookieJar.set(name, {
+				name,
+				value: "",
+				options: opts
+			});
+			map.delete(name);
+		},
+		clear() {
+			assertMutable(store, "clear");
+			if (store.flushed) return;
+			for (const name of Array.from(map.keys())) store.cookieJar.set(name, {
+				name,
+				value: "",
+				options: {
+					...DEFAULT_COOKIE_OPTIONS,
+					maxAge: 0,
+					expires: /* @__PURE__ */ new Date(0)
+				}
+			});
+			map.clear();
+		},
+		toString() {
+			return Array.from(map.entries()).map(([name, value]) => `${name}=${encodeURIComponent(value)}`).join("; ");
+		}
+	};
+}
+/**
+* Returns the value of a single cookie, or undefined if absent.
+*
+* @internal — not part of the public API. Use `defineCookie().get()` or `getCookieJar().get()` instead.
+*/
+function getCookie(name) {
+	return getCookieJar().get(name);
+}
+var DEFAULT_COOKIE_OPTIONS = {
+	path: "/",
+	httpOnly: true,
+	secure: true,
+	sameSite: "lax"
+};
+/**
+* Per-request seed map of cookie name → value, registered out-of-band so the
+* pipeline's `runWithRequestContext` call can pick it up without changing
+* the function's calling convention. Stored in a WeakMap keyed by the
+* synthetic Request object built for the rerender path, so the seed lives
+* exactly as long as the request and is collected with it.
+*
+* The seed exists to eliminate the parse/serialize round-trip on the no-JS
+* form-rerender path — see ONGOING_SECURITY.md H-3 (TIM-868). The action's
+* post-mutation RYW snapshot is threaded directly into the rerender scope's
+* `parsedCookies` map, bypassing `parseCookieHeader` entirely.
+*/
+var seededRequestCookies = /* @__PURE__ */ new WeakMap();
+/**
+* Pop the seed (if any) for `req` and return it. Called from
+* `runWithRequestContext` exactly once per request — the seed is consumed
+* eagerly so it cannot leak into a hypothetical future re-use of the same
+* Request reference.
+*
+* @internal — framework use only.
+*/
+function consumeSeededCookies(req) {
+	const seed = seededRequestCookies.get(req);
+	if (seed) seededRequestCookies.delete(req);
+	return seed;
+}
+/**
+* Collect all Set-Cookie headers from the cookie jar.
+* Called by the framework at flush time to apply cookies to the response.
+*
+* Returns an array of serialized Set-Cookie header values.
+*/
+function getSetCookieHeaders() {
+	const store = requestContextAls.getStore();
+	if (!store) return [];
+	return Array.from(store.cookieJar.values()).map(serializeCookieEntry);
+}
+/** Throw if cookie mutation is attempted in a read-only context. */
+function assertMutable(store, method) {
+	if (!store.mutableContext) throw new Error(`[timber] getCookieJar().${method}() cannot be called in this context.\n  Set cookies in middleware.ts, server actions, or route.ts handlers.`);
+}
+/**
+* Write a cookie to the jar WITHOUT merging DEFAULT_COOKIE_OPTIONS.
+* Used by setFromHeaders to preserve the original header's attributes exactly.
+*
+* For deletion cookies (maxAge=0), the jar entry is still created so the
+* Set-Cookie header is emitted, but the cookie is NOT added to the read map
+* (it would be misleading — the cookie is being deleted).
+*/
+function setRaw(store, readMap, name, value, options) {
+	assertValidCookieName(name);
+	assertValidCookieValue(name, value);
+	assertValidCookieOptions(options);
+	store.cookieJar.set(name, {
+		name,
+		value,
+		options
+	});
+	if (options.maxAge === 0) readMap.delete(name);
+	else readMap.set(name, safeDecodeCookieValue(value));
+}
+//#endregion
+//#region src/server/request-context.ts
+/**
+* Request Context — per-request ALS store for headers, search params,
+* segment params, and request scope lifecycle.
+*
+* Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage
+* instance, public accessor functions that throw outside request scope,
+* and a framework-internal `runWithRequestContext()` to establish scope.
+*
+* Cookie state lives in `cookie-context.ts` (split out in TIM-853). The
+* scope set up here owns the cookie jar / parsedCookies fields on the
+* store, but the cookie API and helpers are in the cookie module.
+*
+* See design/04-authorization.md §"AccessContext does not include cookies or headers"
+* and design/11-platform.md §"AsyncLocalStorage".
+*/
+/**
+* Returns a read-only view of the current request's headers.
+*
+* Available in middleware, access checks, server components, and server actions.
+* Throws if called outside a request context (security principle #2: no global fallback).
+*/
+function getHeaders() {
+	const store = requestContextAls.getStore();
+	if (!store) throw new Error("[timber] getHeaders() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
+	return store.headers;
+}
+/**
+* Returns the value of a single request header, or undefined if absent.
+*
+* Thin wrapper over `getHeaders().get(name)` for the common case where
+* you need exactly one header.
+*
+* @internal — not part of the public API. Use `getHeaders().get(name)` instead.
+*/
+function getHeader(name) {
+	return getHeaders().get(name) ?? void 0;
+}
+/**
+* Returns the current request's raw URLSearchParams.
+*
+* @internal — not part of the public API. Use `defineSearchParams().get()` instead.
+*/
+function getSearchParams() {
+	const store = requestContextAls.getStore();
+	if (!store) throw new Error("[timber] getSearchParams() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
+	return store.searchParams;
+}
+_setGetSearchParamsFn(getSearchParams);
+_setGetSegmentParamsFn(getSegmentParams);
+/**
+* Returns the current request's coerced segment params.
+*
+* The optional `segmentPath` argument exists only for TypeScript narrowing —
+* it does not affect the runtime return value. Pass a segment path
+* (e.g. `'/(browse)/[artistSlug]/[year]'`) to narrow the return type to the
+* exact params shape for that segment.
+*
+* Without an argument, returns all coerced params with optional types.
+*
+* See design/41-global-params.md §Function Signatures
+*/
+function getSegmentParams(segmentPath) {
+	const store = requestContextAls.getStore();
+	if (!store) throw new Error("[timber] getSegmentParams() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
+	if (!store.segmentParams) throw new Error("[timber] getSegmentParams() called before route matching completed. Segment params are not available until after the route is matched.");
+	if (segmentPath && store.slotParamsMap?.has(segmentPath)) {
+		const slotParams = store.slotParamsMap.get(segmentPath);
+		return {
+			...store.segmentParams,
+			...slotParams
+		};
+	}
+	if (segmentPath && isDebug() && store.matchedSegmentPath) {
+		const expected = extractDynamicSegments(segmentPath);
+		const actual = extractDynamicSegments(store.matchedSegmentPath);
+		const missing = expected.filter((s) => !actual.includes(s));
+		if (missing.length > 0) console.warn(`[timber] getSegmentParams('${segmentPath}') called but current segment is '${store.matchedSegmentPath}'\n  Missing params: ${missing.join(", ")}\n  These will be undefined at runtime despite the type annotation.`);
+	}
+	return store.segmentParams;
+}
+/**
+* Set the segment params on the current request context.
+* Called by the pipeline after route matching and param coercion.
+*
+* @internal — framework use only
+*/
+function setSegmentParams(params) {
+	const store = requestContextAls.getStore();
+	if (!store) throw new Error("[timber] setSegmentParams() called outside of a request context.");
+	store.segmentParams = params;
+}
+/**
+* Store the matched segment path (e.g. '/(browse)/[artistSlug]/[year]') for
+* dev-mode validation in getSegmentParams().
+*
+* @internal — framework use only
+*/
+function setMatchedSegmentPath(segmentPath) {
+	const store = requestContextAls.getStore();
+	if (!store) return;
+	store.matchedSegmentPath = segmentPath;
+}
+/**
+* Extract dynamic segment names from a route pattern.
+* '/[artistSlug]/[year]' → ['artistSlug', 'year']
+* '/docs/[...slug]'      → ['slug']
+*/
+function extractDynamicSegments(route) {
+	const segments = [];
+	const re = /\[{1,2}\.{0,3}(\w+)\]{1,2}/g;
+	let m;
+	while ((m = re.exec(route)) !== null) segments.push(m[1]);
+	return segments;
+}
+/**
+* Returns the raw search string from the current request URL (e.g. "?foo=bar").
+* Synchronous — safe for use in `redirect()` which throws synchronously.
+*
+* Returns empty string if called outside a request context (non-throwing for
+* use in redirect's optional preserveSearchParams path).
+*
+* @internal — used by redirect() for preserveSearchParams support.
+*/
+function getRequestSearchString() {
+	return requestContextAls.getStore()?.searchString ?? "";
+}
+/**
+* Run a callback within a request context. Used by the pipeline to establish
+* per-request ALS scope so that `getHeaders()` and `getCookies()` work.
+*
+* If the request was previously registered via `seedRequestCookies`, the
+* resulting context's `parsedCookies` map is initialized from the seed and
+* the raw `cookieHeader` is left empty — `parseCookieHeader` is never called
+* for that request. This is the no-JS form-rerender path. See TIM-868.
+*
+* @param req - The incoming Request object.
+* @param fn - The function to run within the request context.
+*/
+function runWithRequestContext(req, fn) {
+	const originalCopy = new Headers(req.headers);
+	const parsedUrl = new URL(req.url);
+	const seed = consumeSeededCookies(req);
+	const store = {
+		headers: freezeHeaders(req.headers),
+		originalHeaders: originalCopy,
+		cookieHeader: seed ? "" : req.headers.get("cookie") ?? "",
+		parsedCookies: seed,
+		searchParams: parsedUrl.searchParams,
+		searchString: parsedUrl.search,
+		cookieJar: /* @__PURE__ */ new Map(),
+		flushed: false,
+		mutableContext: false
+	};
+	return requestContextAls.run(store, fn);
+}
+/**
+* Enable cookie mutation for the current context. Called by the framework
+* when entering middleware.ts, server actions, or route.ts handlers.
+*
+* See design/29-cookies.md §"Context Tracking"
+*/
+function setMutableCookieContext(mutable) {
+	const store = requestContextAls.getStore();
+	if (store) store.mutableContext = mutable;
+}
+/**
+* Mark the response as flushed (headers committed). After this point,
+* cookie mutations log a warning instead of throwing.
+*
+* See design/29-cookies.md §"Streaming Constraint: Post-Flush Cookie Warning"
+*/
+function markResponseFlushed() {
+	const store = requestContextAls.getStore();
+	if (store) store.flushed = true;
+}
+/**
+* Apply middleware-injected request headers to the current request context.
+*
+* Called by the pipeline after middleware.ts runs. Merges overlay headers
+* on top of the original request headers so downstream code (access.ts,
+* server components, server actions) sees them via `getHeaders()`.
+*
+* The original request headers are never mutated — a new frozen Headers
+* object is created with the overlay applied on top.
+*
+* See design/07-routing.md §"Request Header Injection"
+*/
+function applyRequestHeaderOverlay(overlay) {
+	const store = requestContextAls.getStore();
+	if (!store) throw new Error("[timber] applyRequestHeaderOverlay() called outside of a request context.");
+	let hasOverlay = false;
+	overlay.forEach(() => {
+		hasOverlay = true;
+	});
+	if (!hasOverlay) return;
+	const merged = new Headers(store.originalHeaders);
+	overlay.forEach((value, key) => {
+		merged.set(key, value);
+	});
+	store.headers = freezeHeaders(merged);
+}
+var MUTATING_METHODS = /* @__PURE__ */ new Set([
+	"set",
+	"append",
+	"delete"
+]);
+/**
+* Wrap a Headers object in a Proxy that throws on mutating methods.
+* Object.freeze doesn't work on Headers (native internal slots), so we
+* intercept property access and reject set/append/delete at runtime.
+*
+* Read methods (get, has, entries, etc.) must be bound to the underlying
+* Headers instance because they access private #headersList slots.
+*/
+function freezeHeaders(source) {
+	const copy = new Headers(source);
+	return new Proxy(copy, { get(target, prop) {
+		if (typeof prop === "string" && MUTATING_METHODS.has(prop)) return () => {
+			throw new Error(`[timber] getHeaders() returns a read-only Headers object. Calling .${prop}() is not allowed. Use ctx.requestHeaders in middleware to inject headers for downstream components.`);
+		};
+		const value = Reflect.get(target, prop);
+		if (typeof value === "function") return value.bind(target);
+		return value;
+	} });
+}
+//#endregion
+//#region src/shared/redirect-type.ts
+/**
+* Next.js redirect type discriminator.
+*
+* Provided for API compatibility with libraries that import `RedirectType`
+* from `next/navigation`. In timber, `redirect()` always uses `replace`
+* semantics (no history entry for the redirect itself).
+*
+* Lives in shared/ (isomorphic) so both the server primitives and the
+* client-only next/navigation shim export the same definition without the
+* client shim pulling in server code.
+*/
+var RedirectType = {
+	push: "push",
+	replace: "replace"
+};
+//#endregion
+//#region src/server/primitives.ts
+/**
+* Check if a value is JSON-serializable without data loss.
+* Returns a description of the first non-serializable value found, or null if OK.
+*
+* @internal Exported for testing only.
+*/
+function findNonSerializable(value, path = "data") {
+	if (value === null || value === void 0) return null;
+	switch (typeof value) {
+		case "string":
+		case "number":
+		case "boolean": return null;
+		case "bigint": return `${path} contains a BigInt — BigInt throws in JSON.stringify`;
+		case "function": return `${path} is a function — functions are not JSON-serializable`;
+		case "symbol": return `${path} is a symbol — symbols are not JSON-serializable`;
+		case "object": break;
+		default: return `${path} has unsupported type "${typeof value}"`;
+	}
+	if (value instanceof Date) return `${path} is a Date — Dates silently coerce to strings in JSON.stringify`;
+	if (value instanceof Map) return `${path} is a Map — Maps serialize as {} in JSON.stringify (data loss)`;
+	if (value instanceof Set) return `${path} is a Set — Sets serialize as {} in JSON.stringify (data loss)`;
+	if (value instanceof RegExp) return `${path} is a RegExp — RegExps serialize as {} in JSON.stringify`;
+	if (value instanceof Error) return `${path} is an Error — Errors serialize as {} in JSON.stringify`;
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			const result = findNonSerializable(value[i], `${path}[${i}]`);
+			if (result) return result;
+		}
+		return null;
+	}
+	const proto = Object.getPrototypeOf(value);
+	if (proto === null) return `${path} is a null-prototype object — React Flight rejects null prototypes`;
+	if (proto !== Object.prototype) return `${path} is a ${value.constructor?.name ?? "unknown"} instance — class instances may lose data in JSON.stringify`;
+	for (const key of Object.keys(value)) {
+		const result = findNonSerializable(value[key], `${path}.${key}`);
+		if (result) return result;
+	}
+	return null;
+}
+/**
+* Emit a dev-mode warning if data is not JSON-serializable.
+* No-op in production.
+*/
+function warnIfNotSerializable(data, callerName) {
+	if (!isDebug()) return;
+	if (data === void 0) return;
+	const issue = findNonSerializable(data);
+	if (issue) console.warn(`[timber] ${callerName}: ${issue}. Data passed to deny() or RenderError must be JSON-serializable because the post-flush path uses JSON.stringify, not React Flight.`);
+}
+/**
+* Render-phase signal thrown by `deny()`. Caught by the framework to produce
+* the correct HTTP status code (segment context) or graceful degradation (slot context).
+*/
+var DenySignal = class extends Error {
+	status;
+	data;
+	constructor(status, data) {
+		super(`Access denied with status ${status}`);
+		this.name = "DenySignal";
+		this.status = status;
+		this.data = data;
+	}
+	/**
+	* Extract the file that called deny() from the stack trace.
+	* Returns a short path (e.g. "app/auth/access.ts") or undefined if
+	* the stack can't be parsed. Dev-only — used for dev log output.
+	*/
+	get sourceFile() {
+		if (!this.stack) return void 0;
+		const frames = this.stack.split("\n");
+		for (let i = 2; i < frames.length; i++) {
+			const frame = frames[i];
+			if (!frame) continue;
+			if (frame.includes("primitives.ts") || frame.includes("node_modules")) continue;
+			const match = frame.match(/\(([^)]+?)(?::\d+:\d+)\)/) ?? frame.match(/at\s+([^\s]+?)(?::\d+:\d+)/);
+			if (match?.[1]) {
+				const full = match[1];
+				const appIdx = full.indexOf("/app/");
+				return appIdx >= 0 ? full.slice(appIdx + 1) : full;
+			}
+		}
+	}
+};
+/**
+* Universal denial/error primitive. Throws a `DenySignal` that the framework catches.
+*
+* - In segment context (outside Suspense): produces HTTP status code
+* - In slot context: graceful degradation → denied.tsx → default.tsx → null
+* - Inside Suspense (hold window): promoted to pre-flush behavior
+* - Inside Suspense (after flush): error boundary + noindex meta
+*
+* Supports both positional and object signatures:
+* ```ts
+* deny()                                          // 403 (default)
+* deny(404)                                       // 404
+* deny(503, { retry: true })                      // 503 with data
+* deny({ status: 503, message: 'Maintenance' })   // object form
+* ```
+*
+* Accepts any 4xx or 5xx status code. This replaces the need for
+* `throw new RenderError(...)` in user code — RenderError is now an
+* internal pipeline detail.
+*
+* @param statusOrOptions - Status code (number) or options object. Default: 403.
+* @param data - Optional JSON-serializable data (positional form only).
+*/
+function deny(statusOrOptions, data) {
+	let status;
+	let resolvedData;
+	if (typeof statusOrOptions === "object" && statusOrOptions !== null) {
+		status = statusOrOptions.status ?? 403;
+		resolvedData = statusOrOptions.data;
+	} else {
+		status = statusOrOptions ?? 403;
+		resolvedData = data;
+	}
+	if (status < 400 || status > 599) throw new Error(`deny() requires a 4xx or 5xx status code, got ${status}.`);
+	warnIfNotSerializable(resolvedData, "deny()");
+	throw new DenySignal(status, resolvedData);
+}
+/**
+* Render-phase signal thrown by `redirect()` and `redirectExternal()`.
+* Caught by the framework to produce a 3xx response or client-side navigation.
+*/
+var RedirectSignal = class extends Error {
+	location;
+	status;
+	constructor(location, status) {
+		super(`Redirect to ${location}`);
+		this.name = "RedirectSignal";
+		this.location = location;
+		this.status = status;
+	}
+};
+/**
+* Returns true if the error is a framework control-flow signal (RedirectSignal
+* or DenySignal) rather than a genuine application error. Works both for direct
+* instances (RSC-side) and deserialized digest errors (SSR cross-boundary).
+*
+* See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
+*/
+function isControlFlowSignal(error) {
+	if (error instanceof DenySignal || error instanceof RedirectSignal) return true;
+	if (error && typeof error === "object") {
+		const digest = error.digest;
+		if (typeof digest === "string") try {
+			const parsed = JSON.parse(digest);
+			if (parsed && typeof parsed === "object") return parsed.type === "redirect" || parsed.type === "deny";
+		} catch {}
+	}
+	return false;
+}
+/**
+* Redirect to a relative path. Rejects absolute and protocol-relative URLs.
+* Use `redirectExternal()` for external redirects with an allow-list.
+*
+* @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
+* @param statusOrOptions - HTTP status code (3xx, default 302) or options object.
+*
+* @example
+* // Simple redirect
+* redirect('/login');
+*
+* // With status code
+* redirect('/login', 301);
+*
+* // With preserved search params
+* redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
+*/
+function redirect(path, statusOrOptions) {
+	let status;
+	let preserveSearchParams;
+	if (typeof statusOrOptions === "number") status = statusOrOptions;
+	else if (statusOrOptions) {
+		status = statusOrOptions.status ?? (statusOrOptions.permanent ? 308 : 302);
+		preserveSearchParams = statusOrOptions.preserveSearchParams;
+	} else status = 302;
+	if (status < 300 || status > 399) throw new Error(`redirect() requires a 3xx status code, got ${status}.`);
+	assertRelativeRedirectPath(path);
+	let resolvedPath = path;
+	if (preserveSearchParams) resolvedPath = mergePreservedSearchParams(path, getRequestSearchString(), preserveSearchParams);
+	throw new RedirectSignal(resolvedPath, status);
+}
+/**
+* Redirect to an external URL. The origin must be in the provided allow-list.
+*
+* Only http: and https: schemes are permitted. The allow-list is matched
+* against full origins (scheme + host + port), not bare hostnames.
+*
+* @param url - Absolute URL to redirect to.
+* @param allowList - Array of allowed origins (e.g. ['https://example.com', 'https://auth.example.com']).
+* @param status - HTTP redirect status code (3xx). Defaults to 302.
+*/
+function redirectExternal(url, allowList, status = 302) {
+	if (status < 300 || status > 399) throw new Error(`redirectExternal() requires a 3xx status code, got ${status}.`);
+	throw new RedirectSignal(validateExternalRedirectUrl(url, allowList), status);
+}
+/**
+* Typed throw for render-phase errors that carry structured context to error boundaries.
+*
+* The `digest` (code + data) is serialized into the RSC stream separately from the
+* Error instance — only the digest crosses the RSC → client boundary.
+*
+* @example
+* ```ts
+* throw new RenderError('PRODUCT_NOT_FOUND', {
+*   title: 'Product not found',
+*   resourceId: params.id,
+* })
+* ```
+*/
+var RenderError = class extends Error {
+	code;
+	digest;
+	status;
+	constructor(code, data, options) {
+		super(`RenderError: ${code}`);
+		this.name = "RenderError";
+		this.code = code;
+		this.digest = {
+			code,
+			data
+		};
+		warnIfNotSerializable(data, "RenderError");
+		const status = options?.status ?? 500;
+		if (status < 400 || status > 599) throw new Error(`RenderError status must be 4xx or 5xx, got ${status}.`);
+		this.status = status;
+	}
+};
+var _waitUntilWarned = false;
+/**
+* Register a promise to be kept alive after the response is sent.
+* Maps to `ctx.waitUntil()` on Cloudflare Workers and similar platforms.
+*
+* In production, the platform adapter installs a per-request waitUntil
+* function via ALS (see waituntil-bridge.ts). This function checks the
+* ALS bridge first, then falls back to the legacy adapter argument.
+*
+* If neither is available, a warning is logged once and the promise is
+* left to resolve (or reject) without being tracked.
+*
+* @param promise - The background work to keep alive.
+* @param adapter - Optional legacy adapter (prefer ALS bridge in production).
+*/
+function waitUntil(promise, adapter) {
+	const alsFn = getWaitUntil();
+	if (alsFn) {
+		alsFn(promise);
+		return;
+	}
+	if (adapter && typeof adapter.waitUntil === "function") {
+		adapter.waitUntil(promise);
+		return;
+	}
+	if (!_waitUntilWarned) {
+		_waitUntilWarned = true;
+		console.warn("[timber] waitUntil() is not supported by the current adapter. Background work will not be tracked. This warning is shown once.");
+	}
+}
+//#endregion
+//#region src/server/logger.ts
+/**
+* Logger — structured logging with environment-aware formatting.
+*
+* timber.js ships a DefaultLogger that writes human-readable lines to stderr
+* in production. Users can export a custom logger from instrumentation.ts to
+* replace it with pino, winston, or any TimberLogger-compatible object.
+*
+* See design/17-logging.md §"Production Logging"
+*/
+var _logger = createDefaultLogger();
+/**
+* Set the user-provided logger. Called by the instrumentation loader
+* when it finds a `logger` export in instrumentation.ts. Replaces
+* the DefaultLogger entirely.
+*/
+function setLogger(logger) {
+	_logger = logger;
+}
+/**
+* Get the current logger. Always non-null — returns DefaultLogger when
+* no custom logger is configured.
+*/
+function getLogger() {
+	return _logger;
+}
+/**
+* Inject trace_id and span_id into log data for log–trace correlation.
+* Always injects trace_id (never undefined). Injects span_id only when OTEL is active.
+*/
+function withTraceContext(data) {
+	const store = getTraceStore();
+	const enriched = { ...data };
+	if (store) {
+		enriched.trace_id = store.traceId;
+		if (store.spanId) enriched.span_id = store.spanId;
+	}
+	return enriched;
+}
+/** Log a completed request. Level: info. */
+function logRequestCompleted(data) {
+	_logger.info("request completed", withTraceContext(data));
+}
+/** Log request received. Level: debug. */
+function logRequestReceived(data) {
+	_logger.debug("request received", withTraceContext(data));
+}
+/** Log a slow request warning. Level: warn. */
+function logSlowRequest(data) {
+	_logger.warn("slow request exceeded threshold", withTraceContext(data));
+}
+/** Log middleware short-circuit. Level: debug. */
+function logMiddlewareShortCircuit(data) {
+	_logger.debug("middleware short-circuited", withTraceContext(data));
+}
+/** Log unhandled error in middleware phase. Level: error. */
+function logMiddlewareError(data) {
+	if (isControlFlowSignal(data.error)) return;
+	_logger.error("unhandled error in middleware phase", withTraceContext(data));
+}
+/** Log unhandled render-phase error. Level: error. */
+function logRenderError(data) {
+	if (isControlFlowSignal(data.error)) return;
+	_logger.error("unhandled render-phase error", withTraceContext(data));
+}
+/** Log proxy.ts uncaught error. Level: error. */
+function logProxyError(data) {
+	_logger.error("proxy.ts threw uncaught error", withTraceContext(data));
+}
+/** Log unhandled error in route handler. Level: error. */
+function logRouteError(data) {
+	if (isControlFlowSignal(data.error)) return;
+	_logger.error("unhandled route handler error", withTraceContext(data));
+}
+/** Log waitUntil() adapter missing (once at startup). Level: warn. */
+function logWaitUntilUnsupported() {
+	_logger.warn("adapter does not support waitUntil()");
+}
+/** Log waitUntil() promise rejection. Level: warn. */
+function logWaitUntilRejected(data) {
+	_logger.warn("waitUntil() promise rejected", withTraceContext(data));
+}
+/** Log staleWhileRevalidate refetch failure. Level: warn. */
+function logSwrRefetchFailed(data) {
+	_logger.warn("staleWhileRevalidate refetch failed", withTraceContext(data));
+}
+/** Log cache miss. Level: debug. */
+function logCacheMiss(data) {
+	_logger.debug("timber.cache MISS", withTraceContext(data));
+}
+/**
+* Log an intentionally swallowed error. Provides observability into catch
+* blocks that are deliberately empty — the error is consumed, never rethrown.
+*
+* Default level: `warn` in dev (so the overlay surfaces patterns), `debug`
+* in production (low noise unless TIMBER_DEBUG is set). Pass `opts.level`
+* to override.
+*
+* **Infallible** — swallow() itself never throws, even if the logger is
+* broken. A thrown swallow would turn a benign catch into a crash.
+*/
+function swallow(err, reason, opts) {
+	try {
+		const level = opts?.level ?? (isDevMode() ? "warn" : "debug");
+		_logger[level](`swallowed: ${reason}`, withTraceContext({ error: err }));
+	} catch {}
+}
+//#endregion
+export { revalidationAls as $, runWithRequestContext as A, addSpanEvent as B, RedirectType as C, getSearchParams as D, getHeaders as E, getCookieJar as F, getTraceId as G, generateTraceId as H, getSetCookieHeaders as I, setSpanAttribute as J, replaceTraceId as K, getWaitUntil as L, setMutableCookieContext as M, setSegmentParams as N, getSegmentParams as O, getCookie as P, requestContextAls as Q, isDebug as R, waitUntil as S, getHeader as T, getOtelTraceId as U, addSpanEventSync as V, getSpanId as W, earlyHintsSenderAls as X, withSpan as Y, formFlashAls as Z, RedirectSignal as _, logProxyError as a, redirect as b, logRequestReceived as c, logSwrRefetchFailed as d, timingAls as et, logWaitUntilRejected as f, DenySignal as g, swallow as h, logMiddlewareShortCircuit as i, setMatchedSegmentPath as j, markResponseFlushed as k, logRouteError as l, setLogger as m, logCacheMiss as n, logRenderError as o, logWaitUntilUnsupported as p, runWithTraceId as q, logMiddlewareError as r, logRequestCompleted as s, getLogger as t, logSlowRequest as u, RenderError as v, applyRequestHeaderOverlay as w, redirectExternal as x, deny as y, isDevMode as z };
+
+//# sourceMappingURL=logger-CPoQkGK6.js.map