@rangojs/router 0.16.0 → 0.18.0

package/src/cache/handle-capture.ts

@@ -6,10 +6,82 @@
  * pulling in @vitejs/plugin-rsc/rsc dependencies.
  */
 
+import { getCurrentLoaderBodyId } from "../server/context.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
 
-export interface HandleCapture {
+/**
+ * Scoping for one capture of a cached unit (a loader's own cache(),
+ * loader-cache.ts; a "use cache" function, cache-runtime.ts) that runs
+ * concurrently with live pushes into the same store.
+ */
+export interface HandleCaptureOptions {
+  /** Push-time predicate; a rejected push is not recorded by this capture. */
+  accept?: () => boolean;
+  /**
+   * Recorded pushes do not reach the store. A stale hit's background
+   * revalidation: the foreground already replayed the entry's pushes, so the
+   * fresh body's pushes belong only to the refreshed entry.
+   */
+  divert?: boolean;
+  /**
+   * Record key for an accepted push, in place of its segment id. A loader's
+   * own cache() (loader-cache.ts recordOwnerKey) and "use cache"
+   * (useCacheRecordKey) group pushes by the loader body that made them.
+   */
+  key?: () => string;
+}
+
+// The loader whose recorded push a "use cache" HIT is replaying
+// (replayLoaderPush), for an enclosing "use cache" MISS's record key.
+let replayingOwner: string | undefined;
+
+/**
+ * HandleStore.pushReplayed, attributed to `loaderId` for the record key of an
+ * enclosing "use cache" MISS: an outer cached function records an inner HIT's
+ * replayed loader pushes under that loader, not as its own.
+ */
+export function replayLoaderPush(
+  handleStore: HandleStore,
+  handleName: string,
+  segmentId: string,
+  value: unknown,
+  loaderId: string,
+): void {
+  const prev = replayingOwner;
+  replayingOwner = loaderId;
+  try {
+    handleStore.pushReplayed(handleName, segmentId, value, loaderId);
+  } finally {
+    replayingOwner = prev;
+  }
+}
+
+/**
+ * Record key for a "use cache" capture: run-length groups `${seq}:${owner}`,
+ * so the HIT (handle-snapshot.ts appendHandles) delivers each loader's pushes
+ * at most once per request. The owner is the loader whose body, entered
+ * inside this execution via ctx.use, made the push; empty for the function's
+ * own pushes and those of cached functions it calls. Groups keep push order
+ * across owners. Create at call time: the caller's loader body is the
+ * function's own scope.
+ */
+export function useCacheRecordKey(): () => string {
+  const callerBody = getCurrentLoaderBodyId();
+  let seq = 0;
+  let last: string | undefined;
+  return () => {
+    const body = replayingOwner ?? getCurrentLoaderBodyId();
+    const owner = body === callerBody ? "" : (body ?? "");
+    if (owner !== last) {
+      last = owner;
+      seq++;
+    }
+    return `${seq}:${owner}`;
+  };
+}
+
+export interface HandleCapture extends HandleCaptureOptions {
   data: Record<string, SegmentHandleData>;
 }
 
@@ -42,33 +114,41 @@ function ensureInterceptorInstalled(handleStore: HandleStore): void {
     segmentId: string,
     value: unknown,
   ) => {
+    let diverted = false;
     for (const capture of captures) {
-      if (!capture.data[segmentId]) {
-        capture.data[segmentId] = {};
+      if (capture.accept && !capture.accept()) continue;
+      if (capture.divert) diverted = true;
+      const key = capture.key ? capture.key() : segmentId;
+      if (!capture.data[key]) {
+        capture.data[key] = {};
       }
-      if (!capture.data[segmentId][handleName]) {
-        capture.data[segmentId][handleName] = [];
+      if (!capture.data[key][handleName]) {
+        capture.data[key][handleName] = [];
       }
-      capture.data[segmentId][handleName].push(value);
+      capture.data[key][handleName].push(value);
     }
-    originalPush(handleName, segmentId, value);
+    if (!diverted) originalPush(handleName, segmentId, value);
   };
 }
 
 /**
- * Start capturing handle pushes for a cached function execution.
+ * Start capturing handle pushes for a cached function or cached loader
+ * execution (`options`: see HandleCaptureOptions).
  *
  * Concurrency-safe: multiple overlapping captures on the same
  * HandleStore are independent. Each capture registers a token in a
  * Set; stopping removes it. No ordering requirement (LIFO not needed).
  */
-export function startHandleCapture(handleStore: HandleStore): {
+export function startHandleCapture(
+  handleStore: HandleStore,
+  options?: HandleCaptureOptions,
+): {
   capture: HandleCapture;
   stop: () => void;
 } {
   ensureInterceptorInstalled(handleStore);
 
-  const capture: HandleCapture = { data: {} };
+  const capture: HandleCapture = { data: {}, ...options };
   const captures = activeCapturesMap.get(handleStore)!;
   captures.add(capture);
 

package/src/cache/handle-snapshot.ts

@@ -6,9 +6,10 @@
  * during segment resolution and stored alongside cached segments.
  */
 
+import { replayLoaderPush } from "./handle-capture.js";
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
-import type { SegmentHandleData } from "./types.js";
+import type { HandleOwners, SegmentHandleData } from "./types.js";
 // segment-codec eagerly pulls @vitejs/plugin-rsc (a virtual: module unresolvable
 // in plain node/vitest). It is imported LAZILY inside the two async encode/decode
 // helpers below so that modules which import handle-snapshot only for the
@@ -47,19 +48,32 @@ function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
   ]);
 }
 
-export async function encodeHandles(handles: HandleRecord): Promise<string> {
+/**
+ * `onError` reaches the Flight encode (see serializeResult). A cache writer
+ * passes the collector it gives the value's encode, so a handle value that
+ * fails to encode (a rejected pushed promise) refuses the whole entry like a
+ * failed value does; prerender (prerender-match.ts) passes one too and
+ * hands the error to its prerender.onError policy.
+ */
+export async function encodeHandles(
+  handles: HandleRecord,
+  onError?: (error: unknown) => void,
+): Promise<string> {
   if (!hasHandleData(handles)) return "";
-  return encodeHandleValue(handles);
+  return encodeHandleValue(handles, onError);
 }
 
 export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
   return decodeHandleValue<HandleRecord>(encoded);
 }
 
-export async function encodeHandleValue(value: unknown): Promise<string> {
+export async function encodeHandleValue(
+  value: unknown,
+  onError?: (error: unknown) => void,
+): Promise<string> {
   const { serializeResult } = await import("./segment-codec.js");
   const encoded = await withTimeout(
-    serializeResult(value),
+    serializeResult(value, onError),
     HANDLE_ENCODE_TIMEOUT_MS,
     null,
   );
@@ -84,49 +98,140 @@ export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
  * Capture handle data for a set of segments from the handle store.
  * Used when caching segments to preserve their handle data.
  *
- * `exclude` (shell captures: RequestContext._shellCaptureLoaderHandleValues)
- * drops DSL-loader-scoped push values from the CACHE WRITE only: loaders
- * re-run fresh on every HIT, so replaying their captured values would
- * duplicate the fresh push — and their masked nested promises would stall the
- * Flight handle encode to its timeout. Threaded as an explicit argument so
- * every other getDataForSegment consumer (the render-barrier snapshot,
- * prerender) provably sees every push.
+ * DSL-loader pushes stay out of the CACHE WRITE: a HIT runs loaders exactly
+ * as an uncached render of the same request would (cache-lookup.ts
+ * resolveFreshLoadersAndYield), so replaying a recorded copy would duplicate
+ * the live push. Handler pushes, including
+ * handler-invoked ctx.use(Loader) bodies (skipped with their handler on a
+ * HIT), are kept. The store tags loader pushes by array position at push
+ * time, so primitive values are covered. A PPR shell capture untags the
+ * settled bake-lane pushes its record keeps (shell-capture.ts) and gives
+ * them an owner (captureHandleOwners). Only this call site passes
+ * excludeLoaderPushes; every other getDataForSegment consumer (the
+ * render-barrier snapshot, prerender) sees every push.
  */
 export function captureHandles(
   segments: ResolvedSegment[],
   handleStore: HandleStore,
-  exclude?: WeakSet<object>,
 ): Record<string, SegmentHandleData> {
   const handles: Record<string, SegmentHandleData> = {};
   for (const seg of segments) {
-    const data = handleStore.getDataForSegment(seg.id);
-    if (!exclude) {
-      handles[seg.id] = data;
-      continue;
-    }
-    const filtered: SegmentHandleData = {};
-    for (const [handleName, values] of Object.entries(data)) {
-      const kept = values.filter(
-        (v) => typeof v !== "object" || v === null || !exclude.has(v),
-      );
-      if (kept.length > 0) filtered[handleName] = kept;
-    }
-    handles[seg.id] = filtered;
+    handles[seg.id] = handleStore.getDataForSegment(seg.id, true);
   }
   return handles;
 }
 
+/** The owners of captureHandles' values; undefined when none is owned. */
+export function captureHandleOwners(
+  segments: ResolvedSegment[],
+  handleStore: HandleStore,
+): HandleOwners | undefined {
+  let owners: HandleOwners | undefined;
+  for (const seg of segments) {
+    const segOwners = handleStore.getRecordOwners(seg.id);
+    if (segOwners) (owners ??= {})[seg.id] = segOwners;
+  }
+  return owners;
+}
+
 /**
  * Restore handle data from a cached snapshot into the handle store.
- * Used when serving cached segments to replay their handle data.
+ * 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: if the owning loader
+ * runs on the HIT (a live loader, or a promise-carrying `ssr: false` one;
+ * a promise-free one is served from the shell and does not), 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.
  */
 export function restoreHandles(
   handles: Record<string, SegmentHandleData>,
   handleStore: HandleStore,
+  owners?: HandleOwners,
+  claim?: (loaderId: string) => boolean,
 ): void {
+  let delivers: Map<string, boolean> | undefined;
   for (const [segId, segHandles] of Object.entries(handles)) {
-    if (Object.keys(segHandles).length > 0) {
+    if (Object.keys(segHandles).length === 0) continue;
+    const segOwners = owners?.[segId];
+    if (!segOwners) {
       handleStore.replaySegmentData(segId, segHandles);
+      continue;
+    }
+    const cleared: SegmentHandleData = {};
+    for (const handleName in segHandles) cleared[handleName] = [];
+    handleStore.replaySegmentData(segId, cleared);
+    for (const [handleName, values] of Object.entries(segHandles)) {
+      const valueOwners = segOwners[handleName];
+      for (let i = 0; i < values.length; i++) {
+        const owner = valueOwners?.[i];
+        if (!owner) {
+          handleStore.push(handleName, segId, values[i]);
+          continue;
+        }
+        delivers ??= new Map();
+        let deliver = delivers.get(owner);
+        if (deliver === undefined) {
+          deliver = claim ? claim(owner) : true;
+          delivers.set(owner, deliver);
+        }
+        if (deliver) {
+          handleStore.pushReplayed(handleName, segId, values[i], owner);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * 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
+ * a cached unit that shares its segments with live pushes ("use cache");
+ * restoreHandles would wipe those. `segmentId` redirects every value to one
+ * segment (the caller's).
+ *
+ * Owner-keyed groups (useCacheRecordKey, `${seq}:${loaderId}`) are a loader's
+ * pushes, which reach the page once per request: `claim` (setupLoaderAccess
+ * _claimLoaderPushes) skips a loader that already ran or was replayed in this
+ * request, and a claimed loader that runs later replaces its replayed values
+ * (HandleStore.pushReplayed). `${seq}:` groups are the function's own pushes.
+ * A key without ":" is a segment id (records written before owner keys) and
+ * replays unchanged. A loader's own cache() replays through loader-cache.ts
+ * replayLoaderHandles.
+ */
+export function appendHandles(
+  handles: Record<string, SegmentHandleData>,
+  handleStore: HandleStore,
+  segmentId?: string,
+  claim?: (loaderId: string) => boolean,
+): void {
+  let claims: Map<string, boolean> | undefined;
+  for (const [key, segHandles] of Object.entries(handles)) {
+    const colon = key.indexOf(":");
+    const owner = colon < 0 ? "" : key.slice(colon + 1);
+    if (owner) {
+      claims ??= new Map();
+      let deliver = claims.get(owner);
+      if (deliver === undefined) {
+        deliver = claim ? claim(owner) : true;
+        claims.set(owner, deliver);
+      }
+      if (!deliver) continue;
+    }
+    const target = segmentId ?? key;
+    for (const [handleName, values] of Object.entries(segHandles)) {
+      for (const value of values) {
+        if (owner) {
+          replayLoaderPush(handleStore, handleName, target, value, owner);
+        } else {
+          handleStore.push(handleName, target, value);
+        }
+      }
     }
   }
 }

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/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;
+}