@rangojs/router 0.17.0 → 0.18.0

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

@@ -99,7 +99,11 @@ export interface SegmentCacheStore<TEnv = unknown> {
      */
     get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     /**
-     * Store entry data with TTL
+     * Store entry data with TTL. Resolve once a later `get(key)` from the same
+     * location observes the entry: the route cache() write runs in a background
+     * task, and a PPR shell capture awaits that task before it reads the entry
+     * back (#957). A store that resolves earlier makes the capture re-render
+     * the page instead of replaying the entry.
      * @param key - Cache key
      * @param data - Serialized entry data
      * @param ttl - Time-to-live in seconds
@@ -156,8 +160,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * upgrade — the reactVersion field on the entry gates that at read time).
      * @param key - Cache key
      * @param entry - The shell prelude/postponed/version/createdAt bundle
-     * @param ttlSeconds - Time-to-live in seconds
-     * @param swrSeconds - Optional stale-while-revalidate window in seconds
+     * @param ttlSeconds - Time-to-live in seconds: the route's `ppr.ttl`
+     *   (undefined: the store's default), capped to the route cache() entry
+     *   the capture replayed or wrote. A capped window arrives in whole
+     *   seconds, rounded up, with ttl + swr at least 1; its ttl can be 0 (a
+     *   shell stale from the start, captured from a record inside its swr
+     *   window).
+     * @param swrSeconds - Optional stale-while-revalidate window in seconds,
+     *   under the same cap
      * @param tags - Optional cache tags for invalidation (participates in
      *   invalidateTags via the same tag machinery as the item family)
      * @returns `invalidated` when a generation marker rejected the write,
@@ -169,6 +179,40 @@ export interface SegmentCacheStore<TEnv = unknown> {
      *   without acknowledgements.
      */
     putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
+    /**
+     * @internal The document serve path's shell read, for built-in stores. The
+     * serve path prefers it over getShell: it resolves with the entry and the
+     * raw (decoded) prelude, the snapshot on its own promise, and the read's
+     * `debugPerformance` stats. CFCacheStore's layout keeps the snapshot behind
+     * the prelude, so its HIT can commit before the snapshot is read;
+     * VercelCacheStore reads the whole entry and decodes the prelude once per
+     * memoized shell (issue #941, docs/design/shell-entry-layout.md). Not part
+     * of the custom-store contract.
+     */
+    readShellDocument?(key: string, options?: ShellDocumentReadOptions): Promise<ShellDocumentRead | null>;
+    /**
+     * @internal How long (ms) this store's isolate memos (shell, tag markers)
+     * can serve a read that predates a tag invalidation made elsewhere. After
+     * updateTag()/revalidateTag(), the response's fresh-reads cookie lasts the
+     * longest of these, and the same user's requests skip the memos meanwhile.
+     * Absent or 0: nothing to cover.
+     */
+    readonly freshReadsWindowMs?: number;
+    /**
+     * @internal Drop this isolate's memoized copy of a shell (shell-memo.ts) so
+     * the next read goes to the store. A HIT whose doc record failed to decode
+     * calls it after replacing the entry with a tombstone: the memoized copy
+     * holds the same record. Built-in stores only; not part of the custom-store
+     * contract.
+     */
+    dropShellMemo?(key: string): void;
+    /**
+     * @internal The largest shell entry (prelude, postponed state, and snapshot
+     * bytes) this store can hold in one value. The capture refuses a bigger
+     * entry instead of letting the write fail inside waitUntil. Absent: the
+     * capture applies DEFAULT_SHELL_ENTRY_MAX_BYTES (Cloudflare KV's 25 MiB).
+     */
+    readonly maxShellEntryBytes?: number;
     /**
      * Declares the shell family present-but-inert: getShell/putShell exist but
      * no-op (a custom store whose backing tier is conditionally unavailable).
@@ -210,6 +254,20 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * APIs delegate to. Receives ALL of one invalidation call's tags at once so
      * stores can batch their work (e.g. a single CDN purge request rather than
      * one per tag). Stores that do not support tags simply omit this method.
+     *
+     * Both verbs call it synchronously, inside the request that invalidates
+     * (#973); revalidateTag() then hands the returned promise to waitUntil
+     * without awaiting it. Read-your-own-writes for that request comes from
+     * what the store does before its first await: record the tags as
+     * invalidated in state its reads consult for the rest of the request (the
+     * built-in stores key a map by the request's root context and the store,
+     * so contexts derived from the request share it, and compare each hit's
+     * tags and write time against it), then start the
+     * durable write. Such a mask must only ever turn hits into misses, and only
+     * in that request: a durable write that later fails then costs extra
+     * misses, never a stale read. A store that records nothing before its
+     * first await still works; the request that ran revalidateTag() can read
+     * entries the invalidation covers until the durable write lands.
      * @param tags - The cache tags to invalidate
      */
     invalidateTags?(tags: string[]): Promise<void>;
@@ -295,12 +353,13 @@ export interface ShellCacheEntry {
      */
     buildVersion?: string;
     /**
-     * The initialTheme the CAPTURE render was built with (the derived context's
-     * reqCtx.theme). The resume tail must render ThemeProvider with the SAME
+     * The initialTheme the CAPTURE render was built with: the no-cookie default
+     * (payloadInitialTheme, rsc/full-payload.ts), never the capturing visitor's
+     * theme (#971). The resume tail must render ThemeProvider with the SAME
      * initialTheme the frozen prelude was rendered with: React resume requires the
      * tree above the holes to match the prerendered tree, and initialTheme is
      * per-request METADATA, not part of the cached segments — a visitor whose
-     * theme differs from the capturer's would otherwise produce a divergent resume
+     * theme differs from the capture's would otherwise produce a divergent resume
      * tree (broken stitching/hydration). The visitor's real theme is applied
      * pre-paint by the FOUC script and re-synced from the cookie post-mount by
      * ThemeProvider.
@@ -321,17 +380,21 @@ export interface ShellCacheEntry {
      */
     snapshot?: ShellSnapshotRecord[];
     /**
-     * The key of the CANONICAL document segment record inside `snapshot` — the
-     * one navigation replay can actually consume (resolved under the implicit
-     * doc namespace at capture; see CacheScope.cacheRoute). Replay eligibility
-     * requires this exact record: the snapshot also carries incidentally
-     * recorded explicit-tier records (RecordingShellStore passthroughs) whose
-     * keys a partial lookup can never resolve, and counting those declared
-     * entries "replayable" that always missed (`snapshot-miss` flip-flop).
-     * Absent on entries captured before the field existed OR when the capture
-     * recorded no doc record (cache(false)/condition-false routes, prerender
-     * short-circuit) — both read as `no-segment-snapshot`; recapture heals the
-     * former.
+     * Records the capture dropped from `snapshot` because no reader of this
+     * entry consumes them, by family (`item:4/response:1`). Diagnostic only: the
+     * HIT tail timing reports it next to the kept records. See
+     * docs/design/shell-entry-layout.md ("Record only what a HIT reads").
+     */
+    prunedRecords?: string;
+    /**
+     * The key of the document segment record inside `snapshot`: the handler
+     * layer every HIT replays (a document HIT tail looks the record up by this
+     * key, so a store keyGenerator or a build-time capture host cannot send it
+     * elsewhere) and the record navigation replay consumes (resolved under the
+     * implicit doc namespace at capture; see CacheScope.cacheRoute). A capture
+     * that ran handlers always stores it; only a prerender-served entry (the
+     * prerender store supplies the handler layer) has none. A document entry
+     * without it is served as a MISS.
      */
     docKey?: string;
     /**
@@ -340,26 +403,6 @@ export interface ShellCacheEntry {
      * the partial request's headers and middleware state are not document state.
      */
     navigationOnly?: true;
-    /**
-     * True when the capture's HANDLER layer declared per-request liveness: a
-     * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the
-     * capture mask turns it into a never-filling hole), such a push was still
-     * pending when the entry was written, or a handler-invoked loader
-     * (ctx.use(loader) from a handler body — the consumption lane, #672)
-     * executed during the capture. The serve tail then must NOT take the
-     * handler-free fast path (the implicit doc-cache hit): only a handler
-     * re-run can mint that hole's live promise or refresh that consumed value.
-     * DSL-loader pushes never set this — loaders re-run fresh on every HIT, so
-     * their holes always fill.
-     */
-    handlerLiveHoles?: boolean;
-    /**
-     * Legacy/fallback marker for a transition({ when }) predicate that was not
-     * evaluated by the PPR pre-handler gate. Such an entry stays conservatively
-     * ineligible for handler-free replay. New PPR matches evaluate known segment
-     * predicates before the pipeline and do not set this marker.
-     */
-    transitionWhen?: true;
     /** Capture-generation start time; tag invalidations at or after it win. */
     createdAt: number;
 }
@@ -374,6 +417,117 @@ export type DocumentShellCacheEntry = ShellCacheEntry & {
     prelude: string;
     postponed: string | null;
 };
+/** @internal Options of {@link SegmentCacheStore.readShellDocument}. */
+export interface ShellDocumentReadOptions {
+    /**
+     * Tag names the route declares for its shell (`ppr.tags`), known before the
+     * entry is read: their marker reads can start alongside the entry read.
+     */
+    tagHints?: readonly string[];
+}
+/**
+ * @internal Why a prelude-first read's snapshot is missing although the entry
+ * stored one: `unavailable` (the read timed out or failed; the entry may be
+ * sound) or `corrupt` (the bytes arrived and do not parse; the store evicted
+ * the entry).
+ */
+export type ShellSnapshotFailure = "unavailable" | "corrupt";
+/**
+ * @internal Result of {@link SegmentCacheStore.readShellDocument}.
+ */
+export interface ShellDocumentRead {
+    /** The entry without its prelude and snapshot (delivered separately). */
+    entry: ShellCacheEntry;
+    /** Raw prelude bytes (empty for a navigationOnly entry). */
+    prelude: Uint8Array;
+    shouldRevalidate?: boolean;
+    /**
+     * The capture snapshot, read after the prelude. Resolves undefined when the
+     * entry has none or it could not be read (`snapshotFailure` says which); a
+     * document HIT then cannot replay its doc record and degrades
+     * (rsc-rendering.ts serveShellHit).
+     * Never rejects.
+     */
+    snapshot: Promise<ShellSnapshotRecord[] | undefined>;
+    /**
+     * Why `snapshot` resolved undefined although the entry stored one, or
+     * undefined when it did not fail. A document HIT that cannot replay its
+     * doc record replaces the entry only when it is broken, not when its read
+     * was merely slow (rsc-rendering.ts serveShellHit). Never rejects.
+     */
+    snapshotFailure?: Promise<ShellSnapshotFailure | undefined>;
+    /**
+     * Where the read's time and bytes went, for the `debugPerformance` metrics
+     * (rsc-rendering.ts) and the store's own debug trace. Present only when one
+     * of them is on for the request.
+     */
+    stats?: ShellReadStats;
+}
+/**
+ * @internal Sub-steps of a prelude-first shell read. Times are ms. workerd
+ * advances its clock only on I/O, so a CPU-only field
+ * (`snapshot.parseMs`) reads 0 on a deployed worker: the byte counts are the
+ * cost signal there.
+ */
+export interface ShellReadStats {
+    /**
+     * The tier that answered: `memo` (the store's shell memo), `l1`/`kv`
+     * (CFCacheStore), or `store` (a single-tier store, VercelCacheStore).
+     */
+    tier: "memo" | "l1" | "kv" | "store";
+    /** The per-isolate memo's outcome for this read and its size after it. */
+    memo?: {
+        hit: boolean;
+        bytes: number;
+    };
+    /**
+     * A KV read after an L1 attempt: how long the L1 attempt took and why it
+     * missed. The KV fields below then restart from the KV read.
+     */
+    l1MissMs?: number;
+    l1MissReason?: string;
+    /** Cache API match (L1) or KV get (KV) until the body was available. */
+    matchMs?: number;
+    /** Frame head read (I/O) and parse. */
+    headMs?: number;
+    /** Prelude bytes read. */
+    preludeMs?: number;
+    /** Tag-marker read, start to resolve (runs alongside the prelude read). */
+    markerMs?: number;
+    /** How long the read waited for the marker after the prelude was read. */
+    markerWaitMs?: number;
+    /**
+     * The marker check was awaited after the entry read (VercelCacheStore), not
+     * alongside the prelude read; hinted reads still start with the entry read.
+     */
+    markerSerial?: true;
+    /**
+     * How the isolate marker memo answered the shell's tags (the most
+     * store-bound outcome across them): `fresh`, `stale` (served, refreshing in
+     * the background), `read` (from the store), `bypass` (fresh-reads cookie).
+     */
+    markerMemo?: "fresh" | "stale" | "read" | "bypass";
+    /** Tags whose marker reads were started before the entry's head (hints). */
+    markerHinted?: readonly string[];
+    /** When the hinted marker reads started (performance.now()). */
+    markerHintStartedAt?: number;
+    /** How many of the shell's tags were hinted. */
+    markerHintHits?: number;
+    /** How long the hinted marker reads ran before the entry named its tags. */
+    markerLeadMs?: number;
+    /** The request carried the fresh-reads cookie: no isolate memo was used. */
+    freshReads?: true;
+    headBytes?: number;
+    preludeBytes?: number;
+    /** Number of the shell's tags the marker read covered. */
+    tags?: number;
+    /** Filled after the commit, once the snapshot has been read. */
+    snapshot?: {
+        readMs: number;
+        parseMs: number;
+        bytes: number;
+    };
+}
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family
@@ -398,12 +552,20 @@ export interface ShellSnapshotLoaderValue {
      * container carries hole markers, so a HIT must gate the overlay on the
      * fresh run (only the loader body can mint the live nested promises);
      * 0 = fully pinned, so a HIT resolves the payload promise immediately from
-     * the pin while the fresh run proceeds ungated (side effects and cache
-     * read-through writes preserved; its values were discarded either way —
-     * recorded paths win wholesale). Absent on pre-bit snapshots, which keep
-     * the gated path.
+     * the pin and does not run the loader body (unless `runs`). Absent on
+     * pre-bit snapshots, which keep the gated path.
      */
     holes?: 0 | 1;
+    /**
+     * 1 when the capture saw a loader push it could not record (a deferred
+     * push, one with masked nested promises, or one made outside any loader
+     * body): a HIT then still runs the loader body in the background
+     * (pin-first) so those pushes reach the page. 0: a hole-free record is
+     * served from the pin alone and its body does not run on a HIT. Absent (a
+     * snapshot written before the bit, which lacks the loader-owned pushes)
+     * reads as 1, so the body supplies them.
+     */
+    runs?: 0 | 1;
 }
 /** A serialized cached Response for the response family of a shell snapshot. */
 export interface ShellSnapshotResponseValue {
@@ -527,8 +689,10 @@ export type SegmentHandleData = Record<string, unknown[]>;
 /**
  * segmentId -> handleName -> the owning loader id of each recorded value, by
  * index (null: not owned). Only a PPR shell capture writes owners: the
- * settled pushes of an `ssr: false` loader's own body, which the record keeps
+ * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
+ * the loaders it awaits, and its own cache() replays), which the record keeps
  * because the prelude rendered them. restoreHandles replays an owned value
- * through HandleStore.pushReplayed, so that loader's live re-run replaces it.
+ * through HandleStore.pushReplayed, so a loader that does run on the HIT
+ * replaces it with its live push.
  */
 export type HandleOwners = Record<string, Record<string, (string | null)[]>>;

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

@@ -5,9 +5,10 @@
  * `@vercel/functions`). It is the production store analogue to CFCacheStore, but
  * far smaller: Vercel's Runtime Cache already IS a distributed, tag-aware cache
  * (regional storage, global tag-expire within ~300ms), so none of CFCacheStore's
- * L1/L2 tiering, KV tag-marker comparison, marker memoization, or per-tier
- * timeout budgets are needed here - the platform does that work. What this store
- * adds on top of the raw primitive is the parts Vercel does NOT give us:
+ * L1/L2 tiering or per-tier timeout budgets are needed here - the platform does
+ * that work. Tag markers exist only for the shell family (`tm`, see
+ * isTagsInvalidatedSince), and only PPR shell reads memoize them. What this
+ * store adds on top of the raw primitive is the parts Vercel does NOT give us:
  *
  *   1. Stale-while-revalidate. `getCache` has no stale-but-serve: a TTL'd entry
  *      simply becomes a miss. We store our own {staleAt, expiresAt} envelope and
@@ -30,8 +31,9 @@
  * `getCache(...)` result, which satisfies the shape structurally. That keeps the
  * router free of a hard Vercel dependency.
  */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, CacheReadError } from "../types.js";
-import type { RequestContext } from "../../server/request-context.js";
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
+import { type RequestContext } from "../../server/request-context.js";
+import { type StoreMemoOptions } from "../shell-memo.js";
 /**
  * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
  * from `@vercel/functions`. Declared locally so @rangojs/router carries no hard
@@ -69,7 +71,7 @@ export declare const VERCEL_MAX_TAGS_PER_ITEM: number;
 /** Max tag length in UTF-8 bytes accepted by Vercel; longer tags are skipped. */
 export declare const VERCEL_MAX_TAG_BYTES: number;
 /** Read-path outcome for the debug sink. */
-export type VercelCacheReadOutcome = "miss" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
+export type VercelCacheReadOutcome = "miss" | "memo-hit" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
 /** Diagnostic event emitted on every read when `debug` is set. */
 export interface VercelCacheReadDebugEvent {
     op: "get" | "getItem" | "getResponse" | "getShell";
@@ -100,10 +102,13 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      */
     cache: VercelRuntimeCache;
     /**
-     * `waitUntil` from `@vercel/functions`. Used only to run the stale-read lock
-     * write (herd dampening) off the response path - the router already
-     * backgrounds the actual writes. When omitted, the lock write runs detached
-     * (fire-and-forget) instead.
+     * `waitUntil` from `@vercel/functions`. Keeps two background reads/writes
+     * alive past the response: the stale-read lock write (herd dampening; the
+     * router already backgrounds the actual writes) and the PPR shell reads'
+     * tag-marker memo refreshes (`memo.markerMaxStaleMs`). When omitted, both
+     * run detached (fire-and-forget), and the platform may end a refresh when
+     * the response ends; the next read past the stale window then reads the
+     * marker itself.
      */
     waitUntil?: (promise: Promise<unknown>) => void;
     /**
@@ -136,6 +141,26 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      * receives the structured VercelCacheReadDebugEvent.
      */
     debug?: VercelCacheDebug;
+    /**
+     * Per-process memos ({@link StoreMemoOptions}), kept per `cache` handle:
+     * create the `getCache()` handle once per process, not per request, or the
+     * memos never hit. `shellMs` (default 2000) and `shellMaxBytes` (default
+     * 16 MiB) size the PPR shell memo; `markerFreshMs` (default 300) and
+     * `markerMaxStaleMs` (default 2000) the memo of the tag markers
+     * `invalidateTags()` writes, which PPR shell reads use
+     * (stale-while-revalidate). The process that invalidates writes the new
+     * marker into its memo; another process in the region rejects a memoized
+     * shell once its marker memo sees it (up to `markerMaxStaleMs`). The
+     * markers are a regional `cache.set` (only `expireTag` is global), so
+     * another region serves a shell it memoized before the invalidation until
+     * its window passes, where without the memo `expireTag` removes it within
+     * about 300 ms; a platform `expireTag` issued outside rango is likewise
+     * seen once the window passes. The response of a request that ran
+     * `updateTag()` / `revalidateTag()` sets the fresh-reads cookie, and the
+     * same user's requests carrying it skip both memos. `{ shellMs: 0 }` turns
+     * the shell memo off, `{ markerFreshMs: 0 }` the marker memo.
+     */
+    memo?: StoreMemoOptions;
 }
 /**
  * Vercel Runtime Cache-backed segment cache store.
@@ -170,12 +195,18 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
  * import { getCache, waitUntil } from "@vercel/functions";
  * import { VercelCacheStore } from "@rangojs/router/cache";
  *
+ * // One handle per process: getCache() resolves the platform cache on every
+ * // call, and the PPR shell and tag-marker memos are kept per handle.
+ * // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
+ * // would be undefined here) so cross-deploy busting via `version` works.
+ * const runtimeCache = getCache({
+ *   namespace: process.env.VERCEL_DEPLOYMENT_ID,
+ * });
+ *
  * export const router = createRouter({
  *   cache: () => ({
  *     store: new VercelCacheStore({
- *       // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
- *       // would be undefined here) so cross-deploy busting via `version` works.
- *       cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+ *       cache: runtimeCache,
  *       waitUntil,
  *       defaults: { ttl: 60, swr: 300 },
  *     }),
@@ -191,6 +222,16 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
     private readonly waitUntil?;
     private readonly version?;
     private readonly maxItemBytes;
+    private readonly memo;
+    private readonly handleMemos;
+    /** @internal SegmentCacheStore.freshReadsWindowMs */
+    readonly freshReadsWindowMs: number;
+    /**
+     * @internal SegmentCacheStore.maxShellEntryBytes: the item cap, less the
+     * base64 expansion of the prelude the shell envelope stores (the capture
+     * measures raw prelude bytes).
+     */
+    readonly maxShellEntryBytes: number;
     private readonly name?;
     private readonly debug?;
     constructor(options: VercelCacheStoreOptions<TEnv>);
@@ -210,6 +251,46 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
+    /**
+     * @internal The document serve path's read (SegmentCacheStore
+     * .readShellDocument): the same read as getShell, with the prelude decoded
+     * here, once per memoized shell rather than once per HIT, and the read's
+     * `debugPerformance` stats. The runtime cache returns a parsed value, so
+     * there is no prelude-first read and the tag-marker read follows the entry
+     * read (`markerSerial`).
+     */
+    readShellDocument(key: string, options?: ShellDocumentReadOptions): Promise<ShellDocumentRead | null>;
+    /** @internal SegmentCacheStore.dropShellMemo */
+    dropShellMemo(key: string): void;
+    /**
+     * getShell's read, shared with readShellDocument: the shell memo first
+     * (shell-memo.ts), then the runtime cache. A memoized shell still runs the
+     * tag-marker check; `memoized` is the memo slot's value when the read came
+     * from, or went into, the memo (readShellDocument keeps the decoded prelude
+     * there).
+     */
+    private readShell;
+    /**
+     * The shell's tag-marker check, timed into `stats`. Markers a prefetch
+     * already started (hinted tags) are awaited, not re-read; the check itself
+     * always uses the entry's own tags.
+     */
+    private shellTagsInvalidated;
+    /**
+     * Start the tm-marker reads of the tags this shell key carried last time
+     * (and the route's static tags) alongside the entry read.
+     */
+    private prefetchShellMarkers;
+    /**
+     * A tag's latest invalidatedAt (or null). With `isolateMemo` (PPR shell
+     * reads only) through the per-process marker memo (isolate-tag-memo.ts):
+     * fresh values are used as is, stale ones are used and refreshed in the
+     * background, older ones block on the runtime-cache read. A request
+     * carrying the fresh-reads cookie skips the memo. A failed read rejects and
+     * is never memoized. The shell write gate and build shells
+     * (isTagsInvalidatedSince) read the runtime cache every time.
+     */
+    private readTagMarker;
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
     /**
      * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince).
@@ -218,7 +299,24 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
      * generation start wins; read errors fail open like the CF marker check.
      */
     isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    private tagsInvalidatedSince;
     invalidateTags(tags: string[]): Promise<void>;
+    /**
+     * The request-local half of invalidateTags(), run before its first await
+     * (#973): see requestInvalidations. revalidateTag() waits for nothing
+     * after it.
+     */
+    private maskTagsForRequest;
+    /**
+     * Whether this request invalidated one of `tags` through this store at or
+     * after `taggedAt`. `>=`, as the marker check: an entry written in the
+     * invalidation's millisecond may hold a value computed before it, so it
+     * misses (a false miss, never a stale read). An entry without a stamp was
+     * written before the stamp existed and counts as older.
+     */
+    private maskedForRequest;
+    /** A data read's mask check: reports the miss and returns true when masked. */
+    private maskedMiss;
     private toStoreKey;
     private write;
     /**

package/dist/types/prerender/build-shell-capture.d.ts

@@ -4,9 +4,9 @@
  * Runs in the RSC realm of the build's temp server, AFTER all bundles are
  * written (the prelude embeds built client asset URLs — bootstrap module,
  * chunk preloads — that only exist post-client-build). The capture core is
- * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
- * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
- * quiesce, tags union, putShell barrier). Build capture first replays global
+ * producer A's, verbatim: deriveShellCaptureContext (push funnel, snapshot
+ * recording, implicit doc-cache scope) + settleCaptureRecord (the record-first
+ * step) + captureAndStoreShell (gates, quiesce, tags union, putShell barrier). Build capture first replays global
  * and route middleware with a synthetic build request context
  * (`ctx.build === true`, inert `ctx.waitUntil()`); middleware can seed vars or
  * call `ctx.dynamic()` to skip this URL. The sink is an entry collector instead
@@ -95,10 +95,17 @@ export interface BuildShellCaptureResult {
     tags?: string[];
     /** On route-mismatch: what this router's match actually landed on. */
     matchedRouteName?: string;
+    /**
+     * On no-shell: the attempt ran out of ppr.captureTimeout. It is not
+     * retried: its match may still be running, and the retry would start the
+     * same work beside it (runtime twin: shell-capture.ts runShellCapture).
+     */
+    timedOut?: true;
 }
 /**
  * Capture the PPR shell for one prerendered URL at build time. Retries once
  * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
- * transform graph, mirroring producer A's cold-start retry — same delay).
+ * transform graph, mirroring producer A's cold-start retry — same delay),
+ * unless the attempt ran out of ppr.captureTimeout (`timedOut`).
  */
 export declare function captureShellForBuild(opts: BuildShellCaptureOptions): Promise<BuildShellCaptureResult>;

package/dist/types/router/instrument.d.ts

@@ -163,6 +163,14 @@ export declare function observePhase<T>(spec: PhaseSpec, fn: (span: TraceSpan) =
  * nothing to record here and short-circuits.
  */
 export declare function observeHandler<C, R>(id: string, handler: (ctx: C) => R, ctx: C): R;
+/**
+ * observeHandler, inside segment `segmentId`'s tag scope, so the tags the
+ * handler records reach the route's cache() record (#957, cache-tag.ts
+ * runInSegmentTagScope). `spanId` is observeHandler's `id`. A request that
+ * cannot write a record takes observeHandler's path as is, with the same one
+ * request-context read: no scope, no closure.
+ */
+export declare function observeSegmentHandler<C, R>(segmentId: string, spanId: string, handler: (ctx: C) => R, ctx: C): R;
 /**
  * Emit one discrete telemetry event (the event-shaped counterpart to
  * observePhase). Resolves the sink from the active router context and stamps the

package/dist/types/router/middleware-types.d.ts

@@ -48,7 +48,12 @@ export interface MiddlewareContext<TEnv = any, TParams = Record<string, string |
     header(name: string, value: string): void;
     routeName?: DefaultRouteName;
     debugPerformance(): void;
-    theme?: Theme;
+    /**
+     * The visitor's theme (cookie or default); undefined without theme config.
+     * Guarded like `cookies()`: a read inside a `"use cache"` function throws
+     * (#971).
+     */
+    readonly theme?: Theme;
     setTheme?: (theme: Theme) => void;
     setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
     /** Global route names only; see {@link GlobalReverseFunction}. */

package/dist/types/router/segment-resolution/loader-cache.d.ts

@@ -17,15 +17,39 @@
  * On stale hit (SWR): returns stale data, schedules background revalidation.
  * On miss: executes loader, schedules non-blocking cache write.
  *
+ * Identity (#972): without a key() or a store keyGenerator the entry is
+ * shared across users, so a fill whose execution recorded a request-identity
+ * read fails and is not stored, whoever started that execution
+ * (server/context.ts recordLoaderIdentityRead).
+ *
  * Handle pushes (`ctx.use(Handle)(...)` in the loader body) are a side effect
  * the HIT must reproduce: the MISS records the pushes of the body and of the
  * loaders it awaits via ctx.use into the entry's `handles` blob (the
  * "use cache" capture/encode), and every HIT — stale included — replays
  * them, each loader's pushes at most once per request (a dependency another
  * reader already ran keeps its live pushes). See replayLoaderHandles.
+ *
+ * Tags too (#964): the entry stores its cache() tags plus every tag its
+ * execution recorded, those of the loader values it read included
+ * (cache-tag.ts "Recorded-tag sets"), so updateTag() of any of them drops it.
+ * Every HIT records the stored tags through the loader's tag owner
+ * (recordLoaderTags), so a route cache() record, PPR shell or document built
+ * over the HIT carries them, and a loader that reads this one takes them on.
+ * Once the binding started, a loader body's ctx.use of it gets the same
+ * dataPromise as a handler read (createLoaderExecutor's useLoader); a stale
+ * refresh does not (setupLoaderAccess _runLoaderIsolated).
  */
-import { type LoaderEntry } from "../../server/context.js";
+import { type EntryData, type LoaderEntry } from "../../server/context.js";
 import type { HandlerContext } from "../../types.js";
+/**
+ * Whether a request over the matched chain `entries` resolves a loader bound
+ * with its own cache(): on a chain entry, or on its parallel slots, orphan
+ * layouts or intercepts. The match arms the per-execution loader tag sets on
+ * it (cache-tag.ts armLoaderTagSets), before any loader starts, so a
+ * dependency the handler or another binding starts first still records.
+ * Memoized per entry.
+ */
+export declare function bindsLoaderCache(entries: readonly EntryData[]): boolean;
 /**
  * Resolve loader data with optional caching.
  *
@@ -46,18 +70,23 @@ import type { HandlerContext } from "../../types.js";
  * never run under a shell capture), so the lane is decided here, per LOADER,
  * never by the entry's loading():
  *
- * - BAKE lane: `loader(Def, { ssr: false })` (awaitBeforeFlush) with a
- *   `bakeSegmentKey` from the caller. The loader EXECUTES at capture (the
+ * - BAKE lane: `loader(Def, { ssr: false })` (LoaderEntry `bake`: the
+ *   caller passes a `bakeSegmentKey` for it on document and navigation
+ *   evaluations alike; a capture, a document evaluation, also has
+ *   awaitBeforeFlush). The loader EXECUTES at capture (the
  *   flag's "data in the HTML before first flush" maps to the frozen prelude)
  *   and its settled non-promise data bakes into the shell. Promises nested in
- *   plain objects/arrays are masked (mask-nested.ts) and stay live holes at
- *   the consumer's own Suspense — per-request material must be promise-shaped
- *   (the #692 cross-session scar). The masked container registers on
- *   `_shellCaptureLoaderRecords`: it holds the capture gate (bounded by
- *   `ppr.captureTimeout`) and pins into the snapshot's loader family, and on a
- *   HIT the recorded container is overlaid onto the fresh run (below) so the
- *   payload matches the frozen prelude byte-for-byte. cookies()/headers() in
- *   its body (nested promise bodies included) trip the capture guard.
+ *   plain objects, arrays and JSX props are masked (mask-nested.ts) and stay
+ *   live holes at the consumer's own Suspense — per-request material must be
+ *   promise-shaped (the #692 cross-session scar). The masked container
+ *   registers on `_shellCaptureLoaderRecords`: it holds the capture gate
+ *   (bounded by `ppr.captureTimeout`) and pins into the snapshot's loader
+ *   family, and on a HIT the recorded container is overlaid onto the fresh
+ *   run (below) so the payload matches the frozen prelude outside the holes.
+ *   A server-component element holding a promise is a hole as a whole, so its
+ *   other props come from the fresh run (loader-snapshot.ts
+ *   elideLoaderContainer). cookies()/headers() in its body (nested promise
+ *   bodies included) trip the capture guard.
  * - LIVE lane: every other loader, whatever its entry's loading(). Never
  *   executes at capture: the slot gets a never-resolving promise
  *   (loader-mask.ts) and postpones at the reader's boundary — loading() or an