@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/dist/types/cache/cache-exec-scope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Execution-chain scope for "use cache" function bodies.
+ *
+ * The ambient guards (cookies(), headers(), ctx.set() reached via
+ * getRequestContext()) must fire for code running INSIDE a cached body and
+ * stay silent for everything else on the request. A property stamped on the
+ * shared RequestContext cannot express that: while a slow "use cache" body is
+ * in flight, every parallel read on the same request sees the stamp. Scar: a
+ * 2s cached product fetch running beside a sibling loader made the loader's
+ * cookies() read throw `cannot be called inside a "use cache" function` —
+ * same shared-object hazard as issue #684 plan 010, which fixed only the
+ * background-revalidation path. AsyncLocalStorage follows the cached body's
+ * own async chain, so parallel work is invisible to the guard while genuine
+ * in-body reads still throw.
+ *
+ * Deliberately NOT entered on the store-less bypass paths in cache-runtime.ts:
+ * there the body executes for real on every call, side effects take effect,
+ * and request-scoped reads are safe (see the bypass comments there).
+ *
+ * Kept separate from taint.ts so `node:async_hooks` stays out of that module —
+ * taint.ts is reachable from browser-bundled DSL helpers. The probe
+ * registration below wires assertNotInsideCacheExec to this scope without
+ * taint.ts importing it.
+ */
+/**
+ * Run fn with the "use cache" execution scope active. Continuations spawned
+ * from fn's synchronous kickoff inherit the scope; parallel chains do not.
+ */
+export declare function runWithCacheExecScope<T>(fn: () => T): T;
+/** True when the calling async chain is inside a "use cache" body. */
+export declare function isInsideCacheExecScope(): boolean;

package/dist/types/cache/cache-key-utils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared Cache Key Utilities
+ *
+ * Deterministic normalization of search params and route params
+ * for cache key generation. Used by cache-runtime, cache-scope,
+ * document-cache, and loader-cache.
+ */
+import type { SearchParamsFilter } from "./search-params-filter.js";
+/**
+ * Build a sorted, deterministic query string from URLSearchParams,
+ * excluding the router's reserved params (see isReservedSearchParam).
+ *
+ * `filter` is the compiled `cache.searchParams` config (search-params-filter.ts),
+ * applied AFTER the reserved-param exclusion and BEFORE the sort, so reserved
+ * params can never be re-included (`include: ["__no_cache"]` is a no-op) and
+ * surviving params stay order-insensitive. `undefined` means no filtering --
+ * that path must stay byte-identical to the pre-filter format (cacheKeyBase
+ * output is byte-stable by contract).
+ *
+ * Returns empty string when no user-facing params survive.
+ */
+export declare function sortedSearchString(searchParams: URLSearchParams, filter?: SearchParamsFilter): string;
+/**
+ * Build a sorted, deterministic string from route params.
+ *
+ * Returns empty string when params is empty or undefined.
+ */
+export declare function sortedRouteParams(params: Record<string, string> | undefined): string;
+/**
+ * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
+ *
+ * The ONE composition of the host-namespacing rule, shared by the segment tier
+ * (cache-scope.ts) and the document tier (document-cache.ts) so the rule cannot
+ * drift between them. Host prefixing matters because VercelCacheStore /
+ * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
+ * internally) -- on a single function serving multiple domains an
+ * un-namespaced key bleeds tenant A's cached response to tenant B.
+ *
+ * Output is BYTE-STABLE by contract: changing the composition silently
+ * invalidates every persisted cache entry on upgrade. Callers append their own
+ * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
+ */
+export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;

package/dist/types/cache/cache-policy.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared Cache Policy Utilities
+ *
+ * Resolution cascades for TTL, SWR, cache key, and cache store.
+ * Consolidates the multi-tier resolution pattern:
+ *   explicit option → store defaults → fallback constant
+ */
+import type { CacheDefaults, SegmentCacheStore } from "./types.js";
+import type { RequestContext } from "../server/request-context.js";
+/**
+ * Default TTL for route-level cache() DSL and loader cache.
+ * Applied when neither the cache options nor the store defaults specify a TTL.
+ */
+export declare const DEFAULT_ROUTE_TTL = 60;
+/**
+ * Default TTL for function-level "use cache" (setItem).
+ * Applied when neither the item options nor the store defaults specify a TTL.
+ */
+export declare const DEFAULT_FUNCTION_TTL = 900;
+/**
+ * A finite, non-negative seconds value? A NaN/Infinity ttl/swr (from a bad
+ * cache() option or store defaults) flows into computeExpiration ->
+ * staleAt/expiresAt = NaN, where every `now > NaN` is false so the entry never
+ * evicts and is served fresh forever; a negative value makes every read a miss.
+ * Shared with cache-scope.ts (the segment getters) so every cache path validates
+ * the same way. profile-registry.ts uses the same predicate but fails fast at
+ * config time; the resolvers here degrade because they run on the live path.
+ */
+export declare function isFiniteNonNegativeSeconds(value: number): boolean;
+/**
+ * Resolve effective TTL from the 3-tier cascade:
+ * explicit → store defaults → fallback. A non-finite/negative resolved value
+ * degrades to the fallback (loader cache and "use cache" setItem both resolve
+ * ttl here, so this is where those paths are guarded; the segment cache is
+ * guarded in cache-scope.ts).
+ */
+export declare function resolveTtl(explicit: number | undefined, defaults: CacheDefaults | undefined, fallback: number): number;
+/**
+ * Resolve effective SWR window from the 2-tier cascade:
+ * explicit → store defaults.
+ * Returns 0 when unset (no SWR window) or when the resolved value is
+ * non-finite/negative (degrade rather than feed bad math into expiry).
+ */
+export declare function resolveSwrWindow(explicit: number | undefined, defaults: CacheDefaults | undefined): number;
+/**
+ * Compute staleAt and expiresAt timestamps from TTL and SWR window.
+ *
+ * - staleAt: when the entry becomes stale (TTL boundary)
+ * - expiresAt: when the entry should be evicted (TTL + SWR)
+ *
+ * When swrWindow is 0, staleAt === expiresAt (no SWR).
+ */
+export declare function computeExpiration(ttlSeconds: number, swrSeconds?: number): {
+    staleAt: number;
+    expiresAt: number;
+};
+export declare function resolveCacheKey(keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined, store: SegmentCacheStore | null, defaultKey: string, _label: string): Promise<string>;
+export declare function resolveTagsOption<TEnv>(tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined, ctx: RequestContext<TEnv> | undefined, label: string): string[] | undefined;
+export declare function resolveCacheStore(explicitStore: SegmentCacheStore | undefined): SegmentCacheStore | null;

package/dist/types/cache/cache-runtime.d.ts

@@ -0,0 +1,51 @@
+/**
+ * "use cache" Runtime
+ *
+ * Provides the runtime wrapper for functions marked with "use cache" directive.
+ * The Vite transform plugin wraps exports with registerCachedFunction().
+ *
+ * On cache miss: executes the function, serializes the result via RSC Flight
+ * protocol, captures handle data if tainted ctx is detected, and stores in
+ * the SegmentCacheStore.
+ *
+ * On cache hit: deserializes the cached result, restores handle data if present.
+ *
+ * On stale hit: returns stale data immediately, triggers background
+ * re-execution via waitUntil().
+ */
+import { isCachedFunction } from "./taint.js";
+export { isCachedFunction };
+/**
+ * Convert encodeReply result to a stable string key.
+ *
+ * encodeReply may return a string or FormData. A plain string is already
+ * deterministic for a given arg set, so return it verbatim. FormData (emitted
+ * whenever a key arg is a typed array / Blob / File / a large object React
+ * lazily chunks) carries a per-call RANDOM multipart boundary
+ * (`formdata-undici-<random>`); stringifying the whole body via
+ * `new Response(formData).text()` would therefore produce a DIFFERENT key on
+ * every call, so the cached function would always miss and the store would
+ * accumulate one duplicate entry per call (unbounded growth).
+ *
+ * Instead derive the key from the entries themselves, independent of the
+ * boundary: iterate in sorted-key order and, for each value, emit a
+ * boundary-free token — `s:<value>` for strings, `b:<size>:<type>:<name>:<hash>`
+ * for Blob/File (bytes folded via djb2 so distinct payloads of equal
+ * size/type/name still differ). Strings carry an `s:` type tag so a string whose
+ * value happens to equal a blob token (e.g. the literal `b:4::a:b:<hash>`) cannot
+ * collide with an actual Blob/File entry under the same FormData key. The
+ * user-controlled `type`/`name` are percent-encoded before joining so an embedded
+ * `:` cannot shift the field boundaries and collide two distinct files (e.g.
+ * {name:"a:b",type:""} vs {name:"b",type:":a"}). The result is stable across
+ * identical arg sets.
+ */
+export declare function replyToCacheKey(encoded: string | FormData): Promise<string>;
+/**
+ * Register a function as a cached function.
+ * Called by the Vite transform for each "use cache" function.
+ *
+ * @param fn - The original async function
+ * @param id - Stable identifier (module path + export name)
+ * @param profileName - Cache profile name (from "use cache: profileName" or "default")
+ */
+export declare function registerCachedFunction<T extends (...args: any[]) => any>(fn: T, id: string, profileName: string): T;

package/dist/types/cache/cache-scope.d.ts

@@ -0,0 +1,215 @@
+/**
+ * CacheScope - Runtime cache scope for iterator-based caching
+ *
+ * Each cache() boundary in the route tree creates a new CacheScope.
+ * The scope owns: config, key management, and storage operations.
+ *
+ * Serialization is delegated to segment-codec.ts.
+ * Handle data capture/restore is delegated to handle-snapshot.ts.
+ */
+import type { PartialCacheOptions } from "../types.js";
+import type { ResolvedSegment } from "../types.js";
+import type { SegmentCacheStore } from "./types.js";
+import type { RequestContext } from "../server/request-context.js";
+export declare function resolveCacheTags(config: PartialCacheOptions | false, ctx: RequestContext | undefined): string[] | undefined;
+/**
+ * Discriminated outcome of a route cache lookup — see
+ * {@link CacheScope.lookupRouteDetailed} for what each status licenses.
+ */
+export type CacheRouteLookupOutcome = {
+    status: "hit";
+    result: {
+        segments: ResolvedSegment[];
+        shouldRevalidate: boolean;
+    };
+} | {
+    status: "miss" | "bypass" | "error";
+};
+/**
+ * CacheScope represents a cache boundary in the route tree.
+ *
+ * When withCache encounters an entry with cache config, it creates
+ * a new CacheScope. The scope owns key management, TTL resolution,
+ * and storage operations. Serialization is handled by segment-codec.ts.
+ *
+ * Store resolution priority:
+ * 1. Explicit store in cache() options
+ * 2. App-level store from handler config
+ *
+ * TTL resolution priority:
+ * 1. Explicit value in cache() options
+ * 2. Explicit store's defaults (if store specified)
+ * 3. App-level store's defaults
+ * 4. Hardcoded fallback (60 seconds)
+ */
+export declare class CacheScope {
+    private readonly defaultKeyPrefix?;
+    readonly config: PartialCacheOptions | false;
+    readonly parent: CacheScope | null;
+    /** Explicit store from cache() options, if specified */
+    private readonly explicitStore;
+    constructor(config: PartialCacheOptions | false, parent?: CacheScope | null, defaultKeyPrefix?: "doc" | undefined);
+    /**
+     * Whether caching is enabled for this scope
+     */
+    get enabled(): boolean;
+    /**
+     * Get effective TTL from config or store defaults.
+     *
+     * Unlike profile-registry.ts (which fails fast at config time), the render
+     * path must DEGRADE: a non-finite/negative ttl (NaN/Infinity from a bad
+     * defaults config) would make computeExpiration produce NaN deadlines so the
+     * entry never evicts, or a guaranteed miss for a negative value. Fall back to
+     * DEFAULT_ROUTE_TTL instead of throwing in the foreground render.
+     */
+    get ttl(): number;
+    /**
+     * Get SWR window from config or store defaults.
+     *
+     * A non-finite/negative swr is degraded to undefined (no SWR window) rather
+     * than fed into expiry math; see the ttl getter for the rationale.
+     */
+    get swr(): number | undefined;
+    /**
+     * Get the cache store - resolution priority:
+     * 1. Explicit store from cache() options
+     * 2. App-level store from request context
+     */
+    getStore(): SegmentCacheStore | null;
+    /**
+     * Resolve the cache key using the shared 3-tier priority.
+     * @internal
+     */
+    private resolveKey;
+    /**
+     * @internal Whether a cache read/write is allowed for the current request:
+     * the scope is enabled AND its `condition` (if any) returns true. "read"
+     * is consulted by the PPR navigation-replay gate BEFORE any shell-store
+     * read so a cache(false)/condition-false route reports `cache-disabled`
+     * without spending getShell I/O; "write" gates the capture's snapshot-only
+     * doc record (cache-store middleware) under the same semantics as the
+     * scope's own store write. Consumer opt-outs are absolute — the seeded
+     * fallback must never serve where the consumer refused cached serves.
+     */
+    allowsCache(op: "read" | "write"): boolean;
+    /**
+     * @internal True for scopes minted from the `_shellImplicitCache` marker
+     * (createShellImplicitDocScope) — the only construction path that passes
+     * the `doc` defaultKeyPrefix; route-derived scopes (createCacheScope) never
+     * do. withCacheLookup/withCacheStore use this to tell the implicit doc
+     * scope from a route-derived scope: the two compose on the replay serve
+     * path and only the route-derived kind gets the seeded fallback /
+     * doc-record treatment.
+     */
+    get isShellImplicitDocScope(): boolean;
+    /**
+     * Evaluate the cache `condition` predicate. Returns false (skip the cache
+     * operation) when the predicate returns false or throws; returns true when
+     * there is no condition or no request context to evaluate it against.
+     */
+    /**
+     * One WRITE decision per (scope, request), memoized on the request context.
+     * A capture render has TWO writers consulting the same predicate — the
+     * explicit tier's cacheRoute and the snapshot-only doc record gate
+     * (recordShellCaptureDocRecord) — and a true→false flap between the two
+     * evaluations recorded a REPLAYABLE canonical snapshot for a render whose
+     * real write was refused. The first evaluation pins the answer for the
+     * whole render (the capture's derived context during captures). READ
+     * decisions stay per-lookup by design: pre-deciding a flappable predicate
+     * at the replay gate was the round-2 regression.
+     */
+    private readonly writeConditionMemo;
+    private conditionAllows;
+    /**
+     * Lookup cached segments for a route (single cache entry per request).
+     * Returns { segments, shouldRevalidate } or null if cache miss.
+     *
+     * @param pathname - URL pathname for cache key generation
+     * @param params - Route params for cache key generation
+     * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+     */
+    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<{
+        segments: ResolvedSegment[];
+        shouldRevalidate: boolean;
+    } | null>;
+    /**
+     * @internal lookupRoute with a discriminated outcome. The PPR replay
+     * composition (withCacheLookup) may substitute the seeded doc record ONLY on
+     * a true `miss` — the other non-hit outcomes must not be papered over:
+     *
+     * - `bypass`: the scope refused the read — cache(false), a false
+     *   `condition()`, or no resolvable store. Consumer opt-outs are absolute;
+     *   a fallback here would serve cached segments to a request the consumer
+     *   said must render fresh.
+     * - `error`: a throwing consumer key()/store keyGenerator/store.get. The
+     *   contract on that failure is "render uncached" (see the catch below) —
+     *   falling back would serve the canonical doc record across a broken key
+     *   partition, exactly the collision resolveCacheKey's no-default-fallback
+     *   rule exists to prevent.
+     *
+     * A corrupt entry that was evicted reads as `miss`: the store was consulted
+     * and holds nothing servable, which is the post-eviction truth.
+     */
+    lookupRouteDetailed(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<CacheRouteLookupOutcome>;
+    /**
+     * Record this scope's segment-DSL cache({ tags }) into the request tag union
+     * synchronously, under the same gate cacheRoute() uses for a write.
+     *
+     * cacheRoute() already records these tags, but it is invoked inside
+     * requestCtx.waitUntil() by the cache-store middleware (and the proactive path
+     * re-resolves the whole tree before calling it), so its recording is deferred
+     * and RACES the document cache's post-body-drain snapshot of _requestTags. On a
+     * first-write (segment-cache miss) the document tag union could miss these
+     * tags, and updateTag()/revalidateTag() would then fail to invalidate the
+     * cached document until a later write reseeded it. Calling this synchronously
+     * in the request pipeline (before the snapshot) closes that window. Idempotent
+     * (the tag union is a Set), so the duplicate record in cacheRoute is harmless.
+     */
+    recordTags(requestCtx: RequestContext | undefined): void;
+    /**
+     * Cache all segments for a route (non-blocking via waitUntil)
+     * Single cache entry per route request.
+     * Loaders are excluded - they're always fresh unless they have their own cache() config.
+     *
+     * @param pathname - URL pathname for cache key generation
+     * @param params - Route params for cache key generation
+     * @param segments - All resolved segments to cache
+     * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+     */
+    cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean): Promise<void>;
+}
+/**
+ * Create a cache scope from entry's cache config
+ */
+export declare function createCacheScope(config: {
+    options: PartialCacheOptions | false;
+} | undefined, parent?: CacheScope | null): CacheScope | null;
+type ShellImplicitCacheMarker = NonNullable<RequestContext["_shellImplicitCache"]>;
+/**
+ * Mint the implicit doc-level scope for a `_shellImplicitCache` marker: key
+ * resolution under the marker's `doc` namespace against the marker's store,
+ * with the marker's onHit wired as the hit observer. Shared by
+ * {@link resolveShellImplicitCacheScope} (routes that derived no scope) and
+ * the explicit-scope composition sites (capture doc record in the cache-store
+ * middleware, seeded replay fallback in withCacheLookup) so both ends of the
+ * shell contract resolve the SAME canonical document key.
+ */
+export declare function createShellImplicitDocScope(marker: ShellImplicitCacheMarker): CacheScope;
+/**
+ * Shell fast path: when the route tree derived NO cache scope and the current
+ * request context carries the `_shellImplicitCache` marker (a shell capture,
+ * an eligible HIT tail, or a normal partial navigation replay), substitute an
+ * implicit doc-level scope so withCacheLookup/withCacheStore treat the WHOLE
+ * matched route as a cache() boundary — the shell entry IS a cache() of the
+ * handler layer, with loaders as the live carve-outs
+ * (resolveFreshLoadersAndYield).
+ *
+ * An existing scope — including an explicit cache(false) opt-out — always
+ * wins HERE: the consumer's cache() semantics (their ttl/swr/store/condition)
+ * are never overridden, and cache(false) keeps the tail on the full handler
+ * re-run path. On the navigation-replay serve path the marker still composes
+ * with an explicit scope downstream (withCacheLookup's seeded fallback after
+ * an explicit-tier miss) — see `onExplicitHit` on `_shellImplicitCache`.
+ */
+export declare function resolveShellImplicitCacheScope(scope: CacheScope | null): CacheScope | null;
+export {};

package/dist/types/cache/cache-tag.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Cache Tag API
+ *
+ * Provides cacheTag() for tagging cached entries at runtime inside "use cache"
+ * functions. Tags are scoped via AsyncLocalStorage; calling cacheTag() outside
+ * a "use cache" execution throws.
+ *
+ * The runtime (cache-runtime.ts) wraps "use cache" execution in
+ * runWithCacheTagScope(), collects the runtime tags, and merges them with the
+ * profile/DSL tags before storing.
+ */
+import { type RequestContext } from "../server/request-context.js";
+export declare function normalizeTag(tag: string): string | null;
+export declare function normalizeTags(tags: Iterable<string>): string[];
+/**
+ * Tag content for later invalidation via updateTag() / revalidateTag().
+ *
+ * cacheTag() serves two forms depending on what is active when it runs:
+ *
+ * 1. Inside a "use cache" function — the DEFAULT. The tags go to the current
+ *    cache entry; `revalidateTag(tag)` drops that entry. Tags are additive
+ *    (multiple calls accumulate), and normalizeTag() is the single chokepoint so
+ *    a padded write matches an unpadded invalidate.
+ *
+ * 2. Render-callable (#648) — no "use cache" scope active, but a request context
+ *    is present. The tags record onto the request's DOCUMENT artifact
+ *    (ctx._requestTags) instead of throwing. The collection layers already exist:
+ *    PPR shell capture unions _requestTags into the shell entry, the document
+ *    cache tags the full-page entry with it, and prerender build contexts seed
+ *    their own set — so a server component that renders into a shell makes
+ *    `revalidateTag("campaign:spring")` evict that shell with ZERO cache()/"use
+ *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
+ *    execution-PRESERVING (everything still runs underneath; only document bytes
+ *    are shortcut), so its tags ride this existing instrument rather than a
+ *    first-class ppr key/tag API. The shell-expiry invariant holds by
+ *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
+ *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
+ *    never execute during capture, so nothing under a hole can tag the shell).
+ *
+ * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
+ * level, not the segment (only the "use cache" runtime enters the tag scope) — a
+ * documented semantic, not a filtered one. An empty/whitespace-only tag is
+ * dropped in both forms (the render-callable form silently, via normalizeTags in
+ * recordRequestTags; the scope form with a dev warning).
+ *
+ * With neither a scope nor a request context, cacheTag() throws.
+ *
+ * @example
+ * ```typescript
+ * // Form 1 — inside "use cache":
+ * async function getProduct(ctx) {
+ *   "use cache";
+ *   cacheTag(`product:${ctx.params.id}`, "products");
+ *   return db.getProduct(ctx.params.id);
+ * }
+ *
+ * // Form 2 — render-callable, tags the shell/document from a server component:
+ * function CampaignBanner() {
+ *   cacheTag("campaign:spring");
+ *   return <aside>Spring sale</aside>;
+ * }
+ * ```
+ */
+export declare function cacheTag(...tags: string[]): void;
+export declare function recordRequestTags(tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
+/**
+ * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`
+ * accumulate into the returned Set.
+ *
+ * The returned Set is the LIVE reference - the caller must await `result`
+ * before reading `tags`, because an async cached function may call cacheTag()
+ * after an await boundary.
+ *
+ * @internal Used by cache-runtime.ts to wrap "use cache" execution.
+ */
+export declare function runWithCacheTagScope<T>(fn: () => T): {
+    result: T;
+    tags: Set<string>;
+};

package/dist/types/cache/cf/cf-base64.d.ts

@@ -0,0 +1,4 @@
+/** Encode ArrayBuffer to base64 string. */
+export declare function bufferToBase64(buffer: ArrayBuffer): string;
+/** Decode base64 string to ArrayBuffer. */
+export declare function base64ToBuffer(base64: string): ArrayBuffer;

package/dist/types/cache/cf/cf-cache-constants.d.ts

@@ -0,0 +1,112 @@
+/** Header storing timestamp when entry becomes stale */
+export declare const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
+/** Header storing cache status: HIT | REVALIDATING */
+export declare const CACHE_STATUS_HEADER = "x-edge-cache-status";
+/**
+ * Header storing this entry's cache tags as a JSON array. JSON-encoded (not the
+ * comma-delimited CF `Cache-Tag` format) so tags containing commas round-trip
+ * safely; the read paths parse this to run the tag-invalidation check.
+ */
+export declare const CACHE_TAGS_HEADER = "x-edge-cache-tags";
+/** Header storing the ms-epoch timestamp when this entry's tags were attached. */
+export declare const CACHE_TAGGED_AT_HEADER = "x-edge-cache-tagged-at";
+/**
+ * KV key prefix for tag-invalidation markers. A marker stores the ms-epoch
+ * timestamp of the most recent invalidation of a tag; reads treat any entry
+ * whose taggedAt is older than its tags' latest marker as invalidated. Markers
+ * live in the SAME KV namespace as the cached entries - there is no separate
+ * tag-invalidation store.
+ */
+export declare const TAG_MARKER_PREFIX = "__tag__/";
+/**
+ * Header storing the epoch-ms timestamp when an entry was marked REVALIDATING.
+ * The SWR thundering-herd guard reads this to decide whether the in-flight
+ * revalidation is still recent. It replaces a prior reliance on the HTTP `Age`
+ * header: CF's Cache API does not populate `Age` reliably per-colo (and our own
+ * unit MockCache never set it), so an absent `Age` defaulted to 0 and made every
+ * REVALIDATING entry look "just revalidated" forever -- a dropped/never-finished
+ * background revalidation could then pin an entry stale until hard expiry. An
+ * explicit timestamp we write ourselves (same pattern as CACHE_STALE_AT_HEADER)
+ * is reliable and lets the MAX_REVALIDATION_INTERVAL re-arm actually fire.
+ */
+export declare const CACHE_REVALIDATING_AT_HEADER = "x-edge-cache-revalidating-at";
+/**
+ * Header storing the absolute epoch-ms hard-expiry deadline (staleAt +
+ * swrWindow*1000) of an L1 entry. The stale-path REVALIDATING re-put reads this
+ * to recompute a SHRINKING Cache-Control max-age instead of copying set()'s
+ * original full-window max-age. Without it, every MAX_REVALIDATION_INTERVAL
+ * re-arm re-puts the full window and restarts CF's retention clock, pinning a
+ * perpetually-stale entry (one whose background revalidation keeps failing) past
+ * its intended hard-expiry indefinitely. Mirrors the KVSegmentEnvelope `e`
+ * field and the remaining-ttl math in promoteSegmentToL1/promoteItemToL1.
+ * @internal
+ */
+export declare const CACHE_EXPIRES_AT_HEADER = "x-edge-cache-expires-at";
+/**
+ * Header stashing the route author's original Cache-Control on L1 document
+ * entries. putResponse/promoteResponseToL1 overwrite Cache-Control with a long
+ * `max-age` so the CF Cache API retains the entry across the whole SWR window;
+ * getResponse restores this original value before serving so the client and any
+ * upstream CDN see the author's intended directive, not the internal edge TTL.
+ */
+export declare const CACHE_ORIG_CC_HEADER = "x-edge-cache-orig-cc";
+/**
+ * Maximum age in seconds for REVALIDATING status before allowing new revalidation.
+ * After this period, a stale entry in REVALIDATING status will trigger revalidation again.
+ * @internal
+ */
+export declare const MAX_REVALIDATION_INTERVAL = 30;
+/**
+ * Maximum time (ms) to wait for an L1 edge cache (CF Cache API) read before
+ * giving up and treating it as a miss. The Cache API is normally sub-millisecond
+ * per-colo, so a slow `match` signals a degraded colo; we don't want it adding
+ * latency to the request. On timeout the lookup is abandoned, a warning is
+ * logged, and the read falls through to its normal miss path (L2/KV or render).
+ *
+ * This is the default; override per store via
+ * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ *
+ * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 10ms budget firing frequently on cold colos where the first Cache API touch
+ * is slow but healthy — each false positive downgrades a warm L1 HIT to an
+ * L2/render round trip that costs far more than the 15ms of extra patience.
+ * A genuinely degraded colo still gets cut off; tune per store for
+ * shell-critical routes.
+ */
+export declare const EDGE_LOOKUP_TIMEOUT_MS = 25;
+/**
+ * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read
+ * (response.json()) before treating the read as a miss.
+ *
+ * This is separate from {@link EDGE_LOOKUP_TIMEOUT_MS} on purpose. CF's Cache
+ * API resolves `match()` with a lazily-streamed body, so a fast `match` can be
+ * followed by a multi-second stall while the body bytes are fetched -- the
+ * latency tail lives here, after the match budget has already passed. The
+ * default bounds that tail aggressively: a healthy per-colo body read (fetch +
+ * JSON parse) settles in low single-digit milliseconds, so 20ms clears a
+ * healthy read while still failing fast to L2/KV (or render) on a degraded colo
+ * instead of pinning the request behind a seconds-long read. Raise it per store
+ * if large Flight payloads legitimately need longer.
+ *
+ * Override per store via `CFCacheStoreOptions.edgeReadTimeoutMs` (<= 0 disables).
+ */
+export declare const EDGE_READ_TIMEOUT_MS = 20;
+/**
+ * Maximum time (ms) to wait for an L2 (KV) read (`kv.get(key, {type:"json"})`)
+ * before treating it as a miss. Unlike the L1 budgets, KV is a GLOBAL store: the
+ * file header documents ~50ms healthy reads, and a degraded namespace can tail
+ * to seconds. KV is the LAST cache tier before a full render, so an unbounded
+ * read here pins the whole request behind a degraded global lookup.
+ *
+ * The default (170ms) sits a few multiples above the documented ~50ms healthy
+ * read, leaving headroom for legitimate latency tails (larger payloads,
+ * far-from-colo regions) so a healthy-but-slow read does not false-miss into a
+ * render, while still abandoning a genuinely degraded namespace well before its
+ * multi-second tail can pin the request. A deployment with a tighter SLA can
+ * lower it, and one whose healthy p99 runs higher should raise it: measure the
+ * KV read p99 (Workers Analytics) and add margin. It is a degradation
+ * guard-rail, not a tuning lever for "slow KV is normal here".
+ *
+ * Override per store via `CFCacheStoreOptions.kvReadTimeoutMs` (<= 0 disables).
+ */
+export declare const KV_READ_TIMEOUT_MS = 170;