@rangojs/router 0.17.0 → 0.19.0

package/src/cache/handle-snapshot.ts

@@ -134,27 +134,62 @@ export function captureHandleOwners(
   return owners;
 }
 
+/** 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 function restoreHandles(
   handles: Record<string, SegmentHandleData>,
   handleStore: HandleStore,
   owners?: HandleOwners,
-  claim?: (loaderId: string) => boolean,
+  owned?: OwnedPushDelivery,
 ): void {
   let delivers: Map<string, boolean> | undefined;
+  if (owned?.liveLane) handleStore.markLiveLane(owned.liveLane);
   for (const [segId, segHandles] of Object.entries(handles)) {
     if (Object.keys(segHandles).length === 0) continue;
     const segOwners = owners?.[segId];
@@ -173,10 +208,19 @@ export function restoreHandles(
           handleStore.push(handleName, segId, values[i]);
           continue;
         }
+        const hole = owned?.liveLane?.has(owner) === true;
+        if (owned?.restore && !hole) {
+          handleStore.pushRestored(handleName, segId, values[i], owner);
+          continue;
+        }
+        if (hole) {
+          handleStore.pushReplayed(handleName, segId, values[i], owner);
+          continue;
+        }
         delivers ??= new Map();
         let deliver = delivers.get(owner);
         if (deliver === undefined) {
-          deliver = claim ? claim(owner) : true;
+          deliver = owned?.claim ? owned.claim(owner) : true;
           delivers.set(owner, deliver);
         }
         if (deliver) {

package/src/cache/index.ts

@@ -13,6 +13,8 @@ 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,

package/src/cache/invalidation-order.ts

@@ -0,0 +1,84 @@
+/**
+ * The isolate's order of tag invalidations and cache execution starts
+ * (#973, #977): what the write gate in tag-invalidation.ts
+ * (predatesInvalidation) and the "use cache" join check read to tell whether
+ * an execution's value may predate an invalidation of one of its tags.
+ * Imports nothing, so request-context.ts can take each request's start here
+ * without a cycle through tag-invalidation.ts.
+ *
+ * - `seq` (#973): a counter, not Date.now(). Workers advance the clock only
+ *   on I/O, so an execution started right after an invalidation would share
+ *   its millisecond and read as older.
+ * - `tags` (#977): tag -> the `seq` of its latest invalidation, from every
+ *   request, oldest first. Bounded: dropping the oldest raises `forgotten`,
+ *   and an execution that started before a forgotten invalidation counts as
+ *   invalidated, whatever its tags (a miss, never a stale read).
+ *
+ * Keyed by tag name alone, not by router or store: two routers in one
+ * isolate that share a tag name skip each other's writes started before an
+ * invalidation. That costs a miss, never a stale read.
+ *
+ * On globalThis: a second evaluated copy of this module (a duplicated
+ * package, a dev re-evaluation) must read the invalidations the first one
+ * recorded, or its writers pass the gate.
+ */
+interface IsolateOrder {
+  seq: number;
+  tags: Map<string, number>;
+  forgotten: number;
+}
+const order: IsolateOrder = ((globalThis as any)[
+  Symbol.for("rangojs-router:tag-invalidation-order")
+] ??= { seq: 0, tags: new Map(), forgotten: 0 });
+const ISOLATE_INVALIDATION_HISTORY = 1024;
+
+/**
+ * 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 function executionStart(): ExecutionStart {
+  return { seq: order.seq, at: Date.now() };
+}
+
+/**
+ * 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 function invalidatedSince(
+  tags: readonly string[] | undefined,
+  since: number,
+): boolean {
+  if (!tags || tags.length === 0) return false;
+  if (since < order.forgotten) return true;
+  for (const tag of tags) {
+    const at = order.tags.get(tag);
+    if (at !== undefined && at > since) return true;
+  }
+  return false;
+}
+
+/**
+ * Record an invalidation of `tags` in this isolate's order
+ * (updateTag()/revalidateTag(), before any store sees it).
+ */
+export function markInvalidated(tags: readonly string[]): void {
+  const at = ++order.seq;
+  for (const tag of tags) {
+    order.tags.delete(tag);
+    order.tags.set(tag, at);
+  }
+  for (const [tag, seq] of order.tags) {
+    if (order.tags.size <= ISOLATE_INVALIDATION_HISTORY) break;
+    order.tags.delete(tag);
+    order.forgotten = seq;
+  }
+}

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/request-tag-mask.ts

@@ -0,0 +1,147 @@
+/**
+ * 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 function perRequestStoreValue<T>(
+  map: PerRequestStoreMap<T>,
+  ctx: object,
+  store: object,
+  create: () => T,
+): T {
+  let byStore = map.get(ctx);
+  if (!byStore) {
+    byStore = new WeakMap();
+    map.set(ctx, byStore);
+  }
+  let value = byStore.get(store);
+  if (value === undefined) {
+    value = create();
+    byStore.set(store, value);
+  }
+  return value;
+}
+
+/**
+ * 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 function requestRoot<T extends object>(
+  ctx: T & { _requestRoot?: T },
+): T {
+  return ctx._requestRoot ?? ctx;
+}
+
+/** Request root -> store -> tag -> the invalidatedAt its mask carries. */
+const requestMasks: PerRequestStoreMap<Map<string, number>> = new WeakMap();
+
+/** Mask `tags` at `at` through `store` for the rest of `ctx`'s request. */
+export function maskRequestTags(
+  ctx: object,
+  store: object,
+  tags: readonly string[],
+  at: number,
+): void {
+  const mask = perRequestStoreValue(
+    requestMasks,
+    requestRoot(ctx),
+    store,
+    () => new Map<string, number>(),
+  );
+  for (const tag of tags) mask.set(tag, at);
+}
+
+/**
+ * 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 function maskedForRequest(
+  ctx: object | undefined,
+  store: object,
+  tags: readonly string[] | undefined,
+  taggedAt: number,
+): boolean {
+  if (!ctx || !tags?.length) return false;
+  const mask = requestMasks.get(requestRoot(ctx))?.get(store);
+  if (!mask) return false;
+  for (const tag of tags) {
+    const at = mask.get(tag);
+    if (at !== undefined && at >= taggedAt) return true;
+  }
+  return false;
+}
+
+/**
+ * A marker read the write gate issued (#977) and has not settled: the
+ * store's answer for one tag and the millisecond it was issued in.
+ */
+interface GateRead {
+  issuedAt: number;
+  answer: Promise<unknown>;
+}
+
+/** Request root -> store -> tag -> the gate read in flight for it. */
+const gateReads: PerRequestStoreMap<Map<string, GateRead>> = new WeakMap();
+
+/**
+ * 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 function gateMarkerRead<T>(
+  ctx: object | undefined,
+  store: object,
+  tag: string,
+  sinceMs: number,
+  read: () => Promise<T>,
+): Promise<T> {
+  if (!ctx) return read();
+  const reads = perRequestStoreValue(
+    gateReads,
+    requestRoot(ctx),
+    store,
+    () => new Map<string, GateRead>(),
+  );
+  const inFlight = reads.get(tag);
+  if (inFlight && inFlight.issuedAt >= sinceMs - 1) {
+    return inFlight.answer as Promise<T>;
+  }
+  const answer = read();
+  const entry: GateRead = { issuedAt: Date.now(), answer };
+  reads.set(tag, entry);
+  const settled = (): void => {
+    if (reads.get(tag) === entry) reads.delete(tag);
+  };
+  answer.then(settled, settled);
+  return answer;
+}