fix(ppr): capture lane gets its own render barrier — rendered() no longer reads the foreground handle snapshot (#684 plan 009) - #704

Closes out plan 009 from #684 (capture derived-context render-barrier inheritance — CONFIRMED in the investigation).

Problem statement

A DSL loader on a PPR route that does await ctx.rendered(); ctx.use(handle) (bake lane — no loading() on its entry, so it executes during the background shell capture) read the WRONG request's handle data during capture: the capture context is Object.create(reqCtx), and the entire _renderBarrier* family fell through the prototype to the foreground request's barrier. That barrier's getter and resolver are closure-bound to the foreground context and its handle store, and the resolver no-ops once resolved — so during capture, rendered() resolved instantly (the foreground barrier had already resolved) and ctx.use(handle) returned the foreground's handle snapshot. The capture's fresh _handleStore — the one the capture's own handlers push into — was invisible to the loader.

Consumer-observable consequence: whenever a handler pushes non-deterministic or request-derived handle data, the baked loader value inside the shared shell embedded the TRIGGERING request's handle data instead of the capture render's own — an internal inconsistency between what the shell's handlers rendered and what its baked loader saw. On a streaming tree the inherited state was worse: rendered() proceeded immediately with the foreground's _treeHasStreaming === true, sealing the capture's fresh store at loader start and pairing it with the foreground's segment order.

Before vs. after

The consumer writes nothing differently — the fix changes what rendered() observes during capture:

// A PPR route: handler pushes request-derived handle data,
// a bake-lane loader reads it after the render barrier.
const ProductsPage = (ctx) => {
  const push = ctx.use(RenderedProducts);
  push(personalizedProductId(ctx.request)); // per-request value
  return <Products />;
};

export const LivePricesLoader = createLoader(async (ctx) => {
  "use server";
  await ctx.rendered();
  const ids = ctx.use(RenderedProducts); // ← the fix changes what this sees during capture
  return fetchPrices(ids);
});

Code change

• packages/rangojs-router/src/server/request-context.ts — the barrier closure (lazy _renderBarrier getter, _resolveRenderBarrier, guard teardown) moves verbatim from createRequestContext into an exported wireRenderBarrier(ctx, handleStore), which additionally resets the six barrier-family fields as own properties (no-op for a fresh context, shadowing for a derived one). _renderBarrier is installed via defineProperty, not assignment — on a derived context the prototype's property may already be a pinned non-writable data property, which rejects plain assignment.
• packages/rangojs-router/src/rsc/shell-capture.ts — deriveShellCaptureContext calls wireRenderBarrier(derivedCtx, freshHandleStore) right after installing the fresh store; the attemptCapture doc block's accumulator list gains the barrier family. Both shell producers (runtime capture and build-time prerender capture, PPR producer B: emit the shell entry at BUILD time for prerendered routes (Prerender + ppr = zero runtime capture) #699) go through this derivation.
• packages/rangojs-router/docs/internal/rendered-barrier.md — the Render Barrier Lifecycle section gains the PPR capture lane with the scar tissue.

Location rationale: the wiring lives in server/request-context.ts next to the fields it manages (the closure needs buildHandleSnapshot and the exact teardown semantics); shell-capture only calls it. Duplicating the closure in shell-capture would let the two lifecycles drift — the investigation's exact failure class.

Test plan

• New packages/rangojs-router/src/router/__tests__/shell-capture-barrier-isolation.test.ts — drives the REAL match path (createRequestContext → real deriveShellCaptureContext → router.match under runWithRequestContext), no mocks of the barrier. Pins: (1) capture-lane rendered() + ctx.use(handle) reads the capture's push, not the foreground snapshot; (2) the derived context's resolver/segment order/snapshot/streaming flag are its own and the foreground's state is untouched by the capture; (3) streaming-tree variant — capture-lane rendered() waits for the CAPTURE's streamed push; (4) foreground semantics unchanged by the extraction.
• Red-before-green: with the wireRenderBarrier(derivedCtx, freshHandleStore) call removed, 3 of 4 fail — headline failure expected [['stream-1'], ['stream-1']] to deeply equal [['stream-1'], ['stream-2']] (capture loader read the foreground's data). With the call: 4/4 pass.
• Existing barrier + capture suites green: rendered-barrier.test.ts, shell-capture-live-lane-ctx-use.test.ts, shell-capture-telemetry-suppression.test.ts, rsc/__tests__/shell-capture*.test.ts, capture-queue.test.ts (79 tests).
• pnpm run typecheck (16/16), pnpm run test:unit:all (exit 0), pnpm run lint (0 warnings), pnpm run format (clean).
• No route changes — git status --porcelain | grep '\.gen\.ts' empty.

Notes

• No new e2e: same coverage bar as fix(cache): SWR background revalidation under a derived context — no shared handle-store swap, no shared-arg stamping (#684 plan 010) #689 (plan 010, the sibling confirmed bug from Follow-ups: caching/PPR/render-pipeline audit (DRY consolidations, deferred coverage, held/investigate items) #684) — the regression is pinned at the real-match-path unit level with production wiring. An e2e would need a new test-app PPR route whose handler pushes request-derived handle data plus dev+prod capture-wait machinery to observe the same inconsistency; flagging the gap explicitly rather than silently: if we want it, it composes with the existing rendered-barrier test-app routes as a follow-up.
• _treeHasStreaming reset matters beyond the flag itself: cache-lookup.ts/segment-resolution.ts only compute it when undefined, so the inherited foreground value previously suppressed the capture's own computation.
• The runLoader testing primitive is unaffected — it deliberately mocks rendered() (documented in src/testing/run-loader.ts); the real barrier requires the render pipeline, which is why the new test drives router.match instead.
• Remaining from Follow-ups: caching/PPR/render-pipeline audit (DRY consolidations, deferred coverage, held/investigate items) #684 after this lands: only the A4 warn-once→diagnostics batch, blocked on PPR operability: snapshot size guard, capture diagnostics, and the silent missing-KV no-op #651/PPR capture pipeline hardening: narrow the write barrier, unify bounded drains, tame the backoff-vs-CI flake #652.