create-ailk 0.22.0 → 0.24.0

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

@@ -0,0 +1,140 @@
+/**
+ * The Stripe-backed Offerings catalog source (#8922, spec
+ * docs/specs/8922-the-may-sell-product-list-spec.md D2; contract
+ * docs/specs/8879-the-offerings-security-contract-key-spec.md C8, T1, T7) —
+ * the `OfferingsSourceFor` the routes pass to the read services: one
+ * Organization's active Products and Prices, read through its own
+ * connection's client (#8907 D12) and paged to the normalizer's caps.
+ *
+ * `stripeCatalogSourceFor` does no work when called, so it can never throw
+ * outside the services' failure memo (#8876 D8). It takes a bare
+ * Organization id and checks neither the tenant nor the claim — its callers
+ * do — so `architecture.yaml` confines it to the exact files that call it.
+ *
+ * BOUNDED (SEC-8922-3). Each list is paged by calls, not items: at most
+ * `OFFERINGS_CATALOG_PRODUCTS_MAX / 100` product calls and
+ * `OFFERINGS_CATALOG_PRICES_MAX / 100` price calls, stopping early on
+ * `has_more: false`, an empty page, a page whose last id repeats the cursor
+ * it was asked with, or a full count. The whole read is bounded by
+ * `OFFERINGS_CATALOG_READ_TIMEOUT_MS`; after it fails, no further call is
+ * started.
+ *
+ * A list cut off at its cap while Stripe still had more is logged as
+ * `catalog_truncated` (SEC-8922-7), with the Organization and nothing else.
+ *
+ * Nothing is filtered or cached here: the client lives only inside
+ * one read (C8), and every field is normalized once by `normalizeCatalog`
+ * (T1). A disconnected or unusable connection rejects, never reading as an
+ * empty catalog; a Stripe error rejects as itself, and the services turn it
+ * into `OfferingsSourceError` without its text.
+ */
+import { logger } from "@working-theory/observability";
+
+import {
+  OFFERINGS_CATALOG_PRICES_MAX,
+  OFFERINGS_CATALOG_PRODUCTS_MAX,
+  type OfferingsCatalog,
+  type OfferingsCatalogSource,
+} from "./catalog.js";
+import { stripeClientForOrganization } from "./connection.js";
+
+import type { OfferingsSourceFor } from "./index.js";
+
+/** The longest one catalog read may take, connection lookup included. */
+export const OFFERINGS_CATALOG_READ_TIMEOUT_MS = 20_000;
+
+const PAGE_LIMIT = 100;
+
+/** No usable connection, or the read timed out. The message is fixed; there is no cause. */
+export class OfferingsCatalogUnavailableError extends Error {
+  constructor() {
+    super("The Offerings catalog source is unavailable");
+    this.name = "OfferingsCatalogUnavailableError";
+  }
+}
+
+interface ListParams {
+  active: true;
+  limit: number;
+  starting_after?: string;
+}
+
+interface ListPage<T> {
+  data: T[];
+  has_more: boolean;
+}
+
+/**
+ * One list paged to `maxItems`, by at most `maxItems / PAGE_LIMIT` calls.
+ * `truncated` when the bound stopped it while Stripe still had more.
+ */
+async function pageAll<T extends { id?: unknown }>(
+  list: (params: ListParams) => PromiseLike<ListPage<T>>,
+  maxItems: number,
+  aborted: () => boolean,
+): Promise<{ items: T[]; truncated: boolean }> {
+  const items: T[] = [];
+  let after: string | undefined;
+  for (let call = 0; call < maxItems / PAGE_LIMIT && items.length < maxItems; call++) {
+    if (aborted()) throw new OfferingsCatalogUnavailableError();
+    const page = await list({
+      active: true,
+      limit: PAGE_LIMIT,
+      ...(after !== undefined && { starting_after: after }),
+    });
+    items.push(...page.data);
+    const last = page.data.at(-1)?.id;
+    if (!page.has_more || typeof last !== "string" || last === after) return { items, truncated: false };
+    after = last;
+  }
+  return { items, truncated: true };
+}
+
+/** The Organization's catalog source. Builds nothing until it is read. */
+export const stripeCatalogSourceFor: OfferingsSourceFor = (
+  organizationId: string,
+): OfferingsCatalogSource => ({
+  async listActiveCatalog(): Promise<OfferingsCatalog> {
+    let aborted = false;
+    const isAborted = () => aborted;
+    const read = (async (): Promise<OfferingsCatalog> => {
+      const connection = await stripeClientForOrganization(organizationId);
+      if (connection.kind !== "ok") throw new OfferingsCatalogUnavailableError();
+      const { client } = connection;
+      const products = pageAll(
+        (params) => client.products.list(params),
+        OFFERINGS_CATALOG_PRODUCTS_MAX,
+        isAborted,
+      );
+      const prices = pageAll((params) => client.prices.list(params), OFFERINGS_CATALOG_PRICES_MAX, isAborted);
+      // Each loop is caught on its own, so a page that rejects after the
+      // other loop or the timeout has failed the read is never unhandled.
+      products.catch(() => undefined);
+      prices.catch(() => undefined);
+      const [productPages, pricePages] = await Promise.all([products, prices]);
+      if (productPages.truncated || pricePages.truncated) {
+        logger.warn(
+          { organizationId, reason: "catalog_truncated" },
+          "[offerings] catalog over its read cap",
+        );
+      }
+      return { products: productPages.items, prices: pricePages.items };
+    })();
+    read.catch(() => undefined);
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        aborted = true;
+        reject(new OfferingsCatalogUnavailableError());
+      }, OFFERINGS_CATALOG_READ_TIMEOUT_MS);
+    });
+    try {
+      return await Promise.race([read, timeout]);
+    } finally {
+      clearTimeout(timer);
+      // A loop still running after the other one failed starts no more calls.
+      aborted = true;
+    }
+  },
+});

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

@@ -0,0 +1,150 @@
+/**
+ * The Offerings sets and the snapshot (#8876, spec
+ * docs/specs/8876-the-offerings-data-model-typed-spec.md D6) — the one file
+ * naming the org-enabled set, the workspace selection and its snapshot, and,
+ * for this service, the workspace's Organization.
+ *
+ * Every argument is a server-resolved id, never a request value, except a
+ * set or selection handed to a writer, which its caller checked and the
+ * writer parses; and no function lists or enumerates. The selection read
+ * never names the snapshot, so checkout's allowlist (contract A4) can never
+ * read the display copy.
+ *
+ * This file writes the snapshot, only into a row that exists; for #8922, the
+ * org-enabled set; and, for #8926, the workspace selection and Recommended,
+ * creating its row.
+ */
+import {
+  offeringsProductIdsSchema,
+  workspaceOfferingsSelectionSchema,
+  type OfferingsSnapshot,
+} from "@working-theory/validation";
+
+import { prisma } from "../../lib/prisma.js";
+
+/**
+ * An Offerings result, or a set handed to a writer, failed its schema. The
+ * message is fixed; there is no cause. Re-exported by `index.ts`.
+ */
+export class OfferingsShapeError extends Error {
+  constructor() {
+    super("An Offerings result failed its schema");
+    this.name = "OfferingsShapeError";
+  }
+}
+
+export interface WorkspaceSelection {
+  shownProductIds: string[];
+  /** The shown Prices (#9070 D1); empty for a row saved per Product. */
+  shownPriceIds: string[];
+  recommendedPlanProductId: string | null;
+  recommendedAddonProductId: string | null;
+}
+
+export interface WorkspaceSnapshotRow {
+  snapshot: unknown;
+  snapshotAt: Date | null;
+}
+
+/** The workspace's own Organization, or `null` for no workspace. */
+export async function organizationIdOfWorkspace(workspaceId: string): Promise<string | null> {
+  const row = await prisma.workspace.findUnique({
+    where: { id: workspaceId },
+    select: { organizationId: true },
+  });
+  return row?.organizationId ?? null;
+}
+
+/** The org-enabled set; no row is the empty set. */
+export async function readEnabledProductIds(organizationId: string): Promise<string[]> {
+  const row = await prisma.organizationOfferings.findUnique({
+    where: { organizationId },
+    select: { enabledProductIds: true },
+  });
+  return row?.enabledProductIds ?? [];
+}
+
+/**
+ * Replace the org-enabled set (#8922 D4), creating the row on an
+ * Organization's first save. Every set is parsed first — at most 100
+ * distinct Stripe ids — so the bound holds for every writer.
+ */
+export async function writeEnabledProductIds(organizationId: string, productIds: string[]): Promise<void> {
+  const parsed = offeringsProductIdsSchema.safeParse(productIds);
+  if (!parsed.success) throw new OfferingsShapeError();
+  await prisma.organizationOfferings.upsert({
+    where: { organizationId },
+    create: { organizationId, enabledProductIds: parsed.data },
+    update: { enabledProductIds: parsed.data },
+  });
+}
+
+/** The shown set and Recommended, or `null` for no row. Never the snapshot. */
+export async function readWorkspaceSelection(workspaceId: string): Promise<WorkspaceSelection | null> {
+  return prisma.workspaceOfferings.findUnique({
+    where: { workspaceId },
+    select: {
+      shownProductIds: true,
+      shownPriceIds: true,
+      recommendedPlanProductId: true,
+      recommendedAddonProductId: true,
+    },
+  });
+}
+
+/**
+ * Replace the workspace's selection (#8926 D5), creating the row on its first
+ * save. Every selection is parsed first — at most 100 distinct Product ids
+ * and 300 Price ids, Prices exactly when Products (#9070 D4), each
+ * Recommended shown — so the database's CHECKs never fire and no new save is
+ * at the per-Product grain. Never names the snapshot, so a save keeps the
+ * last good copy.
+ */
+export async function writeWorkspaceSelection(
+  workspaceId: string,
+  selection: WorkspaceSelection,
+): Promise<void> {
+  const parsed = workspaceOfferingsSelectionSchema.safeParse(selection);
+  if (!parsed.success) throw new OfferingsShapeError();
+  const { shownProductIds, shownPriceIds, recommendedPlanProductId, recommendedAddonProductId } =
+    parsed.data;
+  await prisma.workspaceOfferings.upsert({
+    where: { workspaceId },
+    create: { workspaceId, shownProductIds, shownPriceIds, recommendedPlanProductId, recommendedAddonProductId },
+    update: { shownProductIds, shownPriceIds, recommendedPlanProductId, recommendedAddonProductId },
+  });
+}
+
+/** The last-good snapshot and its time, or `null` for no row. */
+export async function readWorkspaceSnapshot(workspaceId: string): Promise<WorkspaceSnapshotRow | null> {
+  return prisma.workspaceOfferings.findUnique({
+    where: { workspaceId },
+    select: { snapshot: true, snapshotAt: true },
+  });
+}
+
+/**
+ * Write a parsed snapshot and its time together (the pairing CHECK). Creates
+ * no row, and never replaces a snapshot dated after `at` (unless it is dated
+ * more than `futureSkewMs` past it, which no reader serves): `false` when
+ * nothing was written.
+ */
+export async function writeWorkspaceSnapshot(
+  workspaceId: string,
+  snapshot: OfferingsSnapshot,
+  at: Date,
+  futureSkewMs: number,
+): Promise<boolean> {
+  const { count } = await prisma.workspaceOfferings.updateMany({
+    where: {
+      workspaceId,
+      OR: [
+        { snapshotAt: null },
+        { snapshotAt: { lte: at } },
+        { snapshotAt: { gt: new Date(at.getTime() + futureSkewMs) } },
+      ],
+    },
+    data: { snapshot, snapshotAt: at },
+  });
+  return count > 0;
+}

package/templates/apps/api/src/services/person.ts

@@ -19,12 +19,21 @@
  *     suites that pin that outcome.
  *   - `resolveMemberPersonId` — the member reads' Person (#7877 D8): the one
  *     linked to the caller, else the one whose email is the caller's
- *     verified email, linked on first read by `stampPersonUser`'s rule.
+ *     verified email, linked on first read by `stampPersonUser`'s rule. That
+ *     first link — and no other — releases the Person's held checkout plan
+ *     (#8793 D2).
  *   - `resolveCallerBillingCustomerId` — the customer id the hub vouches for
  *     in `GET /v1/hub-sign-in/me` (#7961, spec 7894 D13): that same Person's,
  *     only while its `userId` is the caller.
  *   - `setPersonPlanOffering` — the plan's only writer (#7877 D8), called by
- *     the Admin's plan route and the checkout-lead rule in `lead-routing.ts`.
+ *     the Admin's plan route and `releaseHeldCheckoutPlan`.
+ *   - `releaseHeldCheckoutPlan` and `checkoutPlanKey` — the checkout plan
+ *     rule (#7877 D10, #8793 D1–D4). A spoke's checkout lead never writes a
+ *     plan: it holds it (`lead-routing.ts`), because its email is whatever
+ *     the buyer typed at Stripe Checkout. The hold is released once, at the
+ *     Person's first member-path link to the user whose VERIFIED email is the
+ *     Person's own, into a blank plan only, and only when every held purchase
+ *     under that email names the same plan key.
  *   - the contact details (#8435): `findOrCreatePerson` fills BLANK contact
  *     fields of an uncurated Person (D4); `updatePersonContact` (the
  *     operator's save), `ensureMemberPerson` and `setOwnPersonContact` (the
@@ -53,7 +62,8 @@
  *
  * The base-tree `lead-routing.ts` imports this file, so it ships in every
  * build and must never reach the paid import closure: it imports
- * `lib/prisma.js`, `verified-email.js` and types only — never
+ * `lib/prisma.js`, `verified-email.js`, `planOfferingSchema` from the
+ * base-tree kernel `@working-theory/validation` and types only — never
  * `lead-promotion.ts`, `owner-workspaces.ts`, `lead-accept-user.ts` (whose
  * find-or-create shape it mirrors) or `lib/tenant-db.ts`.
  * `packages/create-ailk/__tests__/paid-module-exclusions.test.ts` holds this
@@ -62,7 +72,11 @@
  * ## Tenancy
  *
  * Every `Person` statement is scoped by a server-resolved `workspaceId`;
- * there is no list read here (the reads are `tenantDb(tenant).people`).
+ * there is no `Person` list read here (the reads are
+ * `tenantDb(tenant).people`). The one list read is `releaseHeldCheckoutPlan`'s
+ * (#8793 D3): the newest 51 `spokeCheckout` leads of a Person just linked to
+ * the caller, by `(workspaceId, personId)`, the workspace the member read
+ * resolved.
  * `recordCheckoutPerson`'s two other reads are by a server-minted
  * `FlowCheckout` id from a signature-verified webhook, matched on that
  * session's own `stripeSessionId`, then that row's lead scoped by the row's
@@ -84,7 +98,7 @@
 
 import type { Prisma } from "@working-theory/database";
 import type { Id } from "@working-theory/ids";
-import type { PersonContactPatch } from "@working-theory/validation";
+import { planOfferingSchema, type PersonContactPatch } from "@working-theory/validation";
 
 import { prisma } from "../lib/prisma.js";
 
@@ -455,6 +469,29 @@ function usableCustomerId(raw: string | null | undefined): string | null {
     : null;
 }
 
+/** A Stripe customer id: `cus_` and letters or digits only, no separator. */
+const STRIPE_CUSTOMER_ID = /^cus_[A-Za-z0-9]+$/;
+
+/**
+ * The Stripe Dashboard link to one customer (#9349 DD5). Pure: the caller
+ * reads the mode. `null` unless `customerId` is a well-formed `cus_` id of
+ * at most 255 characters, so a stored value can never add a path segment,
+ * a query or a fragment to the fixed Dashboard host.
+ */
+export function stripeCustomerDashboardUrl(
+  customerId: string,
+  mode: "test" | "live",
+): string | null {
+  if (
+    customerId.length > MAX_CUSTOMER_ID_LENGTH ||
+    !STRIPE_CUSTOMER_ID.test(customerId)
+  ) {
+    return null;
+  }
+  const segment = mode === "test" ? "test/customers" : "customers";
+  return `https://dashboard.stripe.com/${segment}/${customerId}`;
+}
+
 // ─── findOrCreatePerson ───────────────────────────────────────────────────────
 
 /** The one delegate this file writes through — the shared client or a transaction's. */
@@ -872,6 +909,14 @@ export async function resolveCheckoutPerson(input: {
  * every other stamp outcome, and a store error, is `null` too, logged by its
  * kind only. Never throws.
  *
+ * A fresh `stamped` link — and only that — releases the Person's held
+ * checkout plan (#8793 D2, `releaseHeldCheckoutPlan`): the caller has just
+ * proven they own the email the purchases were made under. A Person linked
+ * earlier, a refused stamp and every other caller of `stampPersonUser` (the
+ * Inbox accept above all) release nothing. The release never changes the
+ * answer; an `ambiguous` or `internal_error` release is logged by its kind
+ * only, as `{ event: "checkout-plan-release", outcome }`.
+ *
  * @param workspaceId the SERVER-RESOLVED workspace (the calling spoke's).
  * @param userId the authenticated caller.
  * @param verifiedEmail the caller's verified address, read by the caller.
@@ -902,7 +947,19 @@ export async function resolveMemberPersonId(
   if (!byEmail) return null;
 
   const outcome = await stampPersonUser(workspaceId, byEmail.id, userId);
-  if (outcome === "stamped" || outcome === "already_linked") return byEmail.id;
+  if (outcome === "stamped") {
+    const release = await releaseHeldCheckoutPlan(
+      workspaceId,
+      byEmail.id,
+      userId,
+      normalizePersonEmail(verifiedEmail),
+    );
+    if (release === "ambiguous" || release === "internal_error") {
+      log?.warn({ event: "checkout-plan-release", outcome: release }, "[person] held checkout plan not released");
+    }
+    return byEmail.id;
+  }
+  if (outcome === "already_linked") return byEmail.id;
   log?.warn({ event: "member-person-stamp", outcome }, "[person] member link refused");
   return null;
 }
@@ -943,17 +1000,28 @@ export type SetPlanOfferingOutcome = "set" | "not_found" | "internal_error";
 
 /**
  * Set — or, with `null`, clear — a Person's plan: the ONE writer of
- * `Person.planOffering`. One `updateMany` scoped by the server-resolved
- * workspace; no row → `not_found`. Never throws.
+ * `Person.planOffering`, called by the Admin's plan route and the held
+ * checkout plan's release (#8793). One `updateMany` scoped by the
+ * server-resolved workspace; no row → `not_found`. Never throws.
+ *
+ * With a `guard` (#8793 D5, the release's own write) the statement also
+ * requires a blank plan and the Person still linked to `guard.linkedUserId`,
+ * so a plan already set — or one the operator PUTs at the same moment — wins
+ * and the answer is `not_found`. Without one it is the operator's overwrite.
  */
 export async function setPersonPlanOffering(
   workspaceId: string,
   personId: string,
   planOffering: string | null,
+  guard?: { linkedUserId: string },
 ): Promise<SetPlanOfferingOutcome> {
   try {
     const { count } = await prisma.person.updateMany({
-      where: { id: personId, workspaceId },
+      where: {
+        id: personId,
+        workspaceId,
+        ...(guard !== undefined && { planOffering: null, userId: guard.linkedUserId }),
+      },
       data: { planOffering },
     });
     return count === 0 ? "not_found" : "set";
@@ -962,6 +1030,76 @@ export async function setPersonPlanOffering(
   }
 }
 
+// ─── The held checkout plan (#8793 D3, D4) ───────────────────────────────────
+
+/**
+ * A spoke checkout's plan key: the offering minus a leading `<site>_` (when
+ * the site is a string), answered only when `planOfferingSchema` — the key
+ * the operator's PUT accepts — admits it; else `null`. Shared by the
+ * checkout's hold (`lead-routing.ts`) and the release below.
+ */
+export function checkoutPlanKey(offering: unknown, site: unknown): string | null {
+  if (typeof offering !== "string") return null;
+  const prefix = typeof site === "string" ? `${site}_` : null;
+  const key = prefix !== null && offering.startsWith(prefix) ? offering.slice(prefix.length) : offering;
+  return planOfferingSchema.safeParse(key).success ? key : null;
+}
+
+export type HeldPlanOutcome = "set" | "none" | "ambiguous" | "kept" | "internal_error";
+
+/** The most held purchases a release weighs; one more is `ambiguous`. */
+const HELD_PURCHASES_READ = 50;
+
+/**
+ * Release a Person's held checkout plan (#8793 D3) — called only by
+ * `resolveMemberPersonId` on a fresh `stamped` link, so `verifiedEmail` (the
+ * caller's, normalized) is the Person's own. The Person's marked spoke
+ * checkout leads (`Lead.spokeCheckout`, newest 51) under that email are taken
+ * as a SET: one distinct plan key is written to a blank plan through the
+ * guarded `setPersonPlanOffering` (`set`, or `kept` when the guard matched
+ * nothing — a plan was already there, or the Person is no longer linked to
+ * `userId`); no key is `none`; more than one key, or more than 50 leads, is
+ * `ambiguous` and writes nothing — the operator sets the plan. So a
+ * stranger's purchase under the owner's email can deny the automatic plan,
+ * never choose it (SEC-8793-A). A store error is `internal_error`. Never
+ * throws, and logs nothing: the caller logs the kind.
+ */
+export async function releaseHeldCheckoutPlan(
+  workspaceId: string,
+  personId: string,
+  userId: string,
+  verifiedEmail: string,
+): Promise<HeldPlanOutcome> {
+  try {
+    const rows = await prisma.lead.findMany({
+      where: { workspaceId, personId, spokeCheckout: true },
+      orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+      take: HELD_PURCHASES_READ + 1,
+      select: { email: true, payload: true },
+    });
+    if (rows.length > HELD_PURCHASES_READ) return "ambiguous";
+
+    const keys = new Set<string>();
+    for (const row of rows) {
+      // The purchase read's own rule: a purchase is its Person's only under
+      // the Person's own email.
+      if (normalizePersonEmail(row.email) !== verifiedEmail) continue;
+      const payload = (row.payload ?? {}) as Record<string, unknown>;
+      const key = checkoutPlanKey(payload["offering"], payload["site"]);
+      if (key !== null) keys.add(key);
+    }
+    if (keys.size > 1) return "ambiguous";
+    const [key] = keys;
+    if (key === undefined) return "none";
+
+    const written = await setPersonPlanOffering(workspaceId, personId, key, { linkedUserId: userId });
+    if (written === "set") return "set";
+    return written === "not_found" ? "kept" : "internal_error";
+  } catch {
+    return "internal_error";
+  }
+}
+
 // ─── The two human edits of the contact (#8435 D9, D11) ───────────────────────
 
 export type SavedContact = {

package/templates/apps/api/src/services/plan-offerings.ts

@@ -5,15 +5,29 @@
  * (`services/magnet-completion.ts`) read the same list `GET …/plan-offerings`
  * serves.
  *
- * The workspace's OWN Service then Product pages: `key` is the page slug's
- * last segment when it is an offering key (else the page is skipped), the
- * first page per key wins, at most 200; `name` is the page title. Off the
- * database content adapter only the default workspace has content
- * (`workspaceContentAdapter`), so every other workspace reads `[]`.
+ * Two sources (#8934, spec
+ * docs/specs/8934-re-source-the-plan-offerings-spec.md D1–D4):
  *
- * Never throws: a failed content read answers `{ failed }` with the error's
- * class name only, so a caller can tell "none published" from "could not
- * tell" — a failure is never a pass.
+ * - A connected workspace with the `commerce` claim lists its Offerings
+ *   shown set (`getWorkspaceShownSet`, read from the database and never from
+ *   Stripe — contract T7): one item per sellable Price, in the reader's
+ *   order, `key` the Price's full lookup key (G5), `name` the product name
+ *   and its billing word, `type` the product's group. The page list is not
+ *   consulted.
+ * - An unclaimed workspace, or one the reader answers `null` for (no
+ *   workspace, no connection, no selection), lists its OWN Service then
+ *   Product pages: `key` is the page slug's last segment when it is an
+ *   offering key (else the page is skipped), the first page per key wins, at
+ *   most 200; `name` is the page title. Off the database content adapter only
+ *   the default workspace has content (`workspaceContentAdapter`), so every
+ *   other workspace reads `[]`.
+ *
+ * Never throws: a failed read answers `{ failed }` with a fixed word or the
+ * error's class name only, so a caller can tell "none listed" from "could not
+ * tell" — a failure is never a pass. `LicenseUndetermined` (the licence could
+ * not be read, so the Offerings services may not be called — 8876 D10),
+ * `OfferingsSnapshotExpired` and `OfferingsSnapshotEmpty` (the rows say what
+ * is shown, but no current snapshot says which keys it sells).
  *
  * Base tree (SEC-8757-D): no `oss: false` marker and no `MODULE_SLICES`
  * entry, because the never-gate lead route reaches it.
@@ -24,36 +38,88 @@ import {
   type PlanOfferingItem,
 } from "@working-theory/validation";
 
+import { resolveCommerceClaim } from "../lib/require-commerce-claim.js";
+
+import { getWorkspaceShownSet } from "./offerings/index.js";
 import { workspaceContentAdapter } from "./public-site-resolver.js";
 
-/** The workspace's Service then Product pages as plan keys (D9). */
+/** `planOfferingItemSchema.name`'s bound, in UTF-16 units. */
+const NAME_MAX = 200;
+
+/** The workspace's offerings as plan keys (D3). */
 export async function listPlanOfferings(
   workspaceId: string,
 ): Promise<PlanOfferingItem[] | { failed: string }> {
   try {
-    const adapter = await workspaceContentAdapter(workspaceId);
-    if (!adapter) return [];
-    const [services, products] = await Promise.all([
-      adapter.listPages("Service"),
-      adapter.listPages("Product"),
-    ]);
-    const offerings: PlanOfferingItem[] = [];
-    const seen = new Set<string>();
-    const typed = [
-      ...services.map((page) => ({ page, type: "service" as const })),
-      ...products.map((page) => ({ page, type: "product" as const })),
-    ];
-    for (const { page, type } of typed) {
-      if (offerings.length >= PLAN_OFFERINGS_MAX) break;
-      const key = page.slug.split("/").filter(Boolean).pop() ?? "";
-      const name = page.title.trim().slice(0, 200);
-      if (!planOfferingSchema.safeParse(key).success || name === "" || seen.has(key)) continue;
-      seen.add(key);
-      offerings.push({ key, name, type });
-    }
-    return offerings;
+    const claim = await resolveCommerceClaim();
+    if (claim === "undetermined") return { failed: "LicenseUndetermined" };
+    if (claim === "unclaimed") return await pageOfferings(workspaceId);
+    const shown = await getWorkspaceShownSet(workspaceId);
+    if (shown === null) return await pageOfferings(workspaceId);
+    if (shown.state === "expired") return { failed: "OfferingsSnapshotExpired" };
+    if (shown.state === "empty") return { failed: "OfferingsSnapshotEmpty" };
+    return collect(
+      shown.offerings.flatMap((offering) =>
+        offering.prices.map((price) => ({
+          key: price.lookupKey,
+          name: planOfferingName(offering.name, price.interval),
+          type: offering.ailkGroup,
+        })),
+      ),
+    );
   } catch (error) {
     // The error's class name only — never its message, which may name a slug.
     return { failed: error instanceof Error ? error.name : typeof error };
   }
 }
+
+/** The workspace's Service then Product pages as plan keys (D4, #8514 D9). */
+async function pageOfferings(workspaceId: string): Promise<PlanOfferingItem[]> {
+  const adapter = await workspaceContentAdapter(workspaceId);
+  if (!adapter) return [];
+  const [services, products] = await Promise.all([
+    adapter.listPages("Service"),
+    adapter.listPages("Product"),
+  ]);
+  const typed = [
+    ...services.map((page) => ({ page, type: "service" as const })),
+    ...products.map((page) => ({ page, type: "product" as const })),
+  ];
+  return collect(
+    typed.map(({ page, type }) => ({
+      key: page.slug.split("/").filter(Boolean).pop() ?? "",
+      name: page.title.trim().slice(0, NAME_MAX),
+      type,
+    })),
+  );
+}
+
+/** The guards both sources share: a valid key, a name, each key once, at most 200. */
+function collect(candidates: PlanOfferingItem[]): PlanOfferingItem[] {
+  const offerings: PlanOfferingItem[] = [];
+  const seen = new Set<string>();
+  for (const { key, name, type } of candidates) {
+    if (offerings.length >= PLAN_OFFERINGS_MAX) break;
+    if (!planOfferingSchema.safeParse(key).success || name === "" || seen.has(key)) continue;
+    seen.add(key);
+    offerings.push({ key, name, type });
+  }
+  return offerings;
+}
+
+/**
+ * `<product name> (<word>)`, the word from the Price's interval (D2). Whole
+ * code points are dropped from the end of the product name until the name
+ * fits `NAME_MAX` units, so a surrogate pair is never split; the word is
+ * always kept.
+ */
+function planOfferingName(productName: string, interval: "month" | "year" | null): string {
+  const word = interval === "month" ? "Monthly" : interval === "year" ? "Annual" : "One-time";
+  const suffix = ` (${word})`;
+  let name = "";
+  for (const point of productName) {
+    if (name.length + point.length + suffix.length > NAME_MAX) break;
+    name += point;
+  }
+  return name + suffix;
+}