create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/recommender-capture.test.ts

@@ -0,0 +1,983 @@
+/**
+ * @file recommender-capture.test.ts
+ * @description Unit tests for the recommender email-moment service (#4837).
+ *
+ * Mocks (external boundaries only — the repo's test rule; no internal module
+ * is mocked):
+ *   - ../../lib/prisma (auto-mock via __mocks__/prisma.ts) — the DB
+ *   - @working-theory/email (sendLeadNotification + sendDeliverableEmail) —
+ *     reached transitively through the REAL routeLead / fulfillDeliverable,
+ *     exactly as flow-engine.test.ts drives them
+ *   - @working-theory/license (checkLicense) — the flow-engine.test.ts idiom
+ *   - @working-theory/observability logger — spied for the AC-6 PII walk
+ *
+ * So AC-1 asserts the Lead on `prisma.lead.create` (routeLead's own write),
+ * AC-3 asserts the grant on `prisma.deliverableGrant.create`
+ * (fulfillDeliverable's own mint), and AC-6 drives routeLead to `ok: false`
+ * the way production can — the DB write rejects AND the file fallback
+ * cannot write (`AILK_INBOX_FALLBACK_DIR` pointed at an unwritable path, the
+ * lead-routing.test.ts idiom).
+ *
+ * The fixtures are a schema-valid recommending register + the compiled
+ * FlowConfig `serveFlow` parses; `recommend()` / `price()` are the REAL pure
+ * functions, so AC-1's `fits` and AC-4's `quote` are derived from the same
+ * engine the browser runs (spec D3/D6).
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- prisma is a DB boundary; __mocks__/prisma.ts activates the auto-mock (Jest requires explicit call for local files)
+jest.mock("../../lib/prisma.js");
+
+const mockSendDeliverableEmail = jest.fn();
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-test" }),
+  sendDeliverableEmail: (...args: unknown[]) => mockSendDeliverableEmail(...args),
+}));
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: jest.fn().mockResolvedValue({
+    tier: "free",
+    plan: null,
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  }),
+}));
+
+const mockLoggerInfo = jest.fn();
+const mockLoggerWarn = jest.fn();
+const mockLoggerError = jest.fn();
+jest.mock("@working-theory/observability", () => ({
+  logger: {
+    info: (...args: unknown[]) => mockLoggerInfo(...args),
+    warn: (...args: unknown[]) => mockLoggerWarn(...args),
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    debug: jest.fn(),
+  },
+}));
+
+import { price, recommend } from "@working-theory/validation";
+
+import { prisma } from "../../lib/prisma.js";
+import { MAX_AGGREGATION_ROWS } from "../answer-distributions.js";
+import {
+  attachStripeSession,
+  captureRecommenderChoice,
+  expireFlowCheckout,
+  findRegisterForSlug,
+  FLOW_CHECKOUT_IDEMPOTENCY_TTL_MS,
+  recordCheckout,
+} from "../recommender-capture.js";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const SITE = "site_1";
+const SLUG = "ailk-reco";
+const EMAIL = "buyer@example.com";
+const en = (s: string) => ({ en: s });
+
+const SOURCE_META = {
+  ip: "203.0.113.9",
+  userAgent: "jest",
+  receivedAt: "2026-09-05T20:00:00.000Z",
+};
+
+const OFFERS = [
+  {
+    key: "free_oss",
+    copy: { name: en("Free (OSS)") },
+    price: { kind: "label" as const, label: en("Free — self-hosted") },
+    rules: [{ when: { answer: "q_team", eq: "solo" }, reason: en("Solo builders get it free.") }],
+  },
+  {
+    key: "pro",
+    copy: { name: en("Pro") },
+    price: { kind: "exact" as const, amount: 249, period: "annual" as const },
+    rules: [
+      { when: { answer: "q_team", eq: "small_team" }, reason: en("Teams need seats.") },
+    ],
+  },
+];
+
+function rateTable(currency?: string) {
+  return {
+    seatRates: [{ offer: "pro", amount: 249, period: "annual" as const }],
+    creditLadder: {
+      denomination: "monthly" as const,
+      tiers: [{ credits: 10, amount: 99 }],
+      custom: en("Contact us for larger packages"),
+    },
+    ...(currency !== undefined ? { currency } : {}),
+  };
+}
+
+const QUESTION_OPTIONS = [
+  { value: "solo", label: en("Solo") },
+  { value: "small_team", label: en("Small team") },
+];
+
+function register(overrides: Record<string, unknown> = {}) {
+  return {
+    key: "reco-exp",
+    mode: "recommending" as const,
+    status: "live" as const,
+    waitlists: [{ key: "main", flowSlug: SLUG }],
+    questionSet: {
+      version: 1 as const,
+      questions: [
+        {
+          id: "q_team",
+          prompt: en("Team?"),
+          answerType: "single" as const,
+          options: QUESTION_OPTIONS,
+        },
+      ],
+    },
+    tracking: {
+      version: 1 as const,
+      utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+      waitlists: { main: { campaign: "reco-campaign", channels: ["organic"] } },
+    },
+    stripeConfigRef: "stripe-main",
+    offers: OFFERS,
+    rateTable: rateTable("usd"),
+    ...overrides,
+  };
+}
+
+function flowConfig(overrides: Record<string, unknown> = {}) {
+  return {
+    slug: SLUG,
+    defaultLocale: "en",
+    mode: "recommending" as const,
+    steps: [
+      {
+        key: "team",
+        type: "segmentation" as const,
+        copy: { title: en("Tell us about your team") },
+        questions: [{ name: "q_team", options: QUESTION_OPTIONS }],
+      },
+    ],
+    offers: OFFERS,
+    rateTable: rateTable("usd"),
+    recommendation: { key: "recommendation", copy: { title: en("Your recommendation") } },
+    experiment: { key: "reco-exp", waitlist: "main" },
+    ...overrides,
+  };
+}
+
+const DELIVERABLES = {
+  assets: [{ assetKey: "plan-pdf" }],
+  copy: { subject: en("Your plan"), body: en("Here it is") },
+};
+
+const ANSWERS = { q_team: "small_team" };
+
+function arm(opts: { config?: Record<string, unknown>; register?: Record<string, unknown> } = {}) {
+  (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+    id: "flow_1",
+    siteId: SITE,
+    slug: SLUG,
+    config: flowConfig(opts.config),
+  });
+  (prisma.waitlistExperiment.findMany as jest.Mock).mockResolvedValue([
+    { id: "wlexp_1", config: register(opts.register) },
+  ]);
+  (prisma.flowSession.create as jest.Mock).mockResolvedValue({ id: "flsess_new" });
+  // Resume lookups see no walk session; recordCheckout's owner check sees the
+  // freshly-created session with its lead stamped.
+  (prisma.flowSession.findUnique as jest.Mock).mockImplementation(async (args: { where: { id: string } }) =>
+    args.where.id === "flsess_new" ? { siteId: SITE, flowSlug: SLUG, leadId: "lead_1" } : null,
+  );
+  (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+  (prisma.flowCheckout.create as jest.Mock).mockResolvedValue({ id: "flchk_1" });
+  // #4912 — the keyed idempotency lookup sees no prior attempt by default.
+  (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(null);
+  (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.lead.create as jest.Mock).mockResolvedValue({ id: "lead_1" });
+  (prisma.deliverableAsset.findUnique as jest.Mock).mockResolvedValue({
+    id: "dasset_1",
+    siteId: SITE,
+    key: "plan-pdf",
+  });
+  (prisma.deliverableGrant.create as jest.Mock).mockResolvedValue({ id: "dgrant_1" });
+  (prisma.deliverableGrant.update as jest.Mock).mockResolvedValue({});
+  mockSendDeliverableEmail.mockResolvedValue({ ok: true, messageId: "msg-deliverable" });
+}
+
+function saveInput(extra: Record<string, unknown> = {}) {
+  return {
+    siteId: SITE,
+    flowSlug: SLUG,
+    answers: ANSWERS,
+    email: EMAIL,
+    locale: "en",
+    choice: "save" as const,
+    sourceMeta: SOURCE_META,
+    ...extra,
+  };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env.DATABASE_URL = "postgres://test";
+  process.env.AILK_DELIVERABLE_EMAIL_FROM = "deliverable@example.com";
+  process.env.AILK_INBOX_FALLBACK_DIR = "/dev/null/ailk-fallback-unwritable";
+  delete process.env.AILK_LEAD_NOTIFICATION_TO;
+});
+
+// ─── AC-1 — cold-load save: one session + one lead with the full payload ────
+
+describe("AC-1 — cold-load save creates one session + one lead with the full payload", () => {
+  it("creates exactly one completed session keyed by segmentation step, and one lead via routeLead", async () => {
+    arm();
+    const result = await captureRecommenderChoice(saveInput());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(prisma.flowSession.create).toHaveBeenCalledTimes(1);
+    const createArg = (prisma.flowSession.create as jest.Mock).mock.calls[0][0];
+    expect(createArg.data.siteId).toBe(SITE);
+    expect(createArg.data.flowSlug).toBe(SLUG);
+    expect(createArg.data.email).toBe(EMAIL);
+    expect(createArg.data.completedAt).toBeInstanceOf(Date);
+    expect(createArg.data.state).toEqual({ team: { q_team: "small_team" } });
+
+    // The REAL routeLead ran — its one DB write is the Lead assertion surface.
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    const leadData = (prisma.lead.create as jest.Mock).mock.calls[0][0].data;
+    expect(leadData.siteId).toBe(SITE);
+    expect(leadData.source).toBe(`flow:${SLUG}`);
+    expect(leadData.email).toBe(EMAIL);
+    const expectedFits = recommend(register() as never, ANSWERS).fits.map((f) => f.offerKey);
+    expect(expectedFits).toEqual(["pro"]);
+    expect(leadData.payload).toMatchObject({
+      q_team: "small_team",
+      flowSlug: SLUG,
+      locale: "en",
+      experimentKey: "reco-exp",
+      waitlistKey: "main",
+      recommender: { choice: "save", fits: expectedFits },
+    });
+    expect(result.sessionId).toBe("flsess_new");
+    expect(result.leadId).toBe("lead_1");
+    // leadId is stamped on the session after routeLead succeeds.
+    expect(prisma.flowSession.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: "flsess_new" },
+        data: expect.objectContaining({ leadId: "lead_1" }),
+      }),
+    );
+  });
+
+  it("findRegisterForSlug resolves the register via one siteId-scoped findMany, undefined on no match", async () => {
+    arm();
+    const found = await findRegisterForSlug(SITE, SLUG);
+    expect(found?.stripeConfigRef).toBe("stripe-main");
+    expect(found?.rateTable?.currency).toBe("usd");
+    expect(prisma.waitlistExperiment.findMany).toHaveBeenCalledTimes(1);
+    expect((prisma.waitlistExperiment.findMany as jest.Mock).mock.calls[0][0].where).toEqual({
+      siteId: SITE,
+    });
+    expect(await findRegisterForSlug(SITE, "no-such-flow")).toBeUndefined();
+  });
+
+  it("findRegisterForSlug bounds its findMany with take: MAX_AGGREGATION_ROWS (#5147)", async () => {
+    arm();
+    await findRegisterForSlug(SITE, SLUG);
+    expect((prisma.waitlistExperiment.findMany as jest.Mock).mock.calls[0][0].take).toBe(
+      MAX_AGGREGATION_ROWS,
+    );
+  });
+});
+
+// ─── AC-2 — resume, never duplicate ─────────────────────────────────────────
+
+describe("AC-2 — a walk session is resumed, never duplicated", () => {
+  it("updates the existing session in place and never creates", async () => {
+    arm();
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+      id: "flsess_walk",
+      siteId: SITE,
+      flowSlug: SLUG,
+      // #4912 — SESSION_RESUME_SELECT now returns these two; an unowned walk
+      // session (no Lead stamped yet) is the case this test has always meant.
+      leadId: null,
+      email: null,
+    });
+    const result = await captureRecommenderChoice(saveInput({ sessionId: "flsess_walk" }));
+    expect(result.ok).toBe(true);
+    expect(prisma.flowSession.create).not.toHaveBeenCalled();
+    const updates = (prisma.flowSession.update as jest.Mock).mock.calls;
+    expect(updates.length).toBeGreaterThanOrEqual(1);
+    expect(updates[0][0].where).toEqual({ id: "flsess_walk" });
+    expect(updates[0][0].data).toMatchObject({
+      email: EMAIL,
+      state: { team: { q_team: "small_team" } },
+    });
+    expect(updates[0][0].data.completedAt).toBeInstanceOf(Date);
+    if (result.ok) expect(result.sessionId).toBe("flsess_walk");
+  });
+
+  it.each([
+    ["unknown id", null],
+    ["foreign-site row", { id: "flsess_x", siteId: "site_other", flowSlug: SLUG, leadId: null, email: null }],
+    ["other-slug row", { id: "flsess_x", siteId: SITE, flowSlug: "other-flow", leadId: null, email: null }],
+  ])("falls back to create on an %s", async (_label, row) => {
+    arm();
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue(row);
+    const result = await captureRecommenderChoice(saveInput({ sessionId: "flsess_x" }));
+    expect(result.ok).toBe(true);
+    expect(prisma.flowSession.create).toHaveBeenCalledTimes(1);
+    if (result.ok) expect(result.sessionId).toBe("flsess_new");
+  });
+});
+
+// ─── #4912 AC-2 — resume ownership, and the Lead reused rather than doubled ──
+
+describe("#4912 AC-2 — a session that carries a Lead is resumable only by its own email", () => {
+  const OWNED = {
+    id: "flsess_walk",
+    siteId: SITE,
+    flowSlug: SLUG,
+    leadId: "lead_owner",
+    email: EMAIL,
+  };
+
+  it("resumes for the same email and REUSES the Lead — no second routeLead write", async () => {
+    arm();
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue(OWNED);
+
+    const result = await captureRecommenderChoice(saveInput({ sessionId: "flsess_walk" }));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.sessionId).toBe("flsess_walk");
+    expect(result.leadId).toBe("lead_owner");
+    // The whole point of #4860: routeLead's own write does not happen twice.
+    expect(prisma.lead.create).not.toHaveBeenCalled();
+    expect(prisma.flowSession.create).not.toHaveBeenCalled();
+    // The answers/locale/completion refresh still lands …
+    const updates = (prisma.flowSession.update as jest.Mock).mock.calls;
+    expect(updates).toHaveLength(1);
+    expect(updates[0][0].data).toMatchObject({
+      email: EMAIL,
+      state: { team: { q_team: "small_team" } },
+    });
+    // … and the leadId is NOT re-stamped, because it never changed.
+    expect(updates[0][0].data.leadId).toBeUndefined();
+  });
+
+  it.each([
+    ["a second, different email", "attacker@example.com"],
+    ["an email that merely looks similar", "buyer@example.com.evil.test"],
+  ])("never overwrites the row for %s — it falls back to create", async (_label, email) => {
+    arm();
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue(OWNED);
+
+    const result = await captureRecommenderChoice(saveInput({ sessionId: "flsess_walk", email }));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    // Nothing at all was written to the session somebody else owns.
+    const touched = (prisma.flowSession.update as jest.Mock).mock.calls.filter(
+      (call: [{ where: { id: string } }]) => call[0].where.id === "flsess_walk",
+    );
+    expect(touched).toHaveLength(0);
+    expect(prisma.flowSession.create).toHaveBeenCalledTimes(1);
+    expect(result.sessionId).toBe("flsess_new");
+    expect(result.leadId).toBe("lead_1");
+  });
+
+  it("compares the owner email case-insensitively, after trimming", async () => {
+    arm();
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue(OWNED);
+
+    const result = await captureRecommenderChoice(
+      saveInput({ sessionId: "flsess_walk", email: "  Buyer@Example.COM  " }),
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.sessionId).toBe("flsess_walk");
+    expect(result.leadId).toBe("lead_owner");
+  });
+
+  it("falls back to create when the row carries a leadId but no email to own it", async () => {
+    arm();
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({ ...OWNED, email: null });
+
+    const result = await captureRecommenderChoice(saveInput({ sessionId: "flsess_walk" }));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(prisma.flowSession.create).toHaveBeenCalledTimes(1);
+    expect(result.sessionId).toBe("flsess_new");
+  });
+
+  it("still resumes an unowned walk session (no leadId yet) and stamps the new Lead on it", async () => {
+    arm();
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+      ...OWNED,
+      leadId: null,
+      email: null,
+    });
+
+    const result = await captureRecommenderChoice(saveInput({ sessionId: "flsess_walk" }));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.sessionId).toBe("flsess_walk");
+    expect(result.leadId).toBe("lead_1");
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-mint the T+0 grant on an owned resume", async () => {
+    arm({ config: { deliverables: DELIVERABLES } });
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue(OWNED);
+
+    await captureRecommenderChoice(saveInput({ sessionId: "flsess_walk" }));
+
+    expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+    expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+  });
+});
+
+// ─── AC-3 — the T+0 grant path: reused, opt-in, fail-soft ───────────────────
+
+describe("AC-3 — the T+0 grant path is reused, opt-in, and fail-soft", () => {
+  it("mints one grant for the session + lead ids when the config carries deliverables (the real fulfillDeliverable)", async () => {
+    arm({ config: { deliverables: DELIVERABLES } });
+    const result = await captureRecommenderChoice(saveInput());
+    expect(result.ok).toBe(true);
+    // The asset lookup is keyed on the block's assetKey for THIS site …
+    expect(prisma.deliverableAsset.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { siteId_key: { siteId: SITE, key: "plan-pdf" } } }),
+    );
+    // … and the grant is minted once, against the new session + the lead.
+    expect(prisma.deliverableGrant.create).toHaveBeenCalledTimes(1);
+    expect((prisma.deliverableGrant.create as jest.Mock).mock.calls[0][0].data).toEqual({
+      siteId: SITE,
+      assetId: "dasset_1",
+      leadId: "lead_1",
+      sessionId: "flsess_new",
+    });
+    expect(mockSendDeliverableEmail).toHaveBeenCalledTimes(1);
+    expect(mockSendDeliverableEmail.mock.calls[0][0].to).toBe(EMAIL);
+  });
+
+  it("never touches the grant path without a deliverables block", async () => {
+    arm();
+    await captureRecommenderChoice(saveInput());
+    expect(prisma.deliverableAsset.findUnique).not.toHaveBeenCalled();
+    expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+  });
+
+  it("a grant-path rejection (the asset read throwing) leaves the capture ok", async () => {
+    arm({ config: { deliverables: DELIVERABLES } });
+    (prisma.deliverableAsset.findUnique as jest.Mock).mockRejectedValue(new Error("db down"));
+    const result = await captureRecommenderChoice(saveInput());
+    expect(result.ok).toBe(true);
+    expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+  });
+});
+
+// ─── AC-4 — recordCheckout: MINOR units, and every refusal ──────────────────
+
+describe("AC-4 — the checkout row carries a server-recomputed MINOR-unit amount", () => {
+  function checkoutInput(extra: Record<string, unknown> = {}) {
+    return {
+      siteId: SITE,
+      flowSlug: SLUG,
+      experimentKey: "reco-exp",
+      sessionId: "flsess_new",
+      leadId: "lead_1",
+      email: EMAIL,
+      offerKey: "pro",
+      seats: 1,
+      period: "annual" as const,
+      creditStop: { kind: "none" as const },
+      permalink: "eyJ2ZXJzaW9uIjoxfQ",
+      ...extra,
+    };
+  }
+
+  it("writes one row with amountMinor 24900 (never 249), the currency, the quote and the permalink", async () => {
+    arm();
+    const result = await recordCheckout(checkoutInput());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(prisma.flowCheckout.create).toHaveBeenCalledTimes(1);
+    const data = (prisma.flowCheckout.create as jest.Mock).mock.calls[0][0].data;
+    expect(data.amountMinor).toBe(24900);
+    expect(data.amountMinor).not.toBe(249);
+    expect(data.currency).toBe("usd");
+    expect(data.status).toBe("created");
+    expect(data.stripeSessionId).toBeNull();
+    expect(data.quote).toEqual(price(register() as never, "pro", 1, "annual", { kind: "none" }));
+    expect(data.permalink).toBe("eyJ2ZXJzaW9uIjoxfQ");
+    expect(data).toMatchObject({
+      siteId: SITE,
+      flowSlug: SLUG,
+      experimentKey: "reco-exp",
+      sessionId: "flsess_new",
+      leadId: "lead_1",
+      offerKey: "pro",
+      seats: 1,
+      period: "annual",
+      creditStop: { kind: "none" },
+    });
+    expect(result.flowCheckoutId).toBe("flchk_1");
+    expect(result.amountMinor).toBe(24900);
+  });
+
+  it.each([
+    ["unknown_offer", { offerKey: "nope" }, {}],
+    ["custom_stop", { creditStop: { kind: "custom" as const } }, {}],
+    ["invalid_seats", { seats: 1000 }, {}],
+    ["invalid_seats", { seats: 0 }, {}],
+    ["no_rate_table", {}, { register: { rateTable: undefined } }],
+    ["no_currency", {}, { register: { rateTable: rateTable() } }],
+    ["no_register", { flowSlug: "no-such-flow" }, {}],
+    ["session_mismatch", { sessionId: "flsess_other" }, {}],
+    ["session_mismatch", { leadId: "lead_other" }, {}],
+  ])("returns %s and writes no row", async (kind, extra, armOpts) => {
+    arm(armOpts as never);
+    const result = await recordCheckout(checkoutInput(extra));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe(kind);
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+  });
+
+  it("resolves the register from the DB itself — the caller supplies no register", async () => {
+    arm();
+    await recordCheckout(checkoutInput());
+    expect(prisma.waitlistExperiment.findMany).toHaveBeenCalledTimes(1);
+    expect((prisma.waitlistExperiment.findMany as jest.Mock).mock.calls[0][0].where).toEqual({ siteId: SITE });
+  });
+
+  it("attachStripeSession stamps the session id and the replay URL, scoped to the site", async () => {
+    arm();
+    const attached = await attachStripeSession(
+      SITE,
+      "flchk_1",
+      "cs_test_abc",
+      "https://checkout.stripe.com/c/pay/cs_test_abc",
+    );
+    expect(attached).toEqual({ count: 1 });
+    expect(prisma.flowCheckout.updateMany).toHaveBeenCalledWith({
+      // #4912 — `status: "created"` mirrors the #4838 webhook's own join, so a
+      // row something else already finished or expired never takes the stamp.
+      where: { id: "flchk_1", siteId: SITE, status: "created" },
+      data: {
+        stripeSessionId: "cs_test_abc",
+        checkoutUrl: "https://checkout.stripe.com/c/pay/cs_test_abc",
+      },
+    });
+  });
+});
+
+// ─── #4912 AC-3 / AC-4 — checkout idempotency, replay and reconcile ──────────
+
+describe("#4912 AC-3 — /checkout is keyed by a server-derived fingerprint", () => {
+  function checkoutInput(extra: Record<string, unknown> = {}) {
+    return {
+      siteId: SITE,
+      flowSlug: SLUG,
+      experimentKey: "reco-exp",
+      sessionId: "flsess_new",
+      leadId: "lead_1",
+      email: EMAIL,
+      offerKey: "pro",
+      seats: 1,
+      period: "annual" as const,
+      creditStop: { kind: "none" as const },
+      permalink: "eyJ2ZXJzaW9uIjoxfQ",
+      ...extra,
+    };
+  }
+
+  /** A keyed row as the lookup sees it; `createdAt` defaults to "just now". */
+  function keyedRow(over: Record<string, unknown> = {}) {
+    return {
+      id: "flchk_first",
+      status: "created",
+      stripeSessionId: "cs_test_first",
+      checkoutUrl: "https://checkout.stripe.com/c/pay/cs_test_first",
+      createdAt: new Date(Date.now() - 60_000),
+      ...over,
+    };
+  }
+
+  function lastKey(): string {
+    const calls = (prisma.flowCheckout.findUnique as jest.Mock).mock.calls;
+    return calls[calls.length - 1][0].where.siteId_idempotencyKey.idempotencyKey;
+  }
+
+  function createdKeys(): unknown[] {
+    return (prisma.flowCheckout.create as jest.Mock).mock.calls.map(
+      (call: [{ data: { idempotencyKey: unknown } }]) => call[0].data.idempotencyKey,
+    );
+  }
+
+  it("looks the attempt up on a site-scoped sha256 digest and writes that key onto the new row", async () => {
+    arm();
+    const result = await recordCheckout(checkoutInput());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const where = (prisma.flowCheckout.findUnique as jest.Mock).mock.calls[0][0].where;
+    expect(where.siteId_idempotencyKey.siteId).toBe(SITE);
+    expect(where.siteId_idempotencyKey.idempotencyKey).toMatch(/^[0-9a-f]{64}$/);
+    expect(createdKeys()).toEqual([where.siteId_idempotencyKey.idempotencyKey]);
+    expect(result.replayed).toBe(false);
+  });
+
+  it("gives two identical requests the same key, and any changed field a different one", async () => {
+    arm();
+    await recordCheckout(checkoutInput());
+    const base = lastKey();
+    await recordCheckout(checkoutInput());
+    expect(lastKey()).toBe(base);
+
+    for (const extra of [
+      { seats: 2 },
+      { offerKey: "free_oss" },
+      { period: "monthly" as const },
+      { creditStop: { kind: "tier" as const, index: 0 } },
+      { permalink: "eyJ2ZXJzaW9uIjoyfQ" },
+      { sessionId: "flsess_other_walk" },
+      { email: "someone-else@example.com" },
+      { flowSlug: SLUG.toUpperCase() },
+    ]) {
+      await recordCheckout(checkoutInput(extra));
+      expect(lastKey()).not.toBe(base);
+    }
+    // The email is hashed into the key and never written to the row.
+    for (const call of (prisma.flowCheckout.create as jest.Mock).mock.calls) {
+      expect(JSON.stringify(call[0].data)).not.toContain(EMAIL);
+    }
+  });
+
+  it("distinguishes two credit-stop TIERS, not merely the stop kind", async () => {
+    // A two-rung ladder, so index 1 is a priceable stop rather than a refusal.
+    arm({
+      register: {
+        rateTable: {
+          ...rateTable("usd"),
+          creditLadder: {
+            denomination: "monthly" as const,
+            tiers: [
+              { credits: 10, amount: 99 },
+              { credits: 25, amount: 199 },
+            ],
+            custom: en("Contact us for larger packages"),
+          },
+        },
+      },
+    });
+    const first = await recordCheckout(checkoutInput({ creditStop: { kind: "tier" as const, index: 0 } }));
+    expect(first.ok).toBe(true);
+    const tier0 = lastKey();
+    const second = await recordCheckout(checkoutInput({ creditStop: { kind: "tier" as const, index: 1 } }));
+    expect(second.ok).toBe(true);
+    expect(lastKey()).not.toBe(tier0);
+  });
+
+  it("distinguishes the same request against a DIFFERENT site", async () => {
+    arm();
+    await recordCheckout(checkoutInput());
+    const here = lastKey();
+    (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+      id: "flow_1",
+      siteId: "site_other",
+      slug: SLUG,
+      config: flowConfig(),
+    });
+    (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+      siteId: "site_other",
+      flowSlug: SLUG,
+      leadId: "lead_1",
+    });
+    await recordCheckout(checkoutInput({ siteId: "site_other" }));
+    expect(lastKey()).not.toBe(here);
+  });
+
+  it("changes the key when the SERVER's price moves, so a replay can never serve a stale amount", async () => {
+    arm();
+    await recordCheckout(checkoutInput());
+    const at249 = lastKey();
+    // Only the register's seat rate moves; the request body is identical.
+    arm({ register: { rateTable: { ...rateTable("usd"), seatRates: [{ offer: "pro", amount: 300, period: "annual" as const }] } } });
+    const result = await recordCheckout(checkoutInput());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.amountMinor).toBe(30000);
+    expect(lastKey()).not.toBe(at249);
+  });
+
+  it("replays a live keyed row inside the TTL — no second row, no second Stripe session", async () => {
+    arm();
+    (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(keyedRow());
+
+    const result = await recordCheckout(checkoutInput());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.replayed).toBe(true);
+    if (!result.replayed) return;
+    expect(result.flowCheckoutId).toBe("flchk_first");
+    expect(result.stripeSessionId).toBe("cs_test_first");
+    expect(result.checkoutUrl).toBe("https://checkout.stripe.com/c/pay/cs_test_first");
+    // The price is still the server's own, recomputed on the replay.
+    expect(result.amountMinor).toBe(24900);
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+    expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("replays exactly AT the TTL boundary, and no longer one millisecond past it", async () => {
+    arm();
+    const at = Date.now();
+    jest.spyOn(Date, "now").mockReturnValue(at);
+    try {
+      (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(
+        keyedRow({ createdAt: new Date(at - FLOW_CHECKOUT_IDEMPOTENCY_TTL_MS) }),
+      );
+      const onBoundary = await recordCheckout(checkoutInput());
+      expect(onBoundary.ok && onBoundary.replayed).toBe(true);
+
+      (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(
+        keyedRow({ createdAt: new Date(at - FLOW_CHECKOUT_IDEMPOTENCY_TTL_MS - 1) }),
+      );
+      const pastIt = await recordCheckout(checkoutInput());
+      expect(pastIt.ok && pastIt.replayed).toBe(false);
+    } finally {
+      (Date.now as jest.Mock).mockRestore();
+    }
+  });
+
+  it("never replays a row the webhook already completed — the visitor gets a new session", async () => {
+    arm();
+    (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(
+      keyedRow({ status: "completed" }),
+    );
+
+    const result = await recordCheckout(checkoutInput());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.replayed).toBe(false);
+    // A completed row keeps its status and its Stripe ids; only the key is
+    // released, so this new purchase can take a keyed row of its own.
+    expect(prisma.flowCheckout.updateMany).toHaveBeenCalledWith({
+      where: { id: "flchk_first", siteId: SITE },
+      data: { idempotencyKey: null },
+    });
+    expect(createdKeys()).toHaveLength(1);
+    expect(createdKeys()[0]).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("reconciles a STALE row that never took a Stripe session, then writes a fresh keyed one", async () => {
+    arm();
+    (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(
+      keyedRow({
+        id: "flchk_stale",
+        stripeSessionId: null,
+        checkoutUrl: null,
+        createdAt: new Date(Date.now() - FLOW_CHECKOUT_IDEMPOTENCY_TTL_MS - 60_000),
+      }),
+    );
+
+    const result = await recordCheckout(checkoutInput());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.replayed).toBe(false);
+    // Nothing can ever join it, so it is marked dead and its stored URL dropped.
+    expect(prisma.flowCheckout.updateMany).toHaveBeenCalledWith({
+      where: { id: "flchk_stale", siteId: SITE },
+      data: { status: "expired", idempotencyKey: null, checkoutUrl: null },
+    });
+    expect(result.flowCheckoutId).toBe("flchk_1");
+  });
+
+  it("leaves a STALE row that DID take a Stripe session joinable — key released, status untouched", async () => {
+    arm();
+    (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(
+      keyedRow({
+        id: "flchk_stale",
+        createdAt: new Date(Date.now() - FLOW_CHECKOUT_IDEMPOTENCY_TTL_MS - 60_000),
+      }),
+    );
+
+    await recordCheckout(checkoutInput());
+
+    // Marking it `expired` would make the #4838 webhook's `status: "created"`
+    // update miss, so a payment on that still-open session would go unrecorded.
+    expect(prisma.flowCheckout.updateMany).toHaveBeenCalledWith({
+      where: { id: "flchk_stale", siteId: SITE },
+      data: { idempotencyKey: null },
+    });
+  });
+
+  it("leaves an IN-FLIGHT row completely alone and takes an unkeyed row instead", async () => {
+    arm();
+    // A row created moments ago whose own request is still inside its Stripe
+    // call: stealing its key would strand the session about to be stamped on it.
+    (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(
+      keyedRow({ id: "flchk_inflight", stripeSessionId: null, checkoutUrl: null }),
+    );
+
+    const result = await recordCheckout(checkoutInput());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.replayed).toBe(false);
+    expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+    expect(mockLoggerWarn).not.toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "checkout_reconciled" }),
+      expect.anything(),
+    );
+    expect(createdKeys()).toEqual([null]);
+  });
+
+  it("logs the reconcile with the row-id prefix and an outcome, and nothing else", async () => {
+    arm();
+    (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(
+      keyedRow({
+        id: "flchk_stale_row_id",
+        stripeSessionId: null,
+        checkoutUrl: null,
+        createdAt: new Date(Date.now() - FLOW_CHECKOUT_IDEMPOTENCY_TTL_MS - 60_000),
+      }),
+    );
+
+    await recordCheckout(checkoutInput());
+
+    const line = mockLoggerWarn.mock.calls.find(
+      (call: [Record<string, unknown>]) => call[0]?.["outcome"] === "checkout_reconciled",
+    );
+    expect(line).toBeDefined();
+    expect(line?.[0]).toEqual({
+      flowCheckoutIdPrefix: "flchk_st",
+      outcome: "checkout_reconciled",
+    });
+    expect((line?.[0] as { flowCheckoutIdPrefix: string }).flowCheckoutIdPrefix).toHaveLength(8);
+  });
+
+  it("survives a lost create race: the unique violation becomes an unkeyed row, never a throw", async () => {
+    arm();
+    const conflict = Object.assign(new Error("Unique constraint failed"), { code: "P2002" });
+    (prisma.flowCheckout.create as jest.Mock)
+      .mockRejectedValueOnce(conflict)
+      .mockResolvedValue({ id: "flchk_2" });
+    // The winner has not stamped its Stripe session yet, so there is nothing
+    // to replay.
+    (prisma.flowCheckout.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValue(keyedRow({ stripeSessionId: null, checkoutUrl: null }));
+
+    const result = await recordCheckout(checkoutInput());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.replayed).toBe(false);
+    expect(result.flowCheckoutId).toBe("flchk_2");
+    expect(createdKeys()[1]).toBeNull();
+  });
+
+  it("replays instead, when the create race is lost to a winner that already has its session", async () => {
+    arm();
+    const conflict = Object.assign(new Error("Unique constraint failed"), { code: "P2002" });
+    (prisma.flowCheckout.create as jest.Mock).mockRejectedValueOnce(conflict);
+    (prisma.flowCheckout.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValue(keyedRow());
+
+    const result = await recordCheckout(checkoutInput());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.replayed).toBe(true);
+    if (!result.replayed) return;
+    expect(result.stripeSessionId).toBe("cs_test_first");
+  });
+
+  it("rethrows any create failure that is NOT a unique violation", async () => {
+    arm();
+    (prisma.flowCheckout.create as jest.Mock).mockRejectedValue(new Error("db down"));
+    await expect(recordCheckout(checkoutInput())).rejects.toThrow("db down");
+  });
+
+  it("expireFlowCheckout kills only a still-created row, and releases its key and URL", async () => {
+    arm();
+    const result = await expireFlowCheckout(SITE, "flchk_1");
+    expect(result).toEqual({ count: 1 });
+    expect(prisma.flowCheckout.updateMany).toHaveBeenCalledWith({
+      where: { id: "flchk_1", siteId: SITE, status: "created" },
+      data: { status: "expired", idempotencyKey: null, checkoutUrl: null },
+    });
+  });
+});
+
+// ─── AC-6 — failure asymmetry + PII boundary ────────────────────────────────
+
+describe("AC-6 — failure asymmetry + PII boundary", () => {
+  it("a failed routeLead is a failed capture: completedAt stamped, no checkout row, no grant", async () => {
+    arm({ config: { deliverables: DELIVERABLES } });
+    // The way production fails: the DB write rejects AND the file fallback
+    // cannot write (an unwritable dir — the lead-routing.test.ts idiom), so the
+    // REAL routeLead returns persist_failed.
+    process.env.AILK_INBOX_FALLBACK_DIR = "/dev/null/ailk-fallback-unwritable";
+    (prisma.lead.create as jest.Mock).mockRejectedValue(new Error("db down"));
+    const result = await captureRecommenderChoice(saveInput());
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("lead_failed");
+    expect(prisma.flowSession.update).toHaveBeenCalledTimes(1);
+    expect((prisma.flowSession.update as jest.Mock).mock.calls[0][0].data.completedAt).toBeInstanceOf(
+      Date,
+    );
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+    expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+  });
+
+  it("a grant rejection whose message embeds the recipient address never reaches a log line", async () => {
+    arm({ config: { deliverables: DELIVERABLES } });
+    mockSendDeliverableEmail.mockRejectedValue(new Error(`Resend refused delivery to ${EMAIL}`));
+    const result = await captureRecommenderChoice(saveInput());
+    expect(result.ok).toBe(true);
+    const lines = [...mockLoggerInfo.mock.calls, ...mockLoggerWarn.mock.calls, ...mockLoggerError.mock.calls]
+      .map((call) => JSON.stringify(call))
+      .filter((line) => line.includes("[recommender-capture]"));
+    expect(lines.length).toBeGreaterThan(0);
+    for (const line of lines) expect(line).not.toContain(EMAIL);
+    const grantLine = mockLoggerWarn.mock.calls.find((c) => c[1] === "[recommender-capture] grant_failed");
+    expect(grantLine?.[0].err).toBe("Error");
+  });
+
+  it("every logger call this module emits carries only the allow-listed keys", async () => {
+    const ALLOWED = new Set(["siteId", "flowSlug", "sessionId", "leadId", "choice", "outcome", "err"]);
+    arm({ config: { deliverables: DELIVERABLES } });
+    (prisma.deliverableAsset.findUnique as jest.Mock).mockRejectedValue(new Error("db down"));
+    await captureRecommenderChoice(saveInput());
+    process.env.AILK_INBOX_FALLBACK_DIR = "/dev/null/ailk-fallback-unwritable";
+    (prisma.lead.create as jest.Mock).mockRejectedValue(new Error("db down"));
+    await captureRecommenderChoice(saveInput());
+    // Only THIS module's lines — routeLead / fulfillDeliverable log through the
+    // same logger with their own (already-tested) boundaries.
+    const calls = [
+      ...mockLoggerInfo.mock.calls,
+      ...mockLoggerWarn.mock.calls,
+      ...mockLoggerError.mock.calls,
+    ].filter((call) => typeof call[1] === "string" && call[1].startsWith("[recommender-capture]"));
+    expect(calls.length).toBeGreaterThan(0);
+    for (const call of calls) {
+      const ctx = call[0] as Record<string, unknown>;
+      for (const key of Object.keys(ctx)) expect(ALLOWED.has(key)).toBe(true);
+      const serialized = JSON.stringify(ctx);
+      expect(serialized).not.toContain(EMAIL);
+      expect(serialized).not.toContain("small_team");
+    }
+  });
+});