@rangojs/router 0.20.0 → 0.22.0

package/dist/types/cache/background-task.d.ts

@@ -6,6 +6,7 @@
  * settleGrowing). When waitUntil is unavailable, falls back to blocking or
  * skipping.
  */
+import type { ExecutionContext } from "../types/request-scope.js";
 interface WaitUntilHost {
     waitUntil?: (fn: () => Promise<void>) => void;
 }
@@ -40,4 +41,25 @@ export declare function raceDeadline<T>(work: Promise<T>, deadline: number): Pro
  * mutates `list`: a later call waits for what is still pending.
  */
 export declare function settleGrowing(list: readonly Promise<unknown>[], deadline: number): Promise<boolean>;
+/** Macrotask turns `awaitLaterMillisecond` waits at most. */
+export declare const LATER_MILLISECOND_MAX_TURNS = 10;
+/**
+ * Yield until `Date.now()` passes `since`, so a store's whole-millisecond tag
+ * gate (putShell vs an invalidation made just before) sees a later
+ * millisecond. Bounded: on Cloudflare the clock stands still between I/O
+ * events, so an unbounded wait could hang. At the bound the caller proceeds
+ * and a store may refuse the write, which its result reports.
+ */
+export declare function awaitLaterMillisecond(since: number, maxTurns?: number): Promise<void>;
+/** An ExecutionContext that keeps every promise handed to `waitUntil`. */
+export interface CollectingExecutionContext extends ExecutionContext {
+    readonly tasks: Promise<unknown>[];
+}
+/**
+ * Wrap the caller's ExecutionContext (or none) so a caller can wait for the
+ * request's background work: the deferred cache writes, the shell capture, a
+ * store's own writes. Every other member reads through to `inner`, bound to
+ * it (workerd's methods reject a foreign `this`).
+ */
+export declare function createCollectingExecutionContext(inner?: ExecutionContext): CollectingExecutionContext;
 export {};

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

@@ -6,6 +6,7 @@
  * Used by cache-runtime, cache-scope, document-cache, and loader-cache.
  */
 import type { SearchParamsFilter } from "./search-params-filter.js";
+export declare function isReservedSearchParam(key: string): boolean;
 /**
  * Build a sorted, deterministic query string from URLSearchParams,
  * excluding the router's reserved params (see isReservedSearchParam).
@@ -27,11 +28,40 @@ export declare function sortedSearchString(searchParams: URLSearchParams, filter
  */
 export declare function sortedRouteParams(params: Record<string, string> | undefined): string;
 /**
- * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
+ * THE ROUTER RULE (#1065). A key that names one router's output for a host
+ * and path starts with the router part, `{encodeURIComponent(routerId)}@`. A
+ * key that names a function and its arguments, or a tag, does not.
  *
- * 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 /
+ * - With the part: PPR shells and the build-shell manifest (buildShellKey,
+ *   buildShellManifestKey); route cache() records, the document cache and
+ *   response routes (cacheKeyBase); a loader's own cache() entry; a
+ *   `"use cache"` entry of a call that takes a ctx (a ctx is one router's:
+ *   its variables, env and reverse() map).
+ * - Without: a `"use cache"` entry of plain arguments or a bare Request
+ *   (requestArgKey); tag markers; a key the app builds itself
+ *   (`cache({ key })`, a `keyGenerator`).
+ *
+ * Why: a host and path do not name a router. A `hostOverride` cookie picks
+ * the router and forwards the request unmodified, and a `router.prerender()`
+ * warm requests whatever origin it resolved, so two routers on one store
+ * built one key and read each other's entry.
+ *
+ * The id (router.ts) has to be the same in every isolate and in build-time
+ * discovery: an explicit `id` and the injected `$$id` are, the `router_{n}`
+ * fallback is for a single router only (discover-routers.ts warns about
+ * more). Encoded, the id holds no `@` or `/`, and a host holds no `@`, so a
+ * key has a router part exactly when its first `@` comes before its first
+ * `/`: no id can be chosen to spell another router's key.
+ */
+export declare function routerKeyPrefix(routerId: string): string;
+/**
+ * Key base of one router's output (the router rule, routerKeyPrefix):
+ * `${routerId}@${host}${pathname}[:params][?search]`.
+ *
+ * The ONE composition of the namespacing rule, shared by the segment tier
+ * (cache-scope.ts), the document tier (document-cache.ts), the response tier
+ * (rsc/response-cache-serve.ts) and the loader cache 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.
@@ -40,7 +70,22 @@ export declare function sortedRouteParams(params: Record<string, string> | undef
  * 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;
+export declare function cacheKeyBase(routerId: string, host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
+/**
+ * cacheKeyBase for the request context `ctx`. rsc/handler.ts sets `_routerId`
+ * before the request scope opens and derived contexts inherit it, so a served
+ * request always has one. Only a hand-built context has none (a unit test,
+ * the runLoader / renderHandler primitives): its key has no router part,
+ * which no router's key equals (routerKeyPrefix).
+ */
+export declare function requestKeyBase(ctx: {
+    readonly _routerId?: string;
+} | null | undefined, host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
+/**
+ * The `"use cache"` key part of a bare Request argument: its URL, with no
+ * router part (the router rule, routerKeyPrefix).
+ */
+export declare function requestArgKey(url: URL, filter?: SearchParamsFilter): string;
 /**
  * The prefix of a `key()` result's part in a record key (#975), and of a
  * loader's own `key()` result after its `loader:<id>:` namespace (#1009,

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

@@ -7,6 +7,14 @@
  */
 import type { CacheDefaults, SegmentCacheStore } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+/**
+ * How long a follower trusts an in-flight leader before evicting it and
+ * running fresh. High enough that a slow-but-healthy upstream never triggers
+ * duplicate work (a legitimate cached call taking >15s is already pathological);
+ * low enough to bound the blast radius of a wedged leader to seconds, not the
+ * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
+ */
+export declare const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15000;
 /**
  * Default TTL for route-level cache() DSL and loader cache.
  * Applied when neither the cache options nor the store defaults specify a TTL.
@@ -73,4 +81,13 @@ export declare function computeExpiration(ttlSeconds: number, swrSeconds?: numbe
 };
 export declare function resolveCacheKey(keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined, store: SegmentCacheStore | null, defaultKey: string): Promise<string>;
 export declare function resolveTagsOption<TEnv>(tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined, ctx: RequestContext<TEnv> | undefined, label: string): string[] | undefined;
+/**
+ * Normalize a resolved tags array so the WRITE path matches the invalidate path:
+ * updateTag()/revalidateTag()/cacheTag() all drop empty/whitespace-only tags via
+ * normalizeTag(). Without this, an empty tag attached at write time would enter
+ * the store index but could never be invalidated (the verbs normalize it away),
+ * and on CFCacheStore would also cost a wasted KV marker read per request.
+ * Returns undefined when nothing usable remains, keeping the entry header-free.
+ */
+export declare function normalizeTagList(tags: string[]): string[] | undefined;
 export declare function resolveCacheStore(explicitStore: SegmentCacheStore | undefined): SegmentCacheStore | null;

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

@@ -286,11 +286,10 @@ 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 ownedPushes - How restoreHandles delivers the record's
-     *   loader-owned values (withCacheLookup: the handler context's
-     *   _claimLoaderPushes, and on a document HIT tail the owners it restores)
+     * @param ownedPushes - What the record is to each loader's handle pushes
+     *   (withCacheLookup: loader-cache.ts loaderPins), called on a hit
      */
-    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: OwnedPushDelivery): Promise<{
+    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: () => OwnedPushDelivery): Promise<{
         segments: ResolvedSegment[];
         shouldRevalidate: boolean;
     } | null>;
@@ -312,7 +311,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>, isIntercept?: boolean, ownedPushes?: () => OwnedPushDelivery): 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.
@@ -357,7 +356,7 @@ export declare class CacheScope {
  * enclosing scopes on another store (#974) and of a scope without its own
  * `key()` (#970)); with none, the app store's keyGenerator result
  * given the document default key. Undefined (synchronously, with no work)
- * when neither applies: the shell key stays host + path + filtered search.
+ * when neither applies: the shell key stays unpartitioned (buildShellKey).
  * Resolves to null when the partition is the default key itself (a
  * keyGenerator that returns it unchanged): that partitions nothing, so the
  * shell stays unpartitioned and keeps its build shell. The shell's key, its

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

@@ -3,7 +3,7 @@ declare global {
         readonly default: Cache;
     }
 }
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
+import type { CacheStoreScope, SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
 import { type RequestContext } from "../../server/request-context.js";
 import { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS } from "./cf-cache-constants.js";
 export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, };
@@ -21,7 +21,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly namespace?;
     private readonly explicitBaseUrl?;
     private readonly waitUntil?;
-    private readonly version?;
+    /** The `version` option: used for every versioned family when set. */
+    private readonly explicitVersion?;
     private readonly edgeLookupTimeoutMs;
     private readonly edgeReadTimeoutMs;
     private readonly kvReadTimeoutMs;
@@ -42,6 +43,12 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly kv?;
     /** True when constructed without KV: no durable tag history (see ctor). */
     readonly tagHistoryInert?: boolean;
+    /**
+     * SegmentCacheStore.scope: with KV every colo's L1 miss reads the same L2
+     * entry ("global"); without it entries live in one colo's Cache API
+     * ("local"), purge mode included (a purge evicts, it stores nothing).
+     */
+    readonly scope: CacheStoreScope;
     private readonly onRevalidateTag?;
     private readonly tagPurge?;
     private readonly tagInvalidationTtl?;
@@ -327,9 +334,12 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * on the same context) read their markers as before.
      */
     private recordShellHit;
-    /** The isolate marker memo's key for a tag: markers are per namespace and version. */
+    /**
+     * The isolate marker memo's key for a tag: markers are per namespace, and
+     * shared by every version (tagMarkerKey).
+     */
     private markerMemoKey;
-    /** The memo key: one per namespace, build version, base URL, and shell key. */
+    /** The memo key: one per namespace, document version, base URL, and shell key. */
     private shellMemoKey;
     /**
      * Serve a memoized shell (shell-memo.ts). The tag-marker check is the only
@@ -400,9 +410,16 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private kvReadShellDocument;
     /** Promote a valid KV shell into the per-colo Cache API tier. */
     private promoteShellToL1;
+    private shellRequest;
+    private shellKVKey;
     /**
      * Convert string key to Request object for CF Cache API.
-     * Includes version in URL if specified (for cache invalidation on code changes).
+     *
+     * `family` picks the version in the URL path, so a version change misses:
+     * `"data"` for segment entries and `fn:` items (cached RSC data, valid while
+     * the router's server code is unchanged), `"document"` for `doc:` responses
+     * and `shell2:` shells (their bytes carry asset URLs and the handler
+     * version), `null` for tag markers, which apply to every version.
      * @internal
      */
     private keyToRequest;
@@ -477,7 +494,13 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private kvGetOrEvict;
-    /** KV key for a tag's invalidation marker. */
+    /**
+     * KV key for a tag's invalidation marker. Unversioned: a content-hash
+     * version can come back (deploy A, deploy B, roll back to A), and a marker
+     * written while B was live has to be visible to A's entries. The staleness
+     * check compares the marker time with the entry's taggedAt and nothing else
+     * (isGloballyInvalidated), so one marker per tag serves every version.
+     */
     private tagMarkerKey;
     /**
      * Header entries carrying an entry's tags (JSON-encoded, comma-safe) and the
@@ -554,7 +577,11 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private isL1Invalidated;
-    /** Synthetic Cache API request for a tag's L1-cached invalidation marker. */
+    /**
+     * Synthetic Cache API request for a tag's L1-cached invalidation marker.
+     * Unversioned for the same reason as tagMarkerKey; the cache namespace
+     * (getCache) still scopes it.
+     */
     private tagMarkerRequest;
     /**
      * Read a tag's latest invalidation timestamp (or null if never invalidated)

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

@@ -276,11 +276,19 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      */
     tagCacheTtl?: number;
     /**
-     * Cache version string override. When this changes, all cached entries are
-     * effectively invalidated (new keys won't match old entries).
+     * Cache version string override. When set, this exact value prefixes every
+     * versioned key the store writes (`v/{version}/...`), for cached data and
+     * stored HTML alike; changing it makes every earlier entry unreachable.
      *
-     * Defaults to the auto-generated VERSION from the `@rangojs/router:version` virtual module.
-     * Only set this if you need a custom versioning strategy.
+     * Leave it unset for the default: the store keys with the versions of the
+     * router serving the request. Segment entries and `"use cache"` items use
+     * the router's data version; document responses and PPR shells use its
+     * document version (see `createRouter({ version })`). Those are computed
+     * from the router's built code, so a deploy that does not change the router
+     * keeps its entries.
+     *
+     * Tag invalidation markers are never versioned: an invalidation applies to
+     * the entries of every version, including one that comes back in a rollback.
      */
     version?: string;
     /**

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

@@ -31,11 +31,14 @@ export interface DocumentCacheOptions<TEnv = any> {
     /**
      * Custom cache key generator.
      *
-     * Replaces the default `host + pathname + search` key entirely. On a
-     * multi-domain deployment served by one function you MUST include `url.host`
-     * (or an equivalent tenant discriminator) yourself — the default key is
-     * host-namespaced, but a custom generator's output is used verbatim, so
-     * omitting host bleeds one hostname's cached response to another.
+     * Replaces the default `router id + host + pathname + search` key entirely.
+     * On a multi-domain deployment served by one function you MUST include
+     * `url.host` (or an equivalent tenant discriminator) yourself — the default
+     * key is host-namespaced, but a custom generator's output is used verbatim,
+     * so omitting host bleeds one hostname's cached response to another. The
+     * same goes for the router: two routers that share a cache store and can
+     * serve one host and path (a `hostOverride` cookie) need a generator that
+     * tells them apart.
      */
     keyGenerator?: (url: URL) => string;
     /**

package/dist/types/cache/handle-snapshot.d.ts

@@ -6,7 +6,7 @@
  * during segment resolution and stored alongside cached segments.
  */
 import type { ResolvedSegment } from "../types.js";
-import type { HandleStore } from "../server/handle-store.js";
+import type { HandleStore, RecordAuthority } from "../server/handle-store.js";
 import type { HandleOwners, SegmentHandleData } from "./types.js";
 type HandleRecord = Record<string, SegmentHandleData>;
 /**
@@ -44,54 +44,50 @@ export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>
 export declare function captureHandles(segments: ResolvedSegment[], handleStore: HandleStore): Record<string, SegmentHandleData>;
 /** The owners of captureHandles' values; undefined when none is owned. */
 export declare function captureHandleOwners(segments: ResolvedSegment[], handleStore: HandleStore): HandleOwners | undefined;
-/** How restoreHandles delivers a record's loader-owned values. */
-export interface OwnedPushDelivery {
-    /**
-     * Asked once per owner delivered through pushReplayed
-     * (setupLoaderAccess _claimLoaderPushes); an owner it refuses is skipped.
-     */
-    claim?: (loaderId: string) => boolean;
-    /**
-     * A PPR shell's record (capture, document HIT tail, navigation replay): the
-     * loaders the route runs on the live lane (liveLaneLoaderIds), marked on
-     * the store (HandleStore.markLiveLane). A hole's values are replayed
-     * unclaimed, so its own cache() HIT redelivers its entry's pushes in their
-     * place (HandleStore.redeliverReplays), and its run ending without a push
-     * drops them (HandleStore.settleLoaderRun).
-     */
-    liveLane?: ReadonlySet<string>;
-    /**
-     * A document HIT tail: every owner outside `liveLane` goes through
-     * pushRestored and stands, unclaimed.
-     */
-    restore?: boolean;
-}
+/**
+ * captureHandles and captureHandleOwners cut down to the handle arrays that
+ * hold an owned value, each whole (its unowned values too, in place), so
+ * restoreHandles rebuilds exactly those arrays over a store that already
+ * holds the rest. A prerender-served shell capture stores this: the
+ * prerender store restores the handler pushes on a HIT, and the loader
+ * pushes have no other record (shell-capture.ts captureAndStoreShell).
+ */
+export declare function captureOwnedHandles(handleStore: HandleStore): {
+    handles: HandleRecord;
+    owners?: HandleOwners;
+};
+/**
+ * What the record being restored is to each loader's handle pushes on this
+ * request (HandleStore RecordAuthority). Built by loaderPins (loader-cache.ts)
+ * over the pins resolveLoaderData serves a loader's value from, so a value
+ * and its record copies get one answer.
+ */
+export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
 /**
  * Restore handle data from a cached snapshot into the handle store.
  * Used when serving cached segments to replay their handle data: a route
  * cache() record owns its segments' arrays, so it REPLACES them.
  *
  * A segment with `owners` is replaced with empty arrays and re-pushed in
- * recorded order, an owned value through pushReplayed: if the owning loader
- * runs (a client navigation replaying a ppr route's cache() record runs its
- * `ssr: false` loaders), its live pushes replace the recorded ones in place
- * instead of appending a second copy. `owned.claim` is asked once per
- * owner, so the loader's own cache() HIT does not replay its pushes a second
- * time (loader-cache.ts replayLoaderHandles). A record without owners
- * restores as a plain replay.
- *
- * `owned.restore`: a document HIT tail restoring the shell's doc record
- * (withCacheLookup). A bake-lane owner's values are the prelude's, so they go
- * through pushRestored and stand: a run of that loader on the HIT (a
- * promise-carrying `ssr: false` loader, one whose record asks for a run)
- * reads the store, and its settled pushes are dropped, not swapped in.
- * Nothing is claimed, so the loader's own cache() HIT still replays the
- * pushes the record could not keep (the thenable ones pushRestored lets
- * through). A loader the route also runs on the live lane is a hole: its
- * values keep pushReplayed, unclaimed, and its live run replaces them
- * (#936), even inside a restored loader's body (`owned.liveLane`).
+ * recorded order. A loader-owned value stands (pushRestored) where `owned`
+ * says the record supplies that loader's value too ("pin", "copies"), and is
+ * a placeholder (pushPlaceholder) everywhere else: without `owned`, every
+ * owner. Neither claims its loader, so the loader's own cache() HIT still
+ * delivers (the thenable pushes a restored copy lets through, or its entry's
+ * pushes in a placeholder's place).
  */
 export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery): void;
+/**
+ * Serve a doc record's handles: set its authority over the loaders' pushes
+ * (with or without a handles blob: a pinned loader whose capture pushed
+ * nothing has no copy, and its run must still add no settled push), then
+ * decode and restoreHandles. `keepIds` limits the restore to the segments a
+ * boundary-scoped scope serves. A decode failure skips the restore.
+ */
+export declare function restoreRecordHandles(handleStore: HandleStore, record: {
+    handles?: string;
+    handleOwners?: HandleOwners;
+}, owned: OwnedPushDelivery | undefined, keepIds?: ReadonlySet<string>): Promise<void>;
 /**
  * Append recorded handle pushes to the store, in recorded order, via push()
  * so active captures and loader-scope tagging see them like live pushes. For
@@ -99,14 +95,27 @@ export declare function restoreHandles(handles: Record<string, SegmentHandleData
  * restoreHandles would wipe those. `segmentId` redirects every value to one
  * segment (the caller's).
  *
- * Owner-keyed groups (useCacheRecordKey, `${seq}:${loaderId}`) are a loader's
- * pushes, which reach the page once per request: `claim` (setupLoaderAccess
- * _claimLoaderPushes) skips a loader that already ran or was replayed in this
- * request, and a claimed loader that runs later replaces its replayed values
- * (HandleStore.pushReplayed). `${seq}:` groups are the function's own pushes.
- * A key without ":" is a segment id (records written before owner keys) and
- * replays unchanged. A loader's own cache() replays through loader-cache.ts
- * replayLoaderHandles.
+ * The replay of every cached unit that records by owner: a "use cache"
+ * function (useCacheRecordKey) and a loader's own cache() (loader-cache.ts
+ * recordOwnerKey, with `unitLoader` the cached loader).
+ *
+ * A `${seq}:${loaderId}` group is that loader's pushes, which reach the page
+ * once per request: `claim` (setupLoaderAccess _claimLoaderPushes) is asked
+ * once per loader and skips one that already ran or was replayed in this
+ * request; a claimed loader that runs later replaces its replayed values
+ * (HandleStore.pushReplayed). A group without an owner (`${seq}:`, or a key
+ * without ":" from a record written before owner keys, which is a segment
+ * id) is the unit's own: `unitLoader`'s, or no loader's for a function,
+ * whose pushes are plain.
+ *
+ * The claimed loaders' placeholders give way to this delivery
+ * (HandleStore.replacePlaceholders), `unitLoader`'s even when the entry
+ * recorded no push for it: the entry stands for that loader's run.
+ *
+ * No `claim` means the caller's pushes are diverted off the page (a stale
+ * refresh: cache-runtime.ts refreshView, setupLoaderAccess
+ * _runLoaderIsolated): every group is delivered, into the diverting capture,
+ * and the page's placeholders stay, or the page would lose the push.
  */
-export declare function appendHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, segmentId?: string, claim?: (loaderId: string) => boolean): void;
+export declare function appendHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, segmentId: string | undefined, claim: ((loaderId: string) => boolean) | undefined, unitLoader?: string): void;
 export {};

package/dist/types/cache/index.d.ts

@@ -1,4 +1,4 @@
-export type { SegmentCacheStore, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, CacheReadError, } from "./types.js";
+export type { SegmentCacheStore, CacheStoreScope, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, CacheReadError, } from "./types.js";
 export { CACHE_READ_ERROR } from "./types.js";
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 export type { StoreMemoOptions } from "./shell-memo.js";
@@ -8,3 +8,5 @@ export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./search-params
 export { CacheScope, createCacheScope } from "./cache-scope.js";
 export { createDocumentCacheMiddleware, type DocumentCacheOptions, } from "./document-cache.js";
 export type { CacheErrorCategory } from "./cache-error.js";
+export { getCacheVersions } from "../server/build-version-table.js";
+export type { RouterVersions } from "../router-versions.js";

package/dist/types/cache/invalidation-order.d.ts

@@ -8,6 +8,20 @@ export interface ExecutionStart {
     readonly seq: number;
     readonly at: number;
 }
+/**
+ * The `taggedAt` / `ta` stamp a store writes on a tagged data entry: the start
+ * of the execution that produced the value (`startedAt`), so a marker written
+ * while it ran rejects the entry on read (#1068). Write time when the writer
+ * knows no start. Never later than now: a start from a skewed clock must not
+ * stamp the future, which would make the entry look newer than every marker.
+ */
+export declare function entryStamp(startedAt: number | undefined): number;
+/** The stamp of a data entry: `entryStamp` for a tagged entry, none otherwise. */
+export declare function taggedStamp(tags: readonly string[] | undefined, startedAt: number | undefined): number | undefined;
+/** Mark the execution start behind a Response handed to putResponse. */
+export declare function markResponseStart(response: Response, start: ExecutionStart): Response;
+/** The start a writer marked on `response`, if any. */
+export declare function responseStartedAt(response: Response): number | undefined;
 /** Record an execution's start, before it reads its data. */
 export declare function executionStart(): ExecutionStart;
 /**

package/dist/types/cache/memory-segment-store.d.ts

@@ -4,7 +4,7 @@
  * Simple in-memory implementation of SegmentCacheStore.
  * Uses globalThis to survive HMR in development.
  */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "./types.js";
+import type { CacheStoreScope, SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 /**
  * Options for MemorySegmentCacheStore
@@ -70,6 +70,25 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
      * ```
      */
     maxEntries?: number;
+    /**
+     * Where an entry this store writes can be read; what `router.prerender()`
+     * checks before warming a route. Defaults to `"local"`: the maps live in one
+     * process, and the router cannot tell one long-running server from several
+     * replicas or serverless instances, so a warm into it is refused in
+     * production. Set `"global"` only when exactly one process serves the app
+     * (a single Node server); a warm then reports `warmed`. Under the Vite dev
+     * server a `"local"` instance already counts as shared.
+     *
+     * Like `defaults` and `keyGenerator`, the scope is per instance: two
+     * instances with the same `name` share their maps but each declares its own
+     * scope. Keep them identical.
+     *
+     * @example
+     * ```typescript
+     * const store = new MemorySegmentCacheStore({ scope: "global" });
+     * ```
+     */
+    scope?: CacheStoreScope;
 }
 /**
  * In-memory segment cache store.
@@ -106,6 +125,13 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
  * ```
  */
 export declare class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    /**
+     * SegmentCacheStore.scope: "local" unless `options.scope` says otherwise, so
+     * router.prerender() refuses to warm into these maps in production. Under
+     * the Vite dev server the gate counts a "local" instance as shared
+     * (store-scope.ts resolveWarmStoreScope).
+     */
+    readonly scope: CacheStoreScope;
     readonly supportsPassiveShellReads: true;
     private cache;
     private responseCache;
@@ -151,6 +177,12 @@ export declare class MemorySegmentCacheStore<TEnv = unknown> implements SegmentC
     } | null>;
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated">;
     isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    /**
+     * A tag invalidated in a millisecond after the write's execution started
+     * (#1068). Strictly after: the start's own millisecond is ambiguous, and
+     * invalidation-order.ts orders those exactly.
+     */
+    private invalidatedAfter;
     private tagsInvalidatedSince;
     invalidateTags(tags: string[]): Promise<void>;
     private registerTags;

package/dist/types/cache/shell-snapshot.d.ts

@@ -18,9 +18,11 @@
  * the capture's copy of a value: it is dynamic or has its own cache. A
  * bake-lane loader body that runs on a HIT reads the store too; its pinned
  * container paths stay the pin's (overlayLoaderContainer), and its settled
- * pushes stay the record's (HandleStore.pushRestored).
+ * pushes stay the record's (HandleStore.pushRestored). The two go together:
+ * a loader whose pin the entry lost runs fresh, and the record's copies of
+ * its pushes give way to that run's (restoreHandles).
  */
-import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord, CacheReadError } from "./types.js";
+import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord, ShellSnapshotHandlesValue, CacheReadError } from "./types.js";
 /**
  * A store wrapper the CAPTURE render reads through. Every call passes through
  * to the underlying store unchanged; the one thing it records is the doc
@@ -172,22 +174,45 @@ export interface ShellLoaderSeedEntry {
      * hole-free record: a hole-carrying one always runs.
      */
     runs: boolean;
+    /**
+     * The capture that wrote the pin recorded every settled push of the
+     * loader's run in the doc record (CachedEntryData.handleOwners): the pin
+     * carries the `runs` bit, which captures write since they record those
+     * pushes (v0.18). A replay then drops any other settled push of the loader
+     * (HandleStore RecordAuthority "pin"). False for an older pin, whose record
+     * may hold none and leaves them to the run.
+     */
+    complete: boolean;
 }
 /**
  * Materialize the loader-family seed from a shell snapshot for a HIT's tail
  * render: Flight-deserialize each recorded (promise-elided) bake-lane
- * container into a segment-key -> container Map, which serveShellHit assigns
- * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
+ * container into a loader-id -> pin Map, which serveShellHit assigns to the
+ * tail context's `_shellLoaderSeed` (loader-cache.ts servedPins).
  * Lives here so every snapshot family is decoded in this module (the segment
  * family via {@link SeededShellStore}); the loader family is not a store
  * read, so it seeds the context instead of a store.
  *
+ * Keyed by loader, not by the segment a pin was stored under: a loader runs
+ * once per capture, so every segment that registers it pinned the same
+ * container, and the loader's value and its handle pushes are both looked up
+ * by loader. A key that does not parse pins nothing.
+ *
  * Deserializations run in parallel; a record that fails to decode is skipped
  * (that loader drifts — the pre-snapshot behavior — instead of failing the
  * HIT). Returns undefined when the snapshot carries no loader records, without
  * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
  */
 export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[]): Promise<Map<string, ShellLoaderSeedEntry> | undefined>;
+/** The key of a snapshot's one `handles` record (ShellSnapshotHandlesValue). */
+export declare const SHELL_HANDLES_RECORD_KEY = "handles";
+/**
+ * The `handles` record of a prerender-served entry, which a HIT tail restores
+ * after the prerender store's handles (cache-lookup.ts yieldFromStore), or
+ * undefined: an entry with a doc record, or one written before the record
+ * existed (v0.21), which serves as it did.
+ */
+export declare function shellPrerenderHandles(snapshot: readonly ShellSnapshotRecord[]): ShellSnapshotHandlesValue | undefined;
 /**
  * The implicit doc scope's store on a HIT tail and on a partial replay: it
  * serves the snapshot's segment records, the doc record among them, and

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

@@ -0,0 +1,22 @@
+/**
+ * The store scope `router.prerender()` gates a warm on
+ * (prerender/create-prerender-trigger.ts). See
+ * docs/design/prerender-every-route.md, "The store declaration".
+ */
+import type { CacheStoreScope, SegmentCacheStore } from "./types.js";
+/**
+ * True under the Vite dev server: only its routes-manifest virtual module sets
+ * the dev origin (vite/discovery/virtual-module-codegen.ts). A build, a preview
+ * server and a test runner answer false.
+ */
+export declare function isViteDevServer(): boolean;
+/**
+ * The scope a warm treats `store` as having: its own declaration, with none
+ * or an unknown value being `"local"`.
+ *
+ * One exception: under the Vite dev server a MemorySegmentCacheStore answers
+ * `"global"`, because that one process serves every request. Production reads
+ * the class's own `scope` (`"local"`): changing that declaration is what
+ * would admit it there.
+ */
+export declare function resolveWarmStoreScope(store: SegmentCacheStore<any>, devServer?: boolean): CacheStoreScope;