@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.149

package/src/server/actions.ts

@@ -14,7 +14,7 @@
  * See design/08-forms-and-actions.md
  */
 
-import { getCacheHandler } from '../cache/handler-store';
+import { cache } from '../cache/cache-api';
 import { DenySignal, RedirectSignal } from './primitives';
 import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
@@ -161,12 +161,14 @@ export async function executeAction(
     }
   });
 
-  // Process tag invalidation via the module-level cache handler singleton.
-  // setCacheHandler() is called at boot from rsc-entry when timber.config.ts
-  // provides a cacheHandler; otherwise falls back to in-memory LRU (TIM-599).
+  // Process tag invalidation through cache.invalidate so it records the
+  // invalidation epoch — an in-flight cached fn must not re-store data this
+  // mutation just invalidated (TIM-1028). cache.invalidate resolves the
+  // module-level handler singleton: setCacheHandler() is called at boot from
+  // rsc-entry when timber.config.ts provides a cacheHandler; otherwise falls
+  // back to in-memory LRU (TIM-599).
   if (state.tags.length > 0) {
-    const handler = getCacheHandler();
-    await Promise.all(state.tags.map((tag) => handler.invalidate({ tag })));
+    await Promise.all(state.tags.map((tag) => cache.invalidate({ tag })));
   }
 
   // Process path revalidation — build element tree (not yet serialized)
@@ -212,28 +214,3 @@ export async function executeAction(
     ...(redirectTo ? { redirectTo, redirectStatus } : {}),
   };
 }
-
-/**
- * Build an HTTP Response for a no-JS form submission.
- * Standard POST → 302 redirect pattern.
- *
- * @param redirectPath - Where to redirect after the action executes.
- */
-export function buildNoJsResponse(redirectPath: string, status: number = 302): Response {
-  return new Response(null, {
-    status,
-    headers: { Location: redirectPath },
-  });
-}
-
-/**
- * Detect whether the incoming request is an RSC action request (with JS)
- * or a plain HTML form POST (no JS).
- *
- * RSC action requests use Accept: text/x-component or Content-Type: text/x-component.
- */
-export function isRscActionRequest(req: Request): boolean {
-  const accept = req.headers.get('Accept') ?? '';
-  const contentType = req.headers.get('Content-Type') ?? '';
-  return accept.includes('text/x-component') || contentType.includes('text/x-component');
-}

package/src/server/build-manifest.ts

@@ -101,19 +101,6 @@ export function buildCssLinkTags(cssUrls: string[]): string {
   return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
 }
 
-/**
- * Generate a Link header value for CSS preload hints.
- *
- * Cloudflare CDN automatically converts Link headers with rel=preload
- * into 103 Early Hints responses. This avoids platform-specific 103
- * sending code.
- *
- * Example output: `</assets/root.css>; as=style; rel=preload, </assets/page.css>; as=style; rel=preload`
- */
-export function buildLinkHeaders(cssUrls: string[]): string {
-  return cssUrls.map((url) => `<${url}>; as=style; rel=preload`).join(', ');
-}
-
 // ─── Font utilities ──────────────────────────────────────────────────────
 
 /**
@@ -161,44 +148,8 @@ export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
     .join('');
 }
 
-/**
- * Generate Link header values for font preload hints.
- *
- * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
- *
- * Example: `</fonts/inter.woff2>; as=font; rel=preload; crossorigin`
- */
-export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
-  return fonts.map((f) => `<${f.href}>; as=font; rel=preload; crossorigin`).join(', ');
-}
-
 // ─── JS chunk utilities ──────────────────────────────────────────────────
 
-/**
- * Collect JS chunk URLs for a matched route's segment chain.
- *
- * Walks segments root → leaf, collecting the JS chunk for each layout
- * and page. Deduplicates while preserving order.
- */
-export function collectRouteJs(segments: SegmentWithFiles[], manifest: BuildManifest): string[] {
-  const seen = new Set<string>();
-  const result: string[] = [];
-
-  for (const segment of segments) {
-    for (const file of [segment.layout, segment.page]) {
-      if (!file) continue;
-      const jsUrl = manifest.js[file.filePath];
-      if (!jsUrl) continue;
-      if (!seen.has(jsUrl)) {
-        seen.add(jsUrl);
-        result.push(jsUrl);
-      }
-    }
-  }
-
-  return result;
-}
-
 /**
  * Collect modulepreload URLs for a matched route's segment chain.
  *
@@ -238,10 +189,3 @@ export function collectRouteModulepreloads(
 export function buildModulepreloadTags(urls: string[]): string {
   return urls.map((url) => `<link rel="modulepreload" href="${url}">`).join('');
 }
-
-/**
- * Generate a <script type="module"> tag for a JS entry point.
- */
-export function buildEntryScriptTag(url: string): string {
-  return `<script type="module" src="${url}"></script>`;
-}

package/src/server/canonicalize.ts

@@ -13,11 +13,14 @@ export type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; s
 /**
  * Encoded separators that produce a 400 rejection.
  * %2f (/) and %5c (\) cause path-confusion attacks.
+ *
+ * Shared between the runtime canonicalizer and the build-time route scanner
+ * to ensure both enforce identical security rules. See design/13-security.md.
  */
-const ENCODED_SEPARATOR_RE = /%2f|%5c/i;
+export const ENCODED_SEPARATOR_RE = /%2f|%5c/i;
 
-/** Null byte — rejected. */
-const NULL_BYTE_RE = /%00/i;
+/** Null byte — rejected. Shared with the route scanner. */
+export const NULL_BYTE_RE = /%00/i;
 
 /**
  * Canonicalize a URL pathname.

package/src/server/deny-renderer.ts

@@ -20,6 +20,7 @@ import { renderToReadableStream } from '../rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
 import { renderDenyEntry, type DenyPageEntry } from './deny-boundary.js';
+import { getCookiesForSsr } from './cookie-context.js';
 import { logRenderError } from './logger.js';
 import { loadModule } from './safe-load.js';
 import { isMdxFilePath } from './utils/mdx-file.js';
@@ -184,6 +185,7 @@ export async function renderDenyPage(
 
   // Render the error page to a fresh RSC Flight stream.
   const rscStream = renderToReadableStream(element, {
+    signal: req.signal,
     onError(error: unknown) {
       logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
     },
@@ -201,6 +203,8 @@ export async function renderDenyPage(
     headHtml: headHtml + flightInitScript(),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
+    signal: req.signal,
+    cookies: getCookiesForSsr(),
   };
 
   return callSsr(ssrStream, navContext);
@@ -216,6 +220,7 @@ export async function renderDenyPageAsRsc(
   deny: DenySignal,
   segments: ManifestSegmentNode[],
   layoutComponents: LayoutEntry[],
+  req: Request,
   responseHeaders: Headers,
   createDebugChannelSink: DebugChannelFactory
 ): Promise<Response> {
@@ -251,6 +256,7 @@ export async function renderDenyPageAsRsc(
   }
 
   const rscStream = renderToReadableStream(element, {
+    signal: req.signal,
     onError(error: unknown) {
       console.error('[timber] Error page RSC render error:', error);
     },

package/src/server/html-injector-core.ts

@@ -302,6 +302,7 @@ export class FlightInjectorCore {
   private readonly errorSignal?: AbortSignal;
   private readonly decoder = new TextDecoder('utf-8', { fatal: true });
   private pullPromise: Promise<void> | null = null;
+  private _aborted = false;
 
   constructor(
     rscStream: ReadableStream<Uint8Array>,
@@ -363,6 +364,22 @@ export class FlightInjectorCore {
     return this.machine.state.phase === 'error' ? this.machine.state.error : null;
   }
 
+  /**
+   * Abort the pull loop and release the RSC reader. Called by stream
+   * wrappers when the HTML pipeline is torn down (Node `destroy()`,
+   * Web `cancel()`). Safe to call multiple times.
+   */
+  abort(reason?: unknown): void {
+    if (this._aborted) return;
+    this._aborted = true;
+    this.rscReader.cancel(reason).catch(() => {});
+    this.pending.length = 0;
+  }
+
+  get isAborted(): boolean {
+    return this._aborted;
+  }
+
   private async runPullLoop(onYieldDrain: () => void): Promise<void> {
     // Yield once so the first HTML shell chunk flows through the wrapper
     // before we start reading RSC data.
@@ -370,6 +387,8 @@ export class FlightInjectorCore {
 
     try {
       for (;;) {
+        if (this._aborted) return;
+
         // Guard each read with a timeout so a permanently hung RSC stream
         // eventually aborts. See design/02 §"Streaming Constraints".
         const readPromise = this.rscReader.read();

package/src/server/html-injectors.ts

@@ -271,8 +271,11 @@ function createFlightInjectionTransform(
     if (_controller) drain(_controller);
   };
 
-  return new TransformStream<Uint8Array, Uint8Array>({
-    transform(chunk, controller) {
+  // The cast is needed because TypeScript's lib types don't include the
+  // `cancel` method on Transformer, even though it's part of the WHATWG
+  // Streams spec and supported in all target runtimes.
+  const transformer = {
+    transform(chunk: Uint8Array, controller: TransformStreamDefaultController<Uint8Array>) {
       _controller = controller;
 
       if (core.isInit) {
@@ -287,7 +290,7 @@ function createFlightInjectionTransform(
       controller.enqueue(chunk);
       if (core.pending.length > 0) drain(controller);
     },
-    flush(controller) {
+    flush(controller: TransformStreamDefaultController<Uint8Array>) {
       // All HTML chunks emitted. Pull loop stops yielding.
       core.notifyHtmlDone();
 
@@ -299,7 +302,14 @@ function createFlightInjectionTransform(
       }
       return core.ensurePullLoop(onYieldDrain).then(finish);
     },
-  });
+    cancel(reason: unknown) {
+      core.abort(reason ?? 'transform cancelled');
+    },
+  };
+
+  return new TransformStream<Uint8Array, Uint8Array>(
+    transformer as Transformer<Uint8Array, Uint8Array>
+  );
 }
 
 /**

package/src/server/internal.ts

@@ -86,10 +86,6 @@ export type {
   SlotDeniedKind,
 } from './status-code-resolver.js';
 
-// ── Flush Controller ─────────────────────────────────────────────────────
-export { flushResponse } from './flush.js';
-export type { FlushOptions, FlushResult, RenderFn, RenderResult } from './flush.js';
-
 // ── CSRF Protection ──────────────────────────────────────────────────────
 export { validateCsrf } from './csrf.js';
 export type { CsrfConfig, CsrfResult } from './csrf.js';
@@ -123,7 +119,7 @@ export type {
 } from './metadata-routes.js';
 
 // ── Server Actions (pipeline internals) ──────────────────────────────────
-export { executeAction, buildNoJsResponse, isRscActionRequest } from './actions.js';
+export { executeAction } from './actions.js';
 export type {
   RevalidateRenderer,
   RevalidationState,
@@ -160,19 +156,6 @@ export type {
   InstrumentationErrorContext,
 } from './instrumentation.js';
 
-// ── Dev Warnings ─────────────────────────────────────────────────────────
-export {
-  warnSuspenseWrappingChildren,
-  warnDenyInSuspense,
-  warnRedirectInSuspense,
-  warnRedirectInAccess,
-  warnStaticRequestApi,
-  warnSlowSlotWithoutSuspense,
-  setViteServer,
-  WarningId,
-} from '../dev-tools/warnings.js';
-export type { DevWarningConfig } from '../dev-tools/warnings.js';
-
 // ── Route Handler ────────────────────────────────────────────────────────
 export { handleRouteRequest, resolveAllowedMethods } from './route-handler.js';
 export type { RouteModule, RouteHandler, HttpMethod } from './route-handler.js';

package/src/server/node-stream-transforms.ts

@@ -20,7 +20,6 @@
 
 import { PassThrough, Transform, type Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { createGzip, constants } from 'node:zlib';
 
 import {
   BufferAggregator,
@@ -35,6 +34,7 @@ import {
 } from './html-injector-core.js';
 import { logStreamingError } from './logger.js';
 import { createTickCoalescer } from './coalesce-tick.js';
+import { isAbortError, NOINDEX_SCRIPT } from './render-utils.js';
 
 // ─── Buffered Transform ──────────────────────────────────────────────────────
 
@@ -229,6 +229,10 @@ export function createNodeFlightInjector(
       if (wasInit) core.ensurePullLoop(drain);
       callback();
     },
+    destroy(err, callback) {
+      core.abort(err ?? 'pipeline destroyed');
+      callback(err);
+    },
     flush(callback) {
       // All HTML chunks have been emitted. Pull loop stops yielding.
       core.notifyHtmlDone();
@@ -263,15 +267,6 @@ export function createNodeFlightInjector(
 
 // ─── Error Handling ──────────────────────────────────────────────────────────
 
-const NOINDEX_SCRIPT =
-  '<script>document.head.appendChild(Object.assign(document.createElement("meta"),{name:"robots",content:"noindex"}))</script>';
-
-function isAbortError(error: unknown): boolean {
-  if (error instanceof DOMException && error.name === 'AbortError') return true;
-  if (error instanceof Error && error.name === 'AbortError') return true;
-  return false;
-}
-
 /**
  * Run the Node SSR post-processing pipeline with post-shell error handling.
  *
@@ -334,65 +329,3 @@ export function runNodePipelineWithErrorHandling(
 
   return output;
 }
-
-// ─── Compression ─────────────────────────────────────────────────────────────
-
-const COMPRESSIBLE_TYPES = new Set([
-  'text/html',
-  'text/css',
-  'text/plain',
-  'text/xml',
-  'text/javascript',
-  'text/x-component',
-  'application/json',
-  'application/javascript',
-  'application/xml',
-  'application/xhtml+xml',
-  'application/rss+xml',
-  'image/svg+xml',
-]);
-
-/**
- * Create a Node.js gzip Transform using native node:zlib.
- *
- * Uses `createGzip()` which is backed by C++ zlib — significantly faster
- * than the Web Streams `CompressionStream` API (which is a JS wrapper
- * around the same zlib but with per-chunk Promise overhead).
- *
- * Returns null if the response shouldn't be compressed (wrong content type,
- * client doesn't accept gzip, already encoded, etc.).
- */
-export function createNodeGzipCompressor(
-  requestHeaders: Headers,
-  responseHeaders: Headers
-): Transform | null {
-  // Check Accept-Encoding
-  const acceptEncoding = requestHeaders.get('accept-encoding') || '';
-  if (!acceptEncoding.includes('gzip')) return null;
-
-  // Check content type is compressible
-  const contentType = responseHeaders.get('content-type') || '';
-  const mimeType = contentType.split(';')[0].trim().toLowerCase();
-  if (!COMPRESSIBLE_TYPES.has(mimeType)) return null;
-
-  // Don't double-compress
-  if (responseHeaders.has('content-encoding')) return null;
-
-  // Set response headers for gzip
-  responseHeaders.set('content-encoding', 'gzip');
-  responseHeaders.delete('content-length');
-  const existingVary = responseHeaders.get('vary');
-  if (existingVary) {
-    if (!existingVary.toLowerCase().includes('accept-encoding')) {
-      responseHeaders.set('vary', existingVary + ', Accept-Encoding');
-    }
-  } else {
-    responseHeaders.set('vary', 'Accept-Encoding');
-  }
-
-  // Z_SYNC_FLUSH ensures each chunk is flushed to the output immediately.
-  // Without it, gzip buffers internally and the browser doesn't receive
-  // the HTML shell until the gzip stream closes — breaking streaming.
-  // ~2–5% size overhead vs Z_NO_FLUSH but preserves correct streaming.
-  return createGzip({ flush: constants.Z_SYNC_FLUSH });
-}

package/src/server/render-utils.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared render-phase utilities — used by both the Node.js and Web
+ * stream wrappers. Pure functions only; no stream-shape dependencies.
+ *
+ * Consolidated from duplicated copies in node-stream-transforms.ts,
+ * ssr-render.ts, and rsc-entry/helpers.ts. See TIM-1071 item 1.
+ */
+
+/**
+ * Check if an error is an abort error (connection closed by client).
+ *
+ * When the browser aborts a request (page refresh, navigation away),
+ * the AbortSignal fires and React/streams throw an AbortError. This
+ * is not an application error — suppress it from error boundaries and logs.
+ */
+export function isAbortError(error: unknown): boolean {
+  if (error instanceof DOMException && error.name === 'AbortError') return true;
+  if (error instanceof Error && error.name === 'AbortError') return true;
+  return false;
+}
+
+/**
+ * Inline script that adds `<meta name="robots" content="noindex">` to the
+ * document head. Injected when a render-phase error replaces the shell so
+ * search engines don't index error pages.
+ *
+ * MUST be byte-identical across all stream wrappers (Node and Web) to
+ * ensure consistent Content-Length headers.
+ */
+export const NOINDEX_SCRIPT =
+  '<script>document.head.appendChild(Object.assign(document.createElement("meta"),{name:"robots",content:"noindex"}))</script>';

package/src/server/route-element-builder.ts

@@ -6,12 +6,11 @@
  * rsc-entry.ts under the 500-line limit.
  *
  * This module handles:
- * 1. Loading page/layout components from the segment chain
- * 2. Collecting access.ts checks (executed inside render by AccessPreRunner)
- * 3. Resolving metadata (static object or async function, both exported as `metadata`)
+ * 1. Running access.ts checks eagerly to gate metadata resolution (TIM-1027)
+ * 2. Loading page/layout components from the segment chain
+ * 3. Resolving metadata (skipped for denied segments to prevent side effects)
  * 4. Building the React element tree (page → error boundaries → access gates → layouts)
  * 5. Resolving parallel slots
- * 6. Wrapping the tree with AccessPreRunner for React.cache-scoped access checks
  *
  * See design/02-rendering-pipeline.md, design/04-authorization.md
  */
@@ -154,24 +153,6 @@ export interface RouteElementResult {
   skippedSegments: string[];
 }
 
-/**
- * Wraps a DenySignal or RedirectSignal with the layout components loaded
- * so far, enabling the caller to render deny pages inside the layout shell.
- *
- * @deprecated No longer thrown by buildRouteElement since TIM-662. Access
- * checks now run inside AccessPreRunner during renderToReadableStream, and
- * signals are caught by onError. Kept for backward compat with external code.
- */
-export class RouteSignalWithContext extends Error {
-  constructor(
-    public readonly signal: DenySignal | RedirectSignal,
-    public readonly layoutComponents: LayoutComponentEntry[],
-    public readonly segments: ManifestSegmentNode[]
-  ) {
-    super(signal.message);
-  }
-}
-
 // ─── Module Processing Helpers ─────────────────────────────────────────────
 
 /**
@@ -235,16 +216,18 @@ function extractDeferSuspenseFor(mod: Record<string, unknown>, current: number):
 /**
  * Build a React element tree from a matched route.
  *
- * Loads modules, runs access checks, resolves metadata, and constructs
- * the element tree. DenySignal and RedirectSignal propagate to the caller
- * for HTTP-level handling.
+ * Runs access checks eagerly to gate metadata resolution, then loads
+ * modules, resolves metadata (skipping denied segments), and constructs
+ * the element tree. DenySignal and RedirectSignal from access are stored
+ * as AccessGate verdicts for synchronous replay during render.
  *
  * Does NOT serialize to RSC Flight — the caller decides whether to render
  * to a stream or use the element directly (e.g., for action revalidation).
  *
- * Access checks are collected but NOT executed here. They run inside
- * AccessPreRunner during renderToReadableStream so that access.ts and
- * render components share the same React.cache scope (TIM-662).
+ * For passing segments, AccessGate re-runs access during render so that
+ * React.cache is populated for layout dedup (TIM-662). For denied
+ * segments, the pre-computed verdict is replayed — no re-execution,
+ * no metadata side effects, no head leak (TIM-1027).
  */
 export async function buildRouteElement(
   req: Request,
@@ -255,7 +238,46 @@ export async function buildRouteElement(
 ): Promise<RouteElementResult> {
   const segments = match.segments;
 
-  // Load all modules along the segment chain
+  // ── Access pre-pass ──────────────────────────────────────────────────
+  // Run access checks eagerly to determine which segments are denied.
+  // This gates metadata() resolution: denied segments' metadata functions
+  // are never called, preventing unauthorized side effects (DB queries)
+  // and metadata content leaking into the <head> of denied responses.
+  //
+  // Verdicts are passed to AccessGate for synchronous replay (DenySignal
+  // renders the deny page in-tree; RedirectSignal propagates). For PASSING
+  // segments, no verdict is passed — AccessGate re-runs access during
+  // renderToReadableStream to populate React.cache for layout dedup.
+  //
+  // See TIM-1027, design/04-authorization.md, design/13-security.md.
+  const accessVerdicts = new Map<number, DenySignal | RedirectSignal>();
+  let firstDeniedIndex = Infinity;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (!segment.access || i >= firstDeniedIndex) continue;
+
+    try {
+      const accessMod = await loadModule(segment.access);
+      const accessFn = accessMod.default as (() => Promise<void>) | undefined;
+      if (accessFn) {
+        await withSpan(
+          'timber.access.pre',
+          { 'timber.segment': segment.segmentName ?? 'unknown' },
+          () => accessFn()
+        );
+      }
+    } catch (error: unknown) {
+      if (error instanceof DenySignal || error instanceof RedirectSignal) {
+        accessVerdicts.set(i, error);
+        firstDeniedIndex = i;
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  // ── Module loading + metadata resolution ─────────────────────────────
   const metadataEntries: Array<{ metadata: Metadata; isPage: boolean }> = [];
   const layoutComponents: LayoutComponentEntry[] = [];
   let PageComponent: ((...args: unknown[]) => unknown) | null = null;
@@ -264,6 +286,7 @@ export async function buildRouteElement(
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i];
     const isLeaf = i === segments.length - 1;
+    const isDenied = i >= firstDeniedIndex;
 
     // Load layout
     if (segment.layout) {
@@ -279,9 +302,11 @@ export async function buildRouteElement(
       // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
 
       rejectLegacyGenerateMetadata(mod, segment.layout.filePath ?? segment.urlPath);
-      const layoutMetadata = await extractMetadata(mod, segment);
-      if (layoutMetadata) {
-        metadataEntries.push({ metadata: layoutMetadata, isPage: false });
+      if (!isDenied) {
+        const layoutMetadata = await extractMetadata(mod, segment);
+        if (layoutMetadata) {
+          metadataEntries.push({ metadata: layoutMetadata, isPage: false });
+        }
       }
       deferSuspenseFor = extractDeferSuspenseFor(mod, deferSuspenseFor);
     }
@@ -297,9 +322,11 @@ export async function buildRouteElement(
         PageComponent = mod.default as (...args: unknown[]) => unknown;
       }
       rejectLegacyGenerateMetadata(mod, segment.page.filePath ?? segment.urlPath);
-      const pageMetadata = await extractMetadata(mod, segment);
-      if (pageMetadata) {
-        metadataEntries.push({ metadata: pageMetadata, isPage: true });
+      if (!isDenied) {
+        const pageMetadata = await extractMetadata(mod, segment);
+        if (pageMetadata) {
+          metadataEntries.push({ metadata: pageMetadata, isPage: true });
+        }
       }
       deferSuspenseFor = extractDeferSuspenseFor(mod, deferSuspenseFor);
     }
@@ -317,16 +344,6 @@ export async function buildRouteElement(
     );
   }
 
-  // Access checks are NOT run here. AccessGate components in the element
-  // tree call accessFn directly during renderToReadableStream, sharing the
-  // same React.cache scope as layout/page components. A requireUser() call
-  // in access.ts populates React.cache; the same call in a layout is a hit.
-  //
-  // Previously (before TIM-662), access checks ran eagerly in a pre-render
-  // loop OUTSIDE renderToReadableStream, breaking React.cache dedup.
-  //
-  // See design/04-authorization.md §"Pre-Render Pass and Verdict Replay"
-
   // Build deny page fallback chains for each segment position.
   // When AccessGate or PageDenyBoundary catches a DenySignal, they render
   // the matching deny page in-tree instead of throwing into React Flight.
@@ -359,8 +376,11 @@ export async function buildRouteElement(
       ? new URL(requestUrl.origin)
       : resolvedMetadata.metadataBase;
 
-  for (const segment of segments) {
+  for (let si = 0; si < segments.length; si++) {
+    const segment = segments[si];
     if (!segment.metadataRoutes) continue;
+    // Skip auto-linking for denied segments — same gate as metadata().
+    if (si >= firstDeniedIndex) continue;
     for (const baseName of Object.keys(segment.metadataRoutes)) {
       const convention = METADATA_ROUTE_CONVENTIONS[baseName];
       if (!convention) continue;
@@ -461,7 +481,7 @@ export async function buildRouteElement(
   //
   // When clientStateTree is provided (from X-Timber-State-Tree header on
   // client navigation), sync layouts the client already has are skipped.
-  // Access.ts already ran for ALL segments in the pre-render loop above.
+  // Access.ts was pre-checked eagerly above for metadata gating (TIM-1027).
   // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
   //
   // hasRenderedLayoutBelow tracks whether a non-skipped layout has been
@@ -517,10 +537,15 @@ export async function buildRouteElement(
         const accessMod = await loadModule(segment.access);
         const accessFn = accessMod.default as (() => unknown) | undefined;
         if (accessFn) {
+          // Pass verdict for denied/redirected segments so AccessGate replays
+          // without re-execution. Passing segments omit verdict so AccessGate
+          // re-runs access during render for React.cache population.
+          const verdict = accessVerdicts.get(i);
           element = h(AccessGate, {
             accessFn,
             segmentName: segment.segmentName,
             denyPages: denyPageChains.get(i),
+            ...(verdict ? { verdict } : {}),
             children: element,
           });
         }
@@ -661,10 +686,15 @@ export async function buildRouteElement(
       const accessMod = await loadModule(segment.access);
       const accessFn = accessMod.default as (() => unknown) | undefined;
       if (accessFn) {
+        // Pass verdict for denied/redirected segments so AccessGate replays
+        // without re-execution. Passing segments omit verdict so AccessGate
+        // re-runs access during render for React.cache population.
+        const verdict = accessVerdicts.get(i);
         element = h(AccessGate, {
           accessFn,
           segmentName: segment.segmentName,
           denyPages: denyPageChains.get(i),
+          ...(verdict ? { verdict } : {}),
           children: element,
         });
       }