@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/src/cache/cf/cf-cache-types.ts

@@ -14,6 +14,7 @@
 import type { ExecutionContext } from "../../types/request-scope.js";
 import type { CacheDefaults } from "../types.js";
 import type { RequestContext } from "../../server/request-context.js";
+import type { CloudflareZonePurgeOptions } from "./cf-zone-purge.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.
@@ -197,6 +198,71 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   onRevalidateTag?: (cacheTags: string[]) => Promise<void>;
 
+  /**
+   * Purge-based tag invalidation (purge mode). When configured, the store
+   * delegates L1 (Cache API) tag eviction to Cloudflare's purge-by-tag API
+   * instead of the per-read KV marker lookup.
+   *
+   * Two forms:
+   * - **Credentials object** (the normal wiring): `{ zoneId, apiToken }` — the
+   *   store builds the purge client itself (createCloudflareZonePurge).
+   *   `zoneId` is on the zone's dashboard overview; `apiToken` needs the
+   *   `Zone.Cache Purge` permission for that zone — store it as a Worker
+   *   secret. Validated at store construction (Workers run no code at deploy,
+   *   so with the usual per-request cache factory this means the first request
+   *   throws — loudly and on every request), rather than surfacing only when
+   *   the first invalidation quietly rejects much later.
+   * - **Function** `(cacheTags) => Promise<void>` — an escape hatch for
+   *   proxies, custom transports, or test stubs; receives the exact
+   *   Cache-Tags to purge.
+   *
+   * Semantics:
+   * - Every tagged L1 entry carries a namespaced `Cache-Tag` header
+   *   (`rg:{namespace}:e:{encodedTag}`, plus the broader `rg:{namespace}` /
+   *   `rg:{namespace}:e` tiers for manual resets).
+   * - `updateTag()`/`revalidateTag()` AWAIT the purge with the exact Cache-Tags
+   *   (one batched call per invalidation; entry tags, plus the lookup
+   *   Cache-Tags when `tagCacheTtl > 0`).
+   * - L1 hits then skip the per-read marker lookup entirely: a surviving entry
+   *   is trusted because an invalidated one would have been purged. Only the
+   *   per-request memo is consulted (synchronously, no KV read), so a request
+   *   that ran `updateTag()` still masks its own not-yet-purged entries
+   *   (read-your-own-writes).
+   * - The KV tier and PPR shells still use the KV markers — those are written
+   *   regardless, and purge cannot reach KV — so keep `kv` configured for L2.
+   *   Without `kv`, purge mode is the ONLY tag invalidation and the store is
+   *   L1-only: a supported configuration (previously tag invalidation without
+   *   KV had no read-side effect at all). One KV-less caveat: an entry whose
+   *   tag set overflows Cloudflare's 16 KB Cache-Tag header limit is NOT
+   *   cached (it would be un-invalidatable — no tokens for the purge, no
+   *   marker fallback); with `kv` such an entry caches and falls back to the
+   *   marker check.
+   *
+   * Consistency trade-off vs the default marker mode: invalidation latency for
+   * concurrent requests becomes the purge propagation time (Cloudflare quotes
+   * sub-second "Instant Purge") instead of read-time KV consistency, and a
+   * purge failure leaves L1 stale until TTL — which is why a rejected hook
+   * makes `updateTag()` reject (retry the invalidation; markers and purge are
+   * both idempotent).
+   *
+   * Zone scoping: purge-by-tag clears YOUR zone. workers.dev / pages.dev
+   * previews have an inert Cache API (nothing to purge — the KV tier still
+   * invalidates via markers there); a preview on a SEPARATE zone needs its own
+   * purge credentials.
+   *
+   * @example
+   * ```ts
+   * new CFCacheStore({
+   *   ctx,
+   *   kv: env.CACHE_KV,
+   *   tagPurge: { zoneId: env.CF_ZONE_ID, apiToken: env.CF_PURGE_TOKEN },
+   * })
+   * ```
+   */
+  tagPurge?:
+    | CloudflareZonePurgeOptions
+    | ((cacheTags: string[]) => Promise<void>);
+
   /**
    * Optional expiration (seconds) for tag-invalidation markers in KV. A marker
    * must outlive every entry tagged before the invalidation, so this MUST

package/src/cache/cf/cf-tag-marker-memo.ts

@@ -38,8 +38,11 @@ export const TAG_MARKER_ABSENT = "none";
  * entry A's own KV says is invalidated. Keying by the instance isolates them;
  * two reads through the SAME store still share the memo. A read through one
  * store never populates another's memo, so each store always consults its own KV
- * binding. Markers are read only through isGloballyInvalidated(), which already
- * short-circuits when a store has no KV, so a store without KV never allocates.
+ * binding. Markers are read through isGloballyInvalidated(), which
+ * short-circuits when a store has no KV — and, in purge mode, through
+ * isL1Invalidated(), which consults ONLY this memo on an L1 hit (no KV read),
+ * so a purge-mode store allocates the memo even without KV for same-request
+ * read-your-own-writes after updateTag().
  *
  * Without the memo, isGloballyInvalidated() issues a KV read per tag on every
  * tagged cache read, so a page composed of many segments/items sharing a tag

package/src/cache/cf/cf-zone-purge.ts

@@ -0,0 +1,101 @@
+// ============================================================================
+// Cloudflare zone purge-by-tag helper
+// ============================================================================
+//
+// Ready-made `tagPurge` implementation for CFCacheStoreOptions: POSTs the
+// Cache-Tags handed over by invalidateTags() to the zone purge endpoint.
+// Kept transport-only (no store coupling) so it is unit-testable with an
+// injected fetch and reusable for onRevalidateTag.
+
+/**
+ * Tags per purge_cache API call. Cloudflare's documented purge-by-tag batch
+ * limit has historically been 30 tags per call (the newer all-plans limits
+ * page quotes 100 operations per request); chunking at 30 stays under both.
+ * @internal
+ */
+export const PURGE_TAGS_PER_CALL = 30;
+
+export interface CloudflareZonePurgeOptions {
+  /** Zone to purge (Cloudflare dashboard -> zone overview -> Zone ID). */
+  zoneId: string;
+  /** API token with the `Zone.Cache Purge` permission for that zone. */
+  apiToken: string;
+  /**
+   * API origin override, mainly for tests/proxies.
+   * Defaults to `https://api.cloudflare.com`.
+   */
+  apiBase?: string;
+  /** fetch override, mainly for tests. Defaults to the global fetch. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Create a purge-by-tag function for {@link CFCacheStoreOptions.tagPurge} (or
+ * `onRevalidateTag`). Chunks the tag list under the per-call API limit and
+ * rejects on any non-success response, so a failed purge surfaces through
+ * `updateTag()` instead of silently leaving L1 stale.
+ *
+ * Purge-by-tag is available on ALL Cloudflare plans (since April 2025), but
+ * account-level purge rate limits apply (Free: 5 calls/min) — keep invalidation
+ * tag batches small and low-frequency on lower plans.
+ */
+export function createCloudflareZonePurge(
+  options: CloudflareZonePurgeOptions,
+): (cacheTags: string[]) => Promise<void> {
+  const { zoneId, apiToken } = options;
+  // Fail at construction, not at the first updateTag(): a store wired with an
+  // unset env var would otherwise report the misconfig only when the first
+  // invalidation rejects — long after deploy.
+  if (typeof zoneId !== "string" || zoneId.length === 0) {
+    throw new Error(
+      "[createCloudflareZonePurge] zoneId is required (Cloudflare dashboard " +
+        "-> zone overview -> Zone ID). Check the env var/secret it is read from.",
+    );
+  }
+  if (typeof apiToken !== "string" || apiToken.length === 0) {
+    throw new Error(
+      "[createCloudflareZonePurge] apiToken is required (an API token with " +
+        "the Zone.Cache Purge permission for the zone). Check the secret it " +
+        "is read from.",
+    );
+  }
+  const apiBase = options.apiBase ?? "https://api.cloudflare.com";
+  const fetchImpl = options.fetch ?? fetch;
+  const endpoint = `${apiBase}/client/v4/zones/${zoneId}/purge_cache`;
+
+  return async (cacheTags: string[]): Promise<void> => {
+    for (let i = 0; i < cacheTags.length; i += PURGE_TAGS_PER_CALL) {
+      const chunk = cacheTags.slice(i, i + PURGE_TAGS_PER_CALL);
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ tags: chunk }),
+      });
+      // The API reports failures both via HTTP status and a success flag.
+      // Require an EXPLICIT success: true — an empty body, an HTML error
+      // page, invalid JSON, or `{}` on a 2xx is NOT a confirmed purge, and
+      // purge mode trusts surviving L1 entries on the strength of this call,
+      // so an unconfirmed purge must reject rather than pass silently.
+      const body = (await response.json().catch(() => null)) as {
+        success?: boolean;
+        errors?: { code?: number; message?: string }[];
+      } | null;
+      if (!response.ok || body?.success !== true) {
+        const detail =
+          body?.errors
+            ?.map((e) => `${e.code ?? "?"}: ${e.message ?? "unknown"}`)
+            .join("; ") ??
+          (response.ok
+            ? `HTTP ${response.status} with a missing/invalid success body`
+            : `HTTP ${response.status}`);
+        throw new Error(
+          `[createCloudflareZonePurge] purge_cache failed for ${chunk.length} ` +
+            `tag(s): ${detail}`,
+        );
+      }
+    }
+  };
+}

package/src/cache/cf/index.ts

@@ -17,3 +17,8 @@ export {
   EDGE_READ_TIMEOUT_MS,
   KV_READ_TIMEOUT_MS,
 } from "./cf-cache-store.js";
+
+export {
+  createCloudflareZonePurge,
+  type CloudflareZonePurgeOptions,
+} from "./cf-zone-purge.js";

package/src/cache/handle-snapshot.ts

@@ -83,14 +83,35 @@ export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
 /**
  * Capture handle data for a set of segments from the handle store.
  * Used when caching segments to preserve their handle data.
+ *
+ * `exclude` (shell captures: RequestContext._shellCaptureLoaderHandleValues)
+ * drops DSL-loader-scoped push values from the CACHE WRITE only: loaders
+ * re-run fresh on every HIT, so replaying their captured values would
+ * duplicate the fresh push — and their masked nested promises would stall the
+ * Flight handle encode to its timeout. Threaded as an explicit argument so
+ * every other getDataForSegment consumer (the render-barrier snapshot,
+ * prerender) provably sees every push.
  */
 export function captureHandles(
   segments: ResolvedSegment[],
   handleStore: HandleStore,
+  exclude?: WeakSet<object>,
 ): Record<string, SegmentHandleData> {
   const handles: Record<string, SegmentHandleData> = {};
   for (const seg of segments) {
-    handles[seg.id] = handleStore.getDataForSegment(seg.id);
+    const data = handleStore.getDataForSegment(seg.id);
+    if (!exclude) {
+      handles[seg.id] = data;
+      continue;
+    }
+    const filtered: SegmentHandleData = {};
+    for (const [handleName, values] of Object.entries(data)) {
+      const kept = values.filter(
+        (v) => typeof v !== "object" || v === null || !exclude.has(v),
+      );
+      if (kept.length > 0) filtered[handleName] = kept;
+    }
+    handles[seg.id] = filtered;
   }
   return handles;
 }

package/src/cache/index.ts

@@ -23,6 +23,8 @@ export {
   EDGE_LOOKUP_TIMEOUT_MS,
   EDGE_READ_TIMEOUT_MS,
   KV_READ_TIMEOUT_MS,
+  createCloudflareZonePurge,
+  type CloudflareZonePurgeOptions,
 } from "./cf/index.js";
 
 export {

package/src/cache/memory-segment-store.ts

@@ -30,6 +30,8 @@ const ITEM_CACHE_REGISTRY_KEY = "__rsc_router_item_cache_registry__";
 const SHELL_CACHE_REGISTRY_KEY = "__rsc_router_shell_cache_registry__";
 const TAG_INDEX_REGISTRY_KEY = "__rsc_router_tag_index_registry__";
 const KEY_TAGS_REGISTRY_KEY = "__rsc_router_key_tags_registry__";
+const TAG_INVALIDATED_AT_REGISTRY_KEY =
+  "__rsc_router_tag_invalidated_at_registry__";
 
 /**
  * Get or create a named Map from a globalThis-backed registry.
@@ -194,6 +196,14 @@ export class MemorySegmentCacheStore<
   private tagIndex: Map<string, Set<string>>;
   /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
   private keyTags: Map<string, Set<string>>;
+  /**
+   * tag -> epoch ms of its latest invalidateTags() call. The build-shell
+   * read-through's isTagsInvalidatedSince gate: baked shell entries are
+   * immutable in the build manifest, so eviction is answered by comparing
+   * these markers against the entry's build-time createdAt. Per-isolate,
+   * like every other map here — matching this store's tag semantics.
+   */
+  private tagInvalidatedAt: Map<string, number>;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -228,6 +238,10 @@ export class MemorySegmentCacheStore<
         KEY_TAGS_REGISTRY_KEY,
         options.name,
       );
+      this.tagInvalidatedAt = getNamedMap<number>(
+        TAG_INVALIDATED_AT_REGISTRY_KEY,
+        options.name,
+      );
     } else {
       this.cache = new Map<string, CachedEntryData>();
       this.responseCache = new Map<string, CachedResponseEntry>();
@@ -235,6 +249,7 @@ export class MemorySegmentCacheStore<
       this.shellCache = new Map<string, CachedShellEntry>();
       this.tagIndex = new Map<string, Set<string>>();
       this.keyTags = new Map<string, Set<string>>();
+      this.tagInvalidatedAt = new Map<string, number>();
     }
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
@@ -457,8 +472,25 @@ export class MemorySegmentCacheStore<
     }
   }
 
+  async isTagsInvalidatedSince(
+    tags: string[],
+    sinceMs: number,
+  ): Promise<boolean> {
+    for (const tag of tags) {
+      const at = this.tagInvalidatedAt.get(tag);
+      // >= so a same-millisecond invalidation wins (freshness over staleness),
+      // matching the CF marker comparison.
+      if (at !== undefined && at >= sinceMs) return true;
+    }
+    return false;
+  }
+
   async invalidateTags(tags: string[]): Promise<void> {
+    const invalidatedAt = Date.now();
     for (const tag of tags) {
+      // Marker first: build-shell entries evict by marker comparison even when
+      // no runtime entry currently carries the tag (tagIndex miss below).
+      this.tagInvalidatedAt.set(tag, invalidatedAt);
       const keys = this.tagIndex.get(tag);
       if (!keys || keys.size === 0) continue;
 

package/src/cache/segment-codec.ts

@@ -11,6 +11,7 @@
 import type { ResolvedSegment } from "../types.js";
 import type { SerializedSegmentData } from "./types.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+import { segmentFragment } from "../segment-fragments.js";
 import {
   renderToReadableStream,
   createTemporaryReferenceSet,
@@ -206,6 +207,52 @@ export async function serializeSegments(
   );
 }
 
+/**
+ * Build ResolvedSegments that carry the STORED fragment strings verbatim
+ * instead of decoding them (PPR fast-path payload splice, issue #700; see
+ * segment-fragments.ts). The ReactNode fields (component/layout/loading)
+ * become {@link segmentFragment} envelopes the outer Flight render serializes
+ * as a string copy; the CONSUMER (SSR resume + browser hydration) expands them
+ * through its own deserializer. Loader data fields are NOT enveloped — they
+ * are consumer data of any shape (a marker there could collide) and decode
+ * server-side exactly as deserializeSegments does; on the doc/prerender
+ * records this path serves they are absent in practice (loaders are never
+ * cached with the route record).
+ *
+ * The loading "null" sentinel decodes here (not on the consumer): loading:null
+ * must survive as null, and shipping the raw sentinel would change the
+ * deduplicateLoaderSegments loading-presence check.
+ */
+export async function fragmentSegments(
+  data: SerializedSegmentData[],
+): Promise<ResolvedSegment[]> {
+  return Promise.all(
+    data.map(async (item): Promise<ResolvedSegment> => {
+      const loadingIsNullSentinel = item.encodedLoading === "null";
+      const [loaderData, loaderDataPromise] = await Promise.all([
+        rscDeserialize(item.encodedLoaderData),
+        rscDeserialize(item.encodedLoaderDataPromise),
+      ]);
+      return {
+        ...item.metadata,
+        // Envelopes ride ReactNode-typed fields; the consumer expansion pass
+        // (segment-fragments.ts) replaces them before any render reads them.
+        component: segmentFragment(item.encoded) as unknown,
+        layout: item.encodedLayout
+          ? (segmentFragment(item.encodedLayout) as unknown)
+          : undefined,
+        loading: loadingIsNullSentinel
+          ? null
+          : item.encodedLoading !== undefined
+            ? (segmentFragment(item.encodedLoading) as unknown)
+            : undefined,
+        loaderData,
+        loaderDataPromise,
+      } as ResolvedSegment;
+    }),
+  );
+}
+
 /**
  * Deserialize segments from storage.
  * Reconstructs ResolvedSegment objects from RSC-serialized data.

package/src/cache/shell-snapshot.ts

@@ -110,6 +110,19 @@ export class RecordingShellStore<
     this.writes.push(p);
   }
 
+  /**
+   * Record a segment-family write into the snapshot WITHOUT touching the inner
+   * store. The shell fast path's implicit doc-cache scope writes through this
+   * (via {@link SnapshotOnlySegmentStore}): the recorded doc entry must ride
+   * ONLY inside the shell entry — a passthrough write would leave a doc-keyed
+   * entry in the real store that the NEXT capture's lookup would hit, replaying
+   * the previous generation's segments instead of re-running handlers (breaking
+   * SWR recapture freshness).
+   */
+  recordSegmentWrite(key: string, data: CachedEntryData): void {
+    this.record("segment", key, data);
+  }
+
   /**
    * Await the tracked deferred writes so their records are present before drain.
    * Drains ITERATIVELY: a write task can schedule a NESTED write (the ring-3
@@ -245,6 +258,40 @@ export function getRecordingStore<TEnv>(
   return store instanceof RecordingShellStore ? store : undefined;
 }
 
+/**
+ * The store the shell fast path's IMPLICIT doc-cache scope resolves during a
+ * capture: reads pass through the recording store (a real-store hit is
+ * recorded, exactly like any capture read), but segment WRITES are recorded
+ * into the snapshot only — see {@link RecordingShellStore.recordSegmentWrite}
+ * for why passthrough would break SWR recapture. Routes with their OWN
+ * cache() config never see this store (their scope resolves the app-level
+ * recording store and keeps today's record-and-write behavior).
+ */
+export class SnapshotOnlySegmentStore<
+  TEnv = unknown,
+> implements SegmentCacheStore<TEnv> {
+  constructor(private readonly recording: RecordingShellStore<TEnv>) {}
+
+  get defaults(): SegmentCacheStore<TEnv>["defaults"] {
+    return this.recording.defaults;
+  }
+  get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"] {
+    return this.recording.keyGenerator;
+  }
+
+  async get(key: string): Promise<CacheGetResult | null> {
+    return this.recording.get(key);
+  }
+
+  async set(key: string, data: CachedEntryData): Promise<void> {
+    this.recording.recordSegmentWrite(key, data);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.recording.delete(key);
+  }
+}
+
 /**
  * Materialize the loader-family seed from a shell snapshot for a HIT's tail
  * render: Flight-deserialize each recorded (promise-elided) bake-lane
@@ -259,9 +306,21 @@ export function getRecordingStore<TEnv>(
  * HIT). Returns undefined when the snapshot carries no loader records, without
  * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
  */
+export interface ShellLoaderSeedEntry {
+  /** The Flight-deserialized elided container (recorded paths + markers). */
+  container: unknown;
+  /**
+   * True when the record carries hole markers (or predates the capture-side
+   * hole bit, where hole-ness is unknown): the HIT overlay must gate on the
+   * fresh run. False = fully pinned; the payload promise resolves immediately
+   * from the pin (loader-cache.ts pin-first path).
+   */
+  holes: boolean;
+}
+
 export async function buildShellLoaderSeed(
   snapshot: ShellSnapshotRecord[],
-): Promise<Map<string, unknown> | undefined> {
+): Promise<Map<string, ShellLoaderSeedEntry> | undefined> {
   const loaderRecords: ShellSnapshotRecord[] = [];
   for (const rec of snapshot) {
     if (rec.family === "loader") loaderRecords.push(rec);
@@ -270,20 +329,26 @@ export async function buildShellLoaderSeed(
 
   const { deserializeResult } = await import("./segment-codec.js");
   const entries = await Promise.all(
-    loaderRecords.map(async (rec): Promise<[string, unknown] | null> => {
-      try {
-        return [
-          rec.key,
-          await deserializeResult(
-            (rec.value as ShellSnapshotLoaderValue).value,
-          ),
-        ];
-      } catch {
-        return null;
-      }
-    }),
+    loaderRecords.map(
+      async (rec): Promise<[string, ShellLoaderSeedEntry] | null> => {
+        try {
+          const stored = rec.value as ShellSnapshotLoaderValue;
+          return [
+            rec.key,
+            {
+              container: await deserializeResult(stored.value),
+              // A record without the bit (pre-bit snapshot) reads as
+              // hole-carrying: unknown hole-ness must keep the gated path.
+              holes: stored.holes !== 0,
+            },
+          ];
+        } catch {
+          return null;
+        }
+      },
+    ),
   );
-  const seed = new Map<string, unknown>();
+  const seed = new Map<string, ShellLoaderSeedEntry>();
   for (const entry of entries) {
     if (entry) seed.set(entry[0], entry[1]);
   }

package/src/cache/types.ts

@@ -196,6 +196,20 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param tags - The cache tags to invalidate
    */
   invalidateTags?(tags: string[]): Promise<void>;
+
+  /**
+   * True when ANY of `tags` was invalidated (invalidateTags/updateTag) at or
+   * after `sinceMs` (>= so a same-millisecond invalidation wins, favouring
+   * freshness). Consulted by the build-time shell read-through
+   * (rsc/shell-build-manifest.ts): a baked shell entry is immutable in the
+   * build manifest, so "was it evicted" is answered by the store's tag
+   * markers against the entry's createdAt rather than by deleting anything.
+   * Optional: without it, TAGGED build entries are not served (untagged ones
+   * are unaffected — they are evictable only by deploy/buildVersion anyway).
+   * Fail open to `false` on marker-read errors: a transient store fault must
+   * degrade to "still valid", the same posture as the envelope tag checks.
+   */
+  isTagsInvalidatedSince?(tags: string[], sinceMs: number): Promise<boolean>;
 }
 
 /**
@@ -280,6 +294,19 @@ export interface ShellCacheEntry {
    * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
    */
   snapshot?: ShellSnapshotRecord[];
+  /**
+   * True when the capture's HANDLER layer declared per-request liveness: a
+   * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the
+   * capture mask turns it into a never-filling hole), such a push was still
+   * pending when the entry was written, or a handler-invoked loader
+   * (ctx.use(loader) from a handler body — the consumption lane, #672)
+   * executed during the capture. The serve tail then must NOT take the
+   * handler-free fast path (the implicit doc-cache hit): only a handler
+   * re-run can mint that hole's live promise or refresh that consumed value.
+   * DSL-loader pushes never set this — loaders re-run fresh on every HIT, so
+   * their holes always fill.
+   */
+  handlerLiveHoles?: boolean;
   /** Epoch ms when the shell was captured. */
   createdAt: number;
 }
@@ -305,6 +332,17 @@ export type ShellSnapshotFamily = "item" | "segment" | "response" | "loader";
 export interface ShellSnapshotLoaderValue {
   /** RSC-serialized elided container (see loader-snapshot.ts). */
   value: string;
+  /**
+   * Hole bit, capture-computed (elide already walks every node): 1 = the
+   * container carries hole markers, so a HIT must gate the overlay on the
+   * fresh run (only the loader body can mint the live nested promises);
+   * 0 = fully pinned, so a HIT resolves the payload promise immediately from
+   * the pin while the fresh run proceeds ungated (side effects and cache
+   * read-through writes preserved; its values were discarded either way —
+   * recorded paths win wholesale). Absent on pre-bit snapshots, which keep
+   * the gated path.
+   */
+  holes?: 0 | 1;
 }
 
 /** A serialized cached Response for the response family of a shell snapshot. */