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

package/src/server/prebuilt-runtime.ts

@@ -0,0 +1,813 @@
+/**
+ * Prebuilt component runtime — registration target for the timber-prebuilt
+ * transform (plugins/prebuilt.ts) and the request-time half of
+ * cache.component (TIM-1140).
+ *
+ * `cache.component(fn, opts)` call sites are rewritten at build time to
+ * `__prebuilt(stableId, fn, opts)` (production) or `__prebuiltDev(name, fn)`
+ * (dev). Both are exported via #server-internal — they are framework
+ * plumbing, never called by user code directly.
+ *
+ * Cache hits are served by FLIGHT REVIVAL: the cached `.flight` payload is
+ * decoded back into React elements inside the RSC environment with
+ * `createFromReadableStream` (the flight client running in the flight
+ * server — plugin-rsc wires the server-decode manifest so client
+ * references revive as re-serializable reference proxies). The revived
+ * element is returned from the wrapper and the outer render re-serializes
+ * it like any other subtree. This is the same mechanism as Next.js
+ * `"use cache"` (next/src/server/use-cache/use-cache-wrapper.ts).
+ *
+ * What a hit skips: all user work — data fetching, MDX compilation, the
+ * component function itself never runs. What it re-pays: React
+ * re-serializes the already-resolved tree (cost proportional to payload
+ * size, not to data latency). The alternative — splicing raw payload bytes
+ * into the outer stream — avoids re-serialization but requires byte-level
+ * coupling to the flight wire format (row framing, ID rebasing, marker
+ * detection); it was implemented and reviewed on PR #835 and deliberately
+ * replaced by revival. See design/44-render-at-build-time.md
+ * §Request-Time Injection.
+ *
+ * Misses render the original component live via the wrapper's own closure,
+ * inside the React pass — segment params from ALS, deny()/redirect()
+ * signals, Suspense, and error boundaries behave exactly as an unwrapped
+ * component. `fallbackOnMissingSegmentParams: false` throws instead.
+ */
+
+import { createElement } from 'react';
+
+import { requestContextAls, type RequestContextStore } from './als-registry.ts';
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { SlotParamsRecord } from '../shared/slot-params.ts';
+import { computeComponentCacheKey, tryCanonicalize } from './prebuilt/cache-key.ts';
+import {
+  resolveSlotNames,
+  prepareSlotRender,
+  withoutChildrenOutlet,
+  wrapInSlotsProvider,
+} from './prebuilt/slots.ts';
+import {
+  createKeyDisciplineProxy,
+  emitKeyDisciplineWarning,
+  shouldCheckKeyDiscipline,
+} from './prebuilt/key-discipline.ts';
+import {
+  createCaptureScope,
+  isCaptureActive,
+  noteWrapperRender,
+  type NestedWrapperRender,
+} from './prebuilt/capture-state.ts';
+import { hasRuntimeLifetime, resolveTags, warnNestingClamps } from './prebuilt/lifetime.ts';
+import {
+  hasPrebuiltPayloadSource,
+  lookupPrebuiltPayload,
+  getManifestEntry,
+  isParamIndependent,
+} from './prebuilt/payload-source.ts';
+import { lookupOverlay, storeOverlayEntry, overlayKey } from './prebuilt/overlay.ts';
+import { getWaitUntil } from './waituntil-bridge.ts';
+import { runBackgroundFlight } from './pipeline-helpers.ts';
+import { runOutsideReactCacheScope } from './react-cache-scope.ts';
+import { readAllBytesWithDeadline } from './stream-utils.ts';
+import { DEFAULT_RENDER_TIMEOUT_MS } from './render-timeout.ts';
+import { createSingleflight } from '../cache/singleflight.ts';
+import {
+  currentInvalidationEpoch,
+  wasInvalidatedSince,
+  lastInvalidationEpochFor,
+} from '../cache/invalidation-epoch.ts';
+
+/** Default timeout for component re-renders (overridden by renderTimeoutMs). */
+const DEFAULT_COMPONENT_TIMEOUT_MS = DEFAULT_RENDER_TIMEOUT_MS;
+
+/** Singleflight for component re-renders (inline and background). */
+let componentSingleflight = createSingleflight({
+  timeoutMs: DEFAULT_COMPONENT_TIMEOUT_MS,
+});
+let componentTimeoutMs = DEFAULT_COMPONENT_TIMEOUT_MS;
+
+/**
+ * Set the timeout for component re-render captures. Called at boot from
+ * the RSC entry with renderTimeoutMs from timber.config.ts.
+ */
+export function setComponentRefreshTimeout(timeoutMs: number): void {
+  componentTimeoutMs = timeoutMs;
+  componentSingleflight = createSingleflight({ timeoutMs });
+}
+
+let warnedNoWaitUntil = false;
+
+/**
+ * (outer, inner) pairs already warned about by request-time captures.
+ * Process-wide: re-renders of a hot component repeat, and the warning is
+ * about the code, not the request. Bounded by the number of wrapped
+ * components in the app.
+ */
+const warnedNestingPairs = new Set<string>();
+
+/**
+ * Options captured from the `cache.component(fn, opts)` call site.
+ *
+ * `prerender`/`ttl`/`tags` (design/45) are carried through untouched — the
+ * build phase (TIM-1119) and runtime overlay (design/45 phase 3) consume
+ * them.
+ */
+export interface PrebuiltComponentOptions {
+  /** Populate the cache at build time via generateStaticSegmentParams. */
+  prerender?: boolean;
+  /** Runtime freshness window, seconds (design/45 runtime tier). */
+  ttl?: number;
+  /** Runtime invalidation tags (design/45 runtime tier). */
+  tags?: string[] | ((props: Record<string, unknown>) => string[]);
+  /** Serve stale while a background re-render refreshes (design/45 §SWR). */
+  staleWhileRevalidate?: boolean;
+  /**
+   * Slot props (TIM-1173): prop names whose values are live React
+   * elements composed into the cached shell at request time instead of
+   * participating in the cache. Each declared slot renders as a stable
+   * SlotOutlet client reference at capture time; the live value flows in
+   * through SlotContext per instance. Slot props are excluded from the
+   * cache key — only the remaining data props (+ segment params) hash.
+   * Runtime tier only: `prerender` is ignored (with a warning) because
+   * the build cannot enumerate children variants.
+   */
+  slots?: string[];
+  /**
+   * On a cache miss, render the component live (default: true). When false,
+   * a miss throws instead — for sites that must never render unknown params
+   * dynamically. See design/44 §fallbackOnMissingSegmentParams.
+   */
+  fallbackOnMissingSegmentParams?: boolean;
+}
+
+/** An async server component: props in, renderable out. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ServerComponent = (props: any) => unknown;
+
+/**
+ * View of a ServerComponent that satisfies createElement's overloads.
+ * Server components legitimately return `unknown` from the framework's
+ * perspective (promises, elements, strings, …) — React renders whatever
+ * comes back; the narrowing exists only to cross createElement's
+ * ReactNode-typed signature.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RenderableComponent = (props: any) => React.ReactNode;
+
+export interface PrebuiltRegistration {
+  id: string;
+  component: ServerComponent;
+  options: PrebuiltComponentOptions;
+}
+
+/**
+ * Server-side component registry, keyed by stable component ID. Populated at
+ * module load time by `__prebuilt` calls; consumed by the post-build capture
+ * pass (TIM-1119). Never serialized — component functions are not
+ * Flight-serializable.
+ */
+const registry = new Map<string, PrebuiltRegistration>();
+
+/**
+ * Resolve the params the cache key may faithfully hash, or null if this
+ * render is unkeyable.
+ *
+ * A wrapper rendered inside a parallel slot reads params merged with that
+ * slot's overrides (`getSegmentParams`: `{...segmentParams, ...slotParams}`)
+ * — but the cache key hashes only the route-level params, and the wrapper
+ * cannot know which slot it renders under. The route params are usable
+ * only when every slot's merged view canonicalizes identically to them;
+ * otherwise two renders with the same key could see different effective
+ * inputs and a hit could serve the WRONG cached subtree — so the render
+ * goes live: slower, never wrong. (Build-time capture doesn't model slot
+ * params either, so a divergent request could never have a faithful
+ * entry. Codex review on PR #835; revisit with segment-path-scoped keys
+ * if slot-scoped prebuilt is ever needed.)
+ *
+ * Comparison happens through `tryCanonicalize` — the same single
+ * definition of value equality the cache key uses — so anything it
+ * cannot represent faithfully (bigint-coerced codec params, accessors,
+ * aliases, …) is unkeyable here too, and this guard can never throw.
+ */
+function resolveKeyParams(store: {
+  segmentParams?: CoercedParams;
+  slotParams?: SlotParamsRecord;
+}): CoercedParams | null {
+  const main = store.segmentParams ?? {};
+  const slots = store.slotParams;
+  if (!slots || Object.keys(slots).length === 0) return main;
+  // Spread before canonicalizing: param records are framework-produced
+  // Object.create(null) objects (prototype-pollution defense) — normalize
+  // the records themselves, let nested values face the full allowlist.
+  const mainCanonical = tryCanonicalize({ ...main });
+  if (mainCanonical === null) return null;
+  for (const slotParams of Object.values(slots)) {
+    const merged = tryCanonicalize({ ...main, ...slotParams });
+    if (merged === null || merged !== mainCanonical) return null;
+  }
+  return main;
+}
+
+/**
+ * Mirror the production cache-key decision for a slot render, with no
+ * cache IO — used by the dev wrapper so slot substitution happens in dev
+ * exactly when production would serve the cache path rather than the
+ * live fallback (dev/prod parity, codex P2 on PR #890): requires an ALS
+ * store, keyable params (slot-param divergence unkeys), and keyable data
+ * props (after the children slot outlet strip).
+ */
+function isSlotRenderKeyable(dataProps: Record<string, unknown>): boolean {
+  const store = requestContextAls.getStore();
+  if (!store) return false;
+  const keyParams = resolveKeyParams(store);
+  if (keyParams === null) return false;
+  return computeComponentCacheKey(withoutChildrenOutlet(dataProps), keyParams) !== null;
+}
+
+/** Wrap payload bytes as a single-chunk ReadableStream for the decoder. */
+function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+// ─── Slot components (TIM-1173) ──────────────────────────────────────────
+
+/**
+ * Serve a slot component from the cache: split live slot values out of the
+ * props, look up / capture the shell (data props + a deterministic
+ * SlotOutlet placeholder per slot), and wrap the revived shell in a
+ * per-instance SlotsProvider that feeds the live values to the outlets.
+ *
+ * Null on any miss — the caller renders live with the original props.
+ */
+async function tryReviveSlotShell(
+  id: string,
+  options: PrebuiltComponentOptions,
+  slots: readonly string[],
+  props: Record<string, unknown>
+): Promise<{ element: unknown } | null> {
+  const render = prepareSlotRender(props, slots);
+  if (render === null) return null; // top-level props unkeyable → live render
+  const { shellProps, dataProps, slotValues } = render;
+  const revived = await tryRevivePayload(id, options, shellProps, dataProps);
+  if (revived === null) return null;
+  return { element: wrapInSlotsProvider(revived.element, slotValues) };
+}
+
+// ─── RSC function injection ─────────────────────────────────────────────
+// The flight client/server is only resolvable in the RSC environment
+// (react-server condition). The RSC entry wires these at boot via
+// setRscFunctions(); tests inject mocks directly. Same pattern as
+// setCacheHandler / setPrebuiltPayloadSource.
+
+interface RscFunctions {
+  createFromReadableStream: (stream: ReadableStream<Uint8Array>) => Promise<unknown>;
+  renderToReadableStream: (
+    element: unknown,
+    options?: { onError?: (error: unknown) => string }
+  ) => ReadableStream<Uint8Array>;
+}
+
+let rscFns: RscFunctions | null = null;
+
+/**
+ * Wire the RSC flight client/server functions. Called once at server
+ * startup from the RSC entry module.
+ */
+export function setRscFunctions(fns: RscFunctions): void {
+  rscFns = fns;
+}
+
+function requireRscFunctions(): RscFunctions {
+  if (!rscFns) {
+    throw new Error('[timber] RSC functions not wired — setRscFunctions() must be called at boot');
+  }
+  return rscFns;
+}
+
+/**
+ * Revive flight payload bytes into a React element.
+ * Returns null on any failure (corrupt payload, missing decoder).
+ */
+async function revivePayload(
+  id: string,
+  payload: Uint8Array,
+  outcome: string
+): Promise<{ element: unknown } | null> {
+  try {
+    const { createFromReadableStream } = requireRscFunctions();
+    const element: unknown = await createFromReadableStream(bytesToStream(payload));
+    return { element };
+  } catch (error) {
+    console.error(`[timber] failed to revive prebuilt payload for "${id}" — ${outcome}:`, error);
+    return null;
+  }
+}
+
+/** Ceiling on component re-render capture (design/13 A2). Uses configured renderTimeoutMs. */
+function getCaptureTimeoutMs(): number {
+  return componentTimeoutMs;
+}
+
+/** A request-time capture: the payload and the wrappers baked into it. */
+interface CapturedPayload {
+  bytes: Uint8Array;
+  nested: NestedWrapperRender[];
+}
+
+/**
+ * Render a component in isolation and capture its flight payload bytes.
+ * Used for inline re-renders (tombstone/miss) and SWR background re-renders.
+ *
+ * The stream read is timeout-guarded and the reader is cancelled on
+ * expiry (design/13 A2, A3).
+ */
+async function captureComponentPayload(
+  id: string,
+  component: ServerComponent,
+  props: Record<string, unknown>,
+  options: PrebuiltComponentOptions
+): Promise<CapturedPayload> {
+  const { renderToReadableStream } = requireRscFunctions();
+  const element = createElement(component as RenderableComponent, props);
+  // Render inside a capture scope so nested cache.component wrappers render
+  // live (bake flat into this entry) per design/45 §Nesting Semantics. The
+  // scope is this capture's async context only — concurrent requests
+  // rendering the same or other wrapped components never see it (TIM-1536).
+  const capture = createCaptureScope(id, options, props);
+  // The first error the capture render hit, kept so a failed capture
+  // reports the component's own error rather than a stand-in.
+  let renderError: { error: unknown } | undefined;
+
+  // Key-discipline diagnostic (design/45 §Enforcement): proxy the ALS
+  // store to detect request-context reads during the capture render.
+  // The proxy is transparent — it never blocks or throws; it only observes.
+  const store = requestContextAls.getStore();
+  const discipline = store && shouldCheckKeyDiscipline(id) ? createKeyDisciplineProxy(store) : null;
+
+  const doCapture = (): Promise<Uint8Array> =>
+    capture.run(async () => {
+      // Outside the request's React.cache scope: this payload is stored
+      // cross-request (and the capture is singleflight-coalesced across
+      // requests), so it must not bake in values memoized for the request
+      // that happened to trigger it. Flight gives the capture its own
+      // per-render cache instead (TIM-1529).
+      const stream: ReadableStream<Uint8Array> = runOutsideReactCacheScope(() =>
+        renderToReadableStream(element, {
+          onError(error: unknown) {
+            renderError ??= { error };
+            return '';
+          },
+        })
+      );
+      const bytes = await readAllBytesWithDeadline(
+        stream,
+        getCaptureTimeoutMs(),
+        '[timber] component re-render capture'
+      );
+      // Error rows are never cached. The component's own error is what
+      // failed, so it is what the caller logs and reports.
+      if (renderError) throw renderError.error;
+      return bytes;
+    });
+
+  const bytes = discipline
+    ? await requestContextAls.run(discipline.proxy, doCapture)
+    : await doCapture();
+
+  if (discipline && discipline.accessedApis.size > 0) {
+    emitKeyDisciplineWarning(id, discipline.accessedApis);
+  }
+
+  return { bytes, nested: capture.nestedRenders() };
+}
+
+/**
+ * Store a captured entry in the overlay, then say which embedded
+ * components it clamps (design/45 §Nesting Semantics, TIM-1545). The
+ * warning follows the store: a capture that is discarded (aborted,
+ * invalidated mid-render, failed store) holds no clamped copy, and must
+ * not spend the pair's one warning.
+ */
+async function storeCapturedEntry(
+  id: string,
+  cacheKey: string,
+  captured: CapturedPayload,
+  options: PrebuiltComponentOptions,
+  tags: string[],
+  hasSeed: boolean
+): Promise<void> {
+  await storeOverlayEntry(id, cacheKey, captured.bytes, { ttl: options.ttl, tags, hasSeed });
+  warnNestingClamps({ id, options, tags }, captured.nested, warnedNestingPairs, (m) =>
+    console.warn(m)
+  );
+}
+
+/**
+ * Inline re-render: capture flight bytes, store in overlay, revive for
+ * the current request. Singleflight-coalesced by overlay key.
+ */
+async function inlineRerender(
+  id: string,
+  component: ServerComponent,
+  props: Record<string, unknown>,
+  cacheKey: string,
+  options: PrebuiltComponentOptions,
+  hasSeed: boolean,
+  outcome: string
+): Promise<{ element: unknown } | null> {
+  const tags = resolveTags(options, props);
+  const oKey = overlayKey(id, cacheKey);
+  const sfKey = `prebuilt:${id}:${cacheKey}\0${lastInvalidationEpochFor(oKey, tags)}`;
+
+  try {
+    const payload = await componentSingleflight.do(sfKey, async (signal) => {
+      const startEpoch = currentInvalidationEpoch();
+      const captured = await captureComponentPayload(id, component, props, options);
+      // Skip the store if aborted (singleflight timeout) or if the
+      // key/tags were invalidated while rendering (TIM-1028 guard).
+      if (
+        !signal.aborted &&
+        hasRuntimeLifetime(options) &&
+        !wasInvalidatedSince(startEpoch, oKey, tags)
+      ) {
+        await storeCapturedEntry(id, cacheKey, captured, options, tags, hasSeed);
+      }
+      return captured.bytes;
+    });
+    return await revivePayload(id, payload, outcome);
+  } catch (error) {
+    console.error(`[timber] cache.component re-render failed for "${id}" — ${outcome}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Snapshot the request context values needed for a background re-render.
+ * Creates a FRESH store with copied values — the original ALS store is
+ * not referenced after capture. The `Request` itself is shared, not
+ * copied: the re-render reports its failure against it.
+ */
+function snapshotRequestContext(store: RequestContextStore): RequestContextStore {
+  return {
+    request: store.request,
+    headers: new Headers(store.headers),
+    originalHeaders: new Headers(store.originalHeaders),
+    cookieHeader: store.cookieHeader,
+    parsedCookies: store.parsedCookies ? new Map(store.parsedCookies) : undefined,
+    searchParams: new URLSearchParams(store.searchParams),
+    searchString: store.searchString,
+    segmentParams: store.segmentParams ? { ...store.segmentParams } : undefined,
+    cookieJar: new Map(),
+    flushed: false,
+    mutableContext: false,
+  };
+}
+
+/**
+ * Kick off a background re-render via waitUntil. The re-render runs inside
+ * a fresh ALS scope with snapshotted request context.
+ */
+function backgroundRerender(
+  id: string,
+  component: ServerComponent,
+  props: Record<string, unknown>,
+  cacheKey: string,
+  options: PrebuiltComponentOptions,
+  hasSeed: boolean,
+  snapshot: RequestContextStore
+): void {
+  const waitUntil = getWaitUntil();
+  const tags = resolveTags(options, props);
+  const oKey = overlayKey(id, cacheKey);
+  const startEpoch = currentInvalidationEpoch();
+  const sfKey = `prebuilt-bg:${id}:${cacheKey}\0${lastInvalidationEpochFor(oKey, tags)}`;
+
+  const work = requestContextAls.run(snapshot, () =>
+    componentSingleflight
+      // The stale payload already answered the request, so nothing else sees
+      // a failure here: logged and reported once per flight. Inline re-render
+      // and revive failures are only logged: a live render answers instead.
+      .do(sfKey, (signal) =>
+        runBackgroundFlight(
+          signal,
+          async () => {
+            const captured = await captureComponentPayload(id, component, props, options);
+            if (!signal.aborted && !wasInvalidatedSince(startEpoch, oKey, tags)) {
+              await storeCapturedEntry(id, cacheKey, captured, options, tags, hasSeed);
+            }
+          },
+          (error) =>
+            console.error(
+              `[timber] cache.component background re-render failed for "${id}":`,
+              error
+            )
+        )
+      )
+      // runBackgroundFlight never rejects; only the singleflight timeout,
+      // which it already reported, can reject the flight.
+      .catch(() => {})
+  );
+
+  if (waitUntil) {
+    waitUntil(work);
+  } else if (!warnedNoWaitUntil) {
+    warnedNoWaitUntil = true;
+    console.warn(
+      '[timber] cache.component SWR background re-render has no waitUntil — ' +
+        'the re-render may be killed when the handler returns on serverless platforms. ' +
+        'Ensure the adapter wires runWithWaitUntil().'
+    );
+  }
+}
+
+/**
+ * Try to serve this render from the prebuilt cache: overlay → artifact →
+ * live render. Handles ISR (SWR, tombstones, re-renders) per design/45.
+ *
+ * Null on any miss — the caller renders live.
+ */
+async function tryRevivePayload(
+  id: string,
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>,
+  keyPropsOverride?: Record<string, unknown>
+): Promise<{ element: unknown } | null> {
+  const hasSource = hasPrebuiltPayloadSource();
+  const hasRuntime = hasRuntimeLifetime(options);
+  if (!hasSource && !hasRuntime) return null;
+
+  const store = requestContextAls.getStore();
+  if (!store) return null;
+  const paramIndep = options.prerender ? await isParamIndependent(id) : false;
+  const keyParams = paramIndep ? {} : resolveKeyParams(store);
+  if (keyParams === null) return null;
+
+  // Strip `children` from the cache key ONLY when it is the framework-
+  // injected children slot outlet (<SlotOutlet slot="children" />).
+  // Layout components receive this as children — a deterministic client
+  // reference that is the same on every request, so it should not vary
+  // the key. User-provided React element children are NOT stripped —
+  // they remain unkeyable so the component renders live, which is
+  // correct: the cache cannot distinguish <A> from <B>.
+  // See design/45-cache-lifetimes.md §Layout Propagation, TIM-1181.
+  // keyPropsOverride = slot component (TIM-1173): the wrapper already
+  // split out slot props; only data props participate in the key. The
+  // children outlet strip applies to EITHER source — a cached layout
+  // declaring only named slots (slots: ['modal']) still receives the
+  // framework-injected children outlet in its data props, and it must not
+  // unkey the render there any more than on the non-slot path (codex P2
+  // on PR #890).
+  const allProps = (props ?? {}) as Record<string, unknown>;
+  const cacheKey = computeComponentCacheKey(
+    withoutChildrenOutlet(keyPropsOverride ?? allProps),
+    keyParams
+  );
+  if (cacheKey === null) return null;
+
+  const outcome =
+    options.fallbackOnMissingSegmentParams === false
+      ? 'failing the render (fallbackOnMissingSegmentParams: false)'
+      : 'rendering dynamically';
+
+  const registration = registry.get(id);
+  const component = registration?.component;
+
+  // ─── Step 1: Check overlay (CacheHandler) ─────────────────────────
+  if (hasRuntime) {
+    const overlayResult = await lookupOverlay(id, cacheKey);
+    if (overlayResult) {
+      const overlayHasSeed = overlayResult.record?.s ?? false;
+      if (overlayResult.kind === 'tombstone') {
+        if (component) {
+          return await inlineRerender(id, component, props, cacheKey, options, true, outcome);
+        }
+        return null;
+      }
+      if (overlayResult.kind === 'fresh' && overlayResult.payload) {
+        return await revivePayload(id, overlayResult.payload, outcome);
+      }
+      if (overlayResult.kind === 'stale' && overlayResult.payload) {
+        if (options.staleWhileRevalidate && component) {
+          backgroundRerender(
+            id,
+            component,
+            props,
+            cacheKey,
+            options,
+            overlayHasSeed,
+            snapshotRequestContext(store)
+          );
+          return await revivePayload(id, overlayResult.payload, outcome);
+        }
+        if (component) {
+          return await inlineRerender(
+            id,
+            component,
+            props,
+            cacheKey,
+            options,
+            overlayHasSeed,
+            outcome
+          );
+        }
+        return null;
+      }
+    }
+  }
+
+  // ─── Step 2: Check build artifact ─────────────────────────────────
+  if (hasSource) {
+    const artifactPayload = await lookupPrebuiltPayload(id, cacheKey);
+    if (artifactPayload !== null) {
+      // Check seed freshness when the component has a TTL.
+      if (options.ttl !== undefined) {
+        const entry = await getManifestEntry(id, cacheKey);
+        const buildTs = entry?.buildTimestamp ?? 0;
+        const seedAge = (Date.now() - buildTs) / 1000;
+        if (seedAge > options.ttl) {
+          // Stale seed
+          if (options.staleWhileRevalidate && component) {
+            backgroundRerender(
+              id,
+              component,
+              props,
+              cacheKey,
+              options,
+              true,
+              snapshotRequestContext(store)
+            );
+            return await revivePayload(id, artifactPayload, outcome);
+          }
+          if (component) {
+            return await inlineRerender(id, component, props, cacheKey, options, true, outcome);
+          }
+          // No component in registry — can't re-render; fall through to
+          // live render via the wrapper (design/45 step 3).
+          return null;
+        }
+      }
+      // Fresh seed (or no TTL — immutable until redeploy)
+      return await revivePayload(id, artifactPayload, outcome);
+    }
+
+    // Manifest miss
+    if (options.prerender) {
+      console.warn(
+        `[timber] cache.component cache miss: "${id}" with params ${JSON.stringify(
+          store.segmentParams ?? {}
+        )} — ${outcome}`
+      );
+    }
+  }
+
+  // ─── Step 3: Full miss with runtime lifetime — inline re-render ───
+  // Skip when fallbackOnMissingSegmentParams is false — that option means
+  // "only prebuilt content", so an unenumerated miss must throw (the
+  // wrapper handles the throw after we return null).
+  if (hasRuntime && component && options.fallbackOnMissingSegmentParams !== false) {
+    return await inlineRerender(id, component, props, cacheKey, options, false, outcome);
+  }
+
+  return null;
+}
+
+/**
+ * Production wrapper injected by the timber-prebuilt transform. Registers
+ * the component under its stable ID and returns a wrapper component that
+ * either revives the cached payload (hit) or renders the original
+ * component live (miss).
+ */
+export function __prebuilt<C extends ServerComponent>(
+  id: string,
+  component: C,
+  options: PrebuiltComponentOptions = {}
+): C {
+  // Slot resolution first, then option normalization in its terms
+  // (TIM-1173). ACTIVE slots are runtime-tier only — the build cannot
+  // enumerate slot content — so `prerender` is stripped (loudly); the
+  // capture pass reads the registry's normalized options, so stripping
+  // here also keeps the build from capturing slot components. DISABLED
+  // declarations (malformed shape, missing lifetime — warned inside
+  // resolveSlotNames) fall back wholesale to non-slot semantics: `slots`
+  // is stripped so no downstream consumer (resolveTags' slot filtering,
+  // the registry, the capture pass) ever sees the raw value, and every
+  // other option — including `prerender` — keeps its normal meaning
+  // (codex P2s on PR #890).
+  const resolution = resolveSlotNames(id, options);
+  const slots = resolution.kind === 'active' ? resolution.slots : null;
+  if (resolution.kind === 'active' && options.prerender) {
+    console.warn(
+      `[timber] cache.component "${id}": slots are runtime-tier only — ` +
+        `prerender is ignored (the build cannot enumerate slot content). ` +
+        `Use ttl/tags for the cache lifetime.`
+    );
+    options = { ...options, prerender: undefined };
+  }
+  if (resolution.kind === 'disabled') {
+    options = { ...options, slots: undefined };
+  }
+  registry.set(id, { id, component, options });
+
+  const wrapper = async (props: Parameters<C>[0]) => {
+    // Report this render to the enclosing capture, if any — cycle
+    // detection (throws) and nesting-clamp warnings (design/45 §Nesting
+    // Semantics). Outside a capture this is a single store lookup.
+    noteWrapperRender(id, options, props as Record<string, unknown>);
+    if (isCaptureActive()) {
+      // Nested wrapper inside a capture: render live so the subtree
+      // bakes flat into the enclosing entry (design/45 §Nesting).
+      // This deliberately bypasses fallbackOnMissingSegmentParams: false —
+      // that option means "never serve non-prebuilt content", and a
+      // capture render IS the cached content; throwing here would
+      // spuriously fail the outer entry (codex P2 on PR #836).
+      return createElement(component as RenderableComponent, props as Record<string, unknown>);
+    }
+
+    const revived = slots
+      ? await tryReviveSlotShell(id, options, slots, props as Record<string, unknown>)
+      : await tryRevivePayload(id, options, props as Record<string, unknown>);
+    if (revived !== null) {
+      return revived.element;
+    }
+    if (options.fallbackOnMissingSegmentParams === false) {
+      throw new Error(
+        `[timber] cache.component "${id}": no prebuilt payload for the current params and fallbackOnMissingSegmentParams is false`
+      );
+    }
+    // Return an ELEMENT — React invokes the component itself, with its
+    // render dispatcher active. Calling component(props) here would run
+    // it after this wrapper's await, outside a dispatcher frame, breaking
+    // sync server components that call use() (codex review on PR #835).
+    return createElement(component as RenderableComponent, props as Record<string, unknown>);
+  };
+  Object.defineProperty(wrapper, 'name', { value: `Prebuilt(${id})` });
+  // Double cast, deliberately: C's return type may be narrower than the
+  // wrapper's (a sync component wrapped by an async function, or a revived
+  // subtree in place of C's exact JSX type). Callers only ever *render*
+  // the result — React treats any component returning ReactNode-compatible
+  // values identically — so widening through `unknown` is safe here and a
+  // direct cast would be rejected by the compiler for exactly the
+  // difference we intend.
+  return wrapper as unknown as C;
+}
+
+/** Look up a registration by stable component ID. */
+export function getPrebuiltRegistration(id: string): PrebuiltRegistration | undefined {
+  return registry.get(id);
+}
+
+/** All registrations, for the post-build capture pass (TIM-1119). */
+export function getPrebuiltRegistry(): ReadonlyMap<string, PrebuiltRegistration> {
+  return registry;
+}
+
+/**
+ * Dev-mode wrapper injected by the timber-prebuilt transform: a no-op that
+ * renders the component dynamically on every request, logging once per
+ * component on first render so the production behavior difference is visible.
+ * See design/44 §Dev Mode.
+ */
+export function __prebuiltDev<C extends ServerComponent>(
+  name: string,
+  component: C,
+  options: PrebuiltComponentOptions = {}
+): C {
+  // Dev/prod parity for slot components: in production a slot component
+  // ALWAYS receives a SlotOutlet element for each declared slot (never the
+  // live children), so a component that introspects a slot prop would
+  // behave differently between dev and prod if dev passed children
+  // through. Dev renders the same tree shape — outlets in the props,
+  // live values via SlotsProvider — just without any caching. The same
+  // validation applies (including the lifetime requirement): slots are
+  // active in dev exactly when they would be active in production.
+  const resolution = resolveSlotNames(name, options);
+  const slots = resolution.kind === 'active' ? resolution.slots : null;
+  let logged = false;
+  const wrapper = (props: Parameters<C>[0]) => {
+    if (!logged) {
+      logged = true;
+      console.log(`[timber] cache.component: "${name}" — rendering dynamically (dev mode)`);
+    }
+    if (slots) {
+      const render = prepareSlotRender(props as Record<string, unknown>, slots);
+      // Substitute outlets only when PRODUCTION would: top-level props
+      // splittable AND the data props keyable. Unkeyable inputs render
+      // live with the original props there, so dev must too (parity —
+      // codex P2 on PR #890).
+      if (render !== null && isSlotRenderKeyable(render.dataProps)) {
+        return wrapInSlotsProvider(
+          createElement(component as RenderableComponent, render.shellProps),
+          render.slotValues
+        );
+      }
+    }
+    // Element, not a direct call — same dispatcher reasoning as the
+    // production wrapper's live fallback.
+    return createElement(component as RenderableComponent, props as Record<string, unknown>);
+  };
+  return wrapper as C;
+}