@rangojs/router 0.26.6 → 0.28.0

package/dist/types/rsc/response-cache-serve.d.ts

@@ -5,23 +5,18 @@
  * matched entry tree, condition eval, key resolution (route key() > store
  * keyGenerator > default, CacheScope.resolveKeyFrom), tag resolution,
  * pre-handler-callback timing, and the fresh-hit / SWR-revalidate /
- * miss-write branches — for BOTH the production
- * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
- * primitive (testing/dispatch.ts), so the two can never drift.
+ * miss-write branches — for the response-route handler
+ * (rsc/response-route-handler.ts), which the production handler and the
+ * dispatch testing primitive both run (rsc/request-stages.ts
+ * serveResponseRoute), so the two can never drift.
  *
- * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
- * which the non-Vite unit-test runner cannot resolve, and this module is on the
- * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` is
- * NOT imported here at runtime — it is INJECTED by the caller (production
- * imports it statically; dispatch lazy-imports it only once a response route
- * matches). The only runtime imports here are plugin-rsc-free
- * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
- * type-only import (erased at build).
+ * `createCacheScope` is injected by the caller: the response-route handler
+ * passes the real one, unit tests a stub.
  */
 import type { CacheScope } from "../cache/cache-scope.js";
 import { type RequestContext } from "../server/request-context.js";
 import type { EntryCacheConfig, EntryData } from "../server/context.js";
-/** Injected cache-scope builder (kept off this module's runtime import graph). */
+/** Injected cache-scope builder. */
 export interface CacheScopeDeps {
     createCacheScope: (config: EntryCacheConfig | undefined, parent?: CacheScope | null) => CacheScope | null;
 }

package/dist/types/rsc/response-route-handler.d.ts

@@ -7,7 +7,7 @@
  */
 import type { MiddlewareFn } from "../router/middleware.js";
 import { type EntryData } from "../server/context.js";
-import type { HandlerContext } from "./handler-context.js";
+import type { RequestStageContext } from "./request-stages.js";
 export interface ResponseRouteMatch {
     responseType: string;
     handler: Function;
@@ -26,4 +26,4 @@ export interface ResponseRouteMatch {
  * For partial (client-side navigation) requests, returns X-RSC-Reload
  * so the browser triggers a hard navigation to the response route URL.
  */
-export declare function handleResponseRoute<TEnv>(handlerCtx: HandlerContext<TEnv>, preview: ResponseRouteMatch, request: Request, env: TEnv, url: URL, variables: Record<string, any>): Promise<Response>;
+export declare function handleResponseRoute<TEnv>(handlerCtx: Pick<RequestStageContext<TEnv>, "callOnError" | "getRequiredRouteMap" | "reportResponseRouteError">, preview: ResponseRouteMatch, request: Request, env: TEnv, url: URL, variables: Record<string, any>): Promise<Response>;

package/dist/types/rsc/routine-plan.d.ts

@@ -62,7 +62,7 @@ export declare function step<T>(name: string, execute: () => T | Promise<T>): Ro
  *
  * Settlement tracking follows the RETURNED value: a returned promise is
  * observed until it settles; a scheduler that fires-and-forgets internally
- * (e.g. scheduleShellCapture via runBackground) returns void, so its trace
+ * (e.g. planShellCapture via runBackground) returns void, so its trace
  * entry settles at the scheduling call, not at background completion. That is
  * deliberate — the plan's contract ends at the handoff.
  */

package/dist/types/rsc/server-action.d.ts

@@ -27,8 +27,8 @@ import type { MatchResult } from "../types.js";
  * the revalidation phase so it runs INSIDE the same route-middleware wrapper as
  * a successful revalidation — route middleware (context vars, headers, cookies)
  * must apply to the error render too, matching the module doc's "identical to a
- * normal render". When `errorBoundary` is set, `actionContext` is unused (the
- * boundary is already matched; no matchPartial is run).
+ * normal render". That render is the action's revalidation, cut at the
+ * boundary (ActionContext.boundary).
  */
 export interface ActionContinuation {
     returnValue: {

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -41,7 +41,7 @@ export declare const PPR_REPLAY_STATUS_HEADER: string;
  * producer (rsc-rendering.ts) and the parser (testing/shell-status.ts): a
  * reason the parser does not list parses as null.
  */
-export declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "rewritten"];
+export declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "stale", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "rewritten"];
 /** One of {@link PPR_REPLAY_BYPASS_REASONS}. */
 export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
 /**
@@ -139,7 +139,7 @@ export declare const POST_QUIESCE_TASK_HOPS = 16;
  * short is an acceptable loss — every terminal path backs the key off anyway),
  * and below workerd's ~30s waitUntil grace so the cap timer still fires in a
  * live context. When workerd kills the context BEFORE the cap fires, the timer
- * dies with it — that stranding is healed by scheduleShellCapture's staleness
+ * dies with it — that stranding is healed by planShellCapture's staleness
  * check on the stampede guard, keyed off the same constant.
  */
 export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;

package/dist/types/rsc/shell-capture.d.ts

@@ -4,9 +4,9 @@
  * Capture does NOT flow through the HTTP middleware pipeline. The integrated PPR
  * serve path (rsc-rendering.ts + shell-serve.ts) builds a ShellCaptureDescriptor
  * from the route's `ppr` path option after the served response is built and calls
- * scheduleShellCapture. The capture then runs as a background task that re-derives
+ * planShellCapture with it (ShellCaptureInput). The capture then runs as a background task that re-derives
  * the page via `ctx.router.match()` under its OWN derived request context — fresh
- * handle store, `_shellCaptureRun: true` so live-lane loaders mask (loader-mask.ts)
+ * handle store, `_shellCaptureState.run` so live-lane loaders mask (loader-mask.ts)
  * and postpone at their loading() or inline <Suspense> boundary. The match is
  * MIXED-CHAIN: cache()'d segments replay from ring 3, uncached segments execute
  * their handlers. The record-first step (settleCaptureRecord) waits for the
@@ -20,7 +20,7 @@
  */
 import { type MatchResult } from "../types.js";
 import { type ShellCaptureRefusal } from "./shell-capture-constants.js";
-import { type RequestContext, type RouteRecordWindow } from "../server/request-context.js";
+import { type RequestContext } from "../server/request-context.js";
 import { type HandleStore } from "../server/handle-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { HandlerContext } from "./handler-context.js";
@@ -128,7 +128,7 @@ export interface ShellCaptureDebugEvent {
      * - skip-stored: a capture for the key stored after the scheduling request
      *   read the store and missed (ShellCaptureDescriptor.storedSeqAtRead), so
      *   the shell that request missed exists now
-     * - skip-in-flight: scheduleShellCapture found a capture already running for
+     * - skip-in-flight: planShellCapture found a capture already running for
      *   the key (stampede guard) and scheduled nothing
      * - skip-backoff: the key is inside its refused-capture backoff window and
      *   the capture was not attempted
@@ -268,7 +268,7 @@ export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>)
  * The background shell-capture descriptor: everything the capture task needs to
  * store the shell. Built by the integrated PPR serve path (rsc-rendering.ts) from
  * the route's `ppr` path option (`PartialPrerenderProps`) and the app-level cache
- * store, and passed to scheduleShellCapture directly — it is NOT threaded through
+ * store, and passed to planShellCapture in its input — it is NOT threaded through
  * the request context. `tags` carries the route's OPERATIONAL `ppr.tags`; the
  * capture UNIONS them with the shell's own auto-collected (non-loader) request
  * tags from its derived render (the collected set stays authoritative). That
@@ -336,7 +336,7 @@ export interface ShellCaptureDescriptor {
     /**
      * Set for a shell keyed by the visitor's URL (`rewrite(...).shell("visitor")`,
      * visitorShellKey): the capture renders the visitor's location
-     * (`RequestContext._shellCaptureForVisitor`) and stores it as
+     * (`ShellCaptureState.forVisitor`) and stores it as
      * ShellCacheEntry.pathname.
      */
     pathname?: string;
@@ -351,7 +351,7 @@ export interface ShellCaptureDescriptor {
     /**
      * A `router.prerender()` warm's capture (rsc-rendering.ts shellServePlan):
      * one explicit call that must store, so the guards that shed a herd of
-     * visitors do not apply to it. scheduleShellCapture skips the in-flight
+     * visitors do not apply to it. planShellCapture skips the in-flight
      * dedup and the refused-capture backoff, and attemptCapture waits longer on
      * the write barrier. Every correctness guard, the inert-store skip and the
      * queue limits still decide.
@@ -360,6 +360,21 @@ export interface ShellCaptureDescriptor {
 }
 /** The latest stored capture's sequence number for `key` in this isolate, or 0. */
 export declare function lastStoredCaptureSeq(key: string): number;
+/** One shell capture: the request it re-renders and what it stores. */
+export interface ShellCaptureInput {
+    ctx: HandlerContext<any>;
+    request: Request;
+    env: any;
+    url: URL;
+    reqCtx: RequestContext<any>;
+    /**
+     * The SSR module for the capture's own request and URL, called once the
+     * capture leaves the queue. A document passes the module it already
+     * resolved, returned as is, so the capture awaits only a pending one.
+     */
+    ssr: (request: Request, url: URL) => SSRModule | null | Promise<SSRModule | null>;
+    descriptor: ShellCaptureDescriptor;
+}
 /**
  * Schedule the background shell capture for a served document. Stampede-guarded:
  * one capture per key per isolate. Runs via runBackground (waitUntil on workerd,
@@ -367,15 +382,13 @@ export declare function lastStoredCaptureSeq(key: string): number;
  * error is routed through reportCacheError — capture is best-effort; a failure just
  * means the next request recaptures.
  *
- * Eligibility (nonce/partial/status/strategy) is decided by the caller. An SSR
- * module loader may be passed for cold partial requests; it runs only after the
- * capture enters the guarded background queue, never on response latency.
+ * Eligibility (nonce/partial/status/strategy) is decided by the caller.
  */
-export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule | ((request: Request, url: URL) => Promise<SSRModule | null>), descriptor: ShellCaptureDescriptor): void;
+export declare function planShellCapture(input: ShellCaptureInput): void;
 /**
  * The ttl/swr a shell is stored with: the route's ppr policy, capped by the
  * route cache() records the capture replayed or wrote
- * (RequestContext._routeRecordWindow). A HIT replays the capture's handler
+ * (ShellCaptureState.routeRecordWindow). A HIT replays the capture's handler
  * output, while a client navigation reads the route's cache() tier first, so
  * a shell that outlived its record would show a document request other
  * handler output than a navigation of the same URL. Freshness and total
@@ -456,9 +469,9 @@ type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "write
  * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`
  * that did not run out of ppr.captureTimeout (CaptureAttemptStats.noShellCause),
  * and on `expired`; a genuine render error is NOT retried — it propagates to
- * scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
+ * planShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
  *
- * `request` and `url` are the capture's own identity (scheduleShellCapture
+ * `request` and `url` are the capture's own identity (planShellCapture
  * strips a navigation-only capture's transport parameters). `retryDelayMs` is
  * a parameter (defaulting to the module const) so unit tests can drive the
  * retry without a real 400ms wall-clock wait.
@@ -511,9 +524,113 @@ export type CaptureRecordOutcome = {
  * a HIT restores, and its handle encode has its own 5s timeout that must
  * never be the one that fires); then the capture's onResponse callbacks fire
  * with a synthetic 200 (the implicit doc scope's cacheRoute, an explicit
- * scope's own write), and the deferred writes settle.
+ * scope's own write), and the deferred writes settle. A match holding an
+ * error or notFound boundary throws before the callbacks fire.
  */
 export declare function settleCaptureRecord(match: MatchResult, derivation: CaptureContextDerivation, capture: Pick<ShellCaptureDescriptor, "key">, deadline: number): Promise<CaptureRecordOutcome>;
+/**
+ * @internal The freshness window of a route cache() record, as ms
+ * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
+ * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
+ * the record that sets `staleUntil`: its cache() config, and whether this
+ * capture wrote it (cacheRoute) rather than read it.
+ */
+export interface RouteRecordWindow {
+    freshUntil: number;
+    staleUntil: number;
+    ttl: number;
+    swr: number;
+    written: boolean;
+}
+/**
+ * @internal What a shell capture's render records about itself, on its
+ * derived request context as `_shellCaptureState`.
+ * RENDER_PASS_FIELDS["shell-capture"] (server/render-pass.ts) creates it with
+ * every field present, so it keeps one shape while the capture writes it. A
+ * background re-render the capture starts has none: it writes a route
+ * record, under cache() rules (RENDER_PASS_FIELDS["background-revalidation"]).
+ */
+export interface ShellCaptureState {
+    /**
+     * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
+     * capture task's derived request context (built by shell-capture.ts). This is
+     * the switch every capture-specific behavior reads: loader masking
+     * (loader-mask.ts isShellCaptureActive / resolveOwnerLoaders) and the
+     * identity-read capture guard (server/context.ts guardIdentityRead). The
+     * foreground render never sets it, so the
+     * served response is byte-identical to axis 1. The capture descriptor itself
+     * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
+     * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
+     * locally and passes it to planShellCapture in its input.
+     */
+    readonly run: true;
+    /**
+     * @internal Set beside `run` when the shell is keyed by the
+     * visitor's URL (`rewrite(...).shell("visitor")`): the capture renders the
+     * visitor's location and `ctx.rewrittenFrom`; the theme stays the default.
+     */
+    forVisitor: boolean | undefined;
+    /**
+     * @internal Bake-lane loader containers collected DURING a shell capture:
+     * segment-key -> the loader's (pre-wrap) result promise. Populated by
+     * resolveLoaderData for bake-lane loaders (lane rule: see its JSDoc in
+     * loader-cache.ts). Drained by captureAndStoreShell after the shell
+     * quiesces: settled containers are promise-elided, Flight-serialized, and
+     * pinned into the snapshot's loader family; a REJECTED container refuses
+     * the capture (error UI must never bake into the shared shell).
+     */
+    loaderRecords: Map<string, Promise<unknown>>;
+    /**
+     * @internal Set when a loader pushed a
+     * value the record cannot keep (masked nested promises, a pushed promise
+     * that settled to one, a live-lane loader's push, or a push outside a
+     * loader body): the loader records then carry `runs: 1`, so a HIT still
+     * runs their bodies for those pushes.
+     */
+    unrecordedLoaderPush: true | undefined;
+    /**
+     * @internal The lane of each loader the capture's matched route registers
+     * (loader-cache.ts routeLoaderLanes), set by createMatchContextForFull
+     * before any loader runs. The capture's push funnel credits a push made
+     * under a live-lane loader's body, at any depth, to that loader
+     * (shell-capture.ts deriveShellCaptureContext).
+     */
+    loaderLanes: ReadonlyMap<string, "live" | "bake"> | undefined;
+    /**
+     * @internal Set by the capture guard (server/context.ts
+     * guardIdentityRead) when it throws DURING a capture render: the read
+     * ("cookies()", "headers()", `ctx.get() for a non-cacheable variable`,
+     * "ctx.theme") and the fix the
+     * refusal warning gives for it. Load-bearing for the
+     * bake lane: a guard throw inside an executing loader is swallowed by
+     * wrapLoaderPromise into per-loader error UI, which would otherwise bake
+     * silently into the shared shell — the capture checks this flag after the
+     * render and refuses instead. Deterministic, so the capture does not retry.
+     */
+    guardTripped: {
+        surface: string;
+        fix: string;
+    } | undefined;
+    /**
+     * @internal The loader $$id whose BODY was executing when the capture guard
+     * tripped (read off the loader-body ALS scope at trip time), or undefined
+     * when the read came from handler/render code. Only used to make the
+     * once-per-key refusal warning name the real source — the old text
+     * hardcoded "a bake-lane loader", which misattributed handler-land reads
+     * and sent users debugging the wrong lane (issue #672, secondary).
+     */
+    guardTrippedLoaderId: string | undefined;
+    /**
+     * @internal The freshness window of the route cache() records this
+     * capture read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
+     * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
+     * its scope's swr. The narrowest record wins. A shell capture caps its
+     * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
+     * shell is never fresher, or served longer, than the route cache() entry
+     * it replayed or wrote.
+     */
+    routeRecordWindow: RouteRecordWindow | undefined;
+}
 /**
  * The derived capture context and its fresh (mask-funneled) handle store,
  * shared by BOTH shell producers: the runtime background capture

package/dist/types/rsc/shell-serve.d.ts

@@ -17,6 +17,7 @@
  */
 import { type EntryData } from "../server/context.js";
 import type { DocumentShellCacheEntry, ShellCacheEntry, ShellDocumentRead, ShellEntryHead, ShellReadStats, ShellSnapshotFailure, ShellSnapshotRecord, SegmentCacheStore } from "../cache/types.js";
+import type { MetricsStore } from "../server/context.js";
 export { PPR_REPLAY_STATUS_HEADER, SHELL_STATUS_HEADER, buildShellKey, navigationShellKey, partitionShellKey, shellSearchSeed, } from "./shell-capture-constants.js";
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
@@ -76,18 +77,13 @@ export declare function normalizeCaptureTimeout(value: unknown): number | undefi
  */
 export declare function resolvePprConfig(entry: EntryData | undefined | null): ResolvedPprConfig | null;
 /**
- * The forced-MISS query marker. A document HIT that cannot finish its tail
- * reloads the page with it (shellReloadScript); the serve gate renders a
- * request carrying it on axis 1, with no shell read and no capture, so the
- * reload can never be a HIT that degrades again. The handler drops it from
- * the request on entry (withoutShellMissMarker) and keeps only the flag
- * (RequestContext._shellForcedMiss), so nothing else sees it.
- */
-export declare const SHELL_MISS_PARAM: string;
-/**
- * The request without the forced-MISS marker, or undefined when it carries
- * none. The handler calls it before anything reads the request: left in, the
- * marker reached `ctx.request.url`, `originalUrl`, middleware, and the SSR
+ * The request without the forced-MISS marker (`WIRE.shellMiss`), or
+ * undefined when it carries none. A document HIT that cannot finish its tail
+ * reloads the page with the marker (shellReloadScript); the serve gate
+ * renders a request carrying it on axis 1, with no shell read and no
+ * capture, so the reload can never be a HIT that degrades again. The handler
+ * calls this on entry, before anything reads the request, and keeps only the
+ * flag (RequestContext._shellForcedMiss): left in, the marker reached `ctx.request.url`, `originalUrl`, middleware, and the SSR
  * search seed (so `useSearchParams` rendered it), and a `"use cache"` key
  * built from the request URL was never read again. GET and HEAD only: the
  * reload is a navigation, and a request with a body cannot be re-created
@@ -165,6 +161,35 @@ export interface ShellDocument {
  */
 export declare function openShellDocument(entry: ShellCacheEntry): ShellDocument | null;
 export declare function openShellDocument(entry: ShellEntryHead, read: Pick<ShellDocumentRead, "prelude" | "snapshot" | "snapshotFailure" | "stats">): ShellDocument | null;
+/**
+ * A document serve's store read: a getShell entry, or a prelude-first read
+ * (readShellDocument) whose entry is the head and whose snapshot arrives on
+ * its own promise.
+ */
+export type ShellRead = {
+    entry: ShellCacheEntry;
+    shouldRevalidate?: boolean;
+    read?: undefined;
+} | {
+    entry: ShellEntryHead;
+    shouldRevalidate?: boolean;
+    read: ShellDocumentRead;
+};
+/**
+ * The document serve's shell read from `source`, the app cache store, that
+ * degrades to null on failure (axis 1 MISS, never a 500) and records the raw
+ * `ppr:shell-read` outcome (pre-validity-gates, so a version-mismatch
+ * lifecycle miss stays distinguishable from a store miss). A store with a
+ * prelude-first read (readShellDocument) resolves before the snapshot is
+ * read, so the HIT commits without waiting for it. A build shell is read by
+ * shell-build-manifest.ts lookupBuildShell, which imports this module.
+ */
+export declare function readShell(source: SegmentCacheStore & {
+    getShell: NonNullable<SegmentCacheStore["getShell"]>;
+}, key: string, opts: {
+    tagHints?: readonly string[];
+    metrics?: MetricsStore;
+}): Promise<ShellRead | null>;
 /**
  * Prelude enqueue granularity. A streaming compressor in front of the worker
  * emits its first byte only after compressing the whole write it was handed:

package/dist/types/server/context.d.ts

@@ -121,7 +121,7 @@ export type LoaderEntry = {
      * thrown notFound()/redirect() deterministically precede first flush.
      * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
      * per-isSSR (router/manifest.ts cache key), so the flag is already
-     * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
+     * request-mode-correct when resolveOwnerLoaders reads it and never
      * appears on navigation-lane entries. Set by documentModeLoader, which
      * getDocumentModeEntry also applies to a lazy include's captured ancestors.
      */
@@ -566,7 +566,7 @@ export interface IdentityReadWording {
  *    only observed; it is never rendered. A cached body, loader body or
  *    funnel they start is guarded again.
  * 1. A PPR shell capture (`ctx` is the capture's derived context,
- *    `_shellCaptureRun`) trips first: the capture context is flagged (so a
+ *    `_shellCaptureState`) trips first: the capture context is flagged (so a
  *    caught throw still refuses the capture) and the read throws. The shell is
  *    shared per host+URL, and every HIT replays what the capture read. There
  *    is no loader-body exemption here: a bake-lane loader and a loader a
@@ -737,12 +737,13 @@ export declare function latchPprHeaderScopeForEntries(entries: EntryData[], rout
  * ONLY the ppr (shell) axis is dropped — dynamic() does NOT opt off the CACHE
  * axis. Two cases:
  * - Pure ppr funnel (no cache() boundary): clear the latch → writes re-permit.
- * - ppr route nested under a cache() boundary: fresh.ts latches "ppr" at the
- *   funnel top (first-wins), which MASKS the positional cache() latch, but the
- *   handler still runs inside the cache scope (`insideCacheScope`). A cache()
- *   HIT skips that handler, so the write is still non-deterministic — UNMASK to
- *   "cache" instead of clearing, so the guard keeps throwing (accurate cache()
- *   wording). This is why the check keys off `insideCacheScope`, not just kind.
+ * - ppr route nested under a cache() boundary: resolveAllSegments
+ *   latches "ppr" at the funnel top (first-wins), which MASKS the positional
+ *   cache() latch, but the handler still runs inside the cache scope
+ *   (`insideCacheScope`). A cache() HIT skips that handler, so the write is
+ *   still non-deterministic — UNMASK to "cache" instead of clearing, so the
+ *   guard keeps throwing (accurate cache() wording). This is why the check keys
+ *   off `insideCacheScope`, not just kind.
  *
  * A subsequent cache() entered AFTER dynamic() on a pure-ppr funnel re-latches
  * "cache" via latchCachedHeaderScope's `!store.cachedHeaderScope` guard (the

package/dist/types/server/handle-store.d.ts

@@ -169,6 +169,22 @@ export interface HandleStore {
      * array, in order. Without placeholders it is a plain replay.
      */
     replacePlaceholders(loaderIds: readonly string[], deliver: () => void): void;
+    /**
+     * A cache() or Prerender() HIT restored its stored values into
+     * `segmentIds` (cache-lookup.ts serveStoredSegments). The MISS ran each
+     * segment's handler after it started the segment's loaders, so a push into
+     * a restored array goes in front of the stored values until
+     * releaseRecordedValues: a loader's push lands where the same loader timing
+     * puts it on the MISS.
+     */
+    holdRecordedValues(segmentIds: readonly string[]): void;
+    /**
+     * The HIT's loader walk reached the place where the MISS ran
+     * `segmentId`'s handler (revalidation.ts resolveLoadersOnly,
+     * intercept-resolution.ts resolveInterceptLoadersOnly): later pushes
+     * follow the record's values.
+     */
+    releaseRecordedValues(segmentId: string): void;
     /**
      * Get all collected handle data after all handlers have settled.
      * Waits for `settled` (handler lane), then returns the data at that point.

package/dist/types/server/render-pass.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Derived render passes over a request past its middleware (PPR shell
+ * capture, PPR HIT tail, background re-render, document cache re-run), each
+ * `Object.create(base)`.
+ * A field missing from a RENDER_PASS_FIELDS row reads the foreground
+ * request's value (#684). derived-context-shape.rsc-test.tsx pins each row's
+ * own keys.
+ */
+import type { RecordingShellStore } from "../cache/shell-snapshot.js";
+import type { HandleStore } from "./handle-store.js";
+import { type RequestContext } from "./request-context.js";
+type ShellImplicitCache = NonNullable<RequestContext["_shellImplicitCache"]>;
+/** _handleStore, readonly on RequestContext, is written by the rows. */
+type PassUnderConstruction = RequestContext<any> & {
+    _handleStore: HandleStore;
+};
+/** What each purpose's caller builds for its row. */
+export interface RenderPassInit {
+    "shell-capture": {
+        handleStore: HandleStore;
+        /** A navigation-only capture renders this URL instead of the request's. */
+        identity: {
+            request: Request;
+            url: URL;
+        } | undefined;
+        /** Only with a cache store on the request. */
+        recording: {
+            store: RecordingShellStore;
+            implicitCache: ShellImplicitCache;
+        } | undefined;
+    };
+    "ppr-tail": {
+        /** The request's store, shared: the tail's handles are this response's. */
+        handleStore: HandleStore;
+        loaderSeed: RequestContext["_shellLoaderSeed"];
+        implicitCache: ShellImplicitCache;
+    };
+    "background-revalidation": {
+        handleStore: HandleStore;
+        /** Throwaway: the pass's response writes land here and are dropped. */
+        sink: RequestContext<any>;
+    };
+    "document-revalidation": {
+        /** The request's: the stale HIT pushed nothing into it. */
+        handleStore: HandleStore;
+        /**
+         * Holds the re-run's response writes, which make the response the
+         * document cache stores; starts from the request's response stub.
+         */
+        sink: RequestContext<any>;
+    };
+}
+export type RenderPurpose = keyof RenderPassInit;
+interface PassFieldPolicy<I> {
+    /** "own": wireRenderBarrier(pass, init.handleStore) before `own` runs. */
+    readonly renderBarrier: "own" | "inherited";
+    /**
+     * Named stores, not one Object.assign: on Node 24 an Object.assign that
+     * takes the object to 20 own properties leaves it in V8 dictionary mode
+     * (#1109).
+     */
+    readonly own: (pass: PassUnderConstruction, init: I, base: RequestContext<any>) => void;
+}
+export declare const RENDER_PASS_FIELDS: {
+    readonly [P in RenderPurpose]: PassFieldPolicy<RenderPassInit[P]>;
+};
+/**
+ * `Object.create(base)` with RENDER_PASS_FIELDS[purpose]'s own fields. The only
+ * place a request context is derived (tools/check-internals.mjs).
+ */
+export declare function deriveRenderPass<P extends RenderPurpose, TEnv>(base: RequestContext<TEnv>, purpose: P, init: RenderPassInit[P]): RequestContext<TEnv>;
+export {};