@rangojs/router 0.17.0 → 0.19.0

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

@@ -44,21 +44,54 @@ export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>
 export declare function captureHandles(segments: ResolvedSegment[], handleStore: HandleStore): Record<string, SegmentHandleData>;
 /** The owners of captureHandles' values; undefined when none is owned. */
 export declare function captureHandleOwners(segments: ResolvedSegment[], handleStore: HandleStore): HandleOwners | undefined;
+/** How restoreHandles delivers a record's loader-owned values. */
+export interface OwnedPushDelivery {
+    /**
+     * Asked once per owner delivered through pushReplayed
+     * (setupLoaderAccess _claimLoaderPushes); an owner it refuses is skipped.
+     */
+    claim?: (loaderId: string) => boolean;
+    /**
+     * A PPR shell's record (capture, document HIT tail, navigation replay): the
+     * loaders the route runs on the live lane (liveLaneLoaderIds), marked on
+     * the store (HandleStore.markLiveLane). A hole's values are replayed
+     * unclaimed, so its own cache() HIT redelivers its entry's pushes in their
+     * place (HandleStore.redeliverReplays), and its run ending without a push
+     * drops them (HandleStore.settleLoaderRun).
+     */
+    liveLane?: ReadonlySet<string>;
+    /**
+     * A document HIT tail: every owner outside `liveLane` goes through
+     * pushRestored and stands, unclaimed.
+     */
+    restore?: boolean;
+}
 /**
  * Restore handle data from a cached snapshot into the handle store.
  * Used when serving cached segments to replay their handle data: a route
  * cache() record owns its segments' arrays, so it REPLACES them.
  *
  * A segment with `owners` is replaced with empty arrays and re-pushed in
- * recorded order, an owned value through pushReplayed: the owning loader
- * re-runs on the HIT (loaders stay live), and its live pushes replace the
- * recorded ones in place instead of appending a second copy. `claim`
- * (setupLoaderAccess _claimLoaderPushes) is asked once per owner, so the
- * loader's own cache() HIT does not replay its pushes a second time
- * (loader-cache.ts replayLoaderHandles); an owner it refuses is skipped. A
- * record without owners restores as a plain replay.
+ * recorded order, an owned value through pushReplayed: if the owning loader
+ * runs (a client navigation replaying a ppr route's cache() record runs its
+ * `ssr: false` loaders), its live pushes replace the recorded ones in place
+ * instead of appending a second copy. `owned.claim` is asked once per
+ * owner, so the loader's own cache() HIT does not replay its pushes a second
+ * time (loader-cache.ts replayLoaderHandles). A record without owners
+ * restores as a plain replay.
+ *
+ * `owned.restore`: a document HIT tail restoring the shell's doc record
+ * (withCacheLookup). A bake-lane owner's values are the prelude's, so they go
+ * through pushRestored and stand: a run of that loader on the HIT (a
+ * promise-carrying `ssr: false` loader, one whose record asks for a run)
+ * reads the store, and its settled pushes are dropped, not swapped in.
+ * Nothing is claimed, so the loader's own cache() HIT still replays the
+ * pushes the record could not keep (the thenable ones pushRestored lets
+ * through). A loader the route also runs on the live lane is a hole: its
+ * values keep pushReplayed, unclaimed, and its live run replaces them
+ * (#936), even inside a restored loader's body (`owned.liveLane`).
  */
-export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, claim?: (loaderId: string) => boolean): void;
+export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery): void;
 /**
  * Append recorded handle pushes to the store, in recorded order, via push()
  * so active captures and loader-scope tagging see them like live pushes. For

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

@@ -1,6 +1,7 @@
 export type { SegmentCacheStore, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, CacheReadError, } from "./types.js";
 export { CACHE_READ_ERROR } from "./types.js";
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
+export type { StoreMemoOptions } from "./shell-memo.js";
 export { CFCacheStore, type CFCacheStoreOptions, type CFCacheDebug, type CFCacheReadDebugEvent, type KVNamespace, CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_REVALIDATING_AT_HEADER, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, createCloudflareZonePurge, type CloudflareZonePurgeOptions, } from "./cf/index.js";
 export { VercelCacheStore, type VercelCacheStoreOptions, type VercelRuntimeCache, type VercelCacheDebug, type VercelCacheReadDebugEvent, type VercelCacheReadOutcome, VERCEL_MAX_ITEM_BYTES, VERCEL_MAX_TAGS_PER_ITEM, VERCEL_MAX_TAG_BYTES, } from "./vercel/index.js";
 export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./search-params-filter.js";

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

@@ -0,0 +1,23 @@
+/**
+ * Where a cache execution ("use cache", a loader's own cache(), a route
+ * cache() render, a request's document) started: its position in this
+ * isolate's order, and the store clock for invalidations this isolate did
+ * not see.
+ */
+export interface ExecutionStart {
+    readonly seq: number;
+    readonly at: number;
+}
+/** Record an execution's start, before it reads its data. */
+export declare function executionStart(): ExecutionStart;
+/**
+ * Whether this isolate invalidated any of `tags` after `since` (the `seq` of
+ * an ExecutionStart), in any request: the execution's value may predate the
+ * invalidation, so it is neither joined nor written (#973, #977).
+ */
+export declare function invalidatedSince(tags: readonly string[] | undefined, since: number): boolean;
+/**
+ * Record an invalidation of `tags` in this isolate's order
+ * (updateTag()/revalidateTag(), before any store sees it).
+ */
+export declare function markInvalidated(tags: readonly string[]): void;

package/dist/types/cache/isolate-tag-memo.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Per-isolate tag-marker memos shared by the built-in stores (issue #941;
+ * docs/design/shell-entry-layout.md "The tag-marker memo").
+ *
+ * A tagged shell HIT waits for its tag-invalidation markers before the first
+ * byte. Two things here shorten that wait:
+ *
+ * - {@link TagNameHints}: which tag NAMES a shell key carried last time, so a
+ *   HIT can start the marker reads alongside the entry read instead of after
+ *   the entry's head names its tags. Never marker values.
+ * - {@link TagMarkerMemo}: the marker VALUES (a tag's latest invalidatedAt,
+ *   or null), served stale-while-revalidate. A value younger than
+ *   `markerFreshMs` is used as is; one younger than `markerMaxStaleMs` is used
+ *   and refreshed from the store in the background; an older one blocks on
+ *   the store read as before.
+ *
+ * Simple reads get SWR; a mutation gets correct reads. The request that runs
+ * updateTag()/revalidateTag() reads its own writes through the per-request
+ * memo; the isolate that runs it writes the new value through into this memo;
+ * and its response sets the fresh-reads cookie (request-context.ts), so the
+ * same user's next requests on OTHER isolates skip this memo and the shell
+ * memo for as long as either can be stale. Other users can see a marker up to
+ * `markerMaxStaleMs` old, on top of the platform's own consistency
+ * (Cloudflare KV is eventually consistent across locations, up to about 60 s;
+ * Vercel's `tm` markers are regional).
+ *
+ * Only PPR shell reads use the value memo. Cached data families (`cache()`,
+ * `"use cache"`, responses) and the shell write gate
+ * (`isTagsInvalidatedSince`) keep reading their markers, in every request,
+ * whatever its shell read found: a shell read's memoized values never reach
+ * the data families' per-request memo (cf-tag-marker-memo.ts
+ * ShellMarkerReads).
+ */
+import type { RequestContext } from "../server/request-context.js";
+import type { ShellReadStats } from "./types.js";
+/** Default freshness of a memoized marker on CFCacheStore (ms). */
+export declare const DEFAULT_CF_MARKER_FRESH_MS = 1000;
+/** Default freshness of a memoized marker on VercelCacheStore (ms). */
+export declare const DEFAULT_VERCEL_MARKER_FRESH_MS = 300;
+/** Default oldest memoized marker served while it refreshes (ms), CF. */
+export declare const DEFAULT_CF_MARKER_MAX_STALE_MS = 10000;
+/**
+ * The same cap on VercelCacheStore: the runtime cache expires tags globally
+ * within about 300 ms, so a much longer stale window would widen that for
+ * other users more than KV's own up-to-60 s cross-location lag does on CF.
+ */
+export declare const DEFAULT_VERCEL_MARKER_MAX_STALE_MS = 2000;
+/**
+ * Most shell keys a hint map holds (least recently used evicted).
+ * @internal Exported for tests that fill the map to its cap.
+ */
+export declare const TAG_HINTS_MAX_ENTRIES = 2048;
+/** How a marker read was answered, for the debugPerformance marker row. */
+export type MarkerMemoOutcome = "fresh" | "stale" | "read" | "bypass";
+/** A memoized marker a read may use: its value, and whether it is stale. */
+export interface MarkerMemoHit {
+    value: number | null;
+    stale: boolean;
+}
+/**
+ * A store read of a marker for {@link TagMarkerMemo.readThrough}: the value,
+ * and whether it may be memoized (a timed-out read that failed open may not).
+ */
+export interface MarkerFetch {
+    value: number | null;
+    memoize: boolean;
+}
+/** Options of {@link TagMarkerMemo.readThrough}. */
+export interface MarkerReadThroughOptions {
+    /** Fresh window (ms); 0 or less reads the store and memoizes nothing. */
+    freshMs: number;
+    /** The oldest value served while it refreshes (ms). */
+    maxStaleMs: number;
+    /** The request carries the fresh-reads cookie: read the store. */
+    bypass: boolean;
+    /** Keeps a background refresh alive after the response (waitUntil). */
+    keepAlive?: (pending: Promise<void>) => void;
+    /** How the read was answered, for the debugPerformance marker row. */
+    onOutcome?: (outcome: MarkerMemoOutcome) => void;
+}
+export declare class TagMarkerMemo {
+    private readonly maxEntries;
+    private readonly slots;
+    private readonly refreshing;
+    constructor(maxEntries?: number);
+    /**
+     * The memoized marker for `key` if it is younger than `maxStaleMs` (stale
+     * when older than `freshMs`), or undefined when the caller must read the
+     * store. `freshMs <= 0` disables the memo.
+     */
+    lookup(key: string, freshMs: number, maxStaleMs: number, now?: number): MarkerMemoHit | undefined;
+    /**
+     * Record a marker the store returned to a read that started at
+     * `readStartedAt`. The age counts from the read's start, not its end: a
+     * marker written while the read was in flight may be missing from it, so
+     * the value is only known to be current as of the start. Markers only move
+     * forward, so a value older than one already held (a write-through that
+     * landed during the read) is kept at the newer value, with the later stamp.
+     */
+    store(key: string, value: number | null, readStartedAt?: number): void;
+    /**
+     * Refresh a stale marker in the background: one read per key at a time,
+     * handed to `keepAlive` (the store's waitUntil) so the runtime lets it
+     * finish after the response; without it the read runs detached. A read
+     * that fails, or may not be memoized, stores nothing.
+     */
+    refresh(key: string, read: () => Promise<MarkerFetch>, keepAlive?: (pending: Promise<void>) => void): void;
+    /**
+     * A marker through the memo, stale-while-revalidate: a value within
+     * `freshMs` is used as is; one within `maxStaleMs` is used while one
+     * background read refreshes it; otherwise, and for a request carrying the
+     * fresh-reads cookie, the store is read (`fetch(false)`) and the result
+     * memoized. `fetch(true)` is the background refresh, outside any request.
+     */
+    readThrough(key: string, fetch: (background: boolean) => Promise<MarkerFetch>, options: MarkerReadThroughOptions): Promise<number | null>;
+    clear(): void;
+}
+/**
+ * The tag names a shell key's entry carried when it was last read or written
+ * in this isolate, so the next HIT can start their marker reads before the
+ * entry names them. A wrong or missing hint costs a wasted read or nothing;
+ * the freshness check always uses the entry's own tags.
+ */
+export declare class TagNameHints {
+    private readonly maxEntries;
+    private readonly keys;
+    constructor(maxEntries?: number);
+    get(key: string): readonly string[] | undefined;
+    remember(key: string, tags: readonly string[] | undefined): void;
+    clear(): void;
+}
+/** The union of a key's remembered tag names and the route's static tags. */
+export declare function hintedTags(remembered: readonly string[] | undefined, routeTags: readonly string[] | undefined): string[];
+/**
+ * The marker row's memo outcome for a read's tags: the most store-bound one
+ * (a bypass or store read outranks a stale value, which outranks a fresh one).
+ */
+export declare function summarizeMarkerOutcomes(tags: readonly string[] | undefined, outcomes: ReadonlyMap<string, MarkerMemoOutcome>): MarkerMemoOutcome | undefined;
+/**
+ * Fill a shell read's marker-row stats (debugPerformance) for the entry's
+ * own tags: the memo outcome, and how many of them the read had hinted.
+ */
+export declare function recordMarkerRow(stats: ShellReadStats, tags: readonly string[] | undefined, outcomes: ReadonlyMap<string, MarkerMemoOutcome> | undefined): void;
+/**
+ * True when this request carries the fresh-reads cookie: a request of the same
+ * user after an updateTag()/revalidateTag(), which must not be served from an
+ * isolate memo (shell or marker) that could predate the mutation.
+ */
+export declare function freshReadsRequired(ctx: Pick<RequestContext, "_freshReads"> | undefined): boolean;

package/dist/types/cache/request-tag-mask.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The per-request tag mask behind read-your-own-writes (#973).
+ *
+ * updateTag() and revalidateTag() call a store's invalidateTags() inside the
+ * request, and a built-in store masks the tags here before its first await:
+ * every later read in that request, through any context derived from it,
+ * treats an entry carrying one of the tags, written at or before the mask, as
+ * invalidated, without waiting for the durable write (the KV marker put, the
+ * tag purge, expireTag()) that revalidateTag() leaves to waitUntil. The mask
+ * only ever turns this request's hits into misses: if the durable write then
+ * fails, the request paid extra misses, never a stale read, and other
+ * requests read the durable state. CFCacheStore and VercelCacheStore share it.
+ */
+/** Request context -> store instance -> T, both levels weakly held. */
+export type PerRequestStoreMap<T> = WeakMap<object, WeakMap<object, T>>;
+/** The value for (ctx, store), created on first use. */
+export declare function perRequestStoreValue<T>(map: PerRequestStoreMap<T>, ctx: object, store: object, create: () => T): T;
+/**
+ * The request a context belongs to: RequestContext._requestRoot, which
+ * createRequestContext defines and a derived context (Object.create: a shell
+ * capture, a PPR HIT tail) inherits. A bare test context is its own root.
+ */
+export declare function requestRoot<T extends object>(ctx: T & {
+    _requestRoot?: T;
+}): T;
+/** Mask `tags` at `at` through `store` for the rest of `ctx`'s request. */
+export declare function maskRequestTags(ctx: object, store: object, tags: readonly string[], at: number): void;
+/**
+ * Whether `ctx`'s request masked one of `tags` through `store` at or after
+ * `taggedAt`. `>=`, as the stores' marker checks: an entry written in the
+ * invalidation's millisecond may hold a value computed before it, so it
+ * misses (a false miss, never a stale read).
+ */
+export declare function maskedForRequest(ctx: object | undefined, store: object, tags: readonly string[] | undefined, taggedAt: number): boolean;
+/**
+ * A marker read for a write gate (isTagsInvalidatedSince, from
+ * tag-invalidation.ts predatesInvalidation), shared by the gates of a
+ * request that ask while it is in flight. A page's writes (its "use cache"
+ * misses, its route record, its document) finish together and often carry
+ * the same tags, and each read its own marker before: one KV or
+ * runtime-cache read per tag per write.
+ *
+ * A read answers only for invalidations before it was issued. So a gate
+ * shares one still in flight, issued at or after its execution started
+ * (`sinceMs` is the millisecond after that start), and the read is dropped
+ * once it settles: a gate asking later reads again, and a shared read
+ * leaves open at most one marker round-trip. Reusing a settled read let a
+ * gate asking long after it miss another isolate's invalidation in
+ * between (a capture's putShell answered by a "use cache" write's read
+ * from the start of the capture), and kept a timed-out read's fail-open
+ * answer for the rest of the request. Without a request context `read()`
+ * runs unshared.
+ */
+export declare function gateMarkerRead<T>(ctx: object | undefined, store: object, tag: string, sinceMs: number, read: () => Promise<T>): Promise<T>;

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

@@ -0,0 +1,178 @@
+/**
+ * Per-isolate memo of fresh PPR shell reads (issue #941, decision 1;
+ * docs/design/shell-entry-layout.md).
+ *
+ * A warm isolate serving the same shell many times a second re-reads, and
+ * re-parses, the same stored entry on every HIT. The store keeps the last
+ * fresh read per key for a short window (`memo.shellMs`) and serves the next
+ * HIT from memory. What the memo does NOT skip is the part that decides
+ * whether the entry may be served: the store still runs its tag-marker check
+ * on every read, so with KV bound `updateTag()` / `revalidateTag()` stay
+ * immediate across isolates. The isolate that runs the invalidation drops its
+ * own copies and keeps reads that were in flight from memoizing them again
+ * (RecentTagInvalidations). What another isolate can serve for up to one
+ * window: a newer capture of the same key; a KV-less purge-mode purge; on
+ * Vercel, an invalidation from another region (tag markers are regional) and
+ * a platform `expireTag` issued outside rango (it writes no tag marker).
+ *
+ * Store instances are usually created per request, so the memo must outlive
+ * them: CFCacheStore keeps one module-level memo per isolate, VercelCacheStore
+ * one per runtime-cache handle (the handle carries the namespace). One byte
+ * budget (`memo.shellMaxBytes`) caps a memo; storing sweeps entries past their
+ * window, then evicts the least recently used. Measured on a 3.2 MB shell
+ * (Node 22 heap): CFCacheStore holds 1.08x what it counts (prelude plus
+ * snapshot JSON); VercelCacheStore holds 0.93x (envelope JSON plus the
+ * decoded prelude).
+ */
+/**
+ * Per-isolate memos a built-in store keeps (`CFCacheStore`: one per isolate;
+ * `VercelCacheStore`: one per `cache` handle). A window of 0 turns that memo
+ * off.
+ */
+export interface StoreMemoOptions {
+    /**
+     * PPR shell memo window (ms): after a shell read, the next HITs of that key
+     * within the window are served from memory, with no store read and no
+     * parse. Only a fresh shell whose snapshot read completed is kept. The
+     * tag-marker check still runs on every HIT, and the isolate that runs
+     * `updateTag()` / `revalidateTag()` drops its own copies, so neither that
+     * request nor a later one on the same isolate gets the invalidated shell.
+     * What ANOTHER isolate can serve for up to one window:
+     * - a newer capture of the same key;
+     * - `CFCacheStore` without KV, in purge mode: a purged shell. The purge
+     *   removes the stored entry, not other isolates' memos;
+     * - `VercelCacheStore`: an invalidation from another region (the tag
+     *   markers are a regional `cache.set`; only `expireTag` is global), and a
+     *   platform `expireTag` issued outside rango.
+     *
+     * The mutating user is not served these: the response of a request that
+     * ran `updateTag()` / `revalidateTag()` sets the fresh-reads cookie, and
+     * requests carrying it skip the memos. Set `{ shellMs: 0, markerFreshMs: 0 }`
+     * where every user's next request must see an invalidation (with KV,
+     * `CFCacheStore`'s marker memo alone can serve an invalidated shell for up
+     * to `markerMaxStaleMs`). Default 2000.
+     */
+    shellMs?: number;
+    /**
+     * Total bytes (prelude plus snapshot) the shell memo may hold; the least
+     * recently used shells are evicted first, and a shell larger than the whole
+     * budget is not kept. Default 16 MiB. 0 turns the memo off.
+     */
+    shellMaxBytes?: number;
+    /**
+     * Tag-marker memo for PPR shell reads: a tag's invalidation marker read
+     * within this many ms is used without a store read. Default 1000 on
+     * `CFCacheStore` (with KV; without KV there are no markers), 300 on
+     * `VercelCacheStore`. 0 turns the marker memo off. Cached data families
+     * (`cache()`, `"use cache"`, responses) keep reading their markers.
+     */
+    markerFreshMs?: number;
+    /**
+     * The oldest memoized marker a shell read still uses while a background
+     * read refreshes it; an older one blocks on the store read. Default 10000
+     * on `CFCacheStore`, 2000 on `VercelCacheStore`. The isolate that runs
+     * `updateTag()` / `revalidateTag()` writes the new marker into its memo,
+     * and the response sets the fresh-reads cookie, so the same user's next
+     * requests skip both memos on any isolate.
+     */
+    markerMaxStaleMs?: number;
+}
+/** Default memo window (ms). */
+export declare const DEFAULT_SHELL_MEMO_MS = 2000;
+/** Default total memo size per isolate (bytes). */
+export declare const DEFAULT_SHELL_MEMO_MAX_BYTES: number;
+/** A store's memo options, validated. */
+export interface ResolvedShellMemoOptions {
+    shellMs: number;
+    shellMaxBytes: number;
+    markerFreshMs: number;
+    markerMaxStaleMs: number;
+}
+/**
+ * Validate a store's `memo` option; the marker memo's defaults are per store
+ * (isolate-tag-memo.ts). A non-finite value (`NaN` from `Number(env.UNSET)`,
+ * `Infinity`, null) falls back to the default, like the CFCacheStore read
+ * budgets; a finite 0 or negative passes through and turns that memo off.
+ */
+export declare function resolveShellMemoOptions(memo: StoreMemoOptions | undefined, markerDefaults: {
+    markerFreshMs: number;
+    markerMaxStaleMs: number;
+}): ResolvedShellMemoOptions;
+/**
+ * Headroom on the fresh-reads cookie's lifetime: revalidateTag() writes its
+ * markers in the background, so they can land after the response that sets
+ * the cookie, and the memos' windows count from then.
+ */
+export declare const FRESH_READS_MARGIN_MS = 1000;
+/**
+ * How long the fresh-reads cookie keeps a mutating user off a store's memos:
+ * the longest either memo can still hold a value from before the mutation
+ * (the shell window; the marker memo's max-stale cap when the store reads
+ * markers through it, counted from the start of the read that filled it),
+ * plus FRESH_READS_MARGIN_MS. 0 when both memos are off: no cookie.
+ */
+export declare function freshReadsWindowMs(memo: ResolvedShellMemoOptions, markerMemo: boolean): number;
+/**
+ * Whether a shell is neither stale nor expired: the only kind a memo keeps or
+ * serves (a stale read stays with the store, which schedules the recapture).
+ */
+export declare function isShellFresh(staleAt: number, expiresAt: number, now?: number): boolean;
+/** Whether a shell's tags include any of `tags`. */
+export declare function shellHasAnyTag(shellTags: readonly string[] | undefined, tags: readonly string[]): boolean;
+export declare class ShellMemo<T> {
+    private readonly slots;
+    private totalBytes;
+    /**
+     * The value stored under `key` less than `windowMs` ago, or undefined.
+     * A hit becomes the most recently used entry.
+     */
+    get(key: string, windowMs: number, now?: number): T | undefined;
+    /**
+     * Store `value` (`bytes` counted against `maxBytes`). Entries past their own
+     * window are dropped first, so a key that is never read again does not hold
+     * memory until the cap pushes it out; then the least recently used entries
+     * are evicted until the value fits. A value larger than the whole budget, or
+     * a window of 0, is not stored.
+     */
+    set(key: string, value: T, bytes: number, windowMs: number, maxBytes: number, now?: number): void;
+    delete(key: string): void;
+    /** Drop every entry `predicate` selects. */
+    deleteWhere(predicate: (value: T) => boolean): void;
+    /** Bytes currently held. */
+    get size(): number;
+    clear(): void;
+}
+/**
+ * Tags this isolate invalidated recently, and when. `invalidateTags()` drops
+ * the isolate's memoized shells for its tags at once, but a read that was in
+ * flight (its store read done, its snapshot still arriving) can memoize one
+ * of them again while the markers or the purge are still being written. With
+ * KV that copy is harmless (every memo hit reads the markers); in KV-less
+ * purge mode the memo-hit check sees only the request's own marker memo, so
+ * nothing would reject it for a whole window, and the mutating user's next
+ * request on this isolate got the invalidated shell.
+ *
+ * A record lives from the invalidation's start until `holdMs` after it
+ * settles, which covers a read in flight when it settled (its snapshot read
+ * is bounded by the store's read budget, 170 ms by default on CFCacheStore).
+ * While it lives, a shell carrying the tag and tagged at or before the
+ * invalidation is neither memoized nor served from the memo. It only adds
+ * rejections: a shell tagged after the invalidation is not affected, and no
+ * marker read is skipped. Records are per tag across namespaces, like the
+ * memo drop in `invalidateTags()`: another namespace's shell with the same
+ * tag skips the memo for the record's life.
+ */
+export declare class RecentTagInvalidations {
+    private readonly records;
+    /** An invalidation of `tags` at `at` started. */
+    begin(tags: readonly string[], at: number, now?: number): void;
+    /** The invalidation begun for `tags` settled: hold its records `holdMs`. */
+    settle(tags: readonly string[], holdMs: number, now?: number): void;
+    /**
+     * Whether a shell carrying `tags`, tagged at `taggedAt`, predates a live
+     * record of one of them (a tagged shell with no tag time is treated as
+     * predating it).
+     */
+    covers(tags: readonly string[] | undefined, taggedAt: number | undefined, now?: number): boolean;
+    clear(): void;
+}