feat(ppr): shell fast path — HIT tails replay the handler layer; only loaders are dynamic - #695

Problem statement

A PPR shell HIT commits its prelude headers at ~25ms and then re-runs the entire handler layer to produce a hydration payload the capture already produced once: ctx.router.match() re-executes segment resolution and every path/layout/parallel handler, and the payload is Flight-rendered by re-executing all those components. On a measured storefront (workerd, "use cache"'d handler data) that re-run is 26–36ms of pure waste per HIT; on an app whose handlers do real work it is that work's full cost. Worse, the re-run is a standing parity hazard — the whole capture-data-snapshot apparatus exists to pin cache reads so the re-rendered payload hopefully matches the frozen prelude.

The consumer contract, in one sentence

Only loaders are dynamic. Middleware guards the request (live), loaders load the data (live), handlers render the page (cached). No API change — the primitives already mean this; the fast path makes the runtime agree.

Before vs. after

// Consumer code — IDENTICAL before and after. No new API.
layout(Chrome, () => [
  path("/", HomePage, { ppr: { ttl: 300, swr: 120 } }, () => [
    loader(ProductsLoader),          // live on every HIT (promise-shaped paths stream)
    loading(<Skeleton />),
  ]),
]),

BEFORE (HIT tail):  match → run Chrome → run HomePage → run loaders → Flight-render executed tree
AFTER  (HIT tail):  match → cache-hit: REPLAY Chrome + HomePage from the shell entry
                    → run loaders fresh → Flight-render (per-request metadata rebuilt as always)

The mechanism is the existing cache() hit lane, not a new renderer: the capture treats the whole matched route as an implicit doc-level cache() boundary and records the segment entry INTO the shell entry's snapshot; an eligible HIT's tail match hits that record through the already-shipped SeededShellStore, so withCacheLookup replays segments and resolveLoadersOnly runs loaders — the exact path every cache()-wrapped route already serves in production.

End-to-end consumer example

// urls.tsx — a PPR homepage with a personalized carousel
export const patterns = urls(({ path, layout, loader, loading, middleware }) => [
  middleware(authGate, () => [                       // live on every HIT
    layout(StoreChrome, () => [                      // replayed byte-identically
      path("/", HomePage, { ppr: { ttl: 300, swr: 120 } }, () => [
        loader(CarouselLoader),                      // re-runs on every HIT
        loading(<CarouselSkeleton />),
      ]),
    ]),
  ]),
]);

// CarouselLoader: the nested-promise shape IS the liveness declaration
export const CarouselLoader = createLoader(async () => ({
  categoryId: "featured",
  products: fetchPersonalized(),   // Promise → streams fresh into the shell hole per visitor
}));

On a HIT: prelude flushes immediately, StoreChrome/HomePage never execute (their trees replay from the entry), CarouselLoader runs fresh, and products streams into the baked skeleton.

Semantics table

Eligibility (ShellCacheEntry.handlerLiveHoles) is decided at capture from three signals: a handle pushed OUTSIDE a DSL loader scope carrying a nested thenable, a handler push still pending at the putShell barrier, or a handler-invoked loader executing during capture. Any of them declines the FAST PATH, never the capture — those routes keep today's behavior exactly.

Code-change summary

Four pieces, all riding existing machinery (packages/rangojs-router/src):

1. cache/cache-scope.ts — resolveShellImplicitCacheScope, applied at the single full-match construction site (router/match-api.ts): substitutes an enabled doc-level scope when the route derived NO cache scope and the request context carries the _shellImplicitCache marker. A route-derived scope — including cache(false) — always wins.

export function resolveShellImplicitCacheScope(scope: CacheScope | null): CacheScope | null {
  if (scope) return scope;
  const marker = getRequestContext()?._shellImplicitCache;
  if (!marker) return null;
  return new CacheScope({ ttl: marker.ttl, swr: marker.swr, store: marker.store }, null);
}

2. rsc/shell-capture.ts — capture side: the derived context arms the marker with a SnapshotOnlySegmentStore (cache/shell-snapshot.ts) so the implicit cacheRoute write lands in the snapshot only, never the real store (a passthrough write would make the NEXT capture's lookup replay the previous generation — broken SWR recapture freshness). The PR fix(ppr): nested-promise shape IS the liveness declaration — mask nested thenables at capture (loaders + handles); stops per-user data baking into the shared shell #692 push-mask funnel now also attributes each push (isInsideLoaderScope() read synchronously at push time) via a single-walk MaskReport on maskNestedContainerThenables, folds handler-layer liveness into handlerLiveHoles, and collects DSL-loader push values into _shellCaptureLoaderHandleValues — threaded explicitly into captureHandles(…, exclude) so loader-scoped values stay out of cache-write handle records (they re-push fresh per HIT; their masks would stall the Flight handle encode) while every other getDataForSegment consumer provably sees every push. The capture context also gets its OWN _explicitTaggedStores so capture-ephemeral stores never pin the handler-lifetime tag registry (spurious updateTag partial-store warning + retained snapshot memory — found in review).

3. rsc/rsc-rendering.ts — serve side: serveShellHit's seeded tail context arms the marker when !entry.handlerLiveHoles. Missing/corrupt record, handler-live entry, or route-derived scope all degrade to the full tail automatically (the corrupt case self-heals through lookupRoute's existing evict-and-miss).

4. router/loader-resolution.ts — a handler-invoked loader executing during a capture marks handler-layer liveness (its PPR: live-lane parallel-slot loader consumed via ctx.use() in the slot handler executes (and trips the identity guard) during capture on non-index routes #672 consumption-lane value would freeze under replay).

Location rationale: the serve path stays literally ctx.router.match() — no parallel fast-path renderer; the fast path is scope substitution + an eligibility flag, so every downstream behavior (intercept handling, revalidation gating, metrics, the loader seed overlay) is the production-tested cache-hit lane.

Test plan

• Execution-matrix e2e (red-proven): fast-path HIT executes ONLY middleware and loaders — path/layout/parallel handlers are replayed, not run — per-layer module counters streamed through the live loader, asserted across two consecutive HITs. Without the fix it fails exactly at the frozen-handler assertion (expected 4, received 5); with it, middleware+loader advance and path/layout/parallel stay frozen. Both apps (test-app /shell-cache/exec-matrix, cloudflare-basic /ppr-shell/exec-matrix on workerd/KV), dev AND (production).
• Unit: src/cache/__tests__/shell-fast-path.test.ts — implicit-scope substitution (marker vs route scope vs cache(false)), SnapshotOnlySegmentStore record-only writes/read-through, MaskReport single-walk liveness signal (10 tests). Existing match-api-classified-reuse mock extended for the new export.
• Existing nets as regression coverage: shell-cache + shell-secure + shell-cache-action 32/32 in dev AND production (the handle-liveness fixtures pin the ineligible→full-tail degrade; drift/settled/slot fixtures now exercise the fast lane); semantic matrix 21 dev + 24 production (PPR rows incl. consumption lane); full cloudflare-basic suite 287/287 (incl. ppr-tag-eviction).
• Gate: pnpm run typecheck, pnpm run test:unit:all (0 failures), pnpm run lint, pnpm run format; *.gen.ts committed for both apps (new fixture routes).
• Multi-agent simplify + adversarial review passes applied (state-leak lens: 1 confirmed finding, fixed — the _explicitTaggedStores isolation; semantics lens: zero confirmed regressions; payload segment ordering on the fast path equals what cache() hits already produce in production).

Notes

• Design record: docs/design/shell-fast-path.md (in this PR) — measurements that motivated it, why whole-payload Flight splicing was rejected, the parity argument, and what stays out of v1.
• v1 is document-HIT-tail only: prefetch/partial renders keep the full path (the PDP-prefetch starvation lever is a named follow-up), as does Prerender-as-producer-B of the same entry format.
• Handler-minted prop promises self-degrade: pending at capture, they time out the segment serialization, the doc record never lands, and the route silently keeps the full tail.
• The SWR recapture re-running handlers in a background capture is the deliberate freshness exception, pinned in the fixture comments.