perf(ppr): eager tail handover — first tail byte no longer waits for the resume shell; server-side segment timings + absolute tail/match taps - #693

Problem statement

A consumer measuring a PPR HIT saw Server-Timing: handler-total;dur=18 next to a 964ms content download and could not attribute the difference: the HIT commits headers at the prelude flush, so every millisecond of live-tail work (match, loaders, Flight, resume) happens inside the response body where Server-Timing structurally cannot report it. The existing debug logs could not attribute it either — the [segments] tree-build logs were window-gated (silent on the server), and the [Server][ppr] taps printed only relative +Nms offsets whose t0 starts when each subsystem is created, so a subsystem that started 700ms late logged an innocent-looking +8ms.

On top of the observability gap, the tail had one real plumbing defect: resumeShellHTML awaited react-dom's resume() before returning the composed stream. resume() resolves only when the resumed shell completes — gated on the live loaders — so the already-flowing Flight bytes sat parked behind the handshake that #691's eager injector had just unparked at the stream level (measured on a consumer app: injector output ready at +9ms, first tail byte on the wire at +735ms).

Changes

1. perf(ppr): eager handover (ssr/index.tsx). resumeShellHTML now constructs the eager injector up front, returns its readable immediately, and pipes the resumed fizz stream in when it materializes (pipeTo closes the writable → injector flush → trailer). A resume() rejection aborts the writable, so the error reaches the response stream instead of hanging it.

Consumer-visible effect on a HIT with slow live loaders: the hydration payload's first bytes now leave the server as soon as the Flight render produces them, instead of after the resume shell completes.

The one unit test that pinned the old rejection contract is updated to pin the new stream-error contract (shell-handlers.test.tsx, comment explains the handover).

2. debug(router): segment tree-build timings on both sides (segment-system.tsx). The [segments] logs now run server-side too, environment-tagged ([Server][segments] / [Browser][segments]), with new timers on the previously unmeasured awaits: per-segment build ms, action component await, forceAwait content await, decodeLoaderResults. SSR-pass stalls (blocking loader awaits during fizz) were previously invisible.

3. debug(ppr): absolute timestamps + tail/match brackets (rsc-rendering.ts, inject-rsc-eager.ts, match-handlers.ts). Every [Server][ppr] tap co-prints an absolute performance.now() stamp, and new taps bracket loader-seed build, tail match, tail stream handover, tail completion (duration + bytes), and match context-build vs pipeline-collect. Together they narrate a HIT tail from serve start to last byte.

All of it is gated on the baked INTERNAL_RANGO_DEBUG flag and DCE'd from production bundles when off — zero cost for consumers not debugging.

End-to-end consumer example

Field run on the storefront that motivated this (workerd preview, INTERNAL_RANGO_DEBUG=1, PPR homepage HIT):

[Server][ppr] shell HIT: prelude enqueued (2675649b) +0ms
[Server][ppr] shell HIT: loader seed built +1ms   (abs …755648)
[Server][ppr] shell HIT: tail match done +413ms   (abs …756061)   ← the residual latency, named
[Server][ppr] flight render: first chunk +11ms    (abs …756072)
[Server][ppr] shell HIT: tail stream handed over +425ms
[Server][ppr] shell HIT: first tail chunk on the wire +425ms
[Server][ppr] shell HIT: tail complete +493ms (1088888b)

With these brackets the app's residual tail latency decomposed to per-session upstream auth bootstrap awaited inside its chrome loaders' containers (709ms fresh session → 247ms warm) — an app-fixable pattern — while proving the router's own plumbing is ~40ms end to end. Before this PR the same page read as "964ms, unexplained, invisible to Server-Timing."

Test plan

• Eager handover: full PPR surface green after the change — shell-cache + shell-secure + shell-cache-action + semantic-matrix (107, dev + production) and cloudflare-basic ppr-shell (38, dev + production, workerd/KV).
• shell-handlers.test.tsx resume-error test updated red→green to the stream-error contract (19/19 in file); onError phase assertion unchanged.
• Debug additions are log-only: internal-debug-fe + shell-cache suites green (58); the no-flag negative test still proves silence when INTERNAL_RANGO_DEBUG is off.
• Full gate: pnpm run typecheck, pnpm run test:unit:all (0 failures, 5010 tests), pnpm run lint, pnpm run format; no *.gen.ts changes (no route changes).

Notes

• The debug logs are deliberately permanent (consumer request): they are the only instrument that can see post-header tail work, and the flag bakes to false for everyone else.
• Server-side [Server][segments] lines have no request correlation — segment-system is shared client code and cannot import request-context (node:async_hooks would enter the browser bundle); correlate by timestamp + segment ids.
• Known follow-up candidates surfaced by the field run, deliberately not in this PR: server-side de-prioritization of prefetch renders while a document tail streams (prefetch renders starve the interactive tail in a busy isolate), and a docs note steering session/token acquisition inside the nested (live-shaped) promise so loader containers return instantly.