@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/server/prebuilt/cache-key.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 type { CoercedParams } from '../../shared/param-value.ts';
+/**
+ * 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 declare function tryCanonicalize(value: unknown): string | null;
+export declare function splitSlotProps(props: Record<string, unknown>, slots: readonly string[]): {
+    dataProps: Record<string, unknown>;
+    slotValues: Record<string, unknown>;
+} | null;
+/**
+ * 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 declare function computeComponentCacheKey(props: Record<string, unknown>, params: CoercedParams): string | null;
+//# sourceMappingURL=cache-key.d.ts.map

package/dist/server/prebuilt/cache-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/cache-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAsGjE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAM7D;AAsDD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAqCpF;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,aAAa,GACpB,MAAM,GAAG,IAAI,CAkCf"}

package/dist/server/prebuilt/capture-state.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.ts';
+/** 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 declare class PrebuiltCaptureCycleError extends Error {
+    constructor(componentId: string);
+}
+/**
+ * Mark a capture as active. The builder calls this immediately before
+ * rendering an entry and MUST pair it with `endCapture()` in a finally.
+ */
+export declare function beginCapture(outerId: string): void;
+/**
+ * End the active capture and return the wrapped components that rendered
+ * inside it (first options object wins per inner ID).
+ */
+export declare function endCapture(): NestedWrapperRender[];
+/** Whether a build-time capture is currently rendering. */
+export declare function isCaptureActive(): boolean;
+/**
+ * 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 declare function noteWrapperRender(innerId: string, options: PrebuiltComponentOptions): void;
+//# sourceMappingURL=capture-state.d.ts.map

package/dist/server/prebuilt/capture-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-state.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/capture-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAEvE,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAED,sEAAsE;AACtE,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAY,WAAW,EAAE,MAAM,EAO9B;CACF;AAID;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,mBAAmB,EAAE,CAKlD;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAQ1F"}

package/dist/server/prebuilt/key-discipline.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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
+ * structured, rate-limited production diagnostic.
+ *
+ * The diagnostic fires per offending component, rate-limited to once per
+ * interval (default 60 s) — not once per process. This ensures the
+ * signal stays visible in log aggregators across restarts and deploys.
+ *
+ * When `strictKeyDiscipline` is enabled (via timber.config.ts
+ * `cache.strictKeyDiscipline: true`), the diagnostic is promoted to a
+ * thrown error that prevents the tainted payload from being cached.
+ */
+import type { RequestContextStore } from '../als-registry.ts';
+/**
+ * Configure strict key-discipline mode. When true, a violation throws
+ * instead of logging — the tainted payload is never cached.
+ * Called at boot from the RSC entry with the resolved config value.
+ */
+export declare function setKeyDisciplineStrict(enabled: boolean): void;
+/**
+ * Whether the proxy should be created for this component on this render.
+ * Returns true when strict mode is on (always check) or enough time has
+ * elapsed since the last diagnostic for this component.
+ */
+export declare function shouldCheckKeyDiscipline(id: string): boolean;
+/**
+ * Wrap a store with a proxy that records per-request field access.
+ * The proxy forwards all reads/writes transparently — it only observes.
+ */
+export declare function createKeyDisciplineProxy(store: RequestContextStore): {
+    proxy: RequestContextStore;
+    accessedApis: Set<string>;
+};
+/**
+ * Emit the key-discipline diagnostic or throw in strict mode.
+ *
+ * In strict mode: throws an error so the tainted payload is never cached.
+ * In default mode: emits a structured error-level diagnostic through the
+ * logger (same path as render errors), rate-limited per component.
+ */
+export declare function emitKeyDisciplineWarning(id: string, apis: Set<string>): void;
+/**
+ * Reset all diagnostic state. Exported for tests only.
+ */
+export declare function resetKeyDisciplineState(): void;
+//# sourceMappingURL=key-discipline.d.ts.map

package/dist/server/prebuilt/key-discipline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-discipline.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/key-discipline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAiB9D;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,mBAAmB,GAAG;IACpE,KAAK,EAAE,mBAAmB,CAAC;IAC3B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B,CAUA;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CA8B5E;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C"}

package/dist/server/prebuilt/manifest-tag-index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Manifest tag index — maps tags to seed cache keys for tombstone writes.
+ *
+ * When `revalidateTag(tag)` fires, the framework must write tombstones for
+ * every build-seed entry carrying that tag. The manifest records tags per
+ * entry; this module inverts the index at startup so the lookup is O(1) per
+ * tag instead of a full manifest scan per invalidation.
+ *
+ * The index is built lazily on first access and cached for the process
+ * lifetime — the manifest is immutable within a deploy.
+ *
+ * See design/45-cache-lifetimes.md §ISR mechanics.
+ */
+import type { PrebuiltManifest } from './payload-source.ts';
+export interface SeedKeyInfo {
+    componentId: string;
+    cacheKey: string;
+}
+/**
+ * Build the inverted tag → seed key index from the manifest.
+ *
+ * Returns a Map where each tag maps to the set of (componentId, cacheKey)
+ * pairs whose manifest entries carry that tag. Only entries with non-empty
+ * `tags` arrays participate.
+ */
+export declare function buildTagIndex(manifest: PrebuiltManifest): Map<string, SeedKeyInfo[]>;
+//# sourceMappingURL=manifest-tag-index.d.ts.map

package/dist/server/prebuilt/manifest-tag-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-tag-index.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/manifest-tag-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAiBpF"}

package/dist/server/prebuilt/overlay.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Component cache overlay — runtime CacheHandler layer for ISR.
+ *
+ * Sits in front of the immutable build artifact (`.flight` files) and
+ * stores replacement payloads and tombstones via the configured
+ * CacheHandler. Overlay entries are per-deploy namespaced:
+ *   `timber:c:{deploymentId}:{componentId}:{hash}`
+ *
+ * The CacheHandler contract is untouched — tombstones and the tag index
+ * live above the interface as value conventions. Redis, KV, and custom
+ * handlers work unmodified.
+ *
+ * See design/45-cache-lifetimes.md §ISR mechanics.
+ */
+import { type SeedKeyInfo } from './manifest-tag-index.ts';
+import type { PrebuiltManifest } from './payload-source.ts';
+/**
+ * A cached component flight payload stored in the overlay.
+ * The `_t` discriminant distinguishes this from a tombstone.
+ */
+export interface ComponentOverlayRecord {
+    _t: 'co';
+    /** Base64-encoded flight payload bytes. */
+    p: string;
+    /** Logical freshness deadline (Date.now() + ttl * 1000). */
+    fu: number;
+    /** Whether a build-artifact seed exists for this key. */
+    s: boolean;
+}
+/**
+ * A tombstone marking a build seed as invalidated.
+ * Written by revalidateTag for seeds carrying the invalidated tag.
+ */
+export interface ComponentTombstoneRecord {
+    _t: 'ct';
+}
+export declare function isOverlayRecord(v: unknown): v is ComponentOverlayRecord;
+export declare function isTombstone(v: unknown): v is ComponentTombstoneRecord;
+export declare function overlayKey(componentId: string, cacheKey: string): string;
+export interface OverlayLookupResult {
+    kind: 'fresh' | 'stale' | 'tombstone';
+    /** The overlay value (null for tombstones). */
+    record: ComponentOverlayRecord | null;
+    /** Raw flight payload bytes (decoded from base64). Null for tombstones. */
+    payload: Uint8Array | null;
+}
+/**
+ * Look up an overlay entry in the cache handler.
+ * Returns null on a clean miss (no overlay entry at all).
+ */
+export declare function lookupOverlay(componentId: string, cacheKey: string): Promise<OverlayLookupResult | null>;
+/**
+ * Resolve the effective TTL for a component's runtime lifetime.
+ * Tag-only entries (no explicit ttl) get the ceiling TTL (design/45
+ * §Tag-only entries carry a ceiling TTL).
+ */
+export declare function effectiveTtl(ttl: number | undefined): number;
+/**
+ * Store a component flight payload in the overlay.
+ */
+export declare function storeOverlayEntry(componentId: string, cacheKey: string, payloadBytes: Uint8Array, opts: {
+    ttl?: number;
+    tags: string[];
+    hasSeed: boolean;
+}): Promise<void>;
+/**
+ * Initialize the tag index from the prebuilt manifest. Called once when the
+ * manifest is loaded. Without a manifest (no prebuilt components), this is
+ * never called and revalidateTag skips the tombstone path entirely.
+ */
+export declare function initTagIndex(manifest: PrebuiltManifest): void;
+/**
+ * Get the tag index, if initialized.
+ * @internal — exported for testing.
+ */
+export declare function getTagIndex(): Map<string, SeedKeyInfo[]> | null;
+/**
+ * Reset the tag index (for tests).
+ * @internal
+ */
+export declare function resetTagIndex(): void;
+/**
+ * Write tombstones for all seed entries carrying the given tag.
+ * Called from cache.invalidate (cache-api.ts) AFTER the handler's own
+ * invalidation clears overlay entries.
+ *
+ * The tombstone prevents the immutable seed from being served after
+ * invalidation — without it, a handler.invalidate that clears the overlay
+ * would expose the (now-stale) build artifact on the next request.
+ *
+ * Ensures the manifest is loaded first so cold-process actions that
+ * invalidate before any page render still write tombstones.
+ */
+export declare function writeTombstonesForTag(tag: string): Promise<void>;
+/**
+ * Reset the diagnostic flag (for tests).
+ * @internal
+ */
+export declare function resetIsrDiagnostic(): void;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/server/prebuilt/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAW5D;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,2CAA2C;IAC3C,CAAC,EAAE,MAAM,CAAC;IACV,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,CAAC,EAAE,OAAO,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,IAAI,CAAC;CACV;AAID,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,sBAAsB,CAEvE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,wBAAwB,CAErE;AAID,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAID,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,CAAC;IACtC,+CAA+C;IAC/C,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,2EAA2E;IAC3E,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAoBrC;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,UAAU,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,GACA,OAAO,CAAC,IAAI,CAAC,CAcf;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAG7D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBtE;AA8BD;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/server/prebuilt/payload-source.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Prebuilt payload source — the adapter seam through which the runtime
+ * reads build-time flight artifacts (`.timber/dist/prebuilt/`).
+ *
+ * The runtime never touches the filesystem directly: adapters register a
+ * source at startup (Node: fs reads; Cloudflare: the assets binding —
+ * design/44-render-at-build-time.md §Adapter Integration). Artifacts are
+ * produced by the post-build capture pass (TIM-1119, prebuilt-builder.ts);
+ * adapter registration of the source is TIM-1122. Until a source is
+ * registered (adapter not wired yet, dev mode, no artifacts built), every
+ * lookup misses and cache.component wrappers render live — the designed
+ * dynamic-fallback behavior.
+ *
+ * Phase 3 (design/45 runtime tier) inserts the CacheHandler overlay lookup
+ * in front of `lookupPrebuiltPayload` — overlay first, then artifact. The
+ * single-lookup-function shape here is that seam.
+ */
+import type { CoercedParams } from '../../shared/param-value.ts';
+export interface PrebuiltManifestEntry {
+    /** Segment params this entry was captured under. */
+    params: CoercedParams;
+    /** Payload path relative to the prebuilt/ directory. */
+    file: string;
+    /** Payload size in bytes (build report / diagnostics). */
+    bytes?: number;
+    /** Runtime invalidation tags (design/45 ISR tier). */
+    tags?: string[];
+    /** Epoch ms when this entry was captured (seed freshness for ISR). */
+    buildTimestamp?: number;
+}
+export interface PrebuiltManifest {
+    [componentId: string]: {
+        entries: Record<string, PrebuiltManifestEntry>;
+        /** When true, the component does not read segment params — the cache key uses `{}`. */
+        paramIndependent?: boolean;
+    };
+}
+export interface PrebuiltPayloadSource {
+    /** Load prebuilt/manifest.json. Null when no artifacts exist. */
+    loadManifest(): Promise<PrebuiltManifest | null>;
+    /** Read a `.flight` payload by manifest file path. Null when missing. */
+    readPayload(file: string): Promise<Uint8Array | null>;
+}
+/**
+ * Register the payload source. Called once at server startup by the
+ * adapter/entry wiring (TIM-1122); tests inject fakes. Passing null
+ * unregisters (and drops the memoized manifest).
+ */
+export declare function setPrebuiltPayloadSource(next: PrebuiltPayloadSource | null): void;
+/**
+ * Whether a source is registered — the gate for both marker emission and
+ * splice-transform installation. False means zero prebuilt overhead.
+ */
+export declare function hasPrebuiltPayloadSource(): boolean;
+/**
+ * Ensure the manifest is loaded (and the tag index initialized). No-op
+ * when no source is registered. Used by the tombstone path to avoid
+ * skipping tombstones on cold processes where the first request is an
+ * action rather than a page render.
+ */
+export declare function ensureManifestLoaded(): Promise<void>;
+/**
+ * Look up a manifest entry (metadata only, no payload read).
+ * Used by the overlay to check seed existence and freshness.
+ */
+export declare function isParamIndependent(componentId: string): Promise<boolean>;
+export declare function getManifestEntry(componentId: string, cacheKey: string): Promise<PrebuiltManifestEntry | null>;
+/**
+ * Look up a cached payload: manifest entry → payload bytes.
+ * Null on any miss or read failure — callers fall back to live render.
+ *
+ * The manifest is loaded once and memoized (design/44 §manifest.json:
+ * loaded at startup, held in memory; payloads read on demand). A failed
+ * manifest load is memoized as null rather than retried per-request — a
+ * broken artifact should degrade to dynamic rendering, not add a failing
+ * read to every request.
+ */
+export declare function lookupPrebuiltPayload(componentId: string, cacheKey: string): Promise<Uint8Array | null>;
+//# sourceMappingURL=payload-source.d.ts.map

package/dist/server/prebuilt/payload-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-source.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/payload-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,MAAM,EAAE,aAAa,CAAC;IACtB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,WAAW,EAAE,MAAM,GAAG;QACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;QAC/C,uFAAuF;QACvF,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,YAAY,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACjD,yEAAyE;IACzE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CACvD;AAsED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,qBAAqB,GAAG,IAAI,GAAG,IAAI,CAIjF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI1D;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK9E;AAED,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAKvC;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAmB5B"}

package/dist/server/prebuilt/slots.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Slot-component helpers for cache.component (TIM-1173).
+ *
+ * A `slots: ['children', ...]` declaration caches the component's output
+ * as a shell with a stable <SlotOutlet slot={name} /> client-reference
+ * hole per declared slot prop; live slot content composes in per instance
+ * at request time via SlotsProvider/SlotContext. This generalizes the
+ * TIM-1181 layout mechanism to explicitly declared, named slots on any
+ * cached component. Layouts use the same mechanism with a `children` slot.
+ *
+ * Both the production wrapper (cache path) and the dev wrapper (no cache,
+ * same tree shape for dev/prod parity) build their render from these
+ * helpers. See design/45-cache-lifetimes.md §Slot Components.
+ */
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+/**
+ * Framework-internal slot name for layout children. Uses a prefix that
+ * cannot collide with user-declared slot names (which are React prop
+ * names). Layout children flow through SlotsProvider/SlotOutlet with
+ * this key instead of the bare "children" key, so a cached component
+ * with `slots: ['children']` inside a layout never shadows the layout's
+ * own children delivery.
+ *
+ * Defined here (a server module) rather than in `client/slot-context.ts`
+ * (`'use client'`) because RSC's client-reference proxying would replace
+ * the string value with a proxy object in the server environment. The
+ * client-side SlotOutlet receives this value via props, so it doesn't
+ * need the constant. See TIM-1191.
+ */
+export declare const LAYOUT_CHILDREN_SLOT = "\0timber:children";
+/**
+ * Is this value the framework-injected layout children slot outlet
+ * (`<SlotOutlet slot={LAYOUT_CHILDREN_SLOT} />`)? Layout components
+ * receive this as their `children` prop — a stable client reference
+ * whose cache key is stripped so layout `cache.component` hits work
+ * (design/45 §Layout Propagation).
+ *
+ * Uses a framework-reserved slot name (LAYOUT_CHILDREN_SLOT) that
+ * cannot collide with user-declared slot names, preventing context
+ * shadowing when a cached component with its own SlotsProvider is
+ * nested inside a layout. See TIM-1191.
+ *
+ * Total: the probes run against a user-controlled value, and a Proxy
+ * trap can throw — that must classify as "not the outlet" (the
+ * canonicalizer then rejects the value as unkeyable → live render), not
+ * abort the request (codex P2 on PR #890).
+ */
+export declare function isChildrenSlotOutletElement(value: unknown): boolean;
+/**
+ * Outcome of validating a `slots` declaration at registration time.
+ *
+ * - `none` — not declared (or an empty array): plain non-slot component.
+ * - `disabled` — declared but unusable (malformed shape, or missing the
+ *   required runtime lifetime): warned once here (module load); the
+ *   component falls back WHOLESALE to non-slot semantics — the caller
+ *   strips `slots` from the options and every other option (including
+ *   `prerender`) keeps its normal meaning. Safe by construction:
+ *   element-valued props are unkeyable on the non-slot path, so renders
+ *   with slot content go live. Slower, never wrong.
+ * - `active` — usable slot names.
+ */
+export type SlotResolution = {
+    kind: 'none' | 'disabled';
+} | {
+    kind: 'active';
+    slots: string[];
+};
+/**
+ * Validate the `slots` option. Both the production and dev wrappers gate
+ * on this — slot substitution is active in dev exactly when it would be
+ * active in production, so the tree shape a component sees never
+ * diverges between the two.
+ */
+export declare function resolveSlotNames(id: string, options: PrebuiltComponentOptions): SlotResolution;
+export interface SlotRender {
+    /** Props the shell renders with: data props + a SlotOutlet per slot. */
+    shellProps: Record<string, unknown>;
+    /** Non-slot props — the only props that participate in the cache key. */
+    dataProps: Record<string, unknown>;
+    /** Live slot content, keyed by slot name, for the SlotsProvider. */
+    slotValues: Record<string, unknown>;
+}
+/**
+ * Split the live props into the cacheable shell render (data props plus a
+ * deterministic SlotOutlet placeholder per declared slot — identical
+ * whether or not the caller passed the slot) and the per-instance live
+ * slot values.
+ *
+ * Null when the props object itself is unkeyable at the top level
+ * (accessors, hidden properties, exotic prototype — see splitSlotProps):
+ * the caller must render live with the original props.
+ */
+export declare function prepareSlotRender(props: Record<string, unknown>, slots: readonly string[]): SlotRender | null;
+/**
+ * Wrap a rendered shell (revived payload or live element) in a
+ * per-instance SlotsProvider feeding the live values to its outlets.
+ */
+export declare function wrapInSlotsProvider(shell: unknown, slotValues: Record<string, unknown>): React.ReactElement;
+//# sourceMappingURL=slots.d.ts.map

package/dist/server/prebuilt/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASnE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAqBjG;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,cAAc,CA0B9F;AAED,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,UAAU,GAAG,IAAI,CAiBnB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,KAAK,CAAC,YAAY,CAMpB"}

package/dist/server/prebuilt/synthetic-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Synthetic ALS store for build-time capture (design/44 §Param Injection).
+ *
+ * Each param combo renders inside a `RequestContextStore` that provides
+ * segment params and NOTHING else. Every per-request API is a hard error,
+ * never a silent empty value — a component that branches on a header
+ * (locale, experiment, auth state) must fail the build, not bake the
+ * "header absent" branch into the cache for every future request:
+ *
+ * - `segmentParams.get()` works — reads from this store
+ * - `cookies()` / `headers()` / `searchParams` throw `BuildTimeContextError`
+ *
+ * The enforcement lives in the store's own fields (recording accessors)
+ * rather than in request-context.ts / cookie-context.ts, so the request
+ * path pays nothing and those modules stay untouched. The per-request
+ * fields — `headers`, `parsedCookies`, `searchParams` — are getters that
+ * record a violation and throw, so the CALL itself (`getHeaders()`,
+ * `getCookieJar()`, `getSearchParams()`) is the build error, not some
+ * later member read; merely obtaining and passing the object around is
+ * already outside the build-time contract (codex P2 round 5 on PR #836).
+ * `mutableContext` gets the same treatment because cookie MUTATORS reach
+ * it (via cookie-context's assertMutable, its only reader) before any
+ * other store field (codex P2 round 4).
+ *
+ * Every violation is recorded in a side channel BEFORE the throw — a
+ * component that catches the error (`try { headers() } catch { fallback }`)
+ * still fails its entry; accepting that render would silently bake the
+ * request-dependent fallback branch into the payload (codex P1 on PR #836).
+ * The capture pass checks the side channel after every render.
+ *
+ * This is safe precisely because capture renders the bare component
+ * element — no pipeline, no SSR bridge, no action machinery — so the only
+ * code that can reach these fields during a capture is the component
+ * itself (via the public accessors).
+ */
+import type { RequestContextStore } from '../als-registry.ts';
+import type { CoercedParams } from '../../shared/param-value.ts';
+/**
+ * Thrown when a prerendered component touches per-request context at
+ * build time. The capture pass treats this as a HARD build error —
+ * it indicates a design mistake, not transient bad data (design/44
+ * §Build-Phase Error Handling).
+ */
+export declare class BuildTimeContextError extends Error {
+    /** The per-request API that was called (e.g. "cookies()"). */
+    readonly api: string;
+    constructor(componentId: string, api: string);
+}
+/** A synthetic store plus the side channel its accessors report into. */
+export interface BuildTimeStoreHandle {
+    store: RequestContextStore;
+    /**
+     * Every per-request API access during the render, recorded even when
+     * the accompanying throw was caught by user code. Non-empty after the
+     * render ⇒ the entry must fail as a hard build error.
+     */
+    violations: BuildTimeContextError[];
+    /** Whether the component read `segmentParams` during the render. */
+    segmentParamsRead: boolean;
+}
+/**
+ * Create the synthetic per-combo store. `segmentParams` must already be
+ * coerced through the route's codecs — cache-key parity with request time
+ * depends on hashing the exact record `coerceSegmentParams` produces.
+ */
+export declare function createBuildTimeStore(componentId: string, segmentParams: CoercedParams): BuildTimeStoreHandle;
+//# sourceMappingURL=synthetic-store.d.ts.map

package/dist/server/prebuilt/synthetic-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthetic-store.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/synthetic-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,YAAY,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAU3C;CACF;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;;OAIG;IACH,UAAU,EAAE,qBAAqB,EAAE,CAAC;IACpC,oEAAoE;IACpE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,aAAa,GAC3B,oBAAoB,CAsCtB"}