@rangojs/router 0.21.0 → 0.22.0

package/src/cache/cache-policy.ts

@@ -13,6 +13,15 @@ import type { RequestContext } from "../server/request-context.js";
 import { normalizeTags } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
 
+/**
+ * How long a follower trusts an in-flight leader before evicting it and
+ * running fresh. High enough that a slow-but-healthy upstream never triggers
+ * duplicate work (a legitimate cached call taking >15s is already pathological);
+ * low enough to bound the blast radius of a wedged leader to seconds, not the
+ * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
+ */
+export const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15_000;
+
 /**
  * Default TTL for route-level cache() DSL and loader cache.
  * Applied when neither the cache options nor the store defaults specify a TTL.
@@ -184,8 +193,8 @@ export function resolveTagsOption<TEnv>(
  * and on CFCacheStore would also cost a wasted KV marker read per request.
  * Returns undefined when nothing usable remains, keeping the entry header-free.
  */
-function normalizeTagList(tags: string[]): string[] | undefined {
-  const out = normalizeTags(tags);
+export function normalizeTagList(tags: string[]): string[] | undefined {
+  const out = [...new Set(normalizeTags(tags))];
   return out.length > 0 ? out : undefined;
 }
 

package/src/cache/cache-runtime.ts

@@ -42,7 +42,11 @@ import {
 } from "./handle-snapshot.js";
 import { startHandleCapture, useCacheRecordKey } from "./handle-capture.js";
 import { isHandle } from "../handle.js";
-import { cacheKeyBase, sortedSearchString } from "./cache-key-utils.js";
+import {
+  requestArgKey,
+  requestKeyBase,
+  sortedSearchString,
+} from "./cache-key-utils.js";
 import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -60,6 +64,8 @@ import {
   type CacheExecScope,
 } from "./cache-exec-scope.js";
 import { reportCacheError } from "./cache-error.js";
+import { IN_FLIGHT_LEADER_MAX_WAIT_MS } from "./cache-policy.js";
+import { isWarmReplace, noteWarmWrite } from "../prerender/warm-request.js";
 import {
   executionStart,
   invalidatedSince,
@@ -314,15 +320,6 @@ interface InFlightExecution {
 
 const inFlightExecutions = new Map<string, InFlightExecution>();
 
-/**
- * How long a follower trusts an in-flight leader before evicting it and
- * running fresh. High enough that a slow-but-healthy upstream never triggers
- * duplicate work (a legitimate cached call taking >15s is already pathological);
- * low enough to bound the blast radius of a wedged leader to seconds, not the
- * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
- */
-const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15_000;
-
 /** Distinguishes a leader timeout from a leader rejection in raceLeader. */
 const LEADER_TIMED_OUT = Symbol("leader-timed-out");
 
@@ -499,9 +496,11 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         }
         if (ctx.params && typeof ctx.params === "object") {
           // Include host to prevent cross-host cache collisions (same
-          // pattern as route-level cache-scope.ts key generation).
+          // pattern as route-level cache-scope.ts key generation), led by the
+          // router part: a ctx is one router's (cache-key-utils.ts, the
+          // router rule).
           if (ctx.url?.host) {
-            keyArgs.push(ctx.url.host);
+            keyArgs.push(requestKeyBase(requestCtx, ctx.url.host, ""));
           }
           // Include route name to prevent collisions when the same cached
           // function is reused across routes with identical pathname/params
@@ -529,15 +528,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       } else if (arg instanceof Request) {
         // A raw Request (ctx.request) is request-scoped like ctx: fold in its
         // URL with the same host-namespacing and search normalization.
-        const url = new URL(arg.url);
         keyArgs.push(
-          cacheKeyBase(
-            url.host,
-            url.pathname,
-            url.searchParams,
-            undefined,
-            requestCtx?._searchParamsFilter,
-          ),
+          requestArgKey(new URL(arg.url), requestCtx?._searchParamsFilter),
         );
       } else if (arg != null && arg === requestCtx?.env) {
         // The request's env is left out: constant per deployment, and its
@@ -617,8 +609,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       return result;
     }
 
-    // Cache lookup
-    const cached = await store.getItem(cacheKey);
+    // Cache lookup. A router.prerender() warm reads a miss and leads its own
+    // execution below: a leader that started before the warm was called may
+    // be reading data from before the change the warm publishes, and a
+    // follower writes nothing of its own.
+    const warmReplace = isWarmReplace(requestCtx);
+    const cached = warmReplace ? null : await store.getItem(cacheKey);
 
     // Serve a cached entry on the hit path: deserialize the stored value,
     // replay handle data (gated on tainted args), and surface the entry's tags
@@ -767,7 +763,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                         ttl: profile.ttl,
                         swr: profile.swr,
                         tags: freshTags.length > 0 ? freshTags : undefined,
+                        startedAt: start.at,
                       });
+                      noteWarmWrite(requestCtx, "item");
                     }
                   },
                 ),
@@ -806,7 +804,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // against its OWN handle store (gated on ITS hasTaintedArgs), and records
     // tags into its OWN request — no deserialized result is shared across
     // requests. The store write stays exactly once (the leader's).
-    let existing = inFlightExecutions.get(cacheKey);
+    let existing = warmReplace ? undefined : inFlightExecutions.get(cacheKey);
     while (existing) {
       const remainingMs =
         IN_FLIGHT_LEADER_MAX_WAIT_MS - (Date.now() - existing.registeredAt);
@@ -1022,7 +1020,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           ttl: profile.ttl,
           swr: profile.swr,
           tags: tags.length > 0 ? tags : undefined,
+          startedAt: start.at,
         });
+        noteWarmWrite(requestCtx, "item");
       } catch (writeError) {
         requestCtx?._reportBackgroundError?.(writeError, "cache-write");
       }

package/src/cache/cache-scope.ts

@@ -38,12 +38,11 @@ import {
 import {
   captureHandles,
   captureHandleOwners,
-  restoreHandles,
+  restoreRecordHandles,
   type OwnedPushDelivery,
   encodeHandles,
-  decodeHandles,
 } from "./handle-snapshot.js";
-import { cacheKeyBase, composeCacheKeys } from "./cache-key-utils.js";
+import { composeCacheKeys, requestKeyBase } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
   isFiniteNonNegativeSeconds,
@@ -53,6 +52,7 @@ import {
 } from "./cache-policy.js";
 import type { RequestContext } from "../server/request-context.js";
 import { runIdentityExempt } from "./cache-exec-scope.js";
+import { isWarmReplace, noteWarmWrite } from "../prerender/warm-request.js";
 
 /**
  * Narrow the request's route-record window (RequestContext._routeRecordWindow)
@@ -138,7 +138,7 @@ function getDefaultRouteCacheKey(
     ? "intercept"
     : (prefixOverride ?? (isPartial ? "partial" : "doc"));
 
-  return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params, ctx?._searchParamsFilter)}`;
+  return `${prefix}:${requestKeyBase(ctx, host, pathname, searchParams, params, ctx?._searchParamsFilter)}`;
 }
 
 // ============================================================================
@@ -786,6 +786,12 @@ export class CacheScope {
     const store = this.getStore();
     if (!store) return { status: "bypass" };
 
+    // A router.prerender() warm renders as on a cold cache: the opt-outs
+    // above still answer `bypass`, and the miss lets the write path replace
+    // the record under the key it resolves (cacheRoute).
+    const ambientContext = _getRequestContext();
+    if (isWarmReplace(ambientContext)) return { status: "miss" };
+
     // Resolve cache key INSIDE the try so a throwing consumer key() (or a
     // store.keyGenerator) degrades to a cache miss (return null -> render
     // uncached) instead of crashing the foreground render. resolveCacheKey
@@ -826,7 +832,6 @@ export class CacheScope {
       // seeded record, which a document tail turns into the degrade
       // (ShellRecordUnavailableError).
       let segments: ResolvedSegment[];
-      const ambientContext = _getRequestContext();
       try {
         const codec = await import("./segment-codec.js");
         segments = ambientContext?._shellFragmentPayload
@@ -876,32 +881,17 @@ export class CacheScope {
       await this.onHit?.();
 
       const handleStore = _getRequestContext()?._handleStore;
-      // With or without a handles blob: a pinned loader whose capture pushed
-      // nothing has no copy in the record, and its run on this request must
-      // still add no settled push (HandleStore.setRecordAuthority).
-      const owned = handleStore ? ownedPushes?.() : undefined;
-      if (owned) handleStore?.setRecordAuthority(owned);
-
-      // Replay handle data. An empty string means the route pushed no handles —
-      // skip the decode entirely (the common case). Otherwise decode the
-      // Flight-encoded blob; a decode failure skips handle restore but keeps the
-      // valid cached segments.
-      if (handleStore && cached.handles) {
-        const handlesRecord = await decodeHandles(cached.handles);
-        if (handlesRecord) {
-          if (this.boundary !== undefined) {
-            const kept = new Set(segments.map((s) => s.id));
-            for (const id of Object.keys(handlesRecord)) {
-              if (!kept.has(id)) delete handlesRecord[id];
-            }
-          }
-          restoreHandles(
-            handlesRecord,
-            handleStore,
-            cached.handleOwners,
-            owned,
-          );
-        }
+      // An empty handles string means the route pushed none (the common
+      // case); a decode failure skips the restore but keeps the segments.
+      if (handleStore) {
+        await restoreRecordHandles(
+          handleStore,
+          cached,
+          ownedPushes?.(),
+          this.boundary !== undefined
+            ? new Set(segments.map((s) => s.id))
+            : undefined,
+        );
       }
 
       if (INTERNAL_RANGO_DEBUG) {
@@ -1115,15 +1105,25 @@ export class CacheScope {
         // the tree) or a rejected handle value as an error row and completes
         // normally; stored, every HIT would render that error until expiry.
         if (flightErrors.length > 0) throw flightErrors[0];
+        // A streamed handler recovered into its boundary fallback resolves, so
+        // Flight reports nothing; refuse like a Flight error row.
+        const recovered = requestCtx._recoveredHandlerErrors;
+        if (recovered?.size) {
+          const failed = nonLoaderSegments.find((s) => recovered.has(s.id));
+          if (failed) throw recovered.get(failed.id);
+        }
 
+        const recordTags = collectRecordTags(requestCtx, tags, [
+          ...nonLoaderSegments.map((s) => s.id),
+          handlesOwnerId,
+        ]);
         const data: CachedEntryData = {
           segments: serializedSegments,
           handles: encodedHandles,
           expiresAt: Date.now() + ttl * 1000,
-          tags: collectRecordTags(requestCtx, tags, [
-            ...nonLoaderSegments.map((s) => s.id),
-            handlesOwnerId,
-          ]),
+          tags: recordTags,
+          // The stamp is the render's start, not the write's (#1068).
+          ...(start && recordTags?.length ? { taggedAt: start.at } : {}),
         };
         if (handleOwners && encodedHandles) data.handleOwners = handleOwners;
 
@@ -1137,6 +1137,8 @@ export class CacheScope {
         }
 
         await store.set(key, data, ttl, swr);
+        // The implicit doc scope's record lives in the shell entry only.
+        if (!this.isShellImplicitDocScope) noteWarmWrite(requestCtx, "record");
 
         if (INTERNAL_RANGO_DEBUG) {
           const segmentTypes = nonLoaderSegments.map((s) =>
@@ -1185,7 +1187,7 @@ function collectRecordTags(
  * enclosing scopes on another store (#974) and of a scope without its own
  * `key()` (#970)); with none, the app store's keyGenerator result
  * given the document default key. Undefined (synchronously, with no work)
- * when neither applies: the shell key stays host + path + filtered search.
+ * when neither applies: the shell key stays unpartitioned (buildShellKey).
  * Resolves to null when the partition is the default key itself (a
  * keyGenerator that returns it unchanged): that partitions nothing, so the
  * shell stays unpartitioned and keeps its build shell. The shell's key, its

package/src/cache/cf/cf-cache-store.ts

@@ -27,6 +27,7 @@ declare global {
 
 import { requestHeaders } from "../../server/request-headers.js";
 import type {
+  CacheStoreScope,
   SegmentCacheStore,
   CachedEntryData,
   CacheDefaults,
@@ -118,6 +119,7 @@ import {
   DEFAULT_CF_MARKER_MAX_STALE_MS,
 } from "../isolate-tag-memo.js";
 import { createCloudflareZonePurge } from "./cf-zone-purge.js";
+import { responseStartedAt, taggedStamp } from "../invalidation-order.js";
 
 // ============================================================================
 // Constants
@@ -519,6 +521,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly kv?: KVNamespace;
   /** True when constructed without KV: no durable tag history (see ctor). */
   readonly tagHistoryInert?: boolean;
+  /**
+   * SegmentCacheStore.scope: with KV every colo's L1 miss reads the same L2
+   * entry ("global"); without it entries live in one colo's Cache API
+   * ("local"), purge mode included (a purge evicts, it stores nothing).
+   */
+  readonly scope: CacheStoreScope;
   private readonly onRevalidateTag?: (tags: string[]) => Promise<void>;
   private readonly tagPurge?: (cacheTags: string[]) => Promise<void>;
   private readonly tagInvalidationTtl?: number;
@@ -604,6 +612,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // evict it (purge cannot delete a build asset), so the manifest gate
     // declines on this flag (shell-build-manifest.ts).
     this.tagHistoryInert = options.kv ? undefined : true;
+    this.scope = options.kv ? "global" : "local";
     this.onRevalidateTag = options.onRevalidateTag;
     // tagPurge accepts a ready purge function or a credentials object; the
     // object form is normalized through the built-in zone purge client, which
@@ -1389,13 +1398,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
 
-      // Stamp the tag timestamp at write time and carry it (with the tags)
-      // into both the L1 body and the KV envelope so reads can run the
-      // invalidation check.
-      const taggedAt =
-        Array.isArray(data.tags) && data.tags.length > 0
-          ? Date.now()
-          : undefined;
+      // Stamp the tag timestamp and carry it (with the tags) into both the
+      // L1 body and the KV envelope so reads can run the invalidation check.
+      // It is the render's start when the writer passed it (#1068), else the
+      // write time: a marker written while the render ran then rejects it.
+      const taggedAt = taggedStamp(data.tags, data.taggedAt);
       const dataToStore: CachedEntryData = taggedAt
         ? { ...data, taggedAt }
         : data;
@@ -1640,8 +1647,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const swrWindow = resolveSwrWindow(swr, this.defaults);
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
-      const taggedAt =
-        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
+      const taggedAt = taggedStamp(tags, responseStartedAt(response));
 
       // Clone body for potential KV write before consuming it for L1
       const [l1Body, kvBody] = this.kv
@@ -1941,8 +1947,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const staleAt = Date.now() + ttl * 1000;
 
       const tags = options?.tags;
-      const taggedAt =
-        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
+      const taggedAt = taggedStamp(tags, options?.startedAt);
 
       // Serialize value/handles once; L1 body and KV envelope.v/h share the
       // escaped strings so a large RSC payload is not re-escaped for L2.

package/src/cache/document-cache.ts

@@ -22,10 +22,19 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { mayNeedSSR } from "../rsc/ssr-setup.js";
-import { cacheKeyBase } from "./cache-key-utils.js";
+import { requestKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
+import {
+  isWarmReplace,
+  noteWarmDocument,
+  noteWarmWrite,
+} from "../prerender/warm-request.js";
 import { reportCacheError } from "./cache-error.js";
-import { executionStart, predatesInvalidation } from "./tag-invalidation.js";
+import {
+  executionStart,
+  markResponseStart,
+  predatesInvalidation,
+} from "./tag-invalidation.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
@@ -239,11 +248,14 @@ export interface DocumentCacheOptions<TEnv = any> {
   /**
    * Custom cache key generator.
    *
-   * Replaces the default `host + pathname + search` key entirely. On a
-   * multi-domain deployment served by one function you MUST include `url.host`
-   * (or an equivalent tenant discriminator) yourself — the default key is
-   * host-namespaced, but a custom generator's output is used verbatim, so
-   * omitting host bleeds one hostname's cached response to another.
+   * Replaces the default `router id + host + pathname + search` key entirely.
+   * On a multi-domain deployment served by one function you MUST include
+   * `url.host` (or an equivalent tenant discriminator) yourself — the default
+   * key is host-namespaced, but a custom generator's output is used verbatim,
+   * so omitting host bleeds one hostname's cached response to another. The
+   * same goes for the router: two routers that share a cache store and can
+   * serve one host and path (a `hostOverride` cookie) need a generator that
+   * tells them apart.
    */
   keyGenerator?: (url: URL) => string;
 
@@ -347,7 +359,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
-    // The write gate's start (#977): the request's, not this middleware's. A
+    // The write gate's start (#977) and the entry's stamp (#1068): the
+    // request's, not this middleware's, also for a stale refresh. A
     // middleware ahead of this one can read tagged data the document bakes,
     // and a stale refresh re-runs the handler over what they set.
     const start = requestCtx._requestStart ?? executionStart();
@@ -392,7 +405,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // existing keys and double any host they already include).
       const cacheKey = keyGenerator
         ? keyGenerator(url) + segmentHash + fragmentSuffix + typeSuffix
-        : cacheKeyBase(
+        : requestKeyBase(
+            requestCtx,
             url.host,
             url.pathname,
             url.searchParams,
@@ -406,9 +420,11 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // Recovery must reach CacheScope's server decoder so it can evict the bad
       // segment. Treat it as a miss, then let the ordinary write path replace
       // the corrupt fragment-capable response with the valid fallback bytes.
-      const cached = isFragmentRecovery
-        ? null
-        : await store.getResponse(cacheKey);
+      // A router.prerender() warm is a miss too: it renders and replaces.
+      const cached =
+        isFragmentRecovery || isWarmReplace(requestCtx)
+          ? null
+          : await store.getResponse(cacheKey);
       // Every path past the lookup either returns a fresh HIT, which renders
       // nothing, or renders a response this cache may store.
       requestCtx._documentCacheRender = true;
@@ -462,11 +478,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                   if (await predatesInvalidation(store, tags, start)) return;
                   await store.putResponse!(
                     cacheKey,
-                    new Response(body, fresh),
+                    markResponseStart(new Response(body, fresh), start),
                     directives.sMaxAge!,
                     directives.staleWhileRevalidate,
                     tags,
                   );
+                  noteWarmWrite(requestCtx, "response");
+                  noteWarmDocument(requestCtx, "stored");
                   log(
                     `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
                   );
@@ -531,11 +549,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             if (await predatesInvalidation(store, tags, start)) return;
             await store.putResponse!(
               cacheKey,
-              new Response(body, originalResponse),
+              markResponseStart(new Response(body, originalResponse), start),
               directives.sMaxAge!,
               directives.staleWhileRevalidate,
               tags,
             );
+            noteWarmWrite(requestCtx, "response");
+            noteWarmDocument(requestCtx, "stored");
           } catch (error) {
             // Detached waitUntil task — pass the captured requestCtx so onError
             // fires even though the ALS context is gone (see the revalidation
@@ -556,6 +576,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       }
 
       // No cache headers - pass through
+      noteWarmDocument(requestCtx, "not-cacheable");
       return originalResponse;
     } catch (error) {
       reportCacheError(error, "cache-read", "[DocumentCache] middleware");

package/src/cache/handle-snapshot.ts

@@ -134,6 +134,31 @@ export function captureHandleOwners(
   return owners;
 }
 
+/**
+ * captureHandles and captureHandleOwners cut down to the handle arrays that
+ * hold an owned value, each whole (its unowned values too, in place), so
+ * restoreHandles rebuilds exactly those arrays over a store that already
+ * holds the rest. A prerender-served shell capture stores this: the
+ * prerender store restores the handler pushes on a HIT, and the loader
+ * pushes have no other record (shell-capture.ts captureAndStoreShell).
+ */
+export function captureOwnedHandles(handleStore: HandleStore): {
+  handles: HandleRecord;
+  owners?: HandleOwners;
+} {
+  const handles: HandleRecord = {};
+  let owners: HandleOwners | undefined;
+  for (const id of handleStore.getOwnedSegmentIds()) {
+    const segOwners = handleStore.getRecordOwners(id);
+    if (!segOwners) continue;
+    const kept = handleStore.getDataForSegment(id, true);
+    handles[id] = {};
+    for (const name in segOwners) handles[id][name] = kept[name] ?? [];
+    (owners ??= {})[id] = segOwners;
+  }
+  return { handles, owners };
+}
+
 /**
  * What the record being restored is to each loader's handle pushes on this
  * request (HandleStore RecordAuthority). Built by loaderPins (loader-cache.ts)
@@ -190,6 +215,31 @@ export function restoreHandles(
   }
 }
 
+/**
+ * Serve a doc record's handles: set its authority over the loaders' pushes
+ * (with or without a handles blob: a pinned loader whose capture pushed
+ * nothing has no copy, and its run must still add no settled push), then
+ * decode and restoreHandles. `keepIds` limits the restore to the segments a
+ * boundary-scoped scope serves. A decode failure skips the restore.
+ */
+export async function restoreRecordHandles(
+  handleStore: HandleStore,
+  record: { handles?: string; handleOwners?: HandleOwners },
+  owned: OwnedPushDelivery | undefined,
+  keepIds?: ReadonlySet<string>,
+): Promise<void> {
+  if (owned) handleStore.setRecordAuthority(owned);
+  if (!record.handles) return;
+  const decoded = await decodeHandles(record.handles);
+  if (!decoded) return;
+  if (keepIds) {
+    for (const id of Object.keys(decoded)) {
+      if (!keepIds.has(id)) delete decoded[id];
+    }
+  }
+  restoreHandles(decoded, handleStore, record.handleOwners, owned);
+}
+
 /**
  * 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/src/cache/index.ts

@@ -1,5 +1,6 @@
 export type {
   SegmentCacheStore,
+  CacheStoreScope,
   CachedEntryData,
   CacheGetResult,
   CacheItemResult,

package/src/cache/invalidation-order.ts

@@ -43,6 +43,59 @@ export interface ExecutionStart {
   readonly at: number;
 }
 
+/**
+ * The `taggedAt` / `ta` stamp a store writes on a tagged data entry: the start
+ * of the execution that produced the value (`startedAt`), so a marker written
+ * while it ran rejects the entry on read (#1068). Write time when the writer
+ * knows no start. Never later than now: a start from a skewed clock must not
+ * stamp the future, which would make the entry look newer than every marker.
+ */
+export function entryStamp(startedAt: number | undefined): number {
+  const now = Date.now();
+  // 0 is "no start", not the epoch: no marker is older than it, so such an
+  // entry would never be rejected.
+  return typeof startedAt === "number" &&
+    Number.isFinite(startedAt) &&
+    startedAt > 0
+    ? Math.min(startedAt, now)
+    : now;
+}
+
+/** The stamp of a data entry: `entryStamp` for a tagged entry, none otherwise. */
+export function taggedStamp(
+  tags: readonly string[] | undefined,
+  startedAt: number | undefined,
+): number | undefined {
+  return Array.isArray(tags) && tags.length > 0
+    ? entryStamp(startedAt)
+    : undefined;
+}
+
+/**
+ * putResponse has no options object to carry the start and takes no new
+ * positional parameter, so the writer marks the Response it hands over.
+ * On globalThis like the order: a second evaluated copy of this module that
+ * wrote the mark must be read by the store's copy, else the stamp silently
+ * falls back to write time.
+ */
+const responseStarts: WeakMap<Response, number> = ((globalThis as any)[
+  Symbol.for("rangojs-router:response-execution-start")
+] ??= new WeakMap());
+
+/** Mark the execution start behind a Response handed to putResponse. */
+export function markResponseStart(
+  response: Response,
+  start: ExecutionStart,
+): Response {
+  responseStarts.set(response, start.at);
+  return response;
+}
+
+/** The start a writer marked on `response`, if any. */
+export function responseStartedAt(response: Response): number | undefined {
+  return responseStarts.get(response);
+}
+
 /** Record an execution's start, before it reads its data. */
 export function executionStart(): ExecutionStart {
   return { seq: order.seq, at: Date.now() };