create-ailk 0.22.0 → 0.23.0

package/templates/apps/api/src/services/lead-routing.ts

@@ -59,27 +59,47 @@
  * as `personId`; a callback with no email makes no Person call and writes no
  * `personId`. Every one of these steps is best-effort exactly like the lead's.
  *
- * CHECKOUT PLAN (#7877 D10). A spoke's checkout fulfilment posts one
- * `submit` with the Checkout Session id as its `Idempotency-Key`. When that
- * lead is written (never on a replay) with a Person, and it is a LIVE,
- * paid checkout lead from a registered spoke's server — `viaSpoke`, a
+ * CHECKOUT PLAN (#7877 D10, #8793 D1). A spoke's checkout fulfilment posts
+ * one `submit` with the Checkout Session id as its `Idempotency-Key`. A
+ * LIVE, paid checkout lead from a registered spoke's server — `viaSpoke`, a
  * `cs_live_` key, `source: "web"`, `payload.page: "checkout"`, a string
  * `payload.offering` and `payload.site`, and an `amountTotal` that is
- * absent, `null` or a positive integer — the Person's plan becomes the
- * offering minus a leading `<site>_` (`setPersonPlanOffering`, the plan's
- * only writer). No spoke file changes. The step never throws, never changes
- * `routeLead`'s result, and logs one bare `checkout-plan` line — never the
- * offering, the email or the key. A lead that does not qualify makes no
- * Person call at all.
+ * absent, `null` or a positive integer — names a plan: the offering minus a
+ * leading `<site>_` (`person.ts`'s `checkoutPlanKey`). Its email is what
+ * the buyer typed at Stripe Checkout, which nobody verified, so the lead
+ * never writes any Person's plan (SEC-8748-D). It HOLDS it: on the first
+ * write of a marked lead (below) with a Person, the step logs one bare
+ * `{ event: "checkout-plan", outcome, siteId }` line at `info` — `held` for
+ * a plan key, `skipped` for none — and makes no Person call; the marked lead
+ * itself is the hold. `person.ts`'s `releaseHeldCheckoutPlan` writes it
+ * later, once, at the Person's first member-path link to the user whose
+ * verified email is the Person's own. No spoke file changes. The step never
+ * throws, never changes `routeLead`'s result, and never logs the offering,
+ * the email or the key.
  *
- * SPOKE CHECKOUT MARKER (#8185 D2). The same predicate, plus "not relayed
- * for a visitor" (`SourceMeta.relayed`), is evaluated once BEFORE the lead's
- * create and stored as `Lead.spokeCheckout` — the hub's conclusion at write
+ * THE OFFERINGS TWIN (#8932 D7). The per-Organization Stripe webhook
+ * (`routes/webhooks/stripe-offerings.ts`) is the predicate's second source:
+ * `options.offeringsCheckout`, which it sets only after W3–W6 (its own
+ * signature, the hub's session record for that Organization and workspace,
+ * the recorded Price paid) and no request can set, a key
+ * `"stripe-offerings " + <cs_live_ session id>` (a space no `Idempotency-Key`
+ * header can carry), `source: "web"`, `payload.page: "checkout"`, a
+ * `payload.offering` `parseLookupKey` admits and a `payload.site` equal to
+ * the lead's workspace. Its plan key is the FULL lookup key (no `<site>_`
+ * prefix can match a workspace id), and its consent grant's `sourceRef` is
+ * the bare session id. A test-mode session's key fails the twin, so its lead
+ * is unmarked (#8932 C9).
+ *
+ * SPOKE CHECKOUT MARKER (#8185 D2). The same predicate — or its Offerings
+ * twin (#8932 D7) — plus "not relayed for a visitor" (`SourceMeta.relayed`),
+ * is evaluated once BEFORE the lead's create and stored as
+ * `Lead.spokeCheckout` — the hub's conclusion at write
  * time, which `GET /v1/member/purchases` serves as a purchase
  * (`lib/member-store.ts`). Written only in the submit create below, never by
  * an update; an unmarked create carries no `spokeCheckout` key at all and
- * relies on the column default. The plan rule above is unchanged: it still
- * runs after the write, from the same candidate.
+ * relies on the column default. The plan step above runs only for a marked
+ * lead, after the write, and holds (#8793 D1), so a request relayed for a
+ * visitor never reaches it.
  *
  * PURCHASE EMAIL AND INBOX MESSAGE (#8757 D14). After this request's own
  * write of a lead marked `spokeCheckout` with a Person — so never on a
@@ -136,12 +156,12 @@ import { sendLeadNotification, sendPurchaseConfirmationEmail } from "@working-th
 import { logger } from "@working-theory/observability";
 import {
   accountInvitePath,
-  isContactLeadSource,
+  isConsentLeadSource,
   LEAD_SITE_MARKER_KEY,
   leadInputSchema,
+  parseLookupKey,
   PURCHASE_EMAIL_DEFAULTS,
   PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY,
-  planOfferingSchema,
   stripPlainText,
 } from "@working-theory/validation";
 
@@ -158,10 +178,10 @@ import {
 } from "./consent.js";
 import { enrichLead } from "./enrichment-shim.js";
 import {
+  checkoutPlanKey,
   findOrCreatePerson,
   normalizeCapturedContact,
   normalizeTelephone,
-  setPersonPlanOffering,
 } from "./person.js";
 import type { LeadContact, PersonContact } from "./person.js";
 import { listPlanOfferings } from "./plan-offerings.js";
@@ -232,6 +252,14 @@ export type RouteLeadOptions = {
    * from the caller, never the body. Read for a marked checkout lead only.
    */
   accountOrigin?: string;
+  /**
+   * Set only by the per-Organization Stripe webhook after W5 and W6 (#8932
+   * D7) — a signature from the Organization's own secret, the hub's own
+   * session record for that Organization and workspace, and the recorded
+   * Price paid; never from a request. Admits the Offerings twin of the
+   * checkout plan predicate (`offeringsCheckoutCandidate`).
+   */
+  offeringsCheckout?: true;
 };
 
 export type RouteLeadResult =
@@ -307,9 +335,11 @@ async function findLeadByKey(
 }
 
 /**
- * A contact lead's `payload.consent` is written by the route on every request
- * (#8730 D3) — its `acceptedAt` is that request's receive time — so it is left
- * out of the replay comparison; every key the client sent still counts.
+ * A consent-bearing lead's `payload.consent` — a contact lead's (#8730 D3) or,
+ * since #9130, a job application's — is written by the route on every request,
+ * its `acceptedAt` that request's receive time, so it is left out of the replay
+ * comparison for every `isConsentLeadSource` source; every key the client sent
+ * still counts.
  *
  * A checkout lead's `payload.termsAccepted` (#8778) is left out too: a spoke
  * updated between a stored attempt and Stripe's redelivery sends the key the
@@ -321,7 +351,7 @@ function comparablePayload(payload: unknown, source: string): unknown {
     return payload;
   }
   const record = payload as Record<string, unknown>;
-  if (isContactLeadSource(source)) {
+  if (isConsentLeadSource(source)) {
     const { consent: _serverWritten, ...rest } = record;
     return rest;
   }
@@ -335,9 +365,9 @@ function comparablePayload(payload: unknown, source: string): unknown {
 /**
  * A stored row is a replay only when it carries this request's exact `email`
  * and `source` and a deep-equal `payload` (key order ignored, SEC-7869-3);
- * any other row is a conflict (#7869 D4). A contact lead's server-written
- * `payload.consent` is not compared (#8730), nor a checkout lead's
- * `payload.termsAccepted` (#8778).
+ * any other row is a conflict (#7869 D4). A consent-bearing lead's
+ * server-written `payload.consent` is not compared (#8730, #9130), nor a
+ * checkout lead's `payload.termsAccepted` (#8778).
  */
 function classifyKeyedRow(row: KeyedRow, input: SubmitInput): KeyedOutcome {
   return row.email === input.email &&
@@ -431,6 +461,9 @@ async function resolveLeadPersonId(input: SubmitInput, contact?: LeadContact): P
   });
 }
 
+/** A marked checkout lead's offering and site; `sessionId` is the Offerings twin's bare session id. */
+type CheckoutCandidate = { offering: string; site: string; sessionId?: string };
+
 /** A LIVE-mode Checkout Session id (#7877 D10, SEC-7877-C). */
 const LIVE_CHECKOUT_SESSION_KEY = /^cs_live_[A-Za-z0-9]{1,250}$/;
 const SITE_SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
@@ -443,7 +476,7 @@ function checkoutPlanCandidate(
   input: SubmitInput,
   idempotencyKey: string | undefined,
   viaSpoke: boolean,
-): { offering: string; site: string } | null {
+): CheckoutCandidate | null {
   if (viaSpoke !== true) return null;
   if (idempotencyKey === undefined || !LIVE_CHECKOUT_SESSION_KEY.test(idempotencyKey)) {
     return null;
@@ -466,8 +499,35 @@ function checkoutPlanCandidate(
   return { offering, site };
 }
 
+/** The Offerings webhook's key: a space no `Idempotency-Key` header can carry, then a LIVE session id. */
+const OFFERINGS_CHECKOUT_KEY = /^stripe-offerings (cs_live_[A-Za-z0-9]{1,250})$/;
+
+/**
+ * The Offerings twin of `checkoutPlanCandidate` (#8932 D7): a lead the
+ * per-Organization Stripe webhook wrote after W5 and W6, for a LIVE session
+ * only (C9, SEC-7877-C) — a test-mode session's lead is written unmarked.
+ * Reads no amount: W6 already proved the session paid. `checkoutPlanCandidate`
+ * is not edited, so a spoke lead is marked exactly as before.
+ */
+function offeringsCheckoutCandidate(
+  input: SubmitInput,
+  idempotencyKey: string | undefined,
+  offeringsCheckout: boolean,
+): CheckoutCandidate | null {
+  if (offeringsCheckout !== true || idempotencyKey === undefined) return null;
+  const sessionId = OFFERINGS_CHECKOUT_KEY.exec(idempotencyKey)?.[1];
+  if (sessionId === undefined) return null;
+  const { payload } = input;
+  if (input.source !== "web" || payload["page"] !== "checkout") return null;
+  const offering = payload["offering"];
+  if (typeof offering !== "string" || parseLookupKey(offering) === null) return null;
+  const site = payload[LEAD_SITE_MARKER_KEY];
+  if (typeof site !== "string" || site !== input.siteId) return null;
+  return { offering, site, sessionId };
+}
+
 /** The candidate's offering minus a leading `<site>_` (#7877 D10). */
-function stripSitePrefix(candidate: { offering: string; site: string }): string {
+function stripSitePrefix(candidate: CheckoutCandidate): string {
   const prefix = `${candidate.site}_`;
   return candidate.offering.startsWith(prefix)
     ? candidate.offering.slice(prefix.length)
@@ -475,31 +535,18 @@ function stripSitePrefix(candidate: { offering: string; site: string }): string
 }
 
 /**
- * Set the Person's plan from a qualifying checkout lead (#7877 D10). Never
- * throws and never changes the lead's result; logs the outcome kind and the
- * site only.
+ * Hold the plan of a marked checkout lead (#7877 D10, #8793 D1): no Person
+ * call — the marked lead itself is the hold, released only at the Person's
+ * verified first link (`person.ts`'s `releaseHeldCheckoutPlan`). Logs
+ * `held` for an offering that is a plan key, else `skipped`, and the site
+ * only.
  */
-async function applyCheckoutPlan(
+function applyCheckoutPlan(
   input: SubmitInput,
-  personId: string,
-  candidate: { offering: string; site: string },
-): Promise<void> {
-  const offering = stripSitePrefix(candidate);
-  let outcome: "set" | "skipped" | "failed";
-  // The operator's PUT accepts the same keys (`planOfferingSchema`).
-  if (!planOfferingSchema.safeParse(offering).success) {
-    outcome = "skipped";
-  } else {
-    try {
-      const result = await setPersonPlanOffering(input.siteId, personId, offering);
-      outcome = result === "set" ? "set" : "failed";
-    } catch {
-      outcome = "failed";
-    }
-  }
-  const line = { event: "checkout-plan", outcome, siteId: input.siteId };
-  if (outcome === "failed") logger.error(line, "checkout plan failed");
-  else logger.info(line, "checkout plan");
+  candidate: CheckoutCandidate,
+): void {
+  const outcome = checkoutPlanKey(candidate.offering, candidate.site) === null ? "skipped" : "held";
+  logger.info({ event: "checkout-plan", outcome, siteId: input.siteId }, "checkout plan");
 }
 
 // ─── Purchase email and Inbox message (#8757 D14) ────────────────────────────
@@ -653,7 +700,7 @@ async function sendPurchaseEmail(
 async function recordPurchase(
   input: SubmitInput,
   personId: string,
-  candidate: { offering: string; site: string },
+  candidate: CheckoutCandidate,
   accountOrigin: string | undefined,
 ): Promise<void> {
   // One guard around the whole step: it runs inside `routeLead`'s persist
@@ -738,13 +785,17 @@ async function persistToDb(
   relayed = false,
   contact?: LeadContact,
   accountOrigin?: string,
+  offeringsCheckout = false,
 ): Promise<PersistResult> {
   if (input.kind === "submit") {
     const personId = await resolveLeadPersonId(input, contact);
     // #8185 D2 — the plan rule's own predicate (pure: input, key, flag),
     // evaluated before the create so its result can be stored. A relayed
-    // request is never a spoke's server call (D3).
-    const candidate = checkoutPlanCandidate(input, idempotencyKey, viaSpoke);
+    // request is never a spoke's server call (D3). #8932 D7 — or its
+    // Offerings twin, set only by the per-Organization Stripe webhook.
+    const candidate =
+      checkoutPlanCandidate(input, idempotencyKey, viaSpoke) ??
+      offeringsCheckoutCandidate(input, idempotencyKey, offeringsCheckout);
     const spokeCheckout = candidate !== null && relayed !== true;
     let row: DbRow;
     try {
@@ -790,15 +841,18 @@ async function persistToDb(
       if (!winner) throw err;
       return { ok: "keyed", outcome: classifyKeyedRow(winner, input) };
     }
-    // #7877 D10 — only after THIS request's own write, so a replay sets nothing.
+    // #7877 D10 — only after THIS request's own write, so a replay holds nothing.
     if (candidate !== null && personId !== null) {
-      await applyCheckoutPlan(input, personId, candidate);
       // #8757 D14 — the marked lead only: live, unrelayed, this write.
       if (spokeCheckout) {
+        // #8793 D1 — the plan is held, never written here.
+        applyCheckoutPlan(input, candidate);
         await recordPurchase(input, personId, candidate, accountOrigin);
-        // #8778 — a marked lead's key is its live Checkout Session id.
-        if (idempotencyKey !== undefined) {
-          await recordSpokeCheckoutConsent(input, personId, idempotencyKey);
+        // #8778 — a marked lead's key is its live Checkout Session id;
+        // #8932 D7 — the Offerings twin's key is prefixed, so its bare id.
+        const sessionId = candidate.sessionId ?? idempotencyKey;
+        if (sessionId !== undefined) {
+          await recordSpokeCheckoutConsent(input, personId, sessionId);
         }
       }
     }
@@ -1165,6 +1219,7 @@ export async function routeLead(
       sourceMeta.relayed === true,
       input.kind === "submit" ? options.contact : undefined,
       input.kind === "submit" ? options.accountOrigin : undefined,
+      input.kind === "submit" && options.offeringsCheckout === true,
     );
     // #7869 D5 — a lost race answers like the lookup above: no capture
     // record, no notification.

package/templates/apps/api/src/services/offerings/__tests__/catalog.test.ts

@@ -0,0 +1,295 @@
+/**
+ * services/offerings/catalog.ts — the one normalizer (#8876 spec D5, AC-5):
+ * text normalization (T1), the product marker (G6), sellable Prices (G3) and
+ * one plan per Product (G4), in D5's order, one bad Product never failing the
+ * catalog.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { offeringsSnapshotProductSchema } from "@working-theory/validation";
+
+import {
+  isOfferingsProduct,
+  normalizeCatalog,
+  type CatalogPrice,
+  type CatalogProduct,
+} from "../catalog.js";
+import {
+  EXPECTED_FIXTURE_HELD,
+  EXPECTED_FIXTURE_OFFERINGS,
+  OFFERINGS_FIXTURE_CATALOG,
+} from "./fixtures.js";
+
+function product(id: string, patch: Record<string, unknown> = {}): CatalogProduct {
+  return {
+    id,
+    active: true,
+    name: "Growth",
+    description: null,
+    marketing_features: [],
+    unit_label: null,
+    metadata: { ailk_group: "plan" },
+    ...patch,
+  };
+}
+
+function price(id: string, productId: string, patch: Record<string, unknown> = {}): CatalogPrice {
+  return {
+    id,
+    active: true,
+    product: productId,
+    lookup_key: "growth_monthly",
+    type: "recurring",
+    recurring: { interval: "month", interval_count: 1, usage_type: "licensed" },
+    billing_scheme: "per_unit",
+    unit_amount: 4900,
+    currency: "usd",
+    ...patch,
+  };
+}
+
+/** Normalize one Product with its Prices. */
+function one(p: CatalogProduct, prices: CatalogPrice[]) {
+  return normalizeCatalog({ products: [p], prices });
+}
+
+describe("normalizeCatalog (#8876 D5, AC-5)", () => {
+  it("answers the fixture's offerings and held list exactly, in D5's order", () => {
+    expect(normalizeCatalog(OFFERINGS_FIXTURE_CATALOG)).toEqual({
+      offerings: EXPECTED_FIXTURE_OFFERINGS,
+      held: EXPECTED_FIXTURE_HELD,
+    });
+  });
+
+  it("is pure: the same input answers the same output and is not mutated", () => {
+    const input = structuredClone(OFFERINGS_FIXTURE_CATALOG);
+    expect(normalizeCatalog(input)).toEqual(normalizeCatalog(OFFERINGS_FIXTURE_CATALOG));
+    expect(input).toEqual(OFFERINGS_FIXTURE_CATALOG);
+  });
+
+  describe("text (T1)", () => {
+    it("strips bidi overrides, zero-width characters and a CR from a name", () => {
+      const { offerings } = one(product("prod_a", { name: "Gro‮wth​\r plan" }), [price("price_a", "prod_a")]);
+      expect(offerings[0]!.name).toBe("Growth plan");
+    });
+
+    it("answers the NFC form of a decomposed character", () => {
+      const { offerings } = one(product("prod_a", { name: "Café" }), [price("price_a", "prod_a")]);
+      expect(offerings[0]!.name).toBe("Café");
+    });
+
+    it("keeps a newline in the description only", () => {
+      const { offerings } = one(
+        product("prod_a", {
+          name: "Two\nlines",
+          description: "  First\nsecond
third  ",
+          marketing_features: [{ name: "a\nb" }],
+        }),
+        [price("price_a", "prod_a")],
+      );
+      expect(offerings[0]!.name).toBe("Twolines");
+      expect(offerings[0]!.description).toBe("First\nsecondthird");
+      expect(offerings[0]!.marketingFeatures).toEqual(["ab"]);
+    });
+
+    it("cuts a 2001-code-point description to 2000", () => {
+      const { offerings } = one(product("prod_a", { description: "x".repeat(2001) }), [price("price_a", "prod_a")]);
+      expect([...offerings[0]!.description!]).toHaveLength(2000);
+    });
+
+    it("keeps a name of 200 astral-plane emoji whole, and it parses", () => {
+      const name = "😀".repeat(200);
+      const { offerings } = one(product("prod_a", { name }), [price("price_a", "prod_a")]);
+      expect(offerings[0]!.name).toBe(name);
+      expect(offeringsSnapshotProductSchema.safeParse(offerings[0]).success).toBe(true);
+    });
+
+    it("reads a non-string as null and an empty text as null", () => {
+      const { offerings } = one(
+        product("prod_a", { description: 42, unit_label: "   ", metadata: { ailk_group: "plan", ailk_note: {} } }),
+        [price("price_a", "prod_a")],
+      );
+      expect(offerings[0]).toMatchObject({ description: null, unitLabel: null, note: null });
+    });
+
+    it("never reads images, url, nickname, statement_descriptor or other metadata", () => {
+      const { offerings } = one(
+        product("prod_a", {
+          images: ["https://evil.example/x.png"],
+          url: "https://evil.example",
+          metadata: { ailk_group: "plan", other: "secret-metadata" },
+        } as Record<string, unknown>),
+        [price("price_a", "prod_a", { nickname: "Nick", statement_descriptor: "STMT" } as Record<string, unknown>)],
+      );
+      const text = JSON.stringify(offerings);
+      for (const leaked of ["evil.example", "secret-metadata", "Nick", "STMT", "images", "url", "nickname"]) {
+        expect(text).not.toContain(leaked);
+      }
+    });
+  });
+
+  describe("the marker (G6)", () => {
+    it.each([
+      ["no ailk_group", {}],
+      ["ailk_group Plan", { ailk_group: "Plan" }],
+      ["ailk_group other", { ailk_group: "other" }],
+    ])("holds %s group_invalid", (_label, metadata) => {
+      expect(one(product("prod_a", { metadata }), [price("price_a", "prod_a")])).toEqual({
+        offerings: [],
+        held: [{ productId: "prod_a", name: "Growth", reason: "group_invalid" }],
+      });
+    });
+
+    it("holds an empty name name_missing", () => {
+      expect(one(product("prod_a", { name: "​ " }), [price("price_a", "prod_a")]).held).toEqual([
+        { productId: "prod_a", name: "", reason: "name_missing" },
+      ]);
+    });
+
+    it("isOfferingsProduct is true for any non-empty ailk_group, Plan included", () => {
+      expect(isOfferingsProduct(product("prod_a", { metadata: { ailk_group: "Plan" } }))).toBe(true);
+      expect(isOfferingsProduct(product("prod_a", { metadata: { ailk_group: "addon" } }))).toBe(true);
+      expect(isOfferingsProduct(product("prod_a", { metadata: { ailk_group: "" } }))).toBe(false);
+      expect(isOfferingsProduct(product("prod_a", { metadata: {} }))).toBe(false);
+      expect(isOfferingsProduct(product("prod_a", { metadata: null }))).toBe(false);
+    });
+
+    it("keeps ailk_order of 1–4 digits and sorts anything else last", () => {
+      const products = [
+        product("prod_a", { name: "A", metadata: { ailk_group: "plan", ailk_order: "12345" } }),
+        product("prod_b", { name: "B", metadata: { ailk_group: "plan", ailk_order: "2" } }),
+        product("prod_c", { name: "C", metadata: { ailk_group: "plan", ailk_order: 1 } }),
+      ];
+      const prices = [
+        price("price_a", "prod_a", { lookup_key: "a_monthly" }),
+        price("price_b", "prod_b", { lookup_key: "b_monthly" }),
+        price("price_c", "prod_c", { lookup_key: "c_monthly" }),
+      ];
+      const { offerings } = normalizeCatalog({ products, prices });
+      expect(offerings.map((o) => [o.productId, o.ailkOrder])).toEqual([
+        ["prod_b", 2],
+        ["prod_a", null],
+        ["prod_c", null],
+      ]);
+    });
+  });
+
+  describe("sellable Prices (G3) and one plan per Product (G4)", () => {
+    it.each([
+      ["one sellable and one growth_quarterly Price", [
+        price("price_a", "prod_a"),
+        price("price_b", "prod_a", { lookup_key: "growth_quarterly", recurring: { interval: "month", interval_count: 3 } }),
+      ]],
+      ["a metered Price", [price("price_a", "prod_a", { recurring: { interval: "month", interval_count: 1, usage_type: "metered" } })]],
+      ["a tiered Price", [price("price_a", "prod_a", { billing_scheme: "tiered", unit_amount: null })]],
+      ["a period that disagrees with the Price", [price("price_a", "prod_a", { recurring: { interval: "year", interval_count: 1 } })]],
+      ["no active Price", [price("price_a", "prod_a", { active: false })]],
+      ["no Price at all", []],
+      ["a null unit_amount", [price("price_a", "prod_a", { unit_amount: null })]],
+      ["an uppercase currency", [price("price_a", "prod_a", { currency: "USD" })]],
+      ["two Prices of one period", [
+        price("price_a", "prod_a"),
+        price("price_b", "prod_a", { lookup_key: "growth_monthly" }),
+      ]],
+      ["two plans on one Product", [
+        price("price_a", "prod_a"),
+        price("price_b", "prod_a", { lookup_key: "basic_yearly", recurring: { interval: "year", interval_count: 1 } }),
+      ]],
+    ])("holds a Product with %s needs_lookup_key", (_label, prices) => {
+      expect(one(product("prod_a"), prices as CatalogPrice[]).held).toEqual([
+        { productId: "prod_a", name: "Growth", reason: "needs_lookup_key" },
+      ]);
+    });
+
+    it("ignores an inactive Price beside a sellable one", () => {
+      const { offerings } = one(product("prod_a"), [
+        price("price_a", "prod_a"),
+        price("price_b", "prod_a", { active: false, lookup_key: "growth_quarterly" }),
+      ]);
+      expect(offerings[0]!.prices.map((p) => p.priceId)).toEqual(["price_a"]);
+    });
+
+    it("holds both Products carrying one plan plan_conflict", () => {
+      const { offerings, held } = normalizeCatalog({
+        products: [product("prod_a"), product("prod_b", { name: "Growth two" })],
+        prices: [
+          price("price_a", "prod_a"),
+          price("price_b", "prod_b", { lookup_key: "growth_yearly", recurring: { interval: "year", interval_count: 1 } }),
+        ],
+      });
+      expect(offerings).toEqual([]);
+      expect(held).toEqual([
+        { productId: "prod_a", name: "Growth", reason: "plan_conflict" },
+        { productId: "prod_b", name: "Growth two", reason: "plan_conflict" },
+      ]);
+    });
+
+    it("reads an expanded product object on a Price", () => {
+      const { offerings } = one(product("prod_a"), [price("price_a", "prod_a", { product: { id: "prod_a" } })]);
+      expect(offerings).toHaveLength(1);
+    });
+
+    it("leaves out an inactive Product and an id that is not a Stripe id", () => {
+      expect(
+        normalizeCatalog({
+          products: [product("prod_a", { active: false }), product("prod a"), { ...product("prod_x"), id: 42 }],
+          prices: [price("price_a", "prod_a")],
+        }),
+      ).toEqual({ offerings: [], held: [] });
+    });
+
+    it("holds a Product whose offering fails its parse invalid, and every other still normalizes", () => {
+      // Nothing the normalizer keeps fails the schema today, so the per-Product
+      // parse is driven by a schema that refuses one Product.
+      const original = offeringsSnapshotProductSchema.safeParse.bind(offeringsSnapshotProductSchema);
+      const spy = jest
+        .spyOn(offeringsSnapshotProductSchema, "safeParse")
+        .mockImplementation((value: unknown) =>
+          (value as { productId?: string }).productId === "prod_a"
+            ? ({ success: false } as never)
+            : original(value),
+        );
+      try {
+        const { offerings, held } = normalizeCatalog({
+          products: [product("prod_a"), product("prod_b", { name: "Basic" })],
+          prices: [price("price_a", "prod_a"), price("price_b", "prod_b", { lookup_key: "basic_monthly" })],
+        });
+        expect(held).toEqual([{ productId: "prod_a", name: "Growth", reason: "invalid" }]);
+        expect(offerings.map((o) => o.productId)).toEqual(["prod_b"]);
+      } finally {
+        spy.mockRestore();
+      }
+    });
+
+    it("counts a Product id the source answers twice once", () => {
+      const { offerings, held } = normalizeCatalog({
+        products: [product("prod_a"), product("prod_a", { name: "Growth again" })],
+        prices: [price("price_a", "prod_a")],
+      });
+      expect(offerings.map((o) => [o.productId, o.name])).toEqual([["prod_a", "Growth"]]);
+      expect(held).toEqual([]);
+    });
+
+    it("counts a Price id the source answers twice once", () => {
+      const { offerings } = one(product("prod_a"), [price("price_a", "prod_a"), price("price_a", "prod_a")]);
+      expect(offerings[0]!.prices.map((p) => p.priceId)).toEqual(["price_a"]);
+    });
+
+    it("reads no more than the catalog caps", () => {
+      const products = Array.from({ length: 1001 }, (_, i) =>
+        product(`prod_${i}`, { name: `P${i}`, metadata: {} }),
+      );
+      const { held } = normalizeCatalog({ products, prices: [] });
+      expect(held).toHaveLength(1000);
+      expect(held.some((h) => h.productId === "prod_1000")).toBe(false);
+    });
+  });
+
+  it("splits a lookup key only through parseLookupKey (AC-9)", () => {
+    const source = readFileSync(join(__dirname, "..", "catalog.ts"), "utf8");
+    expect(source).toContain("parseLookupKey(");
+    expect(source).not.toMatch(/split\(\s*["']_["']\s*\)/);
+    expect(source).not.toMatch(/monthly\|yearly/);
+  });
+});