@rangojs/router 0.17.0 → 0.19.0

package/dist/types/cache/shell-snapshot.d.ts

@@ -1,78 +1,76 @@
 /**
  * Capture data snapshot: recording + seeding stores for PPR shell parity.
  *
- * The scar tissue this fixes: a PPR HIT serves frozen prelude bytes, then a
- * FULL FRESH Flight render for hydration. Any shell-baked (non-hole) content
- * that drifts between capture time and hit time — a cache() segment with a
- * shorter ttl than the shell, a tag-invalidated item — makes the fresh payload
- * disagree with the prelude, so React throws a hydration text mismatch and
- * regenerates the tree client-side (wiping the FOUC theme class, flashing
- * content). See docs/design/ppr-shell-resume.md.
+ * A PPR HIT serves frozen prelude bytes, then a Flight payload for hydration
+ * that must agree with them byte for byte. The handler layer's part of that
+ * payload is the capture's own doc segment record: the capture writes it
+ * first, renders its prelude from it, and every HIT replays it (no handler
+ * runs on a HIT). The loader layer's part is the bake-lane (`ssr: false`)
+ * loader pins: a promise-free bake-lane loader is served from its pin and
+ * does not run; one whose return carries promises (`holes`), or whose pushes
+ * the record could not keep (`runs`), runs on the HIT. See
+ * docs/design/ppr-shell-resume.md.
  *
- * The fix (Next.js resume-data-cache analog, adapted to Rango's cache rings):
- * the CAPTURE render records every cache-store read-hit and write it performed
- * (the {@link RecordingShellStore}); the record rides inside the ShellCacheEntry
- * as its `snapshot`; on a HIT the tail render reads through a
- * {@link SeededShellStore} overlay that serves those recorded values AS FRESH,
- * so the shell region reproduces byte-identically while everything NOT recorded
- * (the holes — masked loaders were never executed at capture, so their reads
- * were never recorded) stays live.
- *
- * The invariant, verbatim: the snapshot is exactly the set of cache-store reads
- * the capture render performed; replaying them on a HIT reproduces the shell
- * content byte-identically; everything not recorded stays live.
+ * The invariant, verbatim: the snapshot is the doc record and the bake-lane
+ * loader pins; replaying them on a HIT reproduces the shell content
+ * byte-identically; everything else a HIT reads comes from the store. A hole
+ * (a live-lane loader, or a promise nested in a bake-lane return) never reads
+ * the capture's copy of a value: it is dynamic or has its own cache. A
+ * bake-lane loader body that runs on a HIT reads the store too; its pinned
+ * container paths stay the pin's (overlayLoaderContainer), and its settled
+ * pushes stay the record's (HandleStore.pushRestored).
  */
 import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord, CacheReadError } from "./types.js";
 /**
- * A store wrapper the CAPTURE render reads through. Every call passes through to
- * the underlying store unchanged; for the item/segment/response families it also
- * RECORDS, last-write-wins per (family, key):
- *   - read-hits (get/getItem/getResponse returning non-null) — the value that
- *     fed the shell,
- *   - writes (set/setItem/putResponse) — the value a MISS computed and baked.
- * The shell family (getShell/putShell) is never recorded (the snapshot rides
- * inside a shell entry). Reads that MISS are not recorded (a miss produced no
- * shell content; if the render then computed and wrote, that write is recorded).
+ * A store wrapper the CAPTURE render reads through. Every call passes through
+ * to the underlying store unchanged; the one thing it records is the doc
+ * segment record ({@link recordSegmentWrite}). No cache read is recorded: a
+ * HIT replays the handler layer from the doc record and serves a promise-free
+ * bake-lane loader from its pin, and everything else a HIT reads (a hole, a
+ * bake-lane loader body that runs there) comes from the store.
  *
  * Deferred writes: cache writes run under waitUntil (fire-and-forget on Node,
- * executionContext on workerd), so their setItem/set calls — hence their records
- * — may land after the shell has quiesced. The capture collects those write
- * promises via {@link trackWrite} and awaits them ({@link settleWrites}) before
- * draining, so a MISS-at-capture value is still pinned.
+ * executionContext on workerd), so the doc record's write may land after the
+ * capture's match returns. The capture collects those write promises via
+ * {@link trackWrite} and awaits them ({@link settleWrites}) before reading the
+ * record and draining.
  */
 export declare class RecordingShellStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     private readonly inner;
+    /** The recorded segment records by key, last write wins. */
     private readonly records;
     private readonly writes;
     constructor(inner: SegmentCacheStore<TEnv>);
     get defaults(): SegmentCacheStore<TEnv>["defaults"];
     get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
     get supportsPassiveShellReads(): true | undefined;
-    private record;
+    get isTagsInvalidatedSince(): SegmentCacheStore<TEnv>["isTagsInvalidatedSince"];
     /** Track a deferred cache-write promise so the capture can await it pre-drain. */
     trackWrite(p: Promise<unknown>): void;
     /**
-     * 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
+     * Record the doc segment record into the snapshot WITHOUT touching the
+     * inner store. The capture's implicit doc-cache scope writes through this
+     * (via {@link SnapshotOnlySegmentStore}): the record 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;
     /**
-     * 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
-     * cacheRoute path schedules its actual store.set in a second waitUntil while the
-     * first is running), so each awaited batch may enqueue more. Loop until the
-     * queue empties or the deadline passes. Bounded: a pathologically slow write
-     * must never stall the capture task, so a key that does not settle in time is
-     * left unpinned (it drifts, the pre-snapshot behavior) rather than hanging.
+     * Await the tracked deferred writes so their records are present before
+     * drain, including a NESTED write a settled one scheduled (the ring-3
+     * cacheRoute path schedules its actual store.set in a second waitUntil).
+     * Bounded: a pathologically slow write must never stall the capture task.
+     * Resolves true when every tracked write settled, false at the deadline
+     * (settleCaptureRecord then fails the capture when the doc record is among
+     * the writes still pending); a later call still waits for what is pending.
      */
-    settleWrites(timeoutMs: number): Promise<void>;
-    /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
+    settleWrites(timeoutMs: number): Promise<boolean>;
+    /** The recorded segment records, or undefined if none. */
     drainSnapshot(): ShellSnapshotRecord[] | undefined;
+    /** One recorded segment record, by key. */
+    getRecord(key: string): CachedEntryData | undefined;
     get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
     delete(key: string): Promise<boolean>;
@@ -93,16 +91,61 @@ export declare class RecordingShellStore<TEnv = unknown> implements SegmentCache
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }
-/** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
+/** `store` when it is a RecordingShellStore (an instanceof check). */
 export declare function getRecordingStore<TEnv>(store: SegmentCacheStore<TEnv> | undefined): RecordingShellStore<TEnv> | 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).
+ * True when `snapshot` carries the canonical doc segment record `docKey`
+ * names, with at least one segment: the record partial replay and a document
+ * HIT tail consume.
+ */
+export declare function hasDocRecord(snapshot: readonly ShellSnapshotRecord[] | undefined, docKey: string | undefined): boolean;
+/**
+ * Split a capture's snapshot into what a HIT or a partial replay reads and
+ * the rest (docs/design/shell-entry-layout.md §2). Kept: the doc record
+ * (`docKey`), as a copy inside the entry (a separately stored record could be
+ * evicted on its own, and the HIT would have nothing to replay), and the
+ * loader-family pins unless the entry is navigation-only (partial replay of
+ * such an entry seeds the doc record alone). Every other record goes.
+ */
+export declare function pruneShellSnapshot(snapshot: readonly ShellSnapshotRecord[], navigationOnly: boolean, docKey: string | undefined): {
+    kept: ShellSnapshotRecord[];
+    pruned: ShellSnapshotRecord[];
+};
+/**
+ * The shell entry head's fields estimateShellEntryBytes does not measure
+ * (versions, timestamps, theme, lengths, flags; about 200 bytes in a
+ * CFCacheStore frame) and the frame's 12-byte prefix, with room to spare.
+ */
+export declare const SHELL_ENTRY_HEAD_ALLOWANCE_BYTES: number;
+/**
+ * Bytes (UTF-8) a stored shell entry takes, as the built-in stores write it:
+ * the prelude, the snapshot's JSON, and a JSON head that carries the
+ * postponed state as an escaped string next to the tags and doc key
+ * (CFCacheStore's frame head, VercelCacheStore's envelope), plus
+ * SHELL_ENTRY_HEAD_ALLOWANCE_BYTES for the head's fixed fields and the
+ * frame prefix. Measuring the raw postponed bytes undercounted: every quote
+ * in it is escaped in the head (a /ppr-large/holes entry measured 1,098
+ * bytes under its KV value). The capture's whole-entry guard compares this
+ * with the store's value limit.
+ */
+export declare function estimateShellEntryBytes(parts: {
+    preludeBytes: number;
+    postponed: string | null | undefined;
+    snapshot: readonly ShellSnapshotRecord[] | undefined;
+    tags: readonly string[] | undefined;
+    docKey: string | undefined;
+    prunedRecords: string | undefined;
+}): number;
+/** Snapshot records by family, e.g. `segment:1/loader:2` (no commas: it rides a Server-Timing desc). */
+export declare function countSnapshotFamilies(snapshot: readonly ShellSnapshotRecord[]): string;
+/**
+ * The store the capture's IMPLICIT doc-cache scope resolves: reads pass
+ * through the recording store to the real one, but segment WRITES are
+ * recorded into the snapshot only — see
+ * {@link RecordingShellStore.recordSegmentWrite} for why passthrough would
+ * break SWR recapture. A route with its OWN cache() scope keeps that scope's
+ * real-store reads and writes; recordShellCaptureDocRecord (cache-store.ts)
+ * writes its doc record through this store too.
  */
 export declare class SnapshotOnlySegmentStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     private readonly recording;
@@ -113,74 +156,67 @@ export declare class SnapshotOnlySegmentStore<TEnv = unknown> implements Segment
     set(key: string, data: CachedEntryData): Promise<void>;
     delete(key: string): Promise<boolean>;
 }
+/** One decoded loader-family pin (buildShellLoaderSeed). */
+export interface ShellLoaderSeedEntry {
+    /** The Flight-deserialized elided container (recorded paths + markers). */
+    container: unknown;
+    /**
+     * True when the record carries hole markers: 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;
+    /**
+     * The record needs its loader body to run on a HIT for pushes the capture
+     * could not record (ShellSnapshotLoaderValue.runs). Only read for a
+     * hole-free record: a hole-carrying one always runs.
+     */
+    runs: boolean;
+}
 /**
  * Materialize the loader-family seed from a shell snapshot for a HIT's tail
  * render: Flight-deserialize each recorded (promise-elided) bake-lane
  * container into a segment-key -> container Map, which serveShellHit assigns
  * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
- * Lives here so every snapshot family is decoded in this module (the
- * item/segment/response families via {@link SeededShellStore}); the loader
- * family is not a store read, so it seeds the context instead of a store.
+ * Lives here so every snapshot family is decoded in this module (the segment
+ * family via {@link SeededShellStore}); the loader family is not a store
+ * read, so it seeds the context instead of a store.
  *
  * Deserializations run in parallel; a record that fails to decode is skipped
  * (that loader drifts — the pre-snapshot behavior — instead of failing the
  * 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 declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[]): Promise<Map<string, ShellLoaderSeedEntry> | undefined>;
 /**
- * A read-through overlay the HIT tail render reads through. For a key present in
- * the snapshot it serves the recorded value AS FRESH (shouldRevalidate: false —
- * a pinned key must NOT kick SWR background revalidation) so the tail's payload
- * matches the frozen prelude. Every other read falls through to the real store
- * (the holes — masked loaders were never recorded — stay live). Writes pass
- * through so a live hole may legitimately write, except that `segmentsOnly`
- * fully isolates the segment family: misses do not fall through, and writes or
- * deletes stay local to the navigation overlay. The shell family always passes
- * through. With `segmentsOnly`, item and response reads also pass through so a
- * partial navigation cannot freeze captured data or write a partial result into
- * the canonical document namespace.
+ * The implicit doc scope's store on a HIT tail and on a partial replay: it
+ * serves the snapshot's segment records, the doc record among them, and
+ * fully isolates the segment family. Misses do not fall through, and writes
+ * or deletes stay local to the overlay, so a partial navigation cannot write
+ * a partial result into the canonical document namespace. It carries nothing
+ * else: every other read on a HIT (a hole, a bake-lane loader body that runs
+ * there) resolves the request's own store. Loader-family records are not
+ * store reads: serveShellHit seeds them onto the tail context
+ * (_shellLoaderSeed) for the resolveLoaderData overlay instead.
  */
 export declare class SeededShellStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     private readonly inner;
-    private readonly items;
     private readonly segments;
-    private readonly responses;
-    private readonly segmentsOnly;
-    constructor(inner: SegmentCacheStore<TEnv>, snapshot: ShellSnapshotRecord[], options?: {
-        segmentsOnly?: boolean;
-    });
+    constructor(inner: SegmentCacheStore<TEnv>, snapshot: readonly ShellSnapshotRecord[]);
     get defaults(): SegmentCacheStore<TEnv>["defaults"];
     get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
-    get supportsPassiveShellReads(): true | undefined;
     get(key: string): Promise<CacheGetResult | null | CacheReadError>;
-    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    set(key: string, data: CachedEntryData): Promise<void>;
     delete(key: string): Promise<boolean>;
-    clear(): Promise<void>;
-    getResponse(key: string): Promise<{
-        response: Response;
-        shouldRevalidate: boolean;
-    } | null>;
-    putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
-    getItem(key: string): Promise<CacheItemResult | null>;
-    setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
-    getShell(key: string, options?: {
-        claimRevalidation?: boolean;
-    }): Promise<{
-        entry: ShellCacheEntry;
-        shouldRevalidate?: boolean;
-    } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
-    invalidateTags(tags: string[]): Promise<void>;
+}
+/**
+ * Thrown by a document HIT tail's match when its doc record cannot supply the
+ * handler layer (it failed to decode, or the entry lost it). The tail must not
+ * run handlers after the prelude committed, so withCacheLookup throws this
+ * instead of resolving segments, and serveShellHit degrades the response:
+ * the entry is replaced with a tombstone, the memo is dropped, a recapture is
+ * scheduled, and the browser reloads into a MISS.
+ */
+export declare class ShellRecordUnavailableError extends Error {
+    constructor(docKey: string | undefined);
 }

package/dist/types/cache/tag-invalidation.d.ts

@@ -21,7 +21,56 @@
  * primitive for each tag. A single configured store (the common case) owns its
  * own tag index and distributed invalidation - there is no separate
  * tag-invalidation store.
+ *
+ * Both call invalidateTags() synchronously, inside the request (#973). A store
+ * masks the tags for the rest of the request before its first await (the
+ * built-in stores write their per-request marker state there), so the request
+ * that ran either verb reads its own writes; revalidateTag() leaves only the
+ * durable remainder (KV marker put, tag purge, expireTag) to waitUntil.
+ * Invariant: the mask only turns the invalidating request's hits into misses.
+ * If the durable write then fails, that request paid extra misses, never a
+ * stale read, and other requests read the durable state. Both also record
+ * the tags in the isolate's invalidation order (markInvalidated), so a cache
+ * execution that started before one of its tags was invalidated, in any
+ * request, is neither joined nor written (#973, #977): see
+ * predatesInvalidation, and docs/design/caching.md "Read-your-own-writes".
+ */
+import type { SegmentCacheStore } from "./types.js";
+import { type ExecutionStart } from "./invalidation-order.js";
+export { executionStart, invalidatedSince, type ExecutionStart, } from "./invalidation-order.js";
+/**
+ * The write gate of every cache execution (#977): whether one of `tags` was
+ * invalidated after the execution that produced the value started.
+ *
+ * Every built-in store stamps an entry when it is written (CFCacheStore's
+ * `taggedAt`, VercelCacheStore's `ta`) or checks nothing on write
+ * (MemorySegmentCacheStore), so a value read before an invalidation and
+ * written after it would be served as newer than the invalidation until it
+ * expires. Two answers, either one skips the write:
+ *
+ * - this isolate's order (invalidatedSince), which sees every request's
+ *   updateTag()/revalidateTag() here, the calling one included;
+ * - the store's markers (isTagsInvalidatedSince), for another isolate's
+ *   invalidation, as far as the store can tell: KV markers on CFCacheStore
+ *   (KV-less, only this request's own), `tm` markers on VercelCacheStore,
+ *   the process markers on MemorySegmentCacheStore. Asked about the
+ *   milliseconds after the start's: this isolate's own invalidation that
+ *   preceded the start usually shares its millisecond (Workers freeze
+ *   Date.now() between I/O), and `>=` would skip every write started right
+ *   after it. Another isolate's invalidation in the start's own millisecond
+ *   is not caught. Asked fail-closed: a marker the store cannot read
+ *   counts as an invalidation.
+ *
+ * The order is read again once the store answers: its read can be in flight
+ * while this isolate invalidates (an action awaits a "use cache" miss, whose
+ * write waits on the read, then runs updateTag()), and it then answers with
+ * the markers from before. markInvalidated is synchronous, so this second
+ * look sees every invalidation made before the answer.
+ *
+ * Invariant: a skipped write only costs a later miss, never a stale read.
+ * The caller still returns the value it computed.
  */
+export declare function predatesInvalidation(store: SegmentCacheStore, tags: readonly string[] | undefined, start: ExecutionStart): Promise<boolean>;
 /**
  * Immediately expire every cache entry tagged with any of `tags`, resolving
  * once in-process invalidation across all configured stores completes.
@@ -47,10 +96,12 @@ export declare function updateTag(...tags: string[]): Promise<void>;
  * This is NOT stale-while-revalidate: like updateTag() it hard-purges, so the
  * next read after the invalidation lands is a miss that re-renders fresh. The
  * only difference from updateTag() is awaitability - revalidateTag() defers the
- * purge off the response path and is not awaited.
+ * durable write off the response path and is not awaited.
  *
- * Use in Route Handlers / webhooks. For read-your-own-writes inside a Server
- * Action, use updateTag() instead so the action's own response is fresh.
+ * Read-your-own-writes (#973): each built-in store masks the tags for the rest
+ * of this request before revalidateTag() returns, so a Server Action's own
+ * re-render after it is fresh, as after `await updateTag()`. Other requests see
+ * the invalidation once the durable write lands.
  *
  * Fire-and-forget: because this returns void and runs in the background, a
  * failed durable marker write (e.g. a transient KV outage) is NOT surfaced to