@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/cache/memory-segment-store.d.ts

@@ -0,0 +1,163 @@
+/**
+ * In-Memory Segment Cache Store
+ *
+ * Simple in-memory implementation of SegmentCacheStore.
+ * Uses globalThis to survive HMR in development.
+ */
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "./types.js";
+import type { RequestContext } from "../server/request-context.js";
+/**
+ * Options for MemorySegmentCacheStore
+ */
+export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
+    /**
+     * Optional name for this store instance. Named stores persist their
+     * backing Map on globalThis so data survives Vite HMR module reloads.
+     * Stores with different names get separate Maps.
+     *
+     * When omitted, the store uses a plain instance-level Map with no
+     * globalThis sharing, which is the safest default for isolation.
+     *
+     * Caveat: two instances constructed with the SAME name share all backing maps
+     * (data + tag index), but each keeps its OWN `defaults` and `keyGenerator` from
+     * its options - those are not shared. Use one instance per name, or keep the
+     * options identical, to avoid surprising divergence.
+     *
+     * @example
+     * ```typescript
+     * // Two named stores are isolated from each other
+     * const fast = new MemorySegmentCacheStore({ name: "fast", defaults: { ttl: 10 } });
+     * const slow = new MemorySegmentCacheStore({ name: "slow", defaults: { ttl: 300 } });
+     * ```
+     */
+    name?: string;
+    /**
+     * Default cache options for cache() boundaries.
+     * When cache() is called without explicit ttl/swr,
+     * these defaults are used.
+     *
+     * @example
+     * ```typescript
+     * const store = new MemorySegmentCacheStore({
+     *   defaults: { ttl: 60, swr: 300 }
+     * });
+     * ```
+     */
+    defaults?: CacheDefaults;
+    /**
+     * Custom key generator applied to all cache operations.
+     * Receives the full RequestContext and the default-generated key.
+     *
+     * @example
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const locale = cookies().get('locale')?.value || 'en';
+     *   return `${locale}:${defaultKey}`;
+     * }
+     * ```
+     */
+    keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /**
+     * Maximum number of entries kept per internal family (segment, response,
+     * item, shell). On insert, once a family reaches the cap its oldest entry is
+     * evicted FIFO (insertion order) and its tag-index entries are cleaned up, so
+     * a long-lived instance can't grow without bound. Lazy TTL expiry still runs
+     * independently. Defaults to DEFAULT_MAX_ENTRIES (1000).
+     *
+     * @example
+     * ```typescript
+     * const store = new MemorySegmentCacheStore({ maxEntries: 500 });
+     * ```
+     */
+    maxEntries?: number;
+}
+/**
+ * In-memory segment cache store.
+ *
+ * Suitable for development and single-instance deployments.
+ * For production with multiple instances, use a distributed store
+ * like Cloudflare KV or Redis.
+ *
+ * Each family is size-capped at `maxEntries` (default 1000) with FIFO eviction
+ * on insert, so a long-lived instance can't grow unbounded; TTL expiry stays
+ * lazy on top of that.
+ *
+ * Tag-index cleanup is lazy, mirroring the data maps: a tagged entry that
+ * expires but is never re-read or invalidated leaves its forward+reverse index
+ * entries resident until the key is reused, invalidated, or FIFO-evicted. This
+ * is bounded by the distinct-tag count and acceptable for a dev/single-instance
+ * store. FIFO eviction unregisters the evicted key's tags, so the tag maps do
+ * not outlive the capped data maps.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const store = new MemorySegmentCacheStore();
+ *
+ * // With defaults for cache() boundaries
+ * const store = new MemorySegmentCacheStore({
+ *   defaults: { ttl: 60 }
+ * });
+ *
+ * createRSCHandler({
+ *   router,
+ *   cache: { store }
+ * })
+ * ```
+ */
+export declare class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    readonly supportsPassiveShellReads: true;
+    private cache;
+    private responseCache;
+    private itemCache;
+    private shellCache;
+    /** tag -> set of prefixed cache keys (seg:key, res:key, item:key, shell:key) */
+    private tagIndex;
+    /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
+    private keyTags;
+    /**
+     * tag -> epoch ms of its latest invalidateTags() call. Runtime capture races
+     * and immutable build shells are gated by comparing these markers with the
+     * shell generation start. Per-isolate, like every other map here.
+     */
+    private tagInvalidatedAt;
+    readonly defaults?: CacheDefaults;
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /** Per-family FIFO entry cap. */
+    readonly maxEntries: number;
+    constructor(options?: MemorySegmentCacheStoreOptions<TEnv>);
+    /**
+     * FIFO cap enforcement, called before inserting `incomingKey` into `map`.
+     * When the key is new and the family is at capacity, the oldest entries are
+     * evicted in insertion order and their tag-index entries unregistered (so the
+     * tag maps don't outlive the capped data map). Overwriting an existing key
+     * grows nothing, so it is a no-op.
+     */
+    private evictIfNeeded;
+    get(key: string): Promise<CacheGetResult | null>;
+    set(key: string, data: CachedEntryData, ttl: number, _swr?: number): 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): Promise<{
+        entry: ShellCacheEntry;
+        shouldRevalidate?: boolean;
+    } | null>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated">;
+    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    private tagsInvalidatedSince;
+    invalidateTags(tags: string[]): Promise<void>;
+    private registerTags;
+    private unregisterTags;
+    getStats(): {
+        size: number;
+        keys: string[];
+    };
+    static resetGlobalCache(): void;
+}

package/dist/types/cache/profile-registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cache profile resolution.
+ *
+ * Named cache profiles for the "use cache" directive define TTL, SWR, and
+ * optional default tags. createRouter() resolves the user's profiles once via
+ * resolveCacheProfiles() and threads the resulting map onto each request
+ * context; the "use cache: <profile>" runtime path reads it from there
+ * (request-scoped) — there is no global registry.
+ */
+export interface CacheProfile {
+    /** Time-to-live in seconds */
+    ttl: number;
+    /** Stale-while-revalidate window in seconds */
+    swr?: number;
+    /** Default cache tags for invalidation */
+    tags?: string[];
+    /**
+     * When true, a stale entry encountered during a server action's revalidation
+     * render is re-executed in the FOREGROUND (the action response reflects the
+     * refreshed value) instead of being served stale + revalidated in the
+     * background. Only the store write is deferred. Use this for mutation-related
+     * cached data that an action should refresh immediately; ordinary navigations
+     * always keep SWR. Default false: incidental TTL staleness must not turn an
+     * unrelated action into a synchronous cache-refresh barrier — for strong
+     * read-your-own-writes after a mutation, prefer updateTag() (a hard purge, so
+     * the action's own re-render is a fresh foreground miss).
+     *
+     * Honored only by `"use cache"` functions; route-level `cache()` and cached
+     * loaders ignore it (use updateTag() there).
+     */
+    foregroundOnAction?: boolean;
+}
+/**
+ * Validate and merge user profiles with the default profile.
+ * Returns a new object suitable for both DSL-time and request-scoped use.
+ *
+ * Used by createRouter() to compute the resolved profile map once,
+ * stored on the router instance and passed to every request context.
+ */
+export declare function resolveCacheProfiles(profiles?: Record<string, CacheProfile>): Record<string, CacheProfile>;

package/dist/types/cache/read-through-swr.d.ts

@@ -0,0 +1,60 @@
+/**
+ * SWR Read-Through Engine
+ *
+ * Generic read-through cache with stale-while-revalidate support
+ * for item-level caching (getItem/setItem).
+ *
+ * Flow:
+ * 1. Lookup cached item by key
+ * 2. Fresh hit → deserialize, return
+ * 3. Stale hit → deserialize, return, revalidate in background
+ * 4. Miss → execute, cache write (blocking when no waitUntil), return
+ */
+import type { CacheItemResult, CacheItemOptions } from "./types.js";
+import type { CacheErrorReporter } from "./cache-error.js";
+type WaitUntilHost = {
+    waitUntil?: (fn: () => Promise<void>) => void;
+} & CacheErrorReporter;
+export interface ReadThroughItemConfig<T> {
+    /** Retrieve a cached item by key */
+    getItem: (key: string) => Promise<CacheItemResult | null>;
+    /** Store a serialized item by key */
+    setItem: (key: string, value: string, options?: CacheItemOptions) => Promise<void>;
+    /** Cache key */
+    key: string;
+    /** Execute the underlying function/loader on miss or revalidation */
+    execute: () => Promise<T>;
+    /**
+     * Optional wrapper applied to execute() ONLY on the background
+     * stale-revalidation path (not the foreground miss, where the caller's context
+     * is already established). Used to re-establish the request-context ALS, which
+     * a detached waitUntil task loses on workerd. Defaults to calling execute()
+     * directly.
+     */
+    wrapBackground?: (run: () => Promise<T>) => Promise<T>;
+    /** Serialize result for storage. Return null to skip caching. */
+    serialize: (data: T) => Promise<string | null>;
+    /** Deserialize cached value back to the original type */
+    deserialize: (value: string) => Promise<T>;
+    /** Options passed to setItem on cache write */
+    storeOptions: CacheItemOptions;
+    /** Called on fresh cache hit (before returning data) */
+    onHit?: (cached: CacheItemResult) => void;
+    /** Called on stale cache hit (before scheduling background revalidation) */
+    onStale?: (cached: CacheItemResult) => void;
+    /** Called on cache miss (before executing) */
+    onMiss?: () => void;
+    /** Called after successful cache write */
+    onCached?: () => void;
+    /** Host with optional waitUntil for background tasks */
+    host?: WaitUntilHost | null;
+}
+/**
+ * Read-through cache with SWR support for item-level caching.
+ *
+ * On fresh hit: returns deserialized cached data.
+ * On stale hit: returns stale data, schedules background revalidation.
+ * On miss: executes, writes to cache (blocking when no waitUntil), returns.
+ */
+export declare function readThroughItem<T>(config: ReadThroughItemConfig<T>): Promise<T>;
+export {};

package/dist/types/cache/segment-codec.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Segment Codec
+ *
+ * RSC serialization/deserialization for cached segments.
+ * Handles the Flight protocol stream <-> string conversion
+ * and the segment-level encode/decode lifecycle.
+ */
+import type { ResolvedSegment } from "../types.js";
+import type { SerializedSegmentData } from "./types.js";
+/**
+ * Convert a ReadableStream to a string.
+ */
+export declare function streamToString(stream: ReadableStream<Uint8Array>): Promise<string>;
+/**
+ * Convert a string to a ReadableStream.
+ */
+export declare function stringToStream(str: string): ReadableStream<Uint8Array>;
+/**
+ * RSC-serialize a value using React Server Components stream.
+ * Used for serializing loaderData, layout, loading components etc.
+ *
+ * Returns undefined for null/undefined inputs (component fields that are absent).
+ * For contexts where null is a valid result (loader caching, "use cache"),
+ * use serializeResult() instead which preserves null through RSC Flight.
+ */
+export declare function rscSerialize(value: unknown): Promise<string | undefined>;
+/**
+ * RSC-deserialize a value from a stored string.
+ */
+export declare function rscDeserialize<T>(encoded: string | undefined): Promise<T | undefined>;
+/**
+ * RSC-serialize any value including null.
+ * Unlike rscSerialize(), this does NOT skip null — it serializes it through
+ * RSC Flight so that a loader returning null produces a valid cached entry
+ * rather than a permanent cache miss.
+ *
+ * Returns null only on serialization failure.
+ */
+export declare function serializeResult(value: unknown): Promise<string | null>;
+/**
+ * RSC-deserialize a cached result string.
+ * Counterpart to serializeResult() — always receives a non-empty string.
+ */
+export declare function deserializeResult<T>(encoded: string): Promise<T>;
+/**
+ * RSC-deserialize a single encoded component string back to a React element.
+ * Used by the static handler runtime to revive pre-rendered components.
+ * Identical to deserializeResult<unknown>.
+ */
+export declare const deserializeComponent: (encoded: string) => Promise<unknown>;
+/**
+ * Serialize segments for storage.
+ * Each segment's component, layout, loading, and loaderData are RSC-serialized.
+ * Metadata is preserved as-is.
+ */
+export declare function serializeSegments(segments: ResolvedSegment[]): Promise<SerializedSegmentData[]>;
+/**
+ * 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 declare function fragmentSegments(data: SerializedSegmentData[]): Promise<ResolvedSegment[]>;
+/**
+ * Deserialize segments from storage.
+ * Reconstructs ResolvedSegment objects from RSC-serialized data.
+ */
+export declare function deserializeSegments(data: SerializedSegmentData[]): Promise<ResolvedSegment[]>;

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

@@ -0,0 +1,186 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord } 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).
+ *
+ * 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.
+ */
+export declare class RecordingShellStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    private readonly inner;
+    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;
+    /** 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
+     * 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.
+     */
+    settleWrites(timeoutMs: number): Promise<void>;
+    /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
+    drainSnapshot(): ShellSnapshotRecord[] | undefined;
+    get(key: string): Promise<CacheGetResult | null>;
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): 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" | void>;
+    invalidateTags(tags: string[]): Promise<void>;
+}
+/** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
+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).
+ */
+export declare class SnapshotOnlySegmentStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    private readonly recording;
+    constructor(recording: RecordingShellStore<TEnv>);
+    get defaults(): SegmentCacheStore<TEnv>["defaults"];
+    get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
+    get(key: string): Promise<CacheGetResult | null>;
+    set(key: string, data: CachedEntryData): Promise<void>;
+    delete(key: string): Promise<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.
+ *
+ * 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.
+ */
+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;
+    });
+    get defaults(): SegmentCacheStore<TEnv>["defaults"];
+    get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
+    get supportsPassiveShellReads(): true | undefined;
+    get(key: string): Promise<CacheGetResult | null>;
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): 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" | void>;
+    invalidateTags(tags: string[]): Promise<void>;
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Cache Tag Invalidation API
+ *
+ * Two on-demand invalidation verbs, mirroring the distinction popularized by
+ * Next.js so consumers can pick the right consistency model:
+ *
+ * - updateTag(...tags): read-your-own-writes. Awaitable - resolves only after
+ *   in-process invalidation across every configured store completes. Use in a
+ *   Server Action and `await` it before the action re-renders, so the action's
+ *   own response reflects the mutation.
+ *
+ * - revalidateTag(...tags): fire-and-forget via waitUntil - the response is not
+ *   blocked. Use in Route Handlers / webhooks. NOTE: both verbs hard-purge; the
+ *   only difference is awaitability. revalidateTag does NOT serve stale content -
+ *   the next read after the invalidation lands is a hard miss that re-renders.
+ *   (The name mirrors Next.js, where it is SWR; here it is background-purge.)
+ *
+ * Both fan out across the app-level store (ctx._cacheStore) and every explicit
+ * per-scope store from cache({ store }) registered for this handler
+ * (ctx._explicitTaggedStores), calling the store-level invalidateTags()
+ * 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.
+ */
+/**
+ * Immediately expire every cache entry tagged with any of `tags`, resolving
+ * once in-process invalidation across all configured stores completes.
+ *
+ * Read-your-own-writes: because the returned promise resolves before you return
+ * from a Server Action, awaiting it guarantees the action's own re-render (and
+ * any subsequent read) sees fresh data.
+ *
+ * @example
+ * ```typescript
+ * async function updateProduct(formData: FormData) {
+ *   "use server";
+ *   await db.updateProduct(formData);
+ *   await updateTag("products");   // next render is fresh
+ * }
+ * ```
+ */
+export declare function updateTag(...tags: string[]): Promise<void>;
+/**
+ * Invalidate every cache entry tagged with any of `tags` in the background,
+ * without blocking the current response (fire-and-forget via waitUntil).
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * the caller. It IS reported - logged loudly and routed through the router's
+ * `onError` callback (phase `cache`, `metadata.category === "cache-invalidate"`)
+ * via reportingAsync - so the failure is observable in telemetry even though it
+ * cannot be awaited. If you need the invalidation to be CONFIRMED (and to retry
+ * on failure), use `await updateTag()` instead, which rejects when a store's
+ * durable write fails.
+ *
+ * @example
+ * ```typescript
+ * // route handler invoked by an external webhook
+ * export async function POST() {
+ *   "use server";
+ *   revalidateTag("products");
+ *   return new Response("ok");
+ * }
+ * ```
+ */
+export declare function revalidateTag(...tags: string[]): void;

package/dist/types/cache/taint.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Taint symbol for request-scoped objects.
+ *
+ * Objects branded with NOCACHE_SYMBOL (ctx, env, req) are excluded from
+ * "use cache" cache keys and trigger handle capture mode so that side
+ * effects (breadcrumbs, metadata) are recorded and replayed on cache hit.
+ */
+export declare const NOCACHE_SYMBOL: unique symbol;
+/**
+ * Check if a value is tainted (request-scoped, should not be in cache key).
+ */
+export declare function isTainted(value: unknown): boolean;
+/**
+ * Symbol stamped on tainted ctx during "use cache" function execution.
+ * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
+ * throw if present — reads would cache per-request data under a shared key,
+ * and side effects would be lost on cache hit.
+ *
+ * The value is a numeric reference count, not a boolean. Multiple concurrent
+ * cached functions sharing the same ctx/requestCtx each increment on entry
+ * and decrement on exit. Guards fire when count > 0.
+ */
+export declare const INSIDE_CACHE_EXEC: unique symbol;
+/**
+ * Increment the INSIDE_CACHE_EXEC ref count on an object.
+ */
+export declare function stampCacheExec(obj: object): void;
+/**
+ * Decrement the INSIDE_CACHE_EXEC ref count on an object.
+ * Deletes the symbol when the count reaches zero so the `in` check
+ * used by guards no longer fires.
+ */
+export declare function unstampCacheExec(obj: object): void;
+/**
+ * Throw if ctx is inside a "use cache" execution.
+ * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.
+ */
+export declare function assertNotInsideCacheExec(ctx: unknown, methodName: string): void;
+/**
+ * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
+ * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
+ * ctx.set() (children are also cached) but blocks response-level side effects
+ * (headers, cookies, status) which are lost on cache hit.
+ */
+export declare const INSIDE_CACHE_SCOPE: unique symbol;
+/**
+ * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
+ */
+export declare function stampCacheScope(obj: object): void;
+/**
+ * Remove cache() scope mark.
+ */
+export declare function unstampCacheScope(obj: object): void;
+/**
+ * Throw if ctx is inside a cache() DSL boundary.
+ * Call from response-level side effects (header, setCookie, setStatus, etc.)
+ * which are lost on cache hit because the handler body is skipped.
+ * ctx.set() is allowed inside cache() — children are also cached and can
+ * read the value.
+ */
+export declare function assertNotInsideCacheScope(ctx: unknown, methodName: string): void;
+/**
+ * Brand symbol for functions wrapped by registerCachedFunction().
+ * Used at runtime to detect when a "use cache" function is misused
+ * (e.g., passed as middleware).
+ */
+export declare const CACHED_FN_SYMBOL: unique symbol;
+/**
+ * Check if a value is a "use cache" wrapped function.
+ */
+export declare function isCachedFunction(value: unknown): boolean;