@bygghammar/cms-platform 0.94.0 → 0.96.0

package/src/server/pages-core.ts

@@ -37,6 +37,13 @@ import {
   type PublicationWindow,
 } from "../cms/page-publication";
 import { resolveGlobalsDeep } from "./resolve-globals";
+import { normalizePageListing, type PageListing } from "../cms/page-visibility";
+import {
+  assertNotProtected,
+  PAGE_LISTING_PREFIX,
+  readVisibilitySettingsCore,
+  type VersionToken,
+} from "./page-visibility-core";
 import { CONTRACT_V2_MIGRATIONS, CONTRACT_V3_MIGRATIONS } from "../platform/contract";
 import { digestJson, type DigestValue } from "../platform/digest";
 
@@ -50,8 +57,48 @@ export type PagesDeps = {
   context: PagesContext;
   /** Privileged client; only used to resolve legacy version authors. */
   admin?: () => Promise<any>;
+  /**
+   * Keys of pages that must always stay published and listed (for Voyara the
+   * start page and the contact page). The cores refuse to unpublish, end-date,
+   * trash or unlist them. Supplied by the host's server code, never the browser.
+   */
+  protectedPageKeys?: readonly string[];
+};
+
+/** Listing fields the list and the builder show next to publication. */
+export type PageListingFields = {
+  listing: PageListing;
+  /** Version token to send back with a listing change (null: never changed). */
+  listing_version: VersionToken;
+  /** Protected pages offer neither Unpublish nor Make link-only. */
+  protected: boolean;
 };
 
+function listingFieldsFor(
+  pageId: string,
+  key: string,
+  settings: Awaited<ReturnType<typeof readVisibilitySettingsCore>>,
+  protectedPageKeys: readonly string[] | undefined,
+): PageListingFields {
+  const row = settings.listings.get(pageId.toLowerCase());
+  return {
+    listing: normalizePageListing(row?.listing),
+    listing_version: row?.version ?? null,
+    protected: (protectedPageKeys ?? []).includes(key),
+  };
+}
+
+/** Name and key of one page, for the protected-page rule. */
+async function pageIdentity(client: any, pageId: string): Promise<{ key: string; name: string } | null> {
+  const { data, error } = await client
+    .from("pages")
+    .select("key,name")
+    .eq("id", pageId)
+    .maybeSingle();
+  if (error) throw new Error(error.message);
+  return (data as { key: string; name: string } | null) ?? null;
+}
+
 export type ResolvedPage = {
   key: string;
   name: string;
@@ -304,9 +351,10 @@ export type PageListRow = {
   status: string;
   updated_at: string;
   current_version_id: string | null;
-} & PublicationSummaryFields;
+} & PublicationSummaryFields &
+  PageListingFields;
 
-export async function listPagesCore({ context }: PagesDeps): Promise<PageListRow[]> {
+export async function listPagesCore({ context, protectedPageKeys }: PagesDeps): Promise<PageListRow[]> {
   await assertStaff(context);
   const { data, error } = await context.supabase
     .from("pages")
@@ -315,7 +363,9 @@ export async function listPagesCore({ context }: PagesDeps): Promise<PageListRow
     .order("is_system", { ascending: false })
     .order("name");
   if (error) throw new Error(error.message);
-  const rows = (data ?? []) as Array<Omit<PageListRow, keyof PublicationSummaryFields>>;
+  const rows = (data ?? []) as Array<
+    Omit<PageListRow, keyof PublicationSummaryFields | keyof PageListingFields>
+  >;
   if (rows.length === 0) return [];
 
   /*
@@ -341,11 +391,17 @@ export async function listPagesCore({ context }: PagesDeps): Promise<PageListRow
     byPage.set(pageId, [...(byPage.get(pageId) ?? []), ...toPublicationWindows([row])]);
   }
 
+  // Listing is its own decision, stored apart from publication; read once.
+  const settings = await readVisibilitySettingsCore(context.supabase);
   const now = Date.now();
-  return rows.map((row) => ({ ...row, ...summarize(byPage.get(row.id) ?? [], now) }));
+  return rows.map((row) => ({
+    ...row,
+    ...summarize(byPage.get(row.id) ?? [], now),
+    ...listingFieldsFor(row.id, row.key, settings, protectedPageKeys),
+  }));
 }
 
-export async function getPageForEditCore({ context }: PagesDeps, key: string) {
+export async function getPageForEditCore({ context, protectedPageKeys }: PagesDeps, key: string) {
   await assertStaff(context);
   const { data: page, error } = await context.supabase
     .from("pages")
@@ -373,7 +429,9 @@ export async function getPageForEditCore({ context }: PagesDeps, key: string) {
    * the public routes use.
    */
   const publication = await publicationOf(context.supabase, page.id);
-  return { page: { ...page, ...publication }, blocks };
+  const settings = await readVisibilitySettingsCore(context.supabase);
+  const listing = listingFieldsFor(page.id, page.key, settings, protectedPageKeys);
+  return { page: { ...page, ...publication, ...listing }, blocks };
 }
 
 /**
@@ -649,7 +707,7 @@ export async function createPageCore({ context }: PagesDeps, input: { key: strin
  * or a schedule somebody forgot about.
  */
 export async function setPageStatusCore(
-  { context }: PagesDeps,
+  { context, protectedPageKeys }: PagesDeps,
   input: { pageId: string; status: PageStatus; editSessionId?: string },
 ) {
   await assertStaff(context);
@@ -670,6 +728,7 @@ export async function setPageStatusCore(
   if (status === "published" && !page.current_version_id) {
     throw new Error("This page has no saved content yet, so there is nothing to publish.");
   }
+  if (status === "draft") assertNotProtected(protectedPageKeys, page, "unpublished");
 
   invalidatePublishedCache();
 
@@ -774,6 +833,11 @@ export async function duplicatePageCore(
     blocks = duplicateBlockTree(blocksOf(version.blocks));
   }
 
+  // Before the copy exists: what this duplication means for its listing, fixed
+  // now and kept with the idempotency key, so a retry completes this decision
+  // rather than taking a new one from the source as it is by then.
+  const intent = await recordDuplicateIntent(context, idempotencyKey, input.pageId);
+
   invalidatePublishedCache();
   const copy = await publicationRpc(
     context.supabase,
@@ -797,6 +861,7 @@ export async function duplicatePageCore(
 
   const id = typeof copy?.pageId === "string" ? copy.pageId : "";
   if (!id) throw new Error("The database made no copy of this page.");
+  await completeDuplicateListing(context, intent, id);
   return {
     id,
     key: String(copy.key ?? key),
@@ -846,7 +911,7 @@ export async function renamePageCore(
  * publishing action nobody confirmed.
  */
 export async function deletePageCore(
-  { context }: PagesDeps,
+  { context, protectedPageKeys }: PagesDeps,
   pageId: string,
   editSessionId?: string,
 ) {
@@ -856,6 +921,8 @@ export async function deletePageCore(
     resourceId: pageId,
     sessionId: editSessionId,
   });
+  const identity = await pageIdentity(context.supabase, pageId);
+  if (identity) assertNotProtected(protectedPageKeys, identity, "moved to the trash");
   invalidatePublishedCache();
   await publicationRpc(
     context.supabase,
@@ -956,6 +1023,163 @@ export async function purgePageCore({ context }: PagesDeps, pageId: string) {
   return { ok: true as const };
 }
 
+/** Where a duplication's listing decision is kept until it has been applied. */
+const DUPLICATE_INTENT_PREFIX = "duplicate.intent.";
+
+type DuplicateIntent = {
+  key: string;
+  /** What the copy's listing is to be: the source's, as it was when the row was written. */
+  listing: PageListing;
+  /** When the database wrote the row (`site_settings.created_at`, its own clock). */
+  recordedAt: string;
+};
+
+/**
+ * A copy of a link-only page starts link-only too.
+ *
+ * The copy is a draft, so nothing is public yet; but the moment somebody
+ * publishes it, a listed copy would put the address the original kept out of
+ * menus and the sitemap straight into them. Booking exceptions are never
+ * copied: the safe default for a new page is booking hidden while booking is
+ * off.
+ *
+ * The copy is made in one transaction and listed in a second write, so the
+ * listing can fail after the copy exists, and a retry with the same
+ * idempotency key is how a caller finishes it. A retry must finish *that*
+ * decision and never take a new one: if the source has been listed or
+ * unlisted since, a call that read the source again would change a copy
+ * nobody asked to change. So the decision is written down before the copy is
+ * made — a `site_settings` row keyed by the idempotency key, durable across
+ * processes, no migration — and applied after it.
+ *
+ * Which row is that decision is settled by the database's own record, not by
+ * which call wrote it, whether a cleanup succeeded, or how many calls are in
+ * flight: the decision is the row written **before the copy existed**. The
+ * row's `created_at` and the copy's `pages.created_at` are both the
+ * database's `now()`, and the row is always committed before the call that
+ * makes the copy starts. A row written by a call that arrived after the copy
+ * was made — a replay of a finished duplication, alone or overlapping
+ * another, or one whose cleanup failed — is only an observation of the source
+ * as it is today, and is never applied.
+ *
+ * The row is inserted only if absent (`ON CONFLICT DO NOTHING`), so the first
+ * attempt's decision is the one that stands, and its `created_at` never moves.
+ * The table is publicly readable, so the row holds the decision only, as the
+ * page's own listing row would.
+ */
+async function recordDuplicateIntent(
+  context: PagesContext,
+  idempotencyKey: string,
+  sourceId: string,
+): Promise<DuplicateIntent | null> {
+  const key = `${DUPLICATE_INTENT_PREFIX}${idempotencyKey.toLowerCase()}`;
+  const settings = await readVisibilitySettingsCore(context.supabase);
+  const listing = normalizePageListing(settings.listings.get(sourceId.toLowerCase())?.listing);
+  const { error } = await context.supabase
+    .from("site_settings")
+    .upsert(
+      { key, value: { listing }, updated_by: context.userId },
+      { onConflict: "key", ignoreDuplicates: true },
+    )
+    .select("key");
+  if (error) throw new Error(`Could not prepare the copy: ${error.message}. Nothing was copied.`);
+  // Whoever wrote it, the row now in the database is the one that counts.
+  const { data: row, error: readError } = await context.supabase
+    .from("site_settings")
+    .select("value, created_at")
+    .eq("key", key)
+    .maybeSingle();
+  if (readError) throw new Error(`Could not prepare the copy: ${readError.message}. Nothing was copied.`);
+  // Gone again: a call that finished this duplication has applied and removed it.
+  if (!row) return null;
+  const value = (row.value ?? {}) as { listing?: unknown };
+  return { key, listing: normalizePageListing(value.listing), recordedAt: String(row.created_at) };
+}
+
+/**
+ * Apply the duplication's recorded listing decision to the copy, if it is the
+ * original decision (see {@link recordDuplicateIntent}).
+ *
+ * Only ever inserts a missing listing row, so a listing chosen for the copy
+ * since (a row already present, listed or link-only) is never overwritten,
+ * and applying the same decision twice is harmless.
+ */
+async function completeDuplicateListing(
+  context: PagesContext,
+  intent: DuplicateIntent | null,
+  copyId: string,
+): Promise<void> {
+  if (!intent) return;
+  const { data: copy, error } = await context.supabase
+    .from("pages")
+    .select("created_at")
+    .eq("id", copyId)
+    .maybeSingle();
+  const recorded = timestampMicros(intent.recordedAt);
+  const created = timestampMicros(copy?.created_at);
+  if (error || recorded === null || created === null) {
+    // Undecidable now. The decision stays where it is, for a retry to settle.
+    throw new Error(
+      "The copy was made as a draft, but whether it is listed like the original could not be settled" +
+        (error ? `: ${error.message}` : "") +
+        ". Retrying the same duplication (same idempotency key) completes it without a second copy; " +
+        "otherwise check the copy's listing before publishing it.",
+    );
+  }
+  if (recorded < created && intent.listing === "link-only") {
+    const { error: writeError } = await context.supabase
+      .from("site_settings")
+      .upsert(
+        {
+          key: `${PAGE_LISTING_PREFIX}${copyId.toLowerCase()}`,
+          value: { listing: "link-only" },
+          updated_by: context.userId,
+        },
+        { onConflict: "key", ignoreDuplicates: true },
+      )
+      .select("updated_at");
+    if (writeError) {
+      throw new Error(
+        `The copy was made as a draft, but it could not be marked link-only like the original: ${writeError.message}. ` +
+          "Retrying the same duplication (same idempotency key) completes it without a second copy; " +
+          "otherwise set the copy to link-only before publishing it.",
+      );
+    }
+    invalidatePublishedCache();
+  }
+  await forgetDuplicateIntent(context, intent);
+}
+
+/**
+ * Remove the decision row once it has been dealt with. Nothing depends on this
+ * succeeding, so a failure is not an error: an original decision left behind
+ * only ever inserts what is already there, and a row written after the copy
+ * existed is never applied. Whatever row holds the key by now was written
+ * after the copy existed, so removing it loses no pending decision.
+ */
+async function forgetDuplicateIntent(context: PagesContext, intent: DuplicateIntent): Promise<void> {
+  await context.supabase.from("site_settings").delete().eq("key", intent.key);
+}
+
+/**
+ * A `timestamptz` as PostgREST returns it (`2026-10-16T11:03:36.123456+00:00`),
+ * in whole microseconds since the epoch, so two instants in the same
+ * millisecond still compare correctly. Null when it is not one.
+ */
+function timestampMicros(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  const match = /^(\d{4}-\d\d-\d\d)[T ](\d\d:\d\d:\d\d)(?:\.(\d{1,6})\d*)?(Z|[+-]\d\d(?::?\d\d)?)$/.exec(
+    value.trim(),
+  );
+  if (!match) return null;
+  const offset = match[4]!;
+  const zone =
+    offset === "Z" ? "Z" : offset.length === 3 ? `${offset}:00` : offset.replace(/^([+-]\d\d)(\d\d)$/, "$1:$2");
+  const seconds = Date.parse(`${match[1]}T${match[2]}${zone}`);
+  if (!Number.isFinite(seconds)) return null;
+  return seconds * 1000 + Number((match[3] ?? "").padEnd(6, "0"));
+}
+
 /* ---------- Global blocks ---------- */
 
 /** A global block holds exactly one block and may not reference other globals. */
@@ -1236,7 +1460,7 @@ function scheduleInstant(value: unknown, field: string): number {
  * and the page it promised to reveal stayed hidden for good.
  */
 export async function schedulePageVersionCore(
-  { context }: PagesDeps,
+  { context, protectedPageKeys }: PagesDeps,
   input: {
     versionId: string;
     publishAt: string;
@@ -1271,6 +1495,11 @@ export async function schedulePageVersionCore(
     resourceId: v.page_id,
     sessionId: input.editSessionId,
   });
+  // An end date is an unpublish on a timer, which a protected page refuses too.
+  if (unpublishAt !== null) {
+    const identity = await pageIdentity(context.supabase, v.page_id);
+    if (identity) assertNotProtected(protectedPageKeys, identity, "given an unpublish time");
+  }
   invalidatePublishedCache();
   const scheduled = await publicationRpc(
     context.supabase,

package/src/server/popup-optin-webhook-core.ts

@@ -25,6 +25,14 @@
  * Server-only. Never import from client code.
  */
 
+import {
+  fetchTransport,
+  injectedFetchResolver,
+  safeRequest,
+  WEBHOOK_POLICY,
+  type Resolver,
+  type Transport,
+} from "./outbound-http";
 import { checkWebhookUrl } from "./webhook-url-guard";
 
 export const POPUP_WEBHOOK_SCHEMA_VERSION = 1;
@@ -56,8 +64,15 @@ export interface OptInWebhookInput {
   readonly timeoutMs?: number;
   readonly maxResponseBytes?: number;
   readonly maxRedirects?: number;
-  /** Injected in tests. */
+  /**
+   * Test seam: requests go through this fetch instead of the network. Every
+   * hop is still checked and followed by the outbound policy, but names are
+   * not looked up and the connection is not pinned. Production passes none.
+   */
   readonly fetchImpl?: typeof fetch;
+  /** Test seams for the pinned path: a fake resolver and transport. */
+  readonly resolver?: Resolver;
+  readonly transport?: Transport;
   readonly now?: () => number;
 }
 
@@ -147,71 +162,6 @@ export async function signBody(
     .digest("hex");
 }
 
-/**
- * Read at most `limit` bytes of a response, then stop.
- *
- * A receiver that answers with a gigabyte would otherwise hold this server's
- * memory hostage. Nothing is done with the body but the read has to be bounded.
- */
-async function drainBounded(
-  response: Response,
-  limit: number,
-): Promise<boolean> {
-  const body = response.body;
-  if (body === null) return true;
-  const reader = body.getReader();
-  let total = 0;
-  try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) return true;
-      total += value?.byteLength ?? 0;
-      if (total > limit) return false;
-    }
-  } finally {
-    await reader.cancel().catch(() => undefined);
-  }
-}
-
-/**
- * POST with every redirect hop re-validated.
- *
- * `redirect: "manual"` is what makes the guard meaningful: with the default
- * `follow`, the runtime chases a 302 into the private network before any of
- * this code sees it.
- */
-async function postWithGuardedRedirects(
-  url: string,
-  init: RequestInit,
-  options: { fetchImpl: typeof fetch; maxRedirects: number; maxBytes: number },
-): Promise<
-  | { response: Response; oversize: boolean }
-  | { blocked: DeliveryOutcome["errorCategory"] }
-> {
-  let target = url;
-  for (let hop = 0; hop <= options.maxRedirects; hop += 1) {
-    const check = checkWebhookUrl(target);
-    if (!check.ok) return { blocked: "blocked-endpoint" };
-
-    const response = await options.fetchImpl(target, {
-      ...init,
-      redirect: "manual",
-    });
-
-    if (response.status >= 300 && response.status < 400) {
-      const location = response.headers.get("location");
-      if (location === null) return { response, oversize: false };
-      // Resolve relative redirects against the hop we actually made.
-      target = new URL(location, target).toString();
-      continue;
-    }
-
-    const withinLimit = await drainBounded(response, options.maxBytes);
-    return { response, oversize: !withinLimit };
-  }
-  return { blocked: "too-many-redirects" };
-}
-
 /**
  * Deliver one opt-in. Never throws.
  *
@@ -224,9 +174,6 @@ export async function deliverOptInWebhook(
 ): Promise<DeliveryOutcome> {
   const now = input.now ?? Date.now;
   const startedAt = now();
-  const fetchImpl = input.fetchImpl ?? fetch;
-  const maxBytes = input.maxResponseBytes ?? DEFAULT_MAX_BYTES;
-  const maxRedirects = input.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
 
   const check = checkWebhookUrl(input.endpoint);
   if (!check.ok) {
@@ -242,84 +189,76 @@ export async function deliverOptInWebhook(
   const timestamp = String(Math.floor(now() / 1000));
   const signature = await signBody(input.signingSecret, timestamp, body);
 
-  const controller = new AbortController();
-  const timer = setTimeout(
-    () => controller.abort(),
-    input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-  );
-
-  try {
-    const result = await postWithGuardedRedirects(
-      check.url.toString(),
-      {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          "user-agent": "cms-platform-webhooks/1",
-          "x-webhook-event":
-            input.test === true ? "popup.opt_in.test" : "popup.opt_in",
-          "x-webhook-event-id": input.eventId,
-          // The receiver deduplicates on this. Retries of the same opt-in
-          // reuse the same value, which is what makes a retry safe.
-          "x-webhook-idempotency-key": input.eventId,
-          "x-webhook-timestamp": timestamp,
-          "x-webhook-signature": `v1=${signature}`,
-        },
-        body,
-        signal: controller.signal,
-      },
-      { fetchImpl, maxRedirects, maxBytes },
-    );
+  // Every hop is checked, looked up, pinned and capped by the shared outbound
+  // policy; redirects are followed there, never by the runtime.
+  const network = input.fetchImpl
+    ? { transport: fetchTransport(input.fetchImpl), resolver: injectedFetchResolver }
+    : { transport: input.transport, resolver: input.resolver };
+  const result = await safeRequest({
+    url: check.url.toString(),
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "user-agent": "cms-platform-webhooks/1",
+      "x-webhook-event": input.test === true ? "popup.opt_in.test" : "popup.opt_in",
+      "x-webhook-event-id": input.eventId,
+      // The receiver deduplicates on this. Retries of the same opt-in
+      // reuse the same value, which is what makes a retry safe.
+      "x-webhook-idempotency-key": input.eventId,
+      "x-webhook-timestamp": timestamp,
+      "x-webhook-signature": `v1=${signature}`,
+    },
+    body,
+    policy: {
+      ...WEBHOOK_POLICY,
+      timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      maxResponseBytes: input.maxResponseBytes ?? DEFAULT_MAX_BYTES,
+      maxRedirects: input.maxRedirects ?? DEFAULT_MAX_REDIRECTS,
+    },
+    ...network,
+  });
+  const durationMs = now() - startedAt;
 
-    if ("blocked" in result) {
-      return {
-        ok: false,
-        errorCategory: result.blocked,
-        error:
-          result.blocked === "too-many-redirects"
-            ? "The endpoint redirected too many times."
-            : "The endpoint redirected to an address inside this server's network.",
-        durationMs: now() - startedAt,
-      };
+  if (!result.ok) {
+    switch (result.failure) {
+      case "blocked-url":
+      case "blocked-address":
+        return {
+          ok: false,
+          errorCategory: "blocked-endpoint",
+          error: "The endpoint, or an address it redirected to, is not a public https address.",
+          durationMs,
+        };
+      case "cross-origin-redirect":
+        return {
+          ok: false,
+          errorCategory: "blocked-endpoint",
+          error: "The endpoint redirected to another site; an opt-in is only sent to the configured address.",
+          durationMs,
+        };
+      case "too-many-redirects":
+        return { ok: false, errorCategory: "too-many-redirects", error: "The endpoint redirected too many times.", durationMs };
+      case "too-large":
+        return { ok: false, errorCategory: "too-large", error: "The endpoint's reply was too large.", durationMs };
+      case "timeout":
+        return { ok: false, errorCategory: "timeout", error: "The endpoint did not answer in time.", durationMs };
+      default:
+        return { ok: false, errorCategory: "network", error: "The endpoint could not be reached.", durationMs };
     }
+  }
 
-    const { response, oversize } = result;
-    if (oversize) {
-      return {
-        ok: false,
-        status: response.status,
-        errorCategory: "too-large",
-        error: "The endpoint's reply was too large.",
-        durationMs: now() - startedAt,
-      };
-    }
-    if (!response.ok) {
-      return {
-        ok: false,
-        status: response.status,
-        errorCategory: "http-error",
-        // Deliberately not the response body: it is attacker-influenced text
-        // that would end up in an administrator's screen and the logs.
-        error: `The endpoint answered ${response.status}.`,
-        durationMs: now() - startedAt,
-      };
-    }
-    return { ok: true, status: response.status, durationMs: now() - startedAt };
-  } catch (caught) {
-    const aborted =
-      caught instanceof Error &&
-      (caught.name === "AbortError" || caught.message.includes("aborted"));
+  if (result.status < 200 || result.status >= 300) {
     return {
       ok: false,
-      errorCategory: aborted ? "timeout" : "network",
-      error: aborted
-        ? "The endpoint did not answer in time."
-        : "The endpoint could not be reached.",
-      durationMs: now() - startedAt,
+      status: result.status,
+      errorCategory: "http-error",
+      // Deliberately not the response body: it is attacker-influenced text
+      // that would end up in an administrator's screen and the logs.
+      error: `The endpoint answered ${result.status}.`,
+      durationMs,
     };
-  } finally {
-    clearTimeout(timer);
   }
+  return { ok: true, status: result.status, durationMs };
 }
 
 // ---------------------------------------------------------------------------

package/src/server/published-cache.ts

@@ -13,7 +13,7 @@
  * tests. A cold process simply has an empty cache.
  */
 
-export type PublishedCacheScope = "page" | "global" | "custom";
+export type PublishedCacheScope = "page" | "global" | "policy" | "custom";
 
 type Entry = { value: unknown; expiresAt: number };
 
@@ -22,6 +22,16 @@ const store = new Map<string, Entry>();
 /** How long an entry may be served before it is re-read. */
 let ttlMs = 20_000;
 
+/**
+ * Bumped by every invalidation. A load records the generation it started in
+ * and may only store its answer if no invalidation happened meanwhile: a read
+ * that began before a write and finished after it holds the old state, and
+ * putting that back into the cache would undo the invalidation the write just
+ * made — every request after the write would be served what the write
+ * replaced.
+ */
+let generation = 0;
+
 /** Cheap counters so the backoffice can show whether the cache is working. */
 let hits = 0;
 let misses = 0;
@@ -83,6 +93,10 @@ export function publishedCacheSet(
  */
 export function invalidatePublishedCache(scope?: PublishedCacheScope, key?: string): void {
   invalidations += 1;
+  // Any invalidation, however narrow, retires every load already in flight:
+  // it may only cost a fill that was going to be correct, never let a stale
+  // one through.
+  generation += 1;
   if (!scope) {
     store.clear();
     return;
@@ -116,9 +130,14 @@ export async function withPublishedCache<T>(
     return cached;
   }
   misses += 1;
+  const startedIn = generation;
   const value = await load();
-  // `undefined` is indistinguishable from "absent", so it is never stored.
-  if (value !== undefined) publishedCacheSet(scope, key, value, boundaryOf?.(value));
+  // `undefined` is indistinguishable from "absent", so it is never stored. A
+  // value whose read began before an invalidation is returned to its caller —
+  // it is what that caller asked for — but never stored for anyone else.
+  if (value !== undefined && startedIn === generation) {
+    publishedCacheSet(scope, key, value, boundaryOf?.(value));
+  }
   return value;
 }
 
@@ -136,6 +155,7 @@ export function publishedCacheStats(): {
 /** Resets counters and contents. Tests use this between cases. */
 export function resetPublishedCache(): void {
   store.clear();
+  generation += 1;
   hits = 0;
   misses = 0;
   invalidations = 0;