create-ailk 0.22.0 → 0.23.0

package/templates/apps/api/src/services/offerings/index.ts

@@ -0,0 +1,614 @@
+/**
+ * The Offerings read services (#8876, spec
+ * docs/specs/8876-the-offerings-data-model-typed-spec.md D7, D8) — what
+ * `/pricing`, checkout, plan offerings and the MCP tools read (#8858–#8862).
+ *
+ * - `getOrgEnabledProducts` — the Organization's enabled set and its live
+ *   catalog (the Admin's org pane).
+ * - `getWorkspaceShownSet` — what a workspace shows, from the rows and the
+ *   last-good snapshot. Never calls Stripe (contract T7).
+ * - `getSellableProductIds` — checkout's allowlist, org-enabled ∩
+ *   workspace-shown from the rows alone, never the snapshot (contract A4),
+ *   with the shown Price ids (#9070 D2).
+ * - `shownPriceIdsFor` — the one rule for which Prices a selection shows
+ *   (#9070 D2): its stored Price ids, or every Price of each shown Product
+ *   for a row saved before #9070.
+ * - `refreshWorkspaceSnapshot` — the bounded refresh that writes the snapshot.
+ * - `listOrgProducts` — every active product of the Organization's catalog,
+ *   with its enabled flag and held reason (#8922, the owner's list).
+ * - `setOrgEnabledProducts` — the owner's write of the org-enabled set,
+ *   refusing a held or unknown product (#8922, the lookup-key gate).
+ *
+ * The workspace's Organization always comes from `Workspace.organizationId`,
+ * never from a caller, and a catalog source is built by the service for that
+ * Organization (`sourceFor`), so no caller can pair one workspace with
+ * another Organization's connection or catalog. No connection serves nothing,
+ * never the env key (NFR2); an unreadable one serves nothing and is never
+ * reported as absent.
+ *
+ * Every result is parsed with its `@working-theory/validation` schema before
+ * it is returned; a failure is `OfferingsShapeError`, whose fixed message
+ * carries no Stripe text (contract T6).
+ *
+ * The services read no licence claim: every caller gates on
+ * `requireCommerceClaim` first (D10).
+ *
+ * LOGGING (D11). `workspaceId` or `organizationId`, a fixed `outcome` or
+ * `reason`, a count, and on a source failure the error's class name. Never a
+ * product or price id, a name, any Stripe text, `keyLast4`, a token or a
+ * ciphertext (contract C5, T6).
+ */
+import { logger } from "@working-theory/observability";
+import {
+  offeringsPriceIdsSchema,
+  offeringsProductIdsSchema,
+  offeringsSnapshotSchema,
+  orgEnabledProductsSchema,
+  workspaceShownSetSchema,
+  type OfferingsHeldReason,
+  type OfferingsProduct,
+  type OfferingsSnapshot,
+  type OrgEnabledProducts,
+  type WorkspaceShownSet,
+} from "@working-theory/validation";
+
+import {
+  OFFERINGS_CATALOG_PRICES_MAX,
+  OFFERINGS_CATALOG_PRODUCTS_MAX,
+  normalizeCatalog,
+  type NormalizedCatalog,
+  type OfferingsCatalogSource,
+} from "./catalog.js";
+import { getStripeConnectionSummary } from "./connection.js";
+import {
+  OfferingsShapeError,
+  organizationIdOfWorkspace,
+  readEnabledProductIds,
+  readWorkspaceSelection,
+  readWorkspaceSnapshot,
+  writeEnabledProductIds,
+  writeWorkspaceSnapshot,
+} from "./store.js";
+
+export {
+  OFFERINGS_CATALOG_PRICES_MAX,
+  OFFERINGS_CATALOG_PRODUCTS_MAX,
+  isOfferingsProduct,
+  normalizeCatalog,
+  type CatalogPrice,
+  type CatalogProduct,
+  type NormalizedCatalog,
+  type OfferingsCatalog,
+  type OfferingsCatalogSource,
+} from "./catalog.js";
+export { getStripeConnectionSummary } from "./connection.js";
+export { OfferingsShapeError } from "./store.js";
+
+/** The snapshot is served for at most 24 hours from `snapshotAt` (C5). */
+export const LAST_GOOD_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/** One catalog read per Organization per minute, per process (T7). */
+export const REFRESH_MIN_INTERVAL_MS = 60 * 1000;
+/** A `snapshotAt` further ahead of `now` than this is treated as expired. */
+export const SNAPSHOT_FUTURE_SKEW_MS = 5 * 60 * 1000;
+
+/** Builds the catalog source for the Organization the service resolved. */
+export type OfferingsSourceFor = (organizationId: string) => OfferingsCatalogSource;
+
+/** The catalog source failed, or failed under a minute ago. No Stripe text. */
+export class OfferingsSourceError extends Error {
+  constructor() {
+    super("The Offerings catalog could not be read");
+    this.name = "OfferingsSourceError";
+  }
+}
+
+export type RefreshOutcome =
+  | "no_connection"
+  | "no_selection"
+  | "fresh"
+  | "throttled"
+  | "source_failed"
+  | "refreshed";
+
+export interface SellableProductIds {
+  organizationId: string;
+  productIds: string[];
+  /** The stored shown Price ids, or `null` for a row saved per Product (#9070 D2). */
+  priceIds: string[] | null;
+}
+
+/** One product of the owner's list (#8922 D3). Nothing else crosses the API. */
+export interface OrgProductEntry {
+  productId: string;
+  /** The normalized name; `""` for a `name_missing` product. */
+  name: string;
+  /** The offering's normalized description; `null` for a held product. */
+  description: string | null;
+  /** In the stored set and sellable — a held product is always `false`. */
+  enabled: boolean;
+  /** `null` exactly when the product is sellable. */
+  heldReason: OfferingsHeldReason | null;
+}
+
+export type OrgProductList =
+  | { connection: "none" }
+  | { connection: "unreadable" }
+  | { connection: "connected"; products: OrgProductEntry[] };
+
+export type ConnectedOrgProductList = Extract<OrgProductList, { connection: "connected" }>;
+
+/** Why a set write was refused (#8922 D3 step 3). */
+export type OrgEnabledRefusal = "product_not_in_catalog" | "product_held";
+
+export type SetOrgEnabledResult =
+  | { kind: "not_connected" }
+  | { kind: "connection_unreadable" }
+  | { kind: "refused"; reason: OrgEnabledRefusal }
+  | { kind: "written"; previous: string[]; list: ConnectedOrgProductList };
+
+/** Parse `value` with `schema`, or reject with the fixed-message error. */
+function parseResult<T>(schema: { parse(value: unknown): T }, value: unknown): T {
+  try {
+    return schema.parse(value);
+  } catch {
+    throw new OfferingsShapeError();
+  }
+}
+
+/** `shown` ∩ `enabled`, in shown order, each id once. */
+function intersect(shown: string[], enabled: string[]): string[] {
+  const allowed = new Set(enabled);
+  return [...new Set(shown)].filter((id) => allowed.has(id));
+}
+
+/** Errors' class name only — never a message, which can name a masked key. */
+function errName(err: unknown): string {
+  return err instanceof Error ? err.constructor.name : typeof err;
+}
+
+// ─── The per-process catalog read state (D8 steps 3–5) ──────────────────────
+
+interface OrganizationReadState {
+  inFlight?: Promise<NormalizedCatalog>;
+  /** The last read and when it started; `catalog: null` for a failed one. */
+  last?: { at: number; catalog: NormalizedCatalog | null };
+}
+
+const readState = new Map<string, OrganizationReadState>();
+
+/** Test-only: forget every read in flight and every Organization's last read. */
+export function resetOfferingsRefreshStateForTests(): void {
+  readState.clear();
+}
+
+/** The throttle answer of `readCatalog` — a failed read under a minute old. */
+const THROTTLED = Symbol("throttled");
+
+/**
+ * Whether a last read at `at` still holds the Organization at `now`. A read
+ * dated a little after `now` holds it too: concurrent callers take `now`
+ * before their own database reads, so a caller can arrive with a `now` a
+ * little older than the read another caller just made (SEC-PR8955-1). A read
+ * dated more than the skew ahead holds nothing, so a skewed clock cannot hold
+ * an Organization indefinitely (SEC-PR8955-R2-2).
+ */
+function withinWindow(at: number, now: number): boolean {
+  return now - at < REFRESH_MIN_INTERVAL_MS && at - now <= SNAPSHOT_FUTURE_SKEW_MS;
+}
+
+/**
+ * Forget every Organization whose last read no longer holds it, so the map
+ * keeps at most the Organizations read in the last minute, not every one
+ * this process ever read.
+ */
+function evictStaleReads(now: number): void {
+  for (const [organizationId, state] of readState) {
+    if (!state.inFlight && (!state.last || !withinWindow(state.last.at, now))) {
+      readState.delete(organizationId);
+    }
+  }
+}
+
+/**
+ * One Organization's normalized catalog (D8 steps 3–5): join a read in
+ * flight; unless `force`, reuse a successful read under a minute old, or
+ * answer `THROTTLED` after a failed one; otherwise read once. Every read,
+ * failed or not, becomes the Organization's last read. Rejects with the
+ * source's own error, which no caller passes on.
+ */
+async function readCatalog(
+  organizationId: string,
+  sourceFor: OfferingsSourceFor,
+  now: Date,
+  force: boolean,
+): Promise<NormalizedCatalog | typeof THROTTLED> {
+  evictStaleReads(now.getTime());
+  const state = readState.get(organizationId) ?? {};
+  readState.set(organizationId, state);
+  if (state.inFlight) return state.inFlight;
+  if (!force && state.last && withinWindow(state.last.at, now.getTime())) {
+    return state.last.catalog ?? THROTTLED;
+  }
+  const read = (async () => {
+    const catalog = await sourceFor(organizationId).listActiveCatalog();
+    const dropped =
+      Math.max(0, catalog.products.length - OFFERINGS_CATALOG_PRODUCTS_MAX) +
+      Math.max(0, catalog.prices.length - OFFERINGS_CATALOG_PRICES_MAX);
+    if (dropped > 0) {
+      logger.warn(
+        { organizationId, reason: "catalog_truncated", dropped },
+        "[offerings] catalog over its read cap",
+      );
+    }
+    return normalizeCatalog(catalog);
+  })();
+  state.inFlight = read;
+  try {
+    const catalog = await read;
+    state.last = { at: now.getTime(), catalog };
+    return catalog;
+  } catch (err) {
+    state.last = { at: now.getTime(), catalog: null };
+    throw err;
+  } finally {
+    delete state.inFlight;
+  }
+}
+
+// ─── The readers (D7) ───────────────────────────────────────────────────────
+
+/**
+ * The Organization's enabled set and those Products' live catalog entries.
+ * `null` with no connection. Calls the source at most once (D8's reuse);
+ * rejects with `OfferingsSourceError` when the read fails, or failed under a
+ * minute ago. Every `recommended` is `false`: Recommended is a workspace's.
+ */
+export async function getOrgEnabledProducts(
+  organizationId: string,
+  sourceFor: OfferingsSourceFor,
+  { now = new Date() }: { now?: Date } = {},
+): Promise<OrgEnabledProducts | null> {
+  const connection = await getStripeConnectionSummary(organizationId);
+  if (connection === null) return null;
+  const productIds = await readEnabledProductIds(organizationId);
+  if (connection === "unreadable") {
+    return parseResult(orgEnabledProductsSchema, { organizationId, productIds, offerings: [], held: [] });
+  }
+  const catalog = await catalogOrSourceError(organizationId, sourceFor, now);
+  const enabled = new Set(productIds);
+  return parseResult(orgEnabledProductsSchema, {
+    organizationId,
+    productIds,
+    offerings: catalog.offerings
+      .filter((o) => enabled.has(o.productId))
+      .map((o): OfferingsProduct => ({ ...o, recommended: false })),
+    held: catalog.held.filter((h) => enabled.has(h.productId)),
+  });
+}
+
+/**
+ * The Organization's catalog, read once a minute at most (D8), or the
+ * fixed-message source error. Logs only the error's class name.
+ */
+async function catalogOrSourceError(
+  organizationId: string,
+  sourceFor: OfferingsSourceFor,
+  now: Date,
+): Promise<NormalizedCatalog> {
+  let catalog: NormalizedCatalog | typeof THROTTLED;
+  try {
+    catalog = await readCatalog(organizationId, sourceFor, now, false);
+  } catch (err) {
+    logger.warn(
+      { organizationId, outcome: "source_failed", errName: errName(err) },
+      "[offerings] catalog read failed",
+    );
+    throw new OfferingsSourceError();
+  }
+  if (catalog === THROTTLED) throw new OfferingsSourceError();
+  return catalog;
+}
+
+/** The connected list for `catalog` and the stored `enabled` set (#8922 D3). */
+function orgProductList(
+  catalog: NormalizedCatalog,
+  enabled: string[],
+): ConnectedOrgProductList {
+  const on = new Set(enabled);
+  return {
+    connection: "connected",
+    products: [
+      ...catalog.offerings.map(
+        (o): OrgProductEntry => ({
+          productId: o.productId,
+          name: o.name,
+          description: o.description,
+          enabled: on.has(o.productId),
+          heldReason: null,
+        }),
+      ),
+      ...catalog.held.map(
+        (h): OrgProductEntry => ({
+          productId: h.productId,
+          name: h.name,
+          description: null,
+          enabled: false,
+          heldReason: h.reason,
+        }),
+      ),
+    ],
+  };
+}
+
+/**
+ * Every active product of the Organization's catalog (#8922 D3): the
+ * normalizer's offerings in its order, then its held products, each once,
+ * with its enabled flag and held reason. `none` with no connection and
+ * `unreadable` for a corrupt one, neither calling the source. Shares the
+ * per-minute read; rejects with `OfferingsSourceError`.
+ */
+export async function listOrgProducts(
+  organizationId: string,
+  sourceFor: OfferingsSourceFor,
+  { now = new Date() }: { now?: Date } = {},
+): Promise<OrgProductList> {
+  const connection = await getStripeConnectionSummary(organizationId);
+  if (connection === null) return { connection: "none" };
+  if (connection === "unreadable") return { connection: "unreadable" };
+  const enabled = await readEnabledProductIds(organizationId);
+  return orgProductList(await catalogOrSourceError(organizationId, sourceFor, now), enabled);
+}
+
+/**
+ * Replace the org-enabled set (#8922 D3, contract A12, G3, G4). `productIds`
+ * has passed `offeringsProductIdsSchema` at the route. Every id must be an
+ * offering of the catalog: one in neither list is `product_not_in_catalog`
+ * (which wins when both apply), one held for any reason is `product_held`,
+ * and nothing is written. The answer's list is built, and handed to `validate` (the route's
+ * response parse, which throws to stop the write), before the write, so a
+ * write is never followed by a failed answer. Rejects with
+ * `OfferingsSourceError` when the catalog cannot be read.
+ */
+export async function setOrgEnabledProducts(
+  organizationId: string,
+  productIds: string[],
+  sourceFor: OfferingsSourceFor,
+  {
+    now = new Date(),
+    validate,
+  }: { now?: Date; validate: (list: ConnectedOrgProductList) => void },
+): Promise<SetOrgEnabledResult> {
+  const connection = await getStripeConnectionSummary(organizationId);
+  if (connection === null) return { kind: "not_connected" };
+  if (connection === "unreadable") return { kind: "connection_unreadable" };
+  const catalog = await catalogOrSourceError(organizationId, sourceFor, now);
+
+  const sellable = new Set(catalog.offerings.map((o) => o.productId));
+  const held = new Set(catalog.held.map((h) => h.productId));
+  if (productIds.some((id) => !sellable.has(id) && !held.has(id))) {
+    return { kind: "refused", reason: "product_not_in_catalog" };
+  }
+  if (productIds.some((id) => held.has(id))) return { kind: "refused", reason: "product_held" };
+
+  const list = orgProductList(catalog, productIds);
+  validate(list);
+  const previous = await readEnabledProductIds(organizationId);
+  await writeEnabledProductIds(organizationId, productIds);
+  return { kind: "written", previous, list };
+}
+
+/**
+ * The Price ids a selection shows among `offerings` (#9070 D2): its stored
+ * Price ids, or — for a row saved before #9070 (none stored) — every Price of
+ * each shown Product. Only ids `offerings` carries are answered, so a Price
+ * the seller replaced in Stripe is not shown until its row is switched on.
+ */
+export function shownPriceIdsFor(
+  offerings: ReadonlyArray<{
+    productId: string;
+    prices: ReadonlyArray<{ priceId: string }>;
+  }>,
+  selection: { shownProductIds: string[]; shownPriceIds: string[] },
+): Set<string> {
+  const carried = offerings.flatMap((o) => o.prices.map((p) => p.priceId));
+  if (selection.shownPriceIds.length > 0) {
+    const stored = new Set(selection.shownPriceIds);
+    return new Set(carried.filter((id) => stored.has(id)));
+  }
+  const shown = new Set(selection.shownProductIds);
+  return new Set(
+    offerings.filter((o) => shown.has(o.productId)).flatMap((o) => o.prices.map((p) => p.priceId)),
+  );
+}
+
+interface ResolvedWorkspace {
+  organizationId: string;
+  unreadable: boolean;
+  shownProductIds: string[];
+  shownPriceIds: string[];
+  recommendedPlanProductId: string | null;
+  recommendedAddonProductId: string | null;
+  /** shown ∩ enabled — empty for an unreadable connection. */
+  productIds: string[];
+}
+
+/**
+ * The workspace's Organization, its connection and both sets — or which of
+ * them is missing (no workspace and no selection row are both
+ * `no_selection`; an unreadable connection is never missing). Never reads
+ * the snapshot.
+ */
+async function resolveWorkspace(
+  workspaceId: string,
+): Promise<{ missing: "no_connection" | "no_selection" } | ResolvedWorkspace> {
+  const organizationId = await organizationIdOfWorkspace(workspaceId);
+  if (organizationId === null) return { missing: "no_selection" };
+  const connection = await getStripeConnectionSummary(organizationId);
+  if (connection === null) return { missing: "no_connection" };
+  // An unreadable connection serves nothing, with or without a selection
+  // row, and never reads as unconnected (SEC-PR8955-R2-1).
+  if (connection === "unreadable") {
+    return {
+      organizationId,
+      unreadable: true,
+      shownProductIds: [],
+      shownPriceIds: [],
+      recommendedPlanProductId: null,
+      recommendedAddonProductId: null,
+      productIds: [],
+    };
+  }
+  const selection = await readWorkspaceSelection(workspaceId);
+  if (selection === null) return { missing: "no_selection" };
+  const enabled = await readEnabledProductIds(organizationId);
+  return {
+    organizationId,
+    unreadable: false,
+    ...selection,
+    productIds: intersect(selection.shownProductIds, enabled),
+  };
+}
+
+/**
+ * What a workspace shows (the AC 2 shape): the shown ∩ enabled ids from the
+ * rows on every call, the snapshot's offerings for them, and Recommended per
+ * group. `state` is `current` while the snapshot is at most 24 hours old,
+ * `expired` (with no offerings) after that or when it is dated more than five
+ * minutes ahead, and `empty` with no snapshot or an unreadable one. Never
+ * calls the catalog source.
+ */
+export async function getWorkspaceShownSet(
+  workspaceId: string,
+  { now = new Date() }: { now?: Date } = {},
+): Promise<WorkspaceShownSet | null> {
+  const ws = await resolveWorkspace(workspaceId);
+  if ("missing" in ws) return null;
+  const base = { workspaceId, organizationId: ws.organizationId, productIds: ws.productIds };
+  const empty = {
+    ...base,
+    recommended: { plan: null, addon: null },
+    offerings: [],
+    state: "empty",
+    snapshotAt: null,
+  };
+  if (ws.unreadable) return parseResult(workspaceShownSetSchema, empty);
+
+  const row = await readWorkspaceSnapshot(workspaceId);
+  if (!row || row.snapshot === null || row.snapshotAt === null) {
+    return parseResult(workspaceShownSetSchema, empty);
+  }
+  const snapshot = offeringsSnapshotSchema.safeParse(row.snapshot);
+  if (!snapshot.success) {
+    logger.warn(
+      { workspaceId, reason: "snapshot_unreadable" },
+      "[offerings] workspace snapshot is unreadable",
+    );
+    return parseResult(workspaceShownSetSchema, empty);
+  }
+  const age = now.getTime() - row.snapshotAt.getTime();
+  const snapshotAt = row.snapshotAt.toISOString();
+  if (age > LAST_GOOD_MAX_AGE_MS || -age > SNAPSHOT_FUTURE_SKEW_MS) {
+    return parseResult(workspaceShownSetSchema, { ...empty, state: "expired", snapshotAt });
+  }
+
+  // The Product filter, then each offering keeps only its shown Prices
+  // (#9070 D2); an offering left with none is not shown at all.
+  const shown = new Set(ws.productIds);
+  const byProduct = snapshot.data.offerings.filter((o) => shown.has(o.productId));
+  const shownPrices = shownPriceIdsFor(byProduct, ws);
+  const offerings = byProduct
+    .map((o) => ({ ...o, prices: o.prices.filter((p) => shownPrices.has(p.priceId)) }))
+    .filter((o) => o.prices.length > 0);
+  const recommendedIf = (id: string | null, group: "plan" | "addon") =>
+    id !== null && offerings.some((o) => o.productId === id && o.ailkGroup === group) ? id : null;
+  const recommended = {
+    plan: recommendedIf(ws.recommendedPlanProductId, "plan"),
+    addon: recommendedIf(ws.recommendedAddonProductId, "addon"),
+  };
+  return parseResult(workspaceShownSetSchema, {
+    ...base,
+    recommended,
+    offerings: offerings.map(
+      (o): OfferingsProduct => ({
+        ...o,
+        recommended: o.productId === recommended.plan || o.productId === recommended.addon,
+      }),
+    ),
+    state: "current",
+    snapshotAt,
+  });
+}
+
+/**
+ * Checkout's allowlist (contract A4): org-enabled ∩ workspace-shown, from the
+ * rows alone — never the snapshot column — and the stored shown Price ids, or
+ * `null` for a row saved per Product (#9070 D2; checkout reads the live Price,
+ * so the snapshot's Prices are never needed). `null` in
+ * `getWorkspaceShownSet`'s three cases; an unreadable connection sells
+ * nothing. Never calls Stripe.
+ */
+export async function getSellableProductIds(workspaceId: string): Promise<SellableProductIds | null> {
+  const ws = await resolveWorkspace(workspaceId);
+  if ("missing" in ws) return null;
+  return {
+    organizationId: ws.organizationId,
+    productIds: parseResult(offeringsProductIdsSchema, ws.productIds),
+    priceIds:
+      ws.shownPriceIds.length > 0 ? parseResult(offeringsPriceIdsSchema, ws.shownPriceIds) : null,
+  };
+}
+
+/**
+ * Refresh one workspace's snapshot (D8, contract T7). At most one catalog
+ * read per Organization in flight and, unless `force`, per minute per
+ * process — a failed read holds the Organization as a successful one does.
+ * A failed read writes nothing, so the last good snapshot stays. `force` is
+ * for an authenticated owner write only (#8859's save); an anonymous path
+ * never passes it. The write never replaces a snapshot newer than this
+ * refresh's `now`, so a slow refresh cannot overwrite an owner's save; that
+ * refresh answers `fresh`.
+ *
+ * It answers an outcome for every catalog result, and rejects only on a
+ * database failure or an `OfferingsShapeError`; a caller that fires it
+ * without awaiting must catch.
+ */
+export async function refreshWorkspaceSnapshot(
+  workspaceId: string,
+  sourceFor: OfferingsSourceFor,
+  { now = new Date(), force = false }: { now?: Date; force?: boolean } = {},
+): Promise<RefreshOutcome> {
+  const ws = await resolveWorkspace(workspaceId);
+  if ("missing" in ws) return ws.missing;
+  if (ws.unreadable) return "no_connection";
+
+  if (!force) {
+    const row = await readWorkspaceSnapshot(workspaceId);
+    // A snapshot under a minute old is fresh, and so is one dated a little
+    // after `now` (within the skew a reader still serves as current).
+    const at = row?.snapshotAt?.getTime();
+    if (at !== undefined && withinWindow(at, now.getTime())) return "fresh";
+  }
+
+  let catalog: NormalizedCatalog | typeof THROTTLED;
+  try {
+    catalog = await readCatalog(ws.organizationId, sourceFor, now, force);
+  } catch (err) {
+    logger.warn(
+      { workspaceId, outcome: "source_failed", errName: errName(err) },
+      "[offerings] snapshot refresh failed",
+    );
+    return "source_failed";
+  }
+  if (catalog === THROTTLED) return "throttled";
+
+  const shown = new Set(ws.productIds);
+  const snapshot: OfferingsSnapshot = parseResult(offeringsSnapshotSchema, {
+    v: 1,
+    offerings: catalog.offerings.filter((o) => shown.has(o.productId)),
+  });
+  // The selection row was just read, so a write that lands on no row was
+  // refused by a snapshot newer than this refresh: the row is already fresh.
+  return (await writeWorkspaceSnapshot(workspaceId, snapshot, now, SNAPSHOT_FUTURE_SKEW_MS))
+    ? "refreshed"
+    : "fresh";
+}