@rangojs/router 0.17.0 → 0.18.0

package/src/cache/isolate-tag-memo.ts

@@ -0,0 +1,308 @@
+/**
+ * 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 const DEFAULT_CF_MARKER_FRESH_MS = 1000;
+/** Default freshness of a memoized marker on VercelCacheStore (ms). */
+export const DEFAULT_VERCEL_MARKER_FRESH_MS = 300;
+/** Default oldest memoized marker served while it refreshes (ms), CF. */
+export const DEFAULT_CF_MARKER_MAX_STALE_MS = 10_000;
+/**
+ * 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 const DEFAULT_VERCEL_MARKER_MAX_STALE_MS = 2000;
+/** Most tags a marker memo holds (least recently used evicted). */
+const MARKER_MEMO_MAX_ENTRIES = 4096;
+/**
+ * Most shell keys a hint map holds (least recently used evicted).
+ * @internal Exported for tests that fill the map to its cap.
+ */
+export const TAG_HINTS_MAX_ENTRIES = 2048;
+
+/** How a marker read was answered, for the debugPerformance marker row. */
+export type MarkerMemoOutcome = "fresh" | "stale" | "read" | "bypass";
+
+interface MarkerSlot {
+  value: number | null;
+  readAt: number;
+}
+
+/** 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 class TagMarkerMemo {
+  private readonly slots = new Map<string, MarkerSlot>();
+  private readonly refreshing = new Map<string, Promise<void>>();
+
+  constructor(private readonly maxEntries: number = MARKER_MEMO_MAX_ENTRIES) {}
+
+  /**
+   * 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 = Date.now(),
+  ): MarkerMemoHit | undefined {
+    if (freshMs <= 0) return undefined;
+    const slot = this.slots.get(key);
+    if (!slot) return undefined;
+    const age = now - slot.readAt;
+    if (age >= Math.max(freshMs, maxStaleMs)) return undefined;
+    this.slots.delete(key);
+    this.slots.set(key, slot);
+    return { value: slot.value, stale: age >= freshMs };
+  }
+
+  /**
+   * 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 = Date.now(),
+  ): void {
+    const held = this.slots.get(key);
+    const heldValue = held?.value ?? null;
+    const next =
+      heldValue !== null && (value === null || heldValue > value)
+        ? heldValue
+        : value;
+    this.slots.delete(key);
+    this.slots.set(key, {
+      value: next,
+      readAt: Math.max(held?.readAt ?? readStartedAt, readStartedAt),
+    });
+    if (this.slots.size > this.maxEntries) {
+      const oldest = this.slots.keys().next().value as string;
+      this.slots.delete(oldest);
+    }
+  }
+
+  /**
+   * 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 {
+    if (this.refreshing.has(key)) return;
+    const pending = (async (): Promise<void> => {
+      const startedAt = Date.now();
+      try {
+        const { value, memoize } = await read();
+        if (memoize) this.store(key, value, startedAt);
+      } catch {
+        // The next read past the stale window blocks on the store anyway.
+      } finally {
+        this.refreshing.delete(key);
+      }
+    })();
+    this.refreshing.set(key, pending);
+    keepAlive?.(pending);
+  }
+
+  /**
+   * 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.
+   */
+  async readThrough(
+    key: string,
+    fetch: (background: boolean) => Promise<MarkerFetch>,
+    options: MarkerReadThroughOptions,
+  ): Promise<number | null> {
+    if (options.freshMs <= 0) return (await fetch(false)).value;
+    if (!options.bypass) {
+      const hit = this.lookup(key, options.freshMs, options.maxStaleMs);
+      if (hit) {
+        options.onOutcome?.(hit.stale ? "stale" : "fresh");
+        if (hit.stale) this.refresh(key, () => fetch(true), options.keepAlive);
+        return hit.value;
+      }
+    }
+    const startedAt = Date.now();
+    const { value, memoize } = await fetch(false);
+    if (memoize) this.store(key, value, startedAt);
+    options.onOutcome?.(options.bypass ? "bypass" : "read");
+    return value;
+  }
+
+  clear(): void {
+    this.slots.clear();
+    this.refreshing.clear();
+  }
+}
+
+/**
+ * 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 class TagNameHints {
+  private readonly keys = new Map<string, readonly string[]>();
+
+  constructor(private readonly maxEntries: number = TAG_HINTS_MAX_ENTRIES) {}
+
+  get(key: string): readonly string[] | undefined {
+    return this.keys.get(key);
+  }
+
+  remember(key: string, tags: readonly string[] | undefined): void {
+    this.keys.delete(key);
+    if (!tags || tags.length === 0) return;
+    this.keys.set(key, tags);
+    if (this.keys.size > this.maxEntries) {
+      const oldest = this.keys.keys().next().value as string;
+      this.keys.delete(oldest);
+    }
+  }
+
+  clear(): void {
+    this.keys.clear();
+  }
+}
+
+/** The union of a key's remembered tag names and the route's static tags. */
+export function hintedTags(
+  remembered: readonly string[] | undefined,
+  routeTags: readonly string[] | undefined,
+): string[] {
+  if (!routeTags || routeTags.length === 0)
+    return remembered ? [...remembered] : [];
+  if (!remembered || remembered.length === 0) return [...routeTags];
+  return [...new Set([...remembered, ...routeTags])];
+}
+
+/**
+ * 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 function summarizeMarkerOutcomes(
+  tags: readonly string[] | undefined,
+  outcomes: ReadonlyMap<string, MarkerMemoOutcome>,
+): MarkerMemoOutcome | undefined {
+  let summary: MarkerMemoOutcome | undefined;
+  for (const tag of tags ?? []) {
+    const outcome = outcomes.get(tag);
+    if (
+      outcome &&
+      (!summary || OUTCOME_RANK[outcome] > OUTCOME_RANK[summary])
+    ) {
+      summary = outcome;
+    }
+  }
+  return summary;
+}
+
+const OUTCOME_RANK: Record<MarkerMemoOutcome, number> = {
+  fresh: 0,
+  stale: 1,
+  read: 2,
+  bypass: 3,
+};
+
+/**
+ * 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 function recordMarkerRow(
+  stats: ShellReadStats,
+  tags: readonly string[] | undefined,
+  outcomes: ReadonlyMap<string, MarkerMemoOutcome> | undefined,
+): void {
+  if (!tags || tags.length === 0) return;
+  if (outcomes) stats.markerMemo = summarizeMarkerOutcomes(tags, outcomes);
+  if (stats.markerHinted) {
+    const hinted = stats.markerHinted;
+    stats.markerHintHits = tags.filter((tag) => hinted.includes(tag)).length;
+  }
+}
+
+/**
+ * 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 function freshReadsRequired(
+  ctx: Pick<RequestContext, "_freshReads"> | undefined,
+): boolean {
+  return ctx?._freshReads === true;
+}

package/src/cache/shell-memo.ts

@@ -0,0 +1,341 @@
+/**
+ * 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 const DEFAULT_SHELL_MEMO_MS = 2000;
+
+/** Default total memo size per isolate (bytes). */
+export const DEFAULT_SHELL_MEMO_MAX_BYTES: number = 16 * 1024 * 1024;
+
+/** 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 function resolveShellMemoOptions(
+  memo: StoreMemoOptions | undefined,
+  markerDefaults: { markerFreshMs: number; markerMaxStaleMs: number },
+): ResolvedShellMemoOptions {
+  const finite = (value: number | undefined, fallback: number): number =>
+    typeof value === "number" && Number.isFinite(value) ? value : fallback;
+  return {
+    shellMs: finite(memo?.shellMs, DEFAULT_SHELL_MEMO_MS),
+    shellMaxBytes: finite(memo?.shellMaxBytes, DEFAULT_SHELL_MEMO_MAX_BYTES),
+    markerFreshMs: finite(memo?.markerFreshMs, markerDefaults.markerFreshMs),
+    markerMaxStaleMs: finite(
+      memo?.markerMaxStaleMs,
+      markerDefaults.markerMaxStaleMs,
+    ),
+  };
+}
+
+/**
+ * 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 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 function freshReadsWindowMs(
+  memo: ResolvedShellMemoOptions,
+  markerMemo: boolean,
+): number {
+  const window = Math.max(
+    memo.shellMs > 0 && memo.shellMaxBytes > 0 ? memo.shellMs : 0,
+    markerMemo && memo.markerFreshMs > 0
+      ? Math.max(memo.markerFreshMs, memo.markerMaxStaleMs)
+      : 0,
+  );
+  return window > 0 ? window + FRESH_READS_MARGIN_MS : 0;
+}
+
+/**
+ * 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 function isShellFresh(
+  staleAt: number,
+  expiresAt: number,
+  now: number = Date.now(),
+): boolean {
+  return !(staleAt > 0 && now > staleAt) && now <= expiresAt;
+}
+
+/** Whether a shell's tags include any of `tags`. */
+export function shellHasAnyTag(
+  shellTags: readonly string[] | undefined,
+  tags: readonly string[],
+): boolean {
+  return shellTags?.some((tag) => tags.includes(tag)) === true;
+}
+
+interface ShellMemoSlot<T> {
+  value: T;
+  bytes: number;
+  storedAt: number;
+  /** storedAt + the storing store's window: past it, set() sweeps the slot. */
+  expiresAt: number;
+}
+
+export class ShellMemo<T> {
+  private readonly slots = new Map<string, ShellMemoSlot<T>>();
+  private totalBytes = 0;
+
+  /**
+   * 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 = Date.now()): T | undefined {
+    if (windowMs <= 0) return undefined;
+    const slot = this.slots.get(key);
+    if (!slot) return undefined;
+    this.slots.delete(key);
+    if (now - slot.storedAt >= windowMs) {
+      this.totalBytes -= slot.bytes;
+      return undefined;
+    }
+    this.slots.set(key, slot);
+    return slot.value;
+  }
+
+  /**
+   * 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 = Date.now(),
+  ): void {
+    this.delete(key);
+    if (windowMs <= 0 || bytes > maxBytes) return;
+    for (const [other, slot] of this.slots) {
+      if (now >= slot.expiresAt) this.delete(other);
+    }
+    for (const [oldest, slot] of this.slots) {
+      if (this.totalBytes + bytes <= maxBytes) break;
+      this.slots.delete(oldest);
+      this.totalBytes -= slot.bytes;
+    }
+    this.slots.set(key, {
+      value,
+      bytes,
+      storedAt: now,
+      expiresAt: now + windowMs,
+    });
+    this.totalBytes += bytes;
+  }
+
+  delete(key: string): void {
+    const slot = this.slots.get(key);
+    if (!slot) return;
+    this.slots.delete(key);
+    this.totalBytes -= slot.bytes;
+  }
+
+  /** Drop every entry `predicate` selects. */
+  deleteWhere(predicate: (value: T) => boolean): void {
+    for (const [key, slot] of this.slots) {
+      if (predicate(slot.value)) this.delete(key);
+    }
+  }
+
+  /** Bytes currently held. */
+  get size(): number {
+    return this.totalBytes;
+  }
+
+  clear(): void {
+    this.slots.clear();
+    this.totalBytes = 0;
+  }
+}
+
+interface TagInvalidationRecord {
+  /** The latest invalidation's timestamp. */
+  at: number;
+  /** Invalidations of the tag still writing their markers or purge. */
+  pending: number;
+  /** When the record may be dropped once nothing is pending. */
+  heldUntil: number;
+}
+
+/**
+ * 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 class RecentTagInvalidations {
+  private readonly records = new Map<string, TagInvalidationRecord>();
+
+  /** An invalidation of `tags` at `at` started. */
+  begin(tags: readonly string[], at: number, now: number = Date.now()): void {
+    for (const [tag, record] of this.records) {
+      if (record.pending === 0 && now >= record.heldUntil) {
+        this.records.delete(tag);
+      }
+    }
+    for (const tag of tags) {
+      const record = this.records.get(tag);
+      if (record) {
+        record.at = Math.max(record.at, at);
+        record.pending++;
+      } else {
+        this.records.set(tag, { at, pending: 1, heldUntil: 0 });
+      }
+    }
+  }
+
+  /** The invalidation begun for `tags` settled: hold its records `holdMs`. */
+  settle(
+    tags: readonly string[],
+    holdMs: number,
+    now: number = Date.now(),
+  ): void {
+    for (const tag of tags) {
+      const record = this.records.get(tag);
+      if (!record) continue;
+      record.pending = Math.max(0, record.pending - 1);
+      record.heldUntil = Math.max(record.heldUntil, now + holdMs);
+    }
+  }
+
+  /**
+   * 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 = Date.now(),
+  ): boolean {
+    if (!tags || this.records.size === 0) return false;
+    for (const tag of tags) {
+      const record = this.records.get(tag);
+      if (!record) continue;
+      if (record.pending === 0 && now >= record.heldUntil) continue;
+      if (taggedAt === undefined || taggedAt <= record.at) return true;
+    }
+    return false;
+  }
+
+  clear(): void {
+    this.records.clear();
+  }
+}