@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/server/port-resolution.ts

@@ -0,0 +1,215 @@
+/**
+ * Port resolution for the dev server, Vite preview, and the Node
+ * production preview server.
+ *
+ * Behavior (see TIM-842):
+ *
+ *   1. Default port is **3000** for both dev and prod.
+ *   2. If the user did NOT set an explicit port, auto-bump from 3000
+ *      until a free port is found (3000 → 3001 → 3002 → …).
+ *   3. If the user DID set an explicit port (via `--port`, `PORT` env
+ *      var, or `vite.config.ts` `server.port`), use it as-is and let
+ *      the bind fail loudly on conflict (`strictPort: true`).
+ *
+ * The port-bump probe is performed by binding the **actual** server
+ * (e.g. the dev holding server) — not a throwaway probe — so there is
+ * no time-of-check / time-of-use race between probing and listening.
+ *
+ * Design doc: 21-dev-server.md §"Default Port and Auto-Bump".
+ */
+
+/** Default port used by `timber dev` and `timber preview`. */
+export const DEFAULT_PORT = 3000;
+
+/**
+ * A function that attempts to bind to a given port.
+ *
+ * Resolves with the bound port on success. Rejects with an error
+ * (typically with `code === 'EADDRINUSE'`) on failure.
+ */
+export type ListenFn = (port: number) => Promise<number>;
+
+// ── Pure resolution ────────────────────────────────────────────────────
+
+export interface ResolvePortInput {
+  /**
+   * Port read from `vite.config.ts` `server.port` or the `--port` CLI
+   * flag (Vite merges `--port` into `userConfig.server.port` before
+   * plugins see it).
+   */
+  configPort?: number | undefined;
+  /** Raw value of `process.env.PORT`. */
+  envPort?: string | undefined;
+  /** Default port to use when neither `configPort` nor `envPort` is set. */
+  defaultPort?: number;
+}
+
+export interface ResolvedPortInput {
+  /** Port to start binding from. */
+  port: number;
+  /**
+   * `true` if the port came from an explicit user override (config or
+   * env). When `true`, callers must NOT auto-bump and must surface
+   * `EADDRINUSE` to the user.
+   */
+  explicit: boolean;
+}
+
+/**
+ * Pure: compute the starting port from config / env / defaults.
+ *
+ * Performs no I/O — pair with {@link bindWithBump} to actually listen.
+ */
+export function resolveStartPort(input: ResolvePortInput): ResolvedPortInput {
+  const defaultPort = input.defaultPort ?? DEFAULT_PORT;
+
+  // `configPort` wins over `envPort`. This matches Vite's behavior:
+  // `vite --port 4000` overrides `PORT=5000` in the environment.
+  if (typeof input.configPort === 'number' && Number.isFinite(input.configPort)) {
+    return { port: input.configPort, explicit: true };
+  }
+
+  if (input.envPort != null && input.envPort !== '') {
+    const parsed = Number(input.envPort);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return { port: parsed, explicit: true };
+    }
+  }
+
+  return { port: defaultPort, explicit: false };
+}
+
+// ── Bind with auto-bump ────────────────────────────────────────────────
+
+export interface BindWithBumpOptions {
+  /** First port to attempt. */
+  startPort: number;
+  /**
+   * If `true`, increment the port and retry on `EADDRINUSE`. If
+   * `false`, attempt once and let the error propagate.
+   */
+  autoBump: boolean;
+  /** Maximum number of port attempts when `autoBump` is `true`. */
+  maxAttempts?: number;
+}
+
+export interface BindWithBumpResult {
+  /** Port that was actually bound. */
+  port: number;
+  /** `true` if the bound port differs from `startPort`. */
+  bumped: boolean;
+}
+
+/**
+ * Bind a server starting at `startPort`, optionally bumping the port
+ * on `EADDRINUSE` until a free one is found.
+ *
+ * Use this with the actual server you intend to keep listening (e.g.
+ * the dev holding server). Pairing the probe with the real listen
+ * eliminates the TOCTOU race that a throwaway probe would introduce.
+ */
+export async function bindWithBump(
+  listen: ListenFn,
+  options: BindWithBumpOptions
+): Promise<BindWithBumpResult> {
+  const maxAttempts = options.autoBump ? (options.maxAttempts ?? 100) : 1;
+  let lastErr: unknown = null;
+
+  for (let i = 0; i < maxAttempts; i++) {
+    const port = options.startPort + i;
+    try {
+      const bound = await listen(port);
+      return { port: bound, bumped: i > 0 };
+    } catch (err) {
+      lastErr = err;
+      // Only retry on EADDRINUSE — other errors (EACCES, etc.) are
+      // permanent and must surface immediately.
+      if (!isAddrInUse(err)) throw err;
+    }
+  }
+
+  throw lastErr ?? new Error(`Could not bind to a free port starting at ${options.startPort}`);
+}
+
+/** True if `err` is a Node `EADDRINUSE` error from `server.listen()`. */
+export function isAddrInUse(err: unknown): boolean {
+  return (
+    typeof err === 'object' && err !== null && (err as { code?: string }).code === 'EADDRINUSE'
+  );
+}
+
+// ── High-level helper used by the rootSync plugin ────────────────────
+
+export interface StartDevServerPortInput {
+  /** Resolved port from `userConfig.server?.port` (or `--port`), or undefined. */
+  configPort: number | undefined;
+  /** Raw `process.env.PORT` value. */
+  envPort: string | undefined;
+  /** ListenFn for the holding server (or any pre-bind probe target). */
+  listen: ListenFn;
+  /** Logger — defaults to `console`. Injected for tests. */
+  log?: (msg: string) => void;
+  warn?: (msg: string) => void;
+}
+
+export interface StartDevServerPortResult {
+  /** Port chosen for both the holding server and Vite's dev server. */
+  port: number;
+  /** True if the user explicitly set the port (=> Vite must `strictPort: true`). */
+  explicit: boolean;
+  /** True if the holding server actually bound the port. */
+  bound: boolean;
+}
+
+/**
+ * Run the full dev-server port resolution + holding-server bind sequence.
+ *
+ * Resolves the port from config / env / default, attempts to bind the
+ * holding server (auto-bumping when the port came from the default),
+ * and logs the chosen URL. On a clean failure for an explicit port, it
+ * warns and falls back to the requested port so Vite can surface the
+ * conflict via `strictPort: true`.
+ *
+ * Extracted from `index.ts` so the rootSync `config()` hook stays
+ * focused on plugin assembly.
+ */
+export async function startDevServerPort(
+  input: StartDevServerPortInput
+): Promise<StartDevServerPortResult> {
+  const log = input.log ?? ((msg: string) => console.log(msg));
+  const warn = input.warn ?? ((msg: string) => console.warn(msg));
+
+  const start = resolveStartPort({
+    configPort: input.configPort,
+    envPort: input.envPort,
+    defaultPort: DEFAULT_PORT,
+  });
+
+  try {
+    const result = await bindWithBump(input.listen, {
+      startPort: start.port,
+      autoBump: !start.explicit,
+    });
+    if (result.bumped) {
+      log(`\n  \x1b[33m[timber]\x1b[0m Port ${start.port} in use, using ${result.port}\n`);
+    }
+    log(
+      `\n  \x1b[2m\u{1FAB5} timber.js dev server starting at\x1b[0m ` +
+        `\x1b[36mhttp://localhost:${result.port}\x1b[0m\n`
+    );
+    return { port: result.port, explicit: start.explicit, bound: true };
+  } catch (err) {
+    // Holding server failed to bind. For explicit ports we leave the
+    // bound state false and let Vite fail loudly via strictPort: true.
+    // For implicit ports this is essentially unreachable (auto-bump
+    // tries 100 ports), but if we hit it we still want Vite to surface
+    // the error.
+    if (start.explicit && isAddrInUse(err)) {
+      warn(
+        `\n  \x1b[33m[timber]\x1b[0m Port ${start.port} is already in use. ` +
+          `Set PORT (or remove the override) to pick another port.\n`
+      );
+    }
+    return { port: start.port, explicit: start.explicit, bound: false };
+  }
+}

package/src/server/prebuilt/cache-key.ts

@@ -0,0 +1,299 @@
+/**
+ * Component cache-key hashing for prebuilt (cache.component) entries.
+ *
+ * Key: `sha256(canonicalJson({ props, params })).slice(0, 16)` — see
+ * design/44-render-at-build-time.md §Cache Key. Both the request-time
+ * lookup (prebuilt-runtime.ts) and the post-build capture pass (TIM-1119)
+ * MUST use this exact function, or build artifacts become unaddressable.
+ *
+ * THE IDENTITY CONTRACT (design/44 §Cache Key): cache identity is **JSON
+ * value semantics** — two inputs are the same entry iff they are the same
+ * JSON value. This is an ALLOWLIST, not a denylist: a value participates
+ * in caching iff it is plain JSON data — null, boolean, finite number,
+ * string, dense array, or a plain `Object.prototype` object with only
+ * enumerable string-keyed data properties — plus `undefined` and `-0`,
+ * which hash as distinct sentinels because flight preserves them. Every
+ * value outside that domain (functions, symbols, bigints, accessors,
+ * hidden or symbol-keyed properties, non-`Object.prototype` prototypes
+ * including null, aliased references, sparse arrays, cycles, non-finite
+ * numbers) is UNKEYABLE by definition: `computeComponentCacheKey` returns
+ * null and the caller renders live — slower, never wrong.
+ *
+ * The line between rejected and declared-out-of-domain: values are
+ * REJECTED when the JSON projection itself would be ambiguous or lossy
+ * (hidden/symbol/non-enumerable properties, accessors, exotic
+ * prototypes). Observable state that leaves the projection intact — key
+ * order, reference identity, descriptor metadata (writable/configurable,
+ * frozen/sealed/extensible), proxy behavior — is DECLARED outside
+ * cache.component's supported input domain rather than rejected:
+ * key-order insensitivity is required for determinism, and rejecting
+ * frozen objects would unkey ubiquitous legitimate inputs
+ * (Object.freeze'd config props) to defend against components that
+ * render differently based on property attributes.
+ *
+ * Two hard rules for this walk itself: it must be TOTAL (never throw
+ * anything but UnkeyableValueError) and SIDE-EFFECT-FREE (descriptor
+ * reads only; never invoke user code such as getters).
+ *
+ * Object keys sort recursively so `{a, b}` and `{b, a}` hash identically
+ * (design/13-security.md checklist #14 — cache key determinism; key order
+ * is deliberately NOT part of identity).
+ */
+
+import { createHash } from 'node:crypto';
+import type { CoercedParams } from '../../shared/param-value.js';
+
+class UnkeyableValueError extends Error {}
+
+function canonicalize(value: unknown, seen: Set<object>): string {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value);
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      if (!Number.isFinite(value)) throw new UnkeyableValueError('non-finite number');
+      // -0 is distinct: flight preserves it ("$-0"), and String(-0) would
+      // collapse it to "0" (codex review round 4 on PR #835).
+      return Object.is(value, -0) ? '-0' : String(value);
+    case 'object':
+      break;
+    case 'undefined':
+      // Distinct sentinel, NOT collapsed to null or omitted: flight
+      // serialization preserves `undefined` ("$undefined"), so a component
+      // can render [undefined] differently from [null] and {a: undefined}
+      // differently from {}. Bare `undefined` cannot collide with any
+      // other canonical output (strings are always quoted). Codex review
+      // round 3 on PR #835.
+      return 'undefined';
+    default:
+      // function, symbol, bigint
+      throw new UnkeyableValueError(`unsupported type: ${typeof value}`);
+  }
+  const obj = value as object;
+  // Any REPEATED reference — cycle or alias — is unkeyable. Flight
+  // preserves reference identity (the second occurrence serializes as a
+  // row reference), so a component can observe `props.a === props.b`;
+  // hashing an aliased shape identically to a structurally-equal
+  // non-aliased one could splice the wrong subtree (codex review round 5
+  // on PR #835). Objects are never removed from `seen`: revisiting one
+  // anywhere in the walk throws.
+  if (seen.has(obj)) throw new UnkeyableValueError('repeated object reference (cycle or alias)');
+  seen.add(obj);
+  // Hidden own properties — symbol keys and non-enumerable props — are
+  // readable by a live-rendered component but invisible to this walk, so
+  // two observably different inputs would collide on one key (codex
+  // review on PR #835). Unkeyable.
+  if (Object.getOwnPropertySymbols(obj).length > 0) {
+    throw new UnkeyableValueError('symbol-keyed property');
+  }
+  {
+    if (Array.isArray(obj)) {
+      // Dense-array own names are exactly ['0'..'n-1', 'length'] — anything
+      // else is a custom expando property this walk would silently drop.
+      if (Object.getOwnPropertyNames(obj).length !== obj.length + 1) {
+        throw new UnkeyableValueError('non-index array property');
+      }
+      const parts: string[] = [];
+      for (let i = 0; i < obj.length; i++) {
+        // Sparse holes are unkeyable: a server component receiving the
+        // original array can observe `i in arr`, which no canonical form
+        // survives faithfully. (An explicit undefined element is fine —
+        // handled by the sentinel above.)
+        const desc = Object.getOwnPropertyDescriptor(obj, i);
+        if (desc === undefined) throw new UnkeyableValueError('sparse array hole');
+        // Accessors are rejected WITHOUT invoking them — a getter may
+        // throw or side-effect, and the key walk must never alter a
+        // render (codex review on PR #835).
+        if (desc.get !== undefined || desc.set !== undefined) {
+          throw new UnkeyableValueError('accessor property');
+        }
+        // Non-enumerable elements are invisible to Object.keys/spread/
+        // JSON.stringify — the JSON projection would be ambiguous, same
+        // rule as the object branch's keys-vs-names check.
+        if (!desc.enumerable) throw new UnkeyableValueError('non-enumerable array element');
+        parts.push(canonicalize(desc.value, seen));
+      }
+      return '[' + parts.join(',') + ']';
+    }
+    // Allowlist: exactly Object.prototype. Dates, Maps, class instances —
+    // and null-prototype objects, which a component can distinguish from
+    // literals via Object.getPrototypeOf — are all outside the JSON
+    // domain.
+    if (Object.getPrototypeOf(obj) !== Object.prototype) {
+      throw new UnkeyableValueError('non-plain object');
+    }
+    const keys = Object.keys(obj).sort();
+    if (keys.length !== Object.getOwnPropertyNames(obj).length) {
+      throw new UnkeyableValueError('non-enumerable property');
+    }
+    const parts: string[] = [];
+    for (const key of keys) {
+      // Descriptor read, not property read: accessors are rejected WITHOUT
+      // invoking them — a getter may throw or side-effect, and the key
+      // walk must never alter a render (codex review on PR #835).
+      const desc = Object.getOwnPropertyDescriptor(obj, key)!;
+      if (desc.get !== undefined || desc.set !== undefined) {
+        throw new UnkeyableValueError('accessor property');
+      }
+      parts.push(JSON.stringify(key) + ':' + canonicalize(desc.value, seen));
+    }
+    return '{' + parts.join(',') + '}';
+  }
+}
+
+/**
+ * Canonicalize a single value, or null if it is unkeyable. The ONE
+ * definition of "faithfully comparable" — every prebuilt code path that
+ * needs value equality (cache keys, slot-param divergence) goes through
+ * this, so the unkeyable rules (accessors, hidden props, aliases,
+ * bigints, …) live in exactly one place.
+ */
+export function tryCanonicalize(value: unknown): string | null {
+  try {
+    return canonicalize(value, new Set());
+  } catch (error) {
+    return toUnkeyable(error);
+  }
+}
+
+/**
+ * Totality by construction: ANY throw from the walk means the input is
+ * outside the keyable domain. The walk touches only user-controlled
+ * values through reflection ops — and a Proxy trap can throw arbitrary
+ * errors from any of them (codex review on PR #835) — so converting only
+ * UnkeyableValueError would let hostile/exotic inputs abort a render
+ * that plain live rendering would have served fine. Unexpected error
+ * types are logged for visibility (they would indicate either a proxy
+ * trap or a canonicalizer bug) but still degrade to unkeyable.
+ */
+function toUnkeyable(error: unknown): null {
+  if (!(error instanceof UnkeyableValueError)) {
+    console.error(
+      '[timber] cache key canonicalization threw — treating input as unkeyable:',
+      error
+    );
+  }
+  return null;
+}
+
+/**
+ * Split a props record into data props (participate in the cache key) and
+ * slot values (React-element holes, excluded from the key) per the
+ * component's declared `slots` option (TIM-1173).
+ *
+ * Every DECLARED slot lands in `slotValues` — present or not — because the
+ * capture render always injects a SlotOutlet placeholder for each declared
+ * slot: the cached shell is identical whether the caller passed the slot
+ * or omitted it, so slot presence must not vary the key. `dataProps` is
+ * everything else and is what gets hashed.
+ *
+ * Returns null when the props OBJECT itself is outside the identity
+ * contract at the top level — accessors, symbol-keyed or non-enumerable
+ * properties, or a non-`Object.prototype` prototype. Splitting such an
+ * object would normalize away observable state (and reading an accessor
+ * would invoke user code, which this walk must never do) BEFORE
+ * `computeComponentCacheKey` gets the chance to reject it — a cached
+ * shell could then be served for inputs a live render distinguishes.
+ * Null means unkeyable: the caller renders live with the original props.
+ * The walk is descriptor-reads only; getters are never invoked. Nested
+ * data-prop values still face the full allowlist when hashed.
+ */
+/** Create an own enumerable data property — safe for keys like `__proto__`. */
+function defineOwn(target: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  });
+}
+
+export function splitSlotProps(
+  props: Record<string, unknown>,
+  slots: readonly string[]
+): { dataProps: Record<string, unknown>; slotValues: Record<string, unknown> } | null {
+  // TOTAL, like tryCanonicalize: the reflection ops below run against a
+  // user-controlled object, and a Proxy trap (getPrototypeOf, ownKeys,
+  // getOwnPropertyDescriptor) can throw arbitrarily — that must degrade
+  // to unkeyable (live render), not abort the request. toUnkeyable logs
+  // the unexpected throw for visibility. Codex P2 on PR #890.
+  try {
+    if (Object.getPrototypeOf(props) !== Object.prototype) return null;
+    if (Object.getOwnPropertySymbols(props).length > 0) return null;
+    const slotSet = new Set(slots);
+    const dataProps: Record<string, unknown> = {};
+    const slotValues: Record<string, unknown> = {};
+    // Own-property defines + Object.hasOwn, never assignment or `in`: a
+    // prop/slot legitimately named `__proto__` must land as an own data
+    // property (assignment would mutate the map's prototype), and an absent
+    // slot named `toString`/`constructor` must not read as present through
+    // the prototype chain (the provider would then expose the inherited
+    // function instead of undefined). Codex P2 on PR #890.
+    for (const key of Object.getOwnPropertyNames(props)) {
+      const desc = Object.getOwnPropertyDescriptor(props, key);
+      if (
+        desc === undefined ||
+        desc.get !== undefined ||
+        desc.set !== undefined ||
+        !desc.enumerable
+      ) {
+        return null;
+      }
+      defineOwn(slotSet.has(key) ? slotValues : dataProps, key, desc.value);
+    }
+    for (const slot of slotSet) {
+      if (!Object.hasOwn(slotValues, slot)) defineOwn(slotValues, slot, undefined);
+    }
+    return { dataProps, slotValues };
+  } catch (error) {
+    return toUnkeyable(error);
+  }
+}
+
+/**
+ * Compute the cache-entry hash for a component render:
+ * `sha256({props, params}).slice(0, 16)` over canonical JSON.
+ *
+ * Returns null when props (or params) contain unkeyable values — the
+ * caller must fall back to dynamic rendering.
+ */
+export function computeComponentCacheKey(
+  props: Record<string, unknown>,
+  params: CoercedParams
+): string | null {
+  let canonical: string;
+  try {
+    // One shared `seen` set: an object aliased between params and props is
+    // just as observable as one aliased within either.
+    const seen = new Set<object>();
+    // The params RECORD is framework-produced: coerceSegmentParams builds
+    // it with Object.create(null) as a prototype-pollution defense
+    // (design/13 checklist #36b), uniformly on every request — its
+    // prototype is an implementation detail, not user-observable input
+    // variation, so the record is normalized to a plain object before the
+    // walk (codex P1 on PR #835: rejecting it made every real request
+    // unkeyable). Nested VALUES still face the full allowlist, and user
+    // props stay strict — a null-prototype prop object remains unkeyable.
+    canonical =
+      '{"params":' +
+      canonicalize({ ...params }, seen) +
+      ',"props":' +
+      canonicalize(props, seen) +
+      '}';
+  } catch (error) {
+    return toUnkeyable(error);
+  }
+  // NOTE(hash choice — DECIDED, TIM-1119): 64 bits of truncated sha256 is
+  // the SHIPPED artifact format; the capture pass writes .flight files and
+  // manifest entries named by this hash, so changing the width is now a
+  // build-artifact format break. The width is adequate: entries are
+  // namespaced per component AND per deploy, so birthday odds need ~2^32
+  // entries under ONE component to matter, and design/13 #24 already
+  // accepts 64-bit non-crypto FNV-1a for data-cache keys on the same
+  // namespacing argument. Only revisit (with a format migration) if the
+  // phase-3 runtime tier ever stores attacker-influenced keys more
+  // aggressively.
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}

package/src/server/prebuilt/capture-state.ts

@@ -0,0 +1,89 @@
+/**
+ * Build-time capture state — the channel between the post-build capture
+ * pass (server/prebuilt-builder.ts) and the `__prebuilt` wrapper
+ * (server/prebuilt-runtime.ts).
+ *
+ * During capture, a wrapped component's subtree may render OTHER wrapped
+ * components. With no payload source registered (the capture pass runs
+ * before artifacts exist), those inner wrappers render live and their
+ * output is baked flat into the outer entry — the nesting clamp of
+ * design/45-cache-lifetimes.md §Nesting Semantics (TIM-1136). The capture
+ * pass is the designated detection point for that clamp, so the wrapper
+ * reports every render that happens while a capture is active:
+ *
+ * - **Cycle**: the inner wrapper IS the component being captured (directly
+ *   or transitively — the transitive case still renders the outer's own
+ *   wrapper, so the identity check catches both). Left alone this recurses
+ *   until the render times out; instead the wrapper throws
+ *   `PrebuiltCaptureCycleError`, failing that entry with an error naming
+ *   the cycle while the build continues (doc 44 skip-and-report policy).
+ * - **Nesting**: any other wrapper render is recorded as an (outer, inner)
+ *   pair. The builder warns after the entry completes when the inner
+ *   declares a refresh channel the outer cannot honor (doc 45 clamp rule).
+ *
+ * Captures run strictly sequentially (one entry at a time), so a single
+ * module-level slot is sufficient — there is never a second active capture
+ * to confuse renders between. At request time `active` is null and
+ * `noteWrapperRender` is a single null-check.
+ */
+
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.js';
+
+/** A wrapped component that rendered inside an active capture. */
+export interface NestedWrapperRender {
+  innerId: string;
+  options: PrebuiltComponentOptions;
+}
+
+/** Thrown by the wrapper when a capture renders its own component. */
+export class PrebuiltCaptureCycleError extends Error {
+  constructor(componentId: string) {
+    super(
+      `[timber] cache.component "${componentId}" renders itself (directly or through ` +
+        `other components) — prerendering it would recurse forever. Remove the cycle ` +
+        `or drop { prerender: true } on this component.`
+    );
+    this.name = 'PrebuiltCaptureCycleError';
+  }
+}
+
+let active: { outerId: string; nested: Map<string, PrebuiltComponentOptions> } | null = null;
+
+/**
+ * Mark a capture as active. The builder calls this immediately before
+ * rendering an entry and MUST pair it with `endCapture()` in a finally.
+ */
+export function beginCapture(outerId: string): void {
+  active = { outerId, nested: new Map() };
+}
+
+/**
+ * End the active capture and return the wrapped components that rendered
+ * inside it (first options object wins per inner ID).
+ */
+export function endCapture(): NestedWrapperRender[] {
+  const nested = active?.nested;
+  active = null;
+  if (!nested) return [];
+  return Array.from(nested, ([innerId, options]) => ({ innerId, options }));
+}
+
+/** Whether a build-time capture is currently rendering. */
+export function isCaptureActive(): boolean {
+  return active !== null;
+}
+
+/**
+ * Called by the `__prebuilt` wrapper on every render. No-op unless a
+ * capture is active. Throws `PrebuiltCaptureCycleError` when the wrapper
+ * belongs to the component currently being captured.
+ */
+export function noteWrapperRender(innerId: string, options: PrebuiltComponentOptions): void {
+  if (active === null) return;
+  if (innerId === active.outerId) {
+    throw new PrebuiltCaptureCycleError(innerId);
+  }
+  if (!active.nested.has(innerId)) {
+    active.nested.set(innerId, options);
+  }
+}

package/src/server/prebuilt/key-discipline.ts

@@ -0,0 +1,53 @@
+/**
+ * Key-discipline diagnostic for cache.component (design/45 §Enforcement).
+ *
+ * Runtime-tier cached components MAY read request context, but the cache
+ * key is computed from props and segment params only — request-derived
+ * values in cached output are the data-leak danger zone (design/06
+ * security note). During a capture render the ALS store is wrapped in a
+ * transparent observing proxy; any request-context read produces a
+ * once-per-component warning.
+ */
+
+import type { RequestContextStore } from '../als-registry.js';
+
+/** Components already warned — exported so tests can reset between cases. */
+export const keyDisciplineWarned = new Set<string>();
+
+const REQUEST_CONTEXT_FIELDS: Record<string, string> = {
+  headers: 'headers()',
+  parsedCookies: 'cookies()',
+  searchParams: 'searchParams',
+};
+
+/**
+ * Wrap a store with a proxy that records per-request field access.
+ * The proxy forwards all reads/writes transparently — it only observes.
+ */
+export function createKeyDisciplineProxy(store: RequestContextStore): {
+  proxy: RequestContextStore;
+  accessedApis: Set<string>;
+} {
+  const accessedApis = new Set<string>();
+  const proxy = new Proxy(store, {
+    get(target, prop, receiver) {
+      const api = REQUEST_CONTEXT_FIELDS[prop as string];
+      if (api) accessedApis.add(api);
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+  return { proxy, accessedApis };
+}
+
+export function emitKeyDisciplineWarning(id: string, apis: Set<string>): void {
+  if (keyDisciplineWarned.has(id)) return;
+  keyDisciplineWarned.add(id);
+  const apiList = Array.from(apis).join(', ');
+  console.warn(
+    `[timber] cache.component key-discipline warning: "${id}" reads ${apiList} ` +
+      `but the cache key is computed from props and segment params only. ` +
+      `If the output varies by ${apiList}, different users may see each ` +
+      `other's cached content. Either pass request-derived values as ` +
+      `props (included in the cache key) or remove the ${apiList} call.`
+  );
+}