@rangojs/router 0.26.6 → 0.28.0

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.26.6",
+      version: "0.28.0",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",

package/dist/types/__internal.d.ts

@@ -53,7 +53,13 @@ export type { CachedEntryData, CacheGetResult, SerializedSegmentData, CacheDefau
  * @internal
  * Router context for AsyncLocalStorage.
  */
-export type { RouterContext, RevalidationContext, InterceptResult, } from "./router/router-context.js";
+export type { RouterContext, InterceptResult, } from "./router/router-context.js";
+/**
+ * @internal
+ * The request side of a revalidating resolution pass (RouterContext's
+ * revalidating resolvers take it).
+ */
+export type { ResolutionPassInput } from "./router/segment-resolution/resolution-pass.js";
 /**
  * @internal
  * Route match context during pipeline processing.

package/dist/types/browser/action-coordinator.d.ts

@@ -6,8 +6,6 @@ import type { ActionEntry } from "./event-controller.js";
  */
 type ActionScenario = {
     type: "navigated-away";
-    historyKeyChanged: boolean;
-    onInterceptRoute: boolean;
 } | {
     type: "hmr-missing";
 } | {
@@ -44,8 +42,6 @@ export interface ActionOutcomeInput {
     reconciledSegmentCount: number;
     /** Number of matched segment IDs from server */
     matchedCount: number;
-    /** Current intercept source URL (null when not on intercept route) */
-    currentInterceptSource: string | null;
 }
 /**
  * Classify a post-reconciliation action outcome. Ordered priority chain: each

package/dist/types/browser/action-fence.d.ts

@@ -6,9 +6,11 @@
  * start. While the fence is up, the decision of whether the action invalidated
  * anything is deferred to the response:
  *
- * - prefetch consumption is suspended (a queued prefetch result is not served),
- * - a genuine navigation during the flight fetches with `cache: "no-store"` so
- *   it cannot be served stale bytes from the browser's Vary-keyed HTTP cache,
+ * - a navigation during the flight is an ordinary one: a prefetch is served,
+ *   and the page it commits may hold pre-write data until the follow-up below,
+ * - a navigation without a prefetch, and a prefetch, fetch with
+ *   `cache: "no-store"` so they cannot be served stale bytes from the
+ *   browser's Vary-keyed HTTP cache,
  * - popstate reads are treated as stale-while-revalidate.
  *
  * Nothing is wiped, rotated, or broadcast while the fence is up — that is what
@@ -16,6 +18,12 @@
  * actions compose: each action raises and lowers its own reference, and the
  * fence is down only when the count reaches zero.
  *
+ * The drop runs the batch's follow-up: when an action of the batch did not
+ * land on the page on screen, the action bridge refetches that page once,
+ * whole, after the navigation the user started, unless an intercept is on
+ * screen (server-action-bridge.ts followUp; the rules are R1-R7 in
+ * docs/internal/execution-model.md).
+ *
  * The refcount is a single module-level counter, not keyed by routerId.
  * Consumers (navigation-client.ts, prefetch/fetch.ts, navigation-bridge.ts)
  * read it unscoped, so an action in one router would suppress another router's

package/dist/types/browser/event-controller.d.ts

@@ -20,6 +20,18 @@ export interface NavigationEntry {
     options?: NavigateOptionsInternal & {
         skipLoadingState?: boolean;
     };
+    /**
+     * Resolves once the navigation has ended: its transaction ended and every
+     * stream it opened closed. True when it committed, false when it ended
+     * without a commit (a failure) or was left (aborted, which settles it at
+     * once). A `prefetch: false` fill holds the transaction open
+     * (partial-update.ts awaits fillHoles before it resolves) and its stream
+     * until the fill's answer streamed, so a waiter never cuts a fill or a
+     * stream short. Only the action bridge's follow-up awaits it
+     * (server-action-bridge.ts followUp); no hook reads it, and settling it
+     * notifies nothing.
+     */
+    settled: Promise<boolean>;
 }
 /**
  * Entry tracking an in-flight action
@@ -195,7 +207,8 @@ export interface EventController {
     startAction(actionId: string, args: unknown[], 
     /** Originating history entry key; scopes location-state arbitration. */
     cohort?: string): ActionHandle;
-    abortAllActions(): void;
+    /** Abort every action in flight except `except` (an ActionHandle id). */
+    abortAllActions(except?: string): void;
     getState(): DerivedNavigationState;
     getActionState(actionId: string): TrackedActionState;
     getLocation(): NavigationLocation;
@@ -279,6 +292,12 @@ export interface EventController {
     /** True once after a `treeless` commit. */
     takeTreelessLocationState(): boolean;
     getCurrentNavigation(): NavigationEntry | null;
+    /**
+     * The newest navigation until it settles (NavigationEntry.settled): before
+     * its commit, and after it while its transaction or a stream is still
+     * open. Null once it settled or was left.
+     */
+    getUnsettledNavigation(): NavigationEntry | null;
     getInflightActions(): Map<string, ActionEntry>;
     /** Whether any concurrent actions have occurred (shared across all handles) */
     hadAnyConcurrentActions(): boolean;

package/dist/types/browser/history-state.d.ts

@@ -21,15 +21,9 @@ export declare function hasLocationState(state: unknown): boolean;
  */
 export declare function pushHistoryWithIdx(state: Record<string, unknown> | null, url: string, replace: boolean): void;
 /**
- * The forced-MISS reload marker (`SHELL_MISS_PARAM` in rsc/shell-serve.ts,
- * which the browser bundle must not import): a degraded PPR shell HIT
- * reloads the page with it, and the server renders a marked request like a
- * cache miss.
- */
-export declare const SHELL_MISS_MARKER: string;
-/**
- * Drop the forced-MISS marker from the address bar at boot, keeping the
- * history entry's state (initBrowserApp calls it before any location read).
+ * Drop the forced-MISS marker (`WIRE.shellMiss`, rsc/shell-serve.ts) from the
+ * address bar at boot, keeping the history entry's state (initBrowserApp
+ * calls it before any location read).
  * Left in place, a refresh or a shared link would stay off the shell and the
  * app's search params would carry it. The server strips the same marker from
  * the request before rendering (shell-serve.ts withoutShellMissMarker), so
@@ -46,6 +40,10 @@ export declare function stripShellMissMarker(): void;
  *
  * A slot is recognised by its key alone (the `~r` suffix): at start-up the
  * module that defines it may not be loaded.
+ *
+ * The same pass drops the entry's intercept marks (`intercept`,
+ * `sourceUrl`): a document request never renders an intercept, so the entry
+ * is a full page for later Back/Forward.
  */
 export declare function clearLocationStateOnDocumentLoad(): void;
 /**

package/dist/types/browser/intercept-utils.d.ts

@@ -31,3 +31,26 @@ export declare function hasActiveIntercept(slots?: Record<string, SlotState>): b
  * whether interception happens depends on the current page context.
  */
 export declare function isInterceptOnlyCache(segments: ResolvedSegment[]): boolean;
+/**
+ * An intercept's `matched`: the client's ids without any of the slot's (its
+ * id and every loader segment on it, another intercept's into the same slot
+ * included), then the slot's (interceptSegmentIds). One order for the
+ * prefetch, its fill, an action and a revisit: a fill whose `matched` differs
+ * from its tree's is rendered as a new tree (browser/partial-update.ts
+ * fillHoles). Shared by router/match-result.ts and wholeInterceptMatched.
+ */
+export declare function interceptMatched(clientIds: readonly string[], slotIds: readonly string[]): string[];
+/**
+ * The `matched` the browser keeps for an intercept answer to a request that
+ * held no segments (a followed redirect, a Back/Forward revalidation with
+ * handles pending, the dev HMR refetch), or undefined to keep the answer's.
+ * The server never renders the page under an intercept and lists it only
+ * from the ids a request held, so such an answer has an empty outlet under
+ * the slot. The page it lands over (`held`) stays, as the server lists it for
+ * a request that holds it.
+ */
+export declare function wholeInterceptMatched(held: readonly ResolvedSegment[], answer: {
+    matched?: string[];
+    segments?: ResolvedSegment[];
+    slots?: Record<string, SlotState>;
+}): string[] | undefined;

package/dist/types/browser/navigation-store.d.ts

@@ -24,16 +24,18 @@ export declare function liveHandleDataForCache(eventController: Pick<EventContro
  * Options for generating a history key
  */
 export interface HistoryKeyOptions {
-    /** If true, append :intercept suffix to differentiate intercept entries */
+    /** Key an intercept entry (apart from the plain entry for the URL). */
     intercept?: boolean;
+    /** The page the intercept was opened over (history.state.sourceUrl). */
+    interceptSource?: string;
 }
 /**
- * Generate a cache key from a URL.
- * Uses pathname + search (query params) directly as the key.
- * Hash fragments (#) are excluded since they don't affect server data.
+ * Generate a cache key from a URL: pathname + search. Hash fragments (#) are
+ * excluded since they don't affect server data.
  *
- * For intercept routes, append `:intercept` suffix to cache them separately
- * from non-intercept versions of the same URL.
+ * An intercept entry is keyed `<url>:intercept:<source>`: its cached tree
+ * includes the page under the intercept. hasInterceptCache relies on the
+ * `:intercept:` separator.
  */
 export declare function generateHistoryKey(url?: string, options?: HistoryKeyOptions): string;
 /**

package/dist/types/browser/react/filter-segment-order.d.ts

@@ -26,8 +26,8 @@ export declare function loaderParentId(id: string): string;
  * 2. Place each parallel slot id (contains ".@") immediately after its
  *    parent layout/route id. Raw segment-resolution emission order does NOT
  *    guarantee this: route-mounted parallels are resolved/pushed BEFORE the
- *    route handler's segment is appended (see fresh.ts:resolveSegment for
- *    routes, and revalidation.ts ~915-919), so matched can read
+ *    route handler's segment is appended (see resolveSegment in
+ *    segment-resolution/revalidation.ts), so matched can read
  *    `[..., R0.@panel, R0]`. collectHandleData consumes segmentOrder verbatim
  *    with later-wins semantics, so without normalization the route handler's
  *    Meta would override the slot's more-specific Meta — backwards.

package/dist/types/browser/rsc-router.d.ts

@@ -21,7 +21,7 @@ export interface InitBrowserAppOptions {
     storeOptions?: {
         /**
          * Maximum number of history entries to cache
-         * @default 10
+         * @default 20
          */
         cacheSize?: number;
     };

package/dist/types/browser/segment-reconciler.d.ts

@@ -62,10 +62,12 @@ export interface ReconcileResult {
  */
 export declare function reconcileSegments(input: ReconcileInput): ReconcileResult;
 /**
- * Reconcile error segments with cached segments.
+ * Reconcile an error-boundary response with cached segments.
  *
- * For error responses, the server returns the error boundary segment.
- * This function overlays error segments onto the full cached tree,
- * preserving sibling layouts that aren't in the error parent chain.
+ * The server returns the error boundary segment and, above it, what the
+ * action's revalidation re-ran (rsc/server-action.ts). This function overlays
+ * them onto the full cached tree, preserving sibling layouts that aren't in
+ * the error parent chain. The error segment replaces its cached copy; every
+ * other segment merges as an action's does (mergeCached).
  */
 export declare function reconcileErrorSegments(cachedSegments: ResolvedSegment[], errorSegments: ResolvedSegment[]): ReconcileResult;

package/dist/types/browser/types.d.ts

@@ -558,7 +558,8 @@ export interface NavigationStore {
          */
         handlesPending?: boolean;
     } | undefined;
-    hasHistoryCache(historyKey: string): boolean;
+    /** Whether an intercept entry is cached for the plain `historyKey`, from any source page. */
+    hasInterceptCache(historyKey: string): boolean;
     /**
      * Update only the handleData (and optionally the stale / handlesPending flags)
      * of an existing cache entry. When a flag is omitted the entry's current value

package/dist/types/browser/wire-protocol.d.ts

@@ -0,0 +1,25 @@
+/** The parameters of a partial request: a navigation, a prefetch or a JS server action. */
+export interface PartialRequestInit {
+    /** A JS server action's id: written as `_rsc_action` in place of `_rsc_partial`. */
+    action?: string;
+    /** The mounted segment ids the server diffs against. */
+    segmentIds: readonly string[];
+    /**
+     * An empty `segmentIds`: "send" writes `_rsc_segments=` (navigation,
+     * action), "omit" leaves it out (prefetch). The prefetch cache keys carry
+     * the difference.
+     */
+    emptySegments: "send" | "omit";
+    stale?: boolean;
+    version?: string;
+    routerId?: string;
+    rewriteTarget?: string;
+    fill?: boolean;
+}
+/**
+ * Writes the partial-request parameters onto `url` in the one order every
+ * sender uses. Navigation and prefetch cache keys are built from the result
+ * (prefetch/cache.ts), so a navigation adopts a prefetch only while both
+ * write identically: browser/__tests__/wire-urls.test.ts pins the strings.
+ */
+export declare function writePartialParams(url: URL, init: PartialRequestInit): URL;

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

@@ -97,8 +97,10 @@ export declare const KEY_PART_PREFIX = "key:";
  * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
  * results of the scope's cache() chain, outermost first, then its default
  * parts: the keyGenerator results of enclosing scopes on another store
- * (#974) and, for a record key under a scope without its own `key()`, its
- * default key (or its store's keyGenerator result, #970).
+ * (#974) and, for a route record key, the scope's own part: without a
+ * `key()` of its own, its default key (or its store's keyGenerator result,
+ * #970); with one, the default key's request kind (`doc`, `partial` or
+ * `intercept:<intercept>`, routeRecordKind in cache-scope.ts).
  *
  * Key scheme invariant (#975). A `key()` result is often request input,
  * and a record key has no route or scope discriminator (the store reads
@@ -124,9 +126,13 @@ export declare const KEY_PART_PREFIX = "key:";
  * A namespaced `key()` result starts with `key:` and holds no `|`. A
  * composed key holds a `|` and either starts with `key:` or holds no `:`.
  * Among composed keys, splitting on `|` recovers each part, a part's kind
- * (a `key:` prefix, or no `:` at all) and its value. Pinned by the collision
- * probe in src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator
- * result is the store's own namespace, as before.
+ * (a `key:` prefix, or no `:` at all) and its value. A request kind part is
+ * a default key's prefix without the URL after it, so it never equals a
+ * default key part; a keyGenerator part can equal it (`doc`) only when the
+ * keyGenerator returns a constant, which already gives every URL one record.
+ * Pinned by the collision probe in
+ * src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator result is
+ * the store's own namespace, as before.
  *
  * Shared with the testing helper `shellCacheKey`, so a test builds the
  * production partition.

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

@@ -14,16 +14,23 @@ import { type ExecutionStart } from "./tag-invalidation.js";
 import { type OwnedPushDelivery } from "./handle-snapshot.js";
 import type { RequestContext } from "../server/request-context.js";
 type CacheKeyFn = NonNullable<PartialCacheOptions["key"]>;
+/**
+ * A route record that answered. `restoreHandles` is set when the lookup left
+ * the handle restore to its caller (lookupRouteDetailed `deferHandles`),
+ * which names the segments it sends (handle-snapshot.ts restoreHandles).
+ */
+export interface CachedRouteHit {
+    segments: ResolvedSegment[];
+    shouldRevalidate: boolean;
+    restoreHandles?: (sentIds: ReadonlySet<string>) => Promise<void>;
+}
 /**
  * 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;
-    };
+    result: CachedRouteHit;
 } | {
     status: "miss" | "bypass" | "error";
 };
@@ -187,14 +194,18 @@ export declare class CacheScope {
      * enclosing partition (#970, #974). A scope whose own config sets no
      * `key()` appends its own default key (resolveDefaultKey). Reusing the
      * outer `key()` result alone would give every route under the inner
-     * cache() one record: a `key()` replaces the whole default key, so an
-     * outer key that names no route (`tier:gold`) would make `/a` HIT `/b`'s
-     * record. A scope with its own `key()` adds no default key: a `key()` is a
-     * full override, and its store's keyGenerator does not run. With no
-     * partition part it is resolveDefaultKey alone. With a `key()` on the
-     * chain but no request context it rejects (keyWithoutContextError).
-     * `partitionedPrefix` prefixes a key built from partition parts only (the
-     * response family's `response:`).
+     * cache() one record: a `key()` replaces the default key's URL part, so
+     * an outer key that names no route (`tier:gold`) would make `/a` HIT
+     * `/b`'s record. A scope with its own `key()` adds no default key: its `key()`
+     * replaces the URL part, and its store's keyGenerator does not run. It
+     * appends `kind` instead (routeRecordKind): the `key()` decides which
+     * requests of one kind share a record, never that a document, a
+     * navigation and an intercept navigation do. With no partition part it is
+     * resolveDefaultKey alone. With a `key()` on the chain but no request
+     * context it rejects (keyWithoutContextError). `partitionedPrefix`
+     * prefixes a key built from partition parts only (the response family's
+     * `response:`, which passes no `kind`: a response route answers every
+     * request alike).
      *
      * Each `key()` result lives on the request context (`_resolvedCacheKeys`),
      * by function: it runs once per request whatever the default key
@@ -205,7 +216,7 @@ export declare class CacheScope {
      * itself: a `key()` calling `cookies()` would trip the capture guard there,
      * and a capture must store the partition its request resolved.
      */
-    resolveKeyFrom(defaultKey: string, partitionedPrefix?: string): Promise<string>;
+    resolveKeyFrom(defaultKey: string, partitionedPrefix?: string, kind?: string): Promise<string>;
     /**
      * @internal The request partition of a ppr route's shell under this scope
      * (resolveShellPartition): its partition parts (resolvePartitionParts),
@@ -285,14 +296,14 @@ export declare class CacheScope {
      *
      * @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)
+     * @param intercept - The intercept an intercept navigation selected
+     *   (interceptRecordKey): its record has its own key
      * @param ownedPushes - What the record is to each loader's handle pushes
      *   (withCacheLookup: loader-cache.ts loaderPins), called on a hit
+     * @param deferHandles - Restore no handle value here: the caller calls the
+     *   hit's `restoreHandles` once it decided which segments it sends
      */
-    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: () => OwnedPushDelivery): Promise<{
-        segments: ResolvedSegment[];
-        shouldRevalidate: boolean;
-    } | null>;
+    lookupRoute(pathname: string, params: Record<string, string>, intercept?: string, ownedPushes?: () => OwnedPushDelivery, deferHandles?: boolean): Promise<CachedRouteHit | null>;
     /**
      * @internal lookupRoute with a discriminated outcome. The PPR replay
      * composition (withCacheLookup) may substitute the seeded doc record ONLY on
@@ -311,7 +322,7 @@ export declare class CacheScope {
      * 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, ownedPushes?: () => OwnedPushDelivery): Promise<CacheRouteLookupOutcome>;
+    lookupRouteDetailed(pathname: string, params: Record<string, string>, intercept?: string, ownedPushes?: () => OwnedPushDelivery, deferHandles?: 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.
@@ -341,13 +352,14 @@ export declare class CacheScope {
      * @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)
+     * @param intercept - The intercept an intercept navigation selected
+     *   (interceptRecordKey): its record has its own key
      * @param start - Where the render of `segments` started: the record is not
      *   written when one of its tags was invalidated since (#977,
      *   predatesInvalidation). A shell capture's doc record passes none: it
      *   lives only in the shell entry, which putShell gates by its own start.
      */
-    cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean, start?: ExecutionStart): Promise<void>;
+    cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], intercept?: string, start?: ExecutionStart): Promise<void>;
 }
 /**
  * @internal The request partition of a ppr route's shell: with a route
@@ -392,7 +404,7 @@ export declare function createShellImplicitDocScope(marker: ShellImplicitCacheMa
  * 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).
+ * loaders as the live carve-outs (serveStoredSegments).
  *
  * A document HIT tail (`docTail`) always gets the implicit scope: it replays
  * the shell's own record and never consults a route-derived scope, whose

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

@@ -38,13 +38,13 @@ export declare const CACHE_REVALIDATING_AT_HEADER = "x-edge-cache-revalidating-a
  * 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.
+ * field and the remaining-ttl math in promoteToL1.
  * @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
+ * entries. putResponse/promoteToL1 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.

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

@@ -145,7 +145,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * the faulty per-colo entry ONLY when that fall-through found no good copy.
      *
      * The conditional evict is the load-bearing detail: when KV DOES serve a copy,
-     * kvGet* has already scheduled a same-key promote (`cache.put`); an eager
+     * readKv has already scheduled a same-key promote (`cache.put`); an eager
      * `cache.delete` here would race that put with no CF Cache API ordering
      * guarantee and could clobber the freshly-restored entry. So in that case we
      * lean on #558's heal-by-overwrite (the non-suppressed fall-through promotes /
@@ -164,7 +164,10 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private healCorruptL1;
     /**
      * Re-put a stale L1 entry marked REVALIDATING, so concurrent requests serve it
-     * without each triggering a revalidation. Shared by get()/getItem().
+     * without each triggering a revalidation (readL1). A JSON family re-puts its
+     * parsed body as a string, without a status text as set() writes it; the
+     * document re-puts a clone (`source`) whose original body still streams to
+     * the client.
      *
      * The write is NON-BLOCKING (waitUntil) and best-effort by design:
      * - It runs in waitUntil, so it never adds the put latency to the served stale
@@ -185,20 +188,6 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private markRevalidating;
-    /**
-     * Document-tier counterpart of markRevalidating for getResponse's herd guard.
-     * The segment/item tiers JSON-parse the body, so they re-put with a string
-     * body; document bodies are streamed verbatim, so we re-put with a CLONED
-     * response body (`response.clone()`) supplied by the caller -- the original
-     * body still streams to the client while the marker carries the clone. Same
-     * REVALIDATING status header, same revalidating-at stamp, same
-     * remainingCacheControl re-put math as markRevalidating, so the document tier
-     * suppresses concurrent revalidation for the identical MAX_REVALIDATION_INTERVAL
-     * window the segment tier does. Best-effort and non-blocking: a failed marker
-     * write must not affect the served stale read.
-     * @internal
-     */
-    private markResponseRevalidating;
     /**
      * Guard the segment tier against a `keyGenerator` that returns a key colliding
      * with a reserved tag-marker namespace: `__tag__/` (the KV marker key) or
@@ -212,17 +201,29 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     private isReservedSegmentKey;
     /**
-     * Get cached entry data by key.
-     *
-     * Handles SWR atomically:
+     * Get cached entry data by key (readL1). On L1 miss, falls back to KV (L2)
+     * if configured; KV hits are promoted to L1 in the background.
+     */
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
+    /**
+     * The family's debug sink for one read; the document family is outside the
+     * debug surface (op is only get/getItem). Undefined when debug is off, so
+     * the hot path allocates no event.
+     * @internal
+     */
+    private debugSink;
+    /**
+     * The L1 read of a family, which handles SWR atomically:
      * - If stale and not already revalidating, marks as REVALIDATING and returns shouldRevalidate: true
      * - If already REVALIDATING (and recent), returns shouldRevalidate: false
      * - If fresh, returns shouldRevalidate: false
      *
-     * On L1 miss, falls back to KV (L2) if configured.
-     * KV hits are promoted to L1 in the background.
+     * Every degraded L1 read falls through to KV (readKv). The family methods
+     * return it unwrapped: an async wrapper adds two promises and two microtask
+     * ticks to every read.
+     * @internal
      */
-    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
+    private readL1;
     /**
      * Store entry data with TTL and optional SWR window.
      * Resolves once the L1 write lands, per the SegmentCacheStore.set contract
@@ -236,9 +237,9 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     delete(key: string): Promise<boolean>;
     /**
-     * Get a cached Response by key (for document-level caching).
-     * Returns the response and whether it should be revalidated (SWR).
-     * Falls back to KV (L2) on L1 miss.
+     * Get a cached Response by key (for document-level caching): see readL1.
+     * Its body streams to the client unread, outside the debug surface. Falls
+     * back to KV (L2) on L1 miss.
      */
     getResponse(key: string): Promise<{
         response: Response;
@@ -258,7 +259,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
     /**
      * Get a cached function result by key.
-     * Follows the same SWR pattern as get() for segment caching.
+     * Follows the same SWR pattern as get() for segment caching (readL1).
      * Falls back to KV (L2) on L1 miss.
      */
     getItem(key: string): Promise<CacheItemResult | null>;
@@ -351,7 +352,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * caller's `tagHints`: cfTagHints may have evicted the key while the memo
      * still holds it. A shell a tag marker rejects is dropped and read from
      * the store too, which may hold a capture from after the marker (see
-     * get(), "Tag invalidation"), unless the request's own mask rejected it
+     * readL1(), "Tag invalidation"), unless the request's own mask rejected it
      * (declinesKvFallThrough).
      */
     private readMemoizedShell;
@@ -538,15 +539,6 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private skipUncacheableTagSet;
-    /**
-     * Merge the internal tag headers onto an existing Headers instance. The
-     * from-scratch paths spread tagHeaderEntries() into an object-literal init;
-     * the document put/promote paths build a Headers first, so they .set() each
-     * entry instead — except `Cache-Tag`, which is APPENDED: a document author
-     * may have set their own Cache-Tag, and clobbering it would break their CDN
-     * purging. Append produces the comma-merged list CF expects.
-     */
-    private setTagHeaders;
     /** Read an entry's tags/taggedAt back from its headers. */
     private readTagInfo;
     /**
@@ -780,12 +772,27 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /** invalidateTags' marker writes, tag purge, and hooks. */
     private writeTagInvalidation;
     /**
-     * KV fallback for segment cache reads.
-     * Returns null if KV is not configured, entry is missing, or expired.
-     * Promotes hits to L1 via waitUntil.
+     * The KV (L2) read behind an L1 miss, for every family: a missing,
+     * timed-out, corrupt (kvGetOrEvict reports and evicts it), expired or
+     * tag-invalidated envelope is a miss, a read failure is the family's read
+     * error, and a hit is promoted to L1 in the background.
+     *
+     * A degraded L1 fall-through (body-timeout / non-200) passes
+     * `suppressRevalidate`: KV has no REVALIDATING herd guard, so N concurrent
+     * degraded reads would otherwise each spawn a render exactly when the colo
+     * is already struggling. The stale data is still served and promoted; only
+     * the revalidation is withheld.
+     * @internal
+     */
+    private readKv;
+    /**
+     * Promote a KV hit to L1 in the background, under its remaining ttl, with
+     * its deadlines (so a promoted entry that later goes stale re-puts with the
+     * correct remaining ttl, see set()) and its tags (so it stays
+     * tag-invalidatable). The family builds the entry (toL1).
      * @internal
      */
-    private kvGetSegment;
+    private promoteToL1;
     /**
      * Write segment data to KV.
      *
@@ -794,29 +801,4 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private kvSetSegment;
-    /**
-     * Promote segment data from KV to L1 Cache API.
-     * @internal
-     */
-    private promoteSegmentToL1;
-    /**
-     * KV fallback for function cache reads.
-     * @internal
-     */
-    private kvGetItem;
-    /**
-     * Promote function cache data from KV to L1.
-     * @internal
-     */
-    private promoteItemToL1;
-    /**
-     * KV fallback for document cache reads.
-     * @internal
-     */
-    private kvGetResponse;
-    /**
-     * Promote document cache data from KV to L1.
-     * @internal
-     */
-    private promoteResponseToL1;
 }

package/dist/types/cache/cf/cf-kv-utils.d.ts

@@ -37,7 +37,7 @@ export declare function kvKeyDigest(value: string): Promise<string>;
  * of restarting it -- copying set()'s original full-window max-age would reset
  * CF's retention clock on every re-arm and pin a perpetually-stale entry forever.
  * An entry lacking a valid deadline (legacy/tampered) floors to max-age=1, so it
- * hard-expires in ~1s and self-heals via KV. Mirrors promoteSegmentToL1's math.
+ * hard-expires in ~1s and self-heals via KV. Mirrors promoteToL1's math.
  * @internal
  */
 export declare function remainingCacheControl(headers: Headers, now: number): string;