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

package/src/server/port-resolution.ts

@@ -0,0 +1,53 @@
+/** Port input precedence for dev and preview. Vite owns binding and restart reuse. */
+
+/** Default port used by `timber dev` and `timber preview`. */
+export const DEFAULT_PORT = 3000;
+
+// ── 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). Preview uses this to default to strict port binding.
+   */
+  explicit: boolean;
+}
+
+/**
+ * Pure: compute the starting port from config / env / defaults.
+ *
+ * Performs no I/O.
+ */
+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 };
+}

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.ts';
+
+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.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 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,122 @@
+/**
+ * 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';
+import { getLogger } from '../logger.ts';
+
+const REQUEST_CONTEXT_FIELDS: Record<string, string> = {
+  headers: 'headers()',
+  parsedCookies: 'cookies()',
+  searchParams: 'searchParams',
+};
+
+/** Rate-limit interval: one diagnostic per component per 60 seconds. */
+const RATE_LIMIT_MS = 60_000;
+
+/** Last emission timestamp per component ID. */
+const lastEmitted = new Map<string, number>();
+
+let strict = false;
+
+/**
+ * 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 function setKeyDisciplineStrict(enabled: boolean): void {
+  strict = enabled;
+}
+
+/**
+ * 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 function shouldCheckKeyDiscipline(id: string): boolean {
+  if (strict) return true;
+  const last = lastEmitted.get(id);
+  if (last === undefined) return true;
+  return Date.now() - last >= RATE_LIMIT_MS;
+}
+
+/**
+ * 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 };
+}
+
+/**
+ * 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 function emitKeyDisciplineWarning(id: string, apis: Set<string>): void {
+  const apiList = Array.from(apis).join(', ');
+
+  if (strict) {
+    throw new Error(
+      `[timber] cache.component key-discipline violation: "${id}" reads ${apiList} ` +
+        `during a cache capture render. The cache key does not include ` +
+        `request-derived values — caching this output would serve one ` +
+        `user's data to another. Either pass request-derived values as ` +
+        `props (included in the cache key) or remove the ${apiList} call. ` +
+        `To downgrade this to a warning, set cache.strictKeyDiscipline: false ` +
+        `in timber.config.ts.`
+    );
+  }
+
+  const now = Date.now();
+  const last = lastEmitted.get(id);
+  if (last !== undefined && now - last < RATE_LIMIT_MS) return;
+  lastEmitted.set(id, now);
+
+  getLogger().error('cache.component cross-user data leak risk', {
+    component: id,
+    accessedApis: Array.from(apis),
+    message:
+      `cache.component "${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.`,
+  });
+}
+
+/**
+ * Reset all diagnostic state. Exported for tests only.
+ */
+export function resetKeyDisciplineState(): void {
+  lastEmitted.clear();
+  strict = false;
+}

package/src/server/prebuilt/manifest-tag-index.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 function buildTagIndex(manifest: PrebuiltManifest): Map<string, SeedKeyInfo[]> {
+  const index = new Map<string, SeedKeyInfo[]>();
+  for (const [componentId, component] of Object.entries(manifest)) {
+    if (!component || typeof component !== 'object' || !('entries' in component)) continue;
+    for (const [cacheKey, entry] of Object.entries(component.entries)) {
+      if (!entry.tags || entry.tags.length === 0) continue;
+      for (const tag of entry.tags) {
+        let list = index.get(tag);
+        if (!list) {
+          list = [];
+          index.set(tag, list);
+        }
+        list.push({ componentId, cacheKey });
+      }
+    }
+  }
+  return index;
+}