@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/rsc-entry/rsc-payload.ts

@@ -5,24 +5,39 @@
  * returned directly without SSR HTML rendering. The client decodes it via
  * `createFromFetch` and renders into the hydrated React root.
  *
+ * The response's HTTP status carries no deny semantics: a payload response
+ * commits 200 when Flight's opening window closes (the first chunk plus one
+ * macrotask), and a deny, redirect, or error that lands after that rides
+ * the payload as a Flight error row for the client's boundaries — the same
+ * way a nested component's already did. The status
+ * code contract (design/05) is a document-path contract, enforced by Fizz's
+ * `onShellReady`; Flight has no such checkpoint, and the only reader of a
+ * payload response's status is the static generator's check for an error
+ * envelope — the client router reads the body. See TIM-1495.
+ *
  * Design docs: 19-client-navigation.md §"RSC Payload Handling",
- *              16-metadata.md §"Head Elements"
+ *              04-authorization.md §"Status codes on the RSC payload path"
  */
 
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPageAsRsc } from '#/server/deny-renderer.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import type { RedirectSignal } from '#/server/primitives.js';
-import type { HeadElement, LayoutComponentEntry } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-
-import {
-  buildRedirectResponse,
-  buildSegmentInfo,
-  createDebugChannelSink,
-  RSC_CONTENT_TYPE,
-} from './helpers.js';
-import type { RenderSignals } from './rsc-stream.js';
+import type { LayoutComponentEntry } from '../route-element-builder.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import type { SlotSkipEntry } from '../slot-resolver.ts';
+
+import { buildSegmentInfo } from './helpers.ts';
+import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
+
+import { rscErrorEnvelope } from '../rsc-error-envelope.ts';
+
+import type { RenderSignals } from './render-signals.ts';
+
+/**
+ * Ceiling on waiting for a first chunk that is already in flight, used only
+ * when an addressed deny won the race against it. Matches the 50ms ceiling
+ * documented for the race itself: long enough that the error row — which is
+ * what the render just produced — arrives, short enough that a stalled stream
+ * cannot hold the response open.
+ */
+const FIRST_CHUNK_CEILING_MS = 50;
 
 /**
  * Build an RSC payload Response for a client-side navigation request.
@@ -32,22 +47,34 @@ import type { RenderSignals } from './rsc-stream.js';
  * renderToReadableStream. Reading one chunk triggers rendering of the
  * initial component tree, allowing onError to capture DenySignal/
  * RedirectSignal before we commit the response. See TIM-344.
+ *
+ * The commit point is the close of Flight's opening window: the first chunk
+ * plus one macrotask turn. Nothing is held for it. A signal that lands
+ * inside the window still gets a server-level answer — a redirect response,
+ * the fallback deny page, the hard-navigate envelope — because the race
+ * below and the one timer turn after it deliver it for free. This function
+ * reports that signal rather than answering it: it cancels the stream and
+ * rethrows, and the pipeline's outcome translator builds the redirect or
+ * calls the deny fallback (`rsc-entry/deny-fallback.ts`), exactly as for a
+ * signal thrown out of render (design/49 §"C"). A signal that
+ * lands after it is a row in the stream, and the client's boundaries answer
+ * it. Waiting for the shell components to settle (TIM-1045, TIM-1208) made
+ * the payload path pretend to a status contract it could not keep for
+ * nested components, and was removed in TIM-1495.
  */
 export async function buildRscPayloadResponse(
-  req: Request,
   rscStream: ReadableStream<Uint8Array>,
   signals: RenderSignals,
   segments: ManifestSegmentNode[],
   layoutComponents: LayoutComponentEntry[],
-  headElements: HeadElement[],
-  match: RouteMatch,
   responseHeaders: Headers,
-  skippedSegments?: string[]
+  skippedSegments?: string[],
+  slotSkipInfo?: SlotSkipEntry[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
   // Race the first read against signal detection — if an async component
-  // throws a RedirectSignal or DenySignal, the onError callback fires
-  // signals.onSignal() and we can react immediately without waiting for
+  // throws a RedirectSignal or DenySignal, the onError callback resolves
+  // signals.captured and we can react immediately without waiting for
   // the full macrotask queue.
   //
   // The rejection chain for an async-wrapped page component:
@@ -61,51 +88,124 @@ export async function buildRscPayloadResponse(
   // (no signal). A 50ms ceiling timeout guards against edge cases
   // where onError never fires.
   const reader = rscStream.getReader();
-  const signalDetected = new Promise<void>((resolve) => {
-    signals.onSignal = resolve;
-  });
 
   type RaceResult =
     | { type: 'data'; chunk: ReadableStreamReadResult<Uint8Array> }
     | { type: 'signal' };
 
-  const first: RaceResult = await Promise.race([
-    reader.read().then((chunk) => ({ type: 'data' as const, chunk })),
-    signalDetected.then(() => ({ type: 'signal' as const })),
-  ]);
+  // Retained rather than inlined into the race below. When a signal wins, the
+  // usual answer is to cancel — but an ADDRESSED deny is one whose error row
+  // the client's boundary is going to render, so that payload has to survive
+  // (TIM-1356). Taking delivery of the read already in flight is not the
+  // "bare read() after a signal won" the async rules forbid; issuing a second
+  // one would be. It still gets a ceiling below.
+  const pendingRead = reader.read();
+
+  let first: RaceResult;
+  try {
+    first = await Promise.race([
+      pendingRead.then((chunk) => ({ type: 'data' as const, chunk })),
+      signals.captured.then(() => ({ type: 'signal' as const })),
+    ]);
+  } catch (_readError) {
+    // The RSC stream itself errored on first read. (A component's error is
+    // not this: it arrives as an error row in a stream that reads fine.)
+    // Return an error response so the client can hard-navigate for the
+    // SSR-rendered error page. See design/10-error-handling.md.
+    reader.cancel().catch(() => {});
+    return rscErrorEnvelope(500, responseHeaders);
+  }
 
-  // If data arrived first, still check signals — they may have fired
-  // concurrently. Also do a final ceiling timeout check for edge cases
-  // where the signal fires just after the first read resolves.
+  // The first chunk arrived with no signal yet. Give Flight's opening window
+  // one macrotask to close before committing: Flight pings continuation
+  // tasks as microtasks only during that window (`startWork` closes it with
+  // a `setTimeout(0)`) and as macrotasks after it, so everything that throws
+  // synchronously or after microtask-only work — a page body calling
+  // `redirect()`, a hundred nested components awaiting `Promise.resolve()` —
+  // has reached `onError` by the time this timer fires, and gets the server
+  // answer below (the 204 redirect, the fallback deny page, the envelope)
+  // rather than a row the client has to answer. Anything that awaited a
+  // timer or I/O has left the window and rides the payload. Nothing is
+  // tracked and nothing is waited for: the cost is one timer turn, and the
+  // status is 200 either way — this decides which mechanism answers, not
+  // what the response claims.
   if (first.type === 'data' && !signals.redirectSignal && !signals.denySignal) {
-    // Brief yield to let any in-flight microtask rejections complete.
     await new Promise<void>((r) => setTimeout(r, 0));
   }
 
-  // Detach the callback — no longer needed after this point.
-  signals.onSignal = undefined;
-
-  // Check for redirect/deny signals detected during initial rendering
-  const trackedRedirect = signals.redirectSignal as RedirectSignal | null;
-  if (trackedRedirect) {
-    reader.cancel();
-    return buildRedirectResponse(req, trackedRedirect, responseHeaders);
+  // The window has closed: signals are read once, here, and one arriving
+  // after this is a row in the stream the client answers.
+  //
+  // A redirect or an unplaced deny replaces the payload, so the stream is
+  // released before the signal is rethrown to the pipeline.
+  if (signals.redirectSignal) {
+    reader.cancel().catch(() => {});
+    throw signals.redirectSignal;
   }
-  if (signals.denySignal) {
-    reader.cancel();
-    return renderDenyPageAsRsc(
-      signals.denySignal,
-      segments,
-      layoutComponents as LayoutEntry[],
-      responseHeaders,
-      createDebugChannelSink
-    );
+  // An addressed deny needs no fallback: the payload already carries its error
+  // row, aimed at the boundary the client has mounted at that segment, which
+  // renders it. Cancelling would throw a finished render away and re-run the
+  // whole route — the exact cost TIM-666 removed.
+  //
+  // The question is asked of `unplacedDeny`, not of `denySignal.owners`,
+  // because one render can produce both kinds and `denySignal` holds only one
+  // of them. A deny nothing could place has no boundary that may claim it, so
+  // its row would otherwise stream to a client with nothing to render it —
+  // and it needs the fallback whether or not some other deny was addressed
+  // first. See TIM-1356. The fallback also owns the hard-navigate answer
+  // for a deny AccessGate marked `_hardNavigate` (TIM-1363).
+  if (signals.unplacedDeny) {
+    reader.cancel().catch(() => {});
+    throw signals.unplacedDeny;
   }
 
-  // Extract the first chunk from the race result.
-  // If the signal won the race, read the first chunk now (the stream
-  // was already cancelled above, but we need a firstRead shape below).
-  const firstRead = first.type === 'data' ? first.chunk : await reader.read();
+  // Extract the first chunk from the race result. If a signal won the race,
+  // the redirect and the unplaced deny were rethrown above, so only an
+  // addressed deny reaches the second branch. The last branch is a fail-safe
+  // for a signal that is neither: it cancels the reader rather than issuing
+  // a bare read() that could hang forever on a stalled stream (TIM-519).
+  let firstRead: ReadableStreamReadResult<Uint8Array>;
+  if (first.type === 'data') {
+    firstRead = first.chunk;
+  } else if (signals.denySignal?.owners) {
+    // An addressed deny won the race before its own error row surfaced.
+    // Cancelling here would hand the client a 4xx payload with nothing in it
+    // — no row for the owning boundary to render, so the navigation shows
+    // nothing at all. Take delivery of the read already in flight instead,
+    // under a ceiling so a stalled stream still cannot hang the response.
+    const TIMED_OUT = Symbol('first-chunk-timeout');
+    const raced = await Promise.race([
+      pendingRead,
+      new Promise<typeof TIMED_OUT>((resolve) =>
+        setTimeout(() => resolve(TIMED_OUT), FIRST_CHUNK_CEILING_MS)
+      ),
+    ]);
+
+    // Missing the ceiling must not be reported as a finished stream. Under
+    // event-loop contention or slow serialization the row is late rather than
+    // absent, and fabricating `done: true` here would produce the very empty
+    // 4xx this branch exists to prevent.
+    //
+    // Nor can it fall to the deny fallback. That renderer re-resolves from
+    // the FULL leaf chain and wraps whatever it finds, ignoring `ownerKey` —
+    // so an `/admin` denial addressed to a root `4xx.tsx` would come back as
+    // `/admin/secret/403.tsx` with the denied layouts executed, which is the
+    // TIM-1074 leak TIM-1358 still owns. A deny this path already placed
+    // correctly must not be handed to it.
+    //
+    // So: hard-navigate. The document request renders the same deny through
+    // the boundary at its owner, with the placement intact. A full page load
+    // is a real cost, on a path that needs a status page and a stalled stream
+    // to reach at all.
+    if (raced === TIMED_OUT) {
+      reader.cancel().catch(() => {});
+      return rscErrorEnvelope(signals.denySignal.status, responseHeaders);
+    }
+    firstRead = raced;
+  } else {
+    await reader.cancel();
+    firstRead = { done: true, value: undefined };
+  }
 
   // Reconstruct the stream: prepend the buffered first chunk,
   // then continue piping from the original reader.
@@ -131,22 +231,41 @@ export async function buildRscPayloadResponse(
   });
 
   responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-  // Vary on Accept so CDNs cache HTML and RSC responses separately
-  // for the same URL. The client appends ?_rsc=<id> as a cache-bust,
-  // but Vary ensures correct behavior even without the query param.
-  responseHeaders.set('Vary', 'Accept');
-
-  // Send resolved head elements so the client can update document.title
-  // and <meta> tags after SPA navigation. See design/16-metadata.md.
-  const encoded = encodeURIComponent(JSON.stringify(headElements));
-  if (encoded.length <= 4096) {
-    responseHeaders.set('X-Timber-Head', encoded);
-  }
+
+  // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload as
+  // React elements — React 19 Float manages them in document.head during
+  // client rendering. No X-Timber-Head header needed. See TIM-1151.
 
   // Send segment metadata so the client can populate its segment cache
-  // for state tree diffing on subsequent navigations.
+  // for state tree diffing on subsequent navigations. Request-dependency
+  // is determined by static module-graph analysis (not runtime taint).
   // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  const segmentInfo = buildSegmentInfo(segments, layoutComponents);
+  // Read the deny index before describing the tree — what mounted depends on
+  // it. Recorded in ALS during render by AccessGate's catch path; a gate that
+  // denies after this point leaves it unset, and the header then describes
+  // the full chain, which is the merge-point answer either way.
+  const { getFirstDeniedSegmentIndex } = await import('../deny-boundary.ts');
+  const resolvedDenyIndex = getFirstDeniedSegmentIndex();
+
+  // Emitted in full even when a deny rendered, because this header answers two
+  // questions and they diverge here. The client picks its merge point out of
+  // this list (`buildSegmentUpdates`), and a partial payload with no merge
+  // point is never inserted at all — the URL commits over the stale previous
+  // UI. So it has to keep describing the chain the payload was BUILT against.
+  //
+  // What it must not also do on a deny is seed the segment cache, since the
+  // deny page replaced a subtree and part of that chain never mounted. That
+  // half is decided on the client by the boundary that renders the status
+  // page, at the commit that puts it on screen — the only place that knows,
+  // since the row may arrive after this response has been returned. See
+  // `client/navigation-commit.ts` and TIM-1356, TIM-1495.
+  const segmentInfo = buildSegmentInfo(
+    segments,
+    layoutComponents,
+    slotSkipInfo,
+    skippedSegments,
+    resolvedDenyIndex
+  );
   responseHeaders.set('X-Timber-Segments', JSON.stringify(segmentInfo));
 
   // Send skipped segments so the client can merge the partial RSC payload
@@ -155,12 +274,13 @@ export async function buildRscPayloadResponse(
     responseHeaders.set('X-Timber-Skipped-Segments', JSON.stringify(skippedSegments));
   }
 
-  // Send route params so the client can populate useParams() after
-  // SPA navigation. Without this, useParams() returns {}.
-  if (Object.keys(match.params).length > 0) {
-    responseHeaders.set('X-Timber-Params', JSON.stringify(match.params));
-  }
-
+  // Always 200. A deny that already streamed — addressed at its owner's
+  // boundary — is in the body, not the status line, and the one consumer of
+  // this response, the client router, reads the body. A status here would be
+  // right only for denies that happened to land before this line and wrong
+  // for every nested component that denies after I/O, and a status that is
+  // sometimes right is a contract nothing may rely on. So it makes no claim.
+  // See design/04-authorization.md §"Status codes on the RSC payload path".
   return new Response(patchedStream, {
     status: 200,
     headers: responseHeaders,

package/src/server/rsc-entry/rsc-stream.ts

@@ -2,163 +2,160 @@
  * RSC Stream Renderer — Creates the RSC Flight stream with signal tracking.
  *
  * Wraps `renderToReadableStream` from `@vitejs/plugin-rsc/rsc` and captures
- * render-phase signals (DenySignal, RedirectSignal, RenderError) thrown by
+ * render-phase signals (DenySignal, RedirectSignal) thrown by
  * components during streaming. These signals are tracked in a shared
- * `RenderSignals` object so the caller can decide the HTTP response.
+ * read-only `RenderSignals` object so the caller can decide the HTTP response.
  *
  * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
  *              13-security.md §"Errors don't leak"
  */
 
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
+import { renderToReadableStream } from '../../rsc-runtime/rsc.ts';
+import type { RscPayloadRoot } from '../../shared/payload-root.ts';
+import { encodeErrorDigest } from '../../shared/error-digest.ts';
 
-import { logRenderError } from '#/server/logger.js';
-import { DenySignal, RedirectSignal, RenderError } from '#/server/primitives.js';
-import { checkAndWarnRscPropError } from '#/server/rsc-prop-warnings.js';
+import { randomUUID } from 'node:crypto';
 
-import { createDebugChannelSink, isAbortError } from './helpers.js';
-import { isDebug } from '#/server/debug.js';
+import { matchDenyEntries, type DenyPageEntry } from '../deny-boundary.ts';
+import { reportRenderError } from '../pipeline-helpers.ts';
+import { isDenySignal, isRedirectSignal } from '../signal-identity.ts';
+import { checkAndWarnRscPropError } from '../rsc-prop-warnings.ts';
 
-/**
- * Mutable signal state captured during RSC rendering.
- *
- * Signals fire asynchronously via `onError` during stream consumption.
- * The first signal of each type wins — subsequent signals are ignored.
- *
- * `onSignal` is an optional callback fired when a DenySignal or
- * RedirectSignal is captured. Consumers use it with Promise.race to
- * react immediately instead of polling with setTimeout/queueMicrotask.
- */
-export interface RenderSignals {
-  denySignal: DenySignal | null;
-  redirectSignal: RedirectSignal | null;
-  renderError: { error: unknown; status: number } | null;
-  /** Callback fired when a redirect or deny signal is captured in onError. */
-  onSignal?: () => void;
-}
+import { isAbortError } from './helpers.ts';
+import { createSignalRecorder, type RenderSignals } from './render-signals.ts';
+import { isDebug } from '../debug.ts';
+import { isDevMode } from '../debug.ts';
 
 export interface RscStreamResult {
-  rscStream: ReadableStream<Uint8Array> | undefined;
+  rscStream: ReadableStream<Uint8Array>;
   signals: RenderSignals;
 }
 
 /**
- * Render a React element tree to an RSC Flight stream.
+ * Render a payload root (tree plus its params) to an RSC Flight stream.
  *
  * The stream serializes server components as rendered output and client
  * components ("use client") as serialized references with module ID + export name.
  *
- * DenySignal detection: deny() in sync components throws during
- * renderToReadableStream (caught in try/catch). deny() in async components
- * fires onError during stream consumption. Signals are captured in the
- * returned `signals` object for the caller to handle.
+ * Signals are captured in the returned `signals` object for the caller to
+ * handle. Every one arrives through `onError`, never as a throw from this
+ * call: Flight starts rendering in a microtask after the stream is created,
+ * so even a component that throws synchronously is reported asynchronously.
  */
-export function renderRscStream(element: React.ReactElement, req: Request): RscStreamResult {
-  const signals: RenderSignals = {
-    denySignal: null,
-    redirectSignal: null,
-    renderError: null,
-  };
-
-  let rscStream: ReadableStream<Uint8Array> | undefined;
+export function renderRscStream(
+  payload: RscPayloadRoot,
+  req: Request,
+  leafDenyChain?: DenyPageEntry[]
+): RscStreamResult {
+  const recorder = createSignalRecorder();
 
-  try {
-    rscStream = renderToReadableStream(
-      element,
-      {
-        signal: req.signal,
-        onError(error: unknown) {
-          // Connection abort (user refreshed or navigated away) — suppress.
-          // Not an application error; no need to track or log.
-          if (isAbortError(error) || req.signal?.aborted) return;
-          if (error instanceof DenySignal) {
-            signals.denySignal = error;
-            signals.onSignal?.();
-            // Return structured digest for client-side error boundaries
-            return JSON.stringify({ type: 'deny', status: error.status, data: error.data });
-          }
-          if (error instanceof RedirectSignal) {
-            signals.redirectSignal = error;
-            signals.onSignal?.();
-            return JSON.stringify({
-              type: 'redirect',
-              location: error.location,
-              status: error.status,
-            });
-          }
-          if (error instanceof RenderError) {
-            // Track the first render error for pre-flush handling
-            if (!signals.renderError) {
-              signals.renderError = { error, status: error.status };
+  const rscStream = renderToReadableStream(
+    payload,
+    {
+      signal: req.signal,
+      onError(error: unknown) {
+        // Connection abort (user refreshed or navigated away) — suppress.
+        // Not an application error; no need to track or log.
+        if (isAbortError(error) || req.signal?.aborted) return;
+        if (isDenySignal(error)) {
+          // Late addressing (TIM-1450): a nested-component deny escapes
+          // all in-tree catch sites and arrives here without owners.
+          // Resolve it against the leaf deny chain and stamp the full
+          // candidate list so the client can find the first reachable
+          // owner via its ancestry context.
+          if (!error.owners && leafDenyChain) {
+            const entries = matchDenyEntries(leafDenyChain, error.status);
+            if (entries.length > 0) {
+              error.owners = entries.map((e) => e.ownerKey);
             }
-            logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
-            return JSON.stringify({
-              type: 'render-error',
-              code: error.code,
-              data: error.digest.data,
-              status: error.status,
-            });
-          }
-          // Dev diagnostic: detect "Invalid hook call" errors which indicate
-          // a 'use client' component is being executed during RSC rendering
-          // instead of being serialized as a client reference. This happens when
-          // the RSC plugin's transform doesn't detect the directive — e.g., the
-          // directive isn't at the very top of the file, or the component is
-          // re-exported through a barrel file without 'use client'.
-          // See LOCAL-297.
-          if (isDebug() && error instanceof Error && error.message.includes('Invalid hook call')) {
-            console.error(
-              '[timber] A React hook was called during RSC rendering. This usually means a ' +
-                "'use client' component is being executed as a server component instead of " +
-                'being serialized as a client reference.\n\n' +
-                'Common causes:\n' +
-                "  1. The 'use client' directive is not the FIRST statement in the file (before any imports)\n" +
-                "  2. The component is re-exported through a barrel file (index.ts) that lacks 'use client'\n" +
-                '  3. @vitejs/plugin-rsc is not loaded or is misconfigured\n\n' +
-                `Request: ${req.method} ${new URL(req.url).pathname}`
-            );
           }
+          recorder.deny(error);
+          return JSON.stringify({
+            type: 'deny',
+            status: error.status,
+            data: error.data,
+            owners: error.owners,
+          });
+        }
+        if (isRedirectSignal(error)) {
+          recorder.redirect(error);
+          return JSON.stringify({
+            type: 'redirect',
+            location: error.location,
+            status: error.status,
+          });
+        }
+        // Dev diagnostic: detect "Invalid hook call" errors which indicate
+        // a 'use client' component is being executed during RSC rendering
+        // instead of being serialized as a client reference. This happens when
+        // the RSC plugin's transform doesn't detect the directive — e.g., the
+        // directive isn't at the very top of the file, or the component is
+        // re-exported through a barrel file without 'use client'.
+        // See LOCAL-297.
+        if (isDebug() && error instanceof Error && error.message.includes('Invalid hook call')) {
+          console.error(
+            '[timber] A React hook was called during RSC rendering. This usually means a ' +
+              "'use client' component is being executed as a server component instead of " +
+              'being serialized as a client reference.\n\n' +
+              'Common causes:\n' +
+              "  1. The 'use client' directive is not the FIRST statement in the file (before any imports)\n" +
+              "  2. The component is re-exported through a barrel file (index.ts) that lacks 'use client'\n" +
+              '  3. @vitejs/plugin-rsc is not loaded or is misconfigured\n\n' +
+              `Request: ${req.method} ${new URL(req.url).pathname}`
+          );
+        }
 
-          // Dev-mode: detect non-serializable RSC props and provide
-          // actionable fix suggestions (TIM-358).
-          // checkAndWarnRscPropError no-ops in production internally.
-          if (error instanceof Error) {
-            checkAndWarnRscPropError(error, new URL(req.url).pathname);
-          }
+        // Dev-mode: detect non-serializable RSC props and provide
+        // actionable fix suggestions (TIM-358).
+        // checkAndWarnRscPropError no-ops in production internally.
+        if (error instanceof Error) {
+          checkAndWarnRscPropError(error, new URL(req.url).pathname);
+        }
 
-          // Track unhandled errors for pre-flush handling (500 status)
-          if (!signals.renderError) {
-            signals.renderError = { error, status: 500 };
-          }
-          logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
-        },
-        debugChannel: createDebugChannelSink(),
+        // Log the error but do NOT track it as a page-level signal. If this
+        // error is inside a <Suspense> boundary, React will emit an error
+        // row in the Flight stream and the nearest error boundary renders
+        // it on the client; treating it as page-level would turn a page
+        // whose shell rendered into a 500. See TIM-524. An error no
+        // boundary contains fails SSR's shell instead, and the SSR renderer
+        // answers that with the error page.
+        recorder.unhandledError();
+
+        // Return a digest so React emits a per-row error in the Flight
+        // stream instead of leaving the lazy reference unresolved.
+        //
+        // SECURITY: Never include error.message in the digest — it may
+        // contain SQL queries, filesystem paths, secret fragments, or
+        // internal IDs. Use a generic message with a correlation ID so
+        // the error can be matched to server logs. The ID is the `digest`
+        // prop error pages receive (shared/error-digest.ts).
+        // See design/13-security.md §"Errors don't leak".
+        //
+        // This is the error's one log and one `onRequestError` report,
+        // whether a Suspense boundary contains it or it crashes the shell
+        // and the renderer answers with the error page (design/49
+        // §"Deferred: render-error handoff").
+        const errorId = randomUUID();
+        reportRenderError(error, req, { errorId });
+        return encodeErrorDigest({
+          message: isDevMode()
+            ? error instanceof Error
+              ? error.message
+              : String(error)
+            : 'An unexpected error occurred.',
+          errorId,
+        });
+      },
+    },
+    {
+      onClientReference(info: { id: string; name: string; deps: unknown }) {
+        // Client reference callback — invoked when a "use client"
+        // component is serialized into the RSC stream. Can be extended
+        // for CSS dep collection and Early Hints.
+        void info;
       },
-      {
-        onClientReference(info: { id: string; name: string; deps: unknown }) {
-          // Client reference callback — invoked when a "use client"
-          // component is serialized into the RSC stream. Can be extended
-          // for CSS dep collection and Early Hints.
-          void info;
-        },
-      }
-    );
-  } catch (error) {
-    if (error instanceof DenySignal) {
-      signals.denySignal = error;
-    } else if (error instanceof RedirectSignal) {
-      signals.redirectSignal = error;
-    } else {
-      // Synchronous render error — component threw during
-      // renderToReadableStream creation. Capture instead of crashing
-      // the server; the error page will be rendered below.
-      signals.renderError = {
-        error,
-        status: error instanceof RenderError ? error.status : 500,
-      };
-      logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
     }
-  }
+  );
 
-  return { rscStream, signals };
+  return { rscStream, signals: recorder.signals };
 }