feat(router): loader container bake — one promise doctrine for handlers, handles, and loaders - #663

Supersedes #661 (folded in): this branch carries the trap e2e pins + the design doc as its first four commits, so the diff shows the whole story — the pins were authored against the OLD contract (MISS-forever, proven green pre-implementation on those commits), then flipped red→green by the implementation commit.

Problem

The most common production PPR shape — an app-wide layout registering loaders (session context, basket, wishlist) with a ppr page beneath it — dead-ended: every shell capture refused and the route stayed x-rango-shell: MISS forever, with a warning whose advice ("add loading() to the loader route") could not help layout-registered loaders. The only escapes were structural refactors (parallel-slot widgets, layout splits). #661 pinned that dead end; this PR removes it.

Root cause at the doctrine level: loaders were the one data lane that violated the container rule. Handlers (awaited data bakes, handed-over pending promises hole) and handles (top-level push bakes, nested-in-container holes) already followed "a promise nested inside your data is never baked; the container settles" — loaders were container-level all-or-nothing.

What a consumer writes differently

Nothing, unless they want the new lane — the return shape is the entire API:

// Before: this shape could never produce a shell (eternal MISS).
// After: the container bakes, the nested promise stays a live hole.
export const StorefrontContextLoader = createLoader(async (ctx) => {
  const config = await loadSiteConfig(ctx.params.locale); // bakes (pinned per shell)
  return {
    config,                   // shell material
    basket: fetchBasket(ctx), // hole — consumer <Suspense>s it, fresh per request
  };
});

loading() present is byte-for-byte today's behavior and stays the guaranteed live lane. The storefront homepage shape — layout loaders + bare ppr: true route + zero loading() anywhere — now HITs.

End-to-end example

layout(StoreLayout, () => [           // registers the three loaders, no loading()
  loader(StorefrontContextLoader),    // returns { config, basket: promise }
  loader(WishlistLoader),
  loader(BasketLoader),
  path("/", HomePage, { name: "home", ppr: true }),
]),

First GET: MISS + background capture (the capture gate holds for the loaders' real latency). Later GETs: HIT — chrome and the loader containers stream from the frozen prelude instantly, nested promises resolve fresh per request, and the hydration payload matches the prelude byte-for-byte (snapshot overlay), so zero hydration errors.

Semantics table

Code changes

• router/segment-resolution/loader-snapshot.ts (new): promise-elide (settled nested promise inlines — it baked by physics; pending → hole marker; rejected → poisons the record) + HIT overlay (recorded paths pinned, markers take the fresh promises, fresh-only keys pass). Unit-tested.
• router/segment-resolution/loader-cache.ts: resolveLoaderData is the lane-policy funnel — mask (live lane) / execute+record (capture bake) / execute+overlay (HIT seed), one ALS read, bakeSegmentKey threaded from fresh.ts per entry (entryLoadingMasksLoaders in loader-mask.ts mirrors segment-system's isRenderableLoading).
• rsc/shell-capture.ts: capture gate holdUntil extended over bake-lane containers (same mechanism as top-level handle pushes); drain elides + Flight-serializes containers into the snapshot's new loader family; deterministic "refused" outcome (no retry, backs off) via one refuseOnGuardTrip choke point; warnNullCaptureOnce rewritten (old text gave route-level advice that could not fix layout loaders).
• cache/shell-snapshot.ts + cache/types.ts: ShellSnapshotFamily gains "loader"; buildShellLoaderSeed decodes records in parallel next to SeededShellStore; rsc/rsc-rendering.ts#serveShellHit seeds _shellLoaderSeed on the tail context.
• server/cookie-store.ts: the capture guard stamps _shellCaptureGuardTripped before throwing — load-bearing because the throw is swallowed by wrapLoaderPromise (error UI) or rejects the prerender promise; both capture exits check the flag.
• ssr/index.tsx: pre-attached no-op catch on the prerender() promise — an early bake-lane rejection otherwise sat handler-less until the post-quiesce await and killed the worker as an unhandled rejection (found live via an async-hooks probe).
• server/request-context.ts: _shellCaptureLoaderRecords, _shellLoaderSeed, _shellCaptureGuardTripped (flat, matching _shellCaptureRun).
• Docs in the same PR: /ppr skill rewritten around the two lanes (doctrine table, bake-lane section, layout-with-loaders playbook now leads with return-shaping, pitfalls), migrate-nextjs (the "loader MUST have loading()" requirement deleted), execution-model.md, ppr-shell-resume.md (loader family), loader-container-bake.md flipped to IMPLEMENTED with deviations noted.

Test plan

• Red before green: the test(ppr): e2e-pin the layout-loader trap + slot escape; design doc for loader container bake #661 trap tests (layout-loader with child loading(), bare storefront shape, route-level no-hole) were run against this change asserting MISS-forever and failed (routes flip to HIT), then rewritten to pin the new contract — in the test-app suite AND the cloudflare-basic twin on workerd with the real KV-backed store (loader-family snapshot round-trips the KV envelope).
• The decisive parity pin: across two HITs the baked outer container seq is frozen (snapshot overlay) while the nested inner seq advances (live hole) — both suites, dev + production.
• Identity wall e2e: /shell-cache/guard (bake-lane loader reading cookies()) stays MISS with the per-user value intact on axis 1, dev + production.
• Unit: loader-snapshot.test.ts (elide/overlay semantics incl. shape drift), shell-capture.test.ts +3 (guard refusal, rejected-container refusal, pending-container omission), full suite 4830.
• Suites: shell-cache 44/44, cloudflare ppr-shell 36/36 (dev + production each), semantic matrix 64/64 (segment-resolution touched), typecheck / lint / format / bucketing, *.gen.ts regenerated.
• /simplify pass applied (4-agent review): shared isThenable reuse, single guard-refusal choke point, flattened gate hold, one-ALS-read hot path, parallel seed decode in shell-snapshot.ts, splitPrelude e2e helper.

Notes

• Baked containers show CAPTURE-time data for the shell's lifetime on document GETs (client navigations stay fresh) — that is the lane's meaning, same doctrine as all shell material; the live lane and nested promises are the freshness escape hatches.
• Rebased over fix(router): PPR gate honors a token-set per-request nonce (#656) #657 (nonce gate) and fix(router): dev PPR capture backoff cap + cloudflare-basic ppr warmup (#652 item 3) #659 (backoff/warmup) — the nonce gate composes with the bake lane with no changes on either side; both suites prove it together.
• Deferred per the design doc's open questions: snapshot size caps for large containers; a cloudflare twin of the identity-guard fixture (covered in test-app both modes).