create-ailk 0.14.0 → 0.15.0

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-site-filter.test.ts

@@ -0,0 +1,366 @@
+/**
+ * POST /api/webhooks/stripe — the hub's site filter (#7868).
+ *
+ * A Checkout session stamped `metadata.site` for ANOTHER site (a spoke on the
+ * shared Stripe account) produces no hub side effect on
+ * `checkout.session.completed` or `.expired`, and answers 200. An unstamped
+ * session, an empty stamp, and the hub's own stamp are handled exactly as
+ * today (roadmap D4). Spec D3/D7, AC-2 … AC-4.
+ *
+ * The stripe-flow-checkout.test.ts harness: the commerce claim mocked present,
+ * the prisma manual mock, `verifyWebhookSignature` mocked at the package
+ * boundary, the idempotency store reset per test. The seven existing
+ * `stripe*.test.ts` suites are the regression floor and are not edited.
+ */
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+const mockTrack = jest.fn().mockResolvedValue(undefined);
+jest.mock("@working-theory/license", () => ({
+  checkLicense: jest.fn().mockResolvedValue({
+    tier: "pro",
+    plan: "pro-monthly",
+    features: ["commerce"],
+    expiresAt: null,
+    revoked: false,
+  }),
+}));
+
+jest.mock("@working-theory/analytics/server", () => ({
+  track: (...args: unknown[]) => mockTrack(...args),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../../lib/prisma.js");
+
+const mockVerifyWebhookSignature = jest.fn();
+class MockStripeWebhookSignatureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StripeWebhookSignatureError";
+  }
+}
+jest.mock("@working-theory/stripe-client", () => ({
+  verifyWebhookSignature: (...args: unknown[]) => mockVerifyWebhookSignature(...args),
+  StripeWebhookSignatureError: MockStripeWebhookSignatureError,
+  assertSandboxKey: jest.fn(),
+  createCheckoutSession: jest.fn(),
+  getStripeClient: jest.fn(),
+  STRIPE_API_VERSION: "2024-06-20",
+  StripeConfigError: class StripeConfigError extends Error {},
+  UnknownProductCodeError: class UnknownProductCodeError extends Error {},
+  WEBHOOK_TOLERANCE_SECONDS: 300,
+}));
+
+import * as configModule from "../../../config/index.js";
+import { stripeWebhookHandler } from "../stripe.js";
+import { __resetIdempotencyStore } from "../../../lib/webhook-idempotency.js";
+import { prisma } from "../../../lib/prisma.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const SESSION_ID = "cs_test_session_12345678901234567890";
+const CUSTOMER_ID = "cus_test_12345678901234567890";
+const EMAIL = "spoke-buyer@example.com";
+const AMOUNT_TOTAL = 24917;
+const USER_ID = "usr_buyer_7868";
+const ORG_ID = "org_buyer_7868";
+
+/**
+ * A session that reaches every one of the four `completed` tasks if it is
+ * dispatched: telemetry, the billing bind (customer + `ailk_user_id`), the
+ * recommender stamp (`flowCheckoutId`) and the request-paid stamp
+ * (`payment_link`, paid).
+ */
+function sessionEvent(
+  type: "checkout.session.completed" | "checkout.session.expired",
+  metadata: Record<string, unknown> = {},
+) {
+  return {
+    id: "evt_test_12345678abcdef",
+    type,
+    data: {
+      object: {
+        id: SESSION_ID,
+        payment_status: "paid",
+        payment_link: "plink_test_1234567890",
+        amount_total: AMOUNT_TOTAL,
+        currency: "usd",
+        customer: CUSTOMER_ID,
+        customer_details: { email: EMAIL },
+        metadata: {
+          flowCheckoutId: "flchk_test_1",
+          flowSlug: "ailk-reco",
+          offerKey: "pro",
+          ailk_user_id: USER_ID,
+          ...metadata,
+        },
+      },
+    },
+  };
+}
+
+type LogCall = [unknown, string?];
+const logCalls: LogCall[] = [];
+
+async function buildTestServer(): Promise<FastifyInstance> {
+  const server = Fastify({ logger: false });
+  await server.register(async (webhooksScope) => {
+    webhooksScope.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => {
+      done(null, body);
+    });
+    webhooksScope.addHook("onRequest", async (request) => {
+      for (const level of ["info", "warn", "error"] as const) {
+        const original = request.log[level].bind(request.log);
+        request.log[level] = ((...args: unknown[]) => {
+          logCalls.push(args as LogCall);
+          return (original as (...a: unknown[]) => void)(...args);
+        }) as typeof request.log.info;
+      }
+    });
+    webhooksScope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+  });
+  await server.ready();
+  return server;
+}
+
+const VALID_BODY = Buffer.from(JSON.stringify({ type: "test" }));
+const HEADERS = { "content-type": "application/json", "stripe-signature": "t=1234,v1=abc" };
+const ORIGINAL_AILK_SITE_ID = process.env.AILK_SITE_ID;
+
+let server: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  logCalls.length = 0;
+  __resetIdempotencyStore();
+  delete process.env.AILK_SITE_ID;
+  jest.replaceProperty(configModule, "config", {
+    ...configModule.config,
+    STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+  });
+  (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue({ amountMinor: AMOUNT_TOTAL });
+  (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.user.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+  (prisma.organization.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.organization.update as jest.Mock).mockResolvedValue({});
+  server = await buildTestServer();
+});
+
+afterEach(async () => {
+  await server.close();
+  jest.restoreAllMocks();
+  if (ORIGINAL_AILK_SITE_ID === undefined) delete process.env.AILK_SITE_ID;
+  else process.env.AILK_SITE_ID = ORIGINAL_AILK_SITE_ID;
+});
+
+async function post() {
+  return server.inject({ method: "POST", url: "/v1/webhooks/stripe", payload: VALID_BODY, headers: HEADERS });
+}
+
+function foreignSiteLogs() {
+  return logCalls.filter(
+    ([obj]) => typeof obj === "object" && obj !== null && (obj as Record<string, unknown>)["outcome"] === "foreign_site",
+  );
+}
+
+function expectNoHubSideEffect() {
+  expect(mockTrack).not.toHaveBeenCalled();
+  expect(prisma.flowCheckout.findUnique).not.toHaveBeenCalled();
+  expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+  expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+  expect(prisma.user.findFirst).not.toHaveBeenCalled();
+  expect(prisma.user.findUnique).not.toHaveBeenCalled();
+  expect(prisma.user.update).not.toHaveBeenCalled();
+  expect(prisma.user.updateMany).not.toHaveBeenCalled();
+  expect(prisma.organization.findFirst).not.toHaveBeenCalled();
+  expect(prisma.organization.update).not.toHaveBeenCalled();
+}
+
+function expectHandledAsToday() {
+  expect(mockTrack).toHaveBeenCalledTimes(1);
+  expect(mockTrack).toHaveBeenCalledWith(
+    "purchase-completed",
+    expect.objectContaining({ amount: AMOUNT_TOTAL, eventType: "checkout.session.completed" }),
+  );
+  expect(prisma.flowCheckout.updateMany).toHaveBeenCalledTimes(1);
+  expect(prisma.callback.updateMany).toHaveBeenCalledTimes(1);
+  expect(prisma.user.findFirst).toHaveBeenCalledWith({
+    where: { billingProvider: "stripe", billingCustomerId: CUSTOMER_ID },
+  });
+  expect(foreignSiteLogs()).toHaveLength(0);
+}
+
+// ── Case 1 — a foreign `completed` produces no hub side effect (AC-2) ───────
+
+describe("case 1 — a completed session stamped for another site", () => {
+  it("answers 200 and runs none of the four tasks", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "samhenry" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+    expectNoHubSideEffect();
+  });
+
+  it("logs one foreign_site line carrying the stamp and the own site, and no buyer field or amount", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "samhenry" }),
+    );
+    await post();
+
+    const lines = foreignSiteLogs();
+    expect(lines).toHaveLength(1);
+    expect(lines[0]![0]).toEqual({
+      eventType: "checkout.session.completed",
+      eventIdPrefix: "evt_test",
+      outcome: "foreign_site",
+      stamp: "samhenry",
+      ownSite: "default",
+    });
+
+    const logged = JSON.stringify(logCalls);
+    expect(logged).not.toContain(EMAIL);
+    expect(logged).not.toContain(String(AMOUNT_TOTAL));
+    expect(logged).not.toContain(USER_ID);
+  });
+
+  it("logs exactly the first 64 characters of a long foreign stamp", async () => {
+    const longStamp = "s".repeat(36) + "t".repeat(64);
+    expect(longStamp).toHaveLength(100);
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: longStamp }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectNoHubSideEffect();
+    const lines = foreignSiteLogs();
+    expect(lines).toHaveLength(1);
+    expect((lines[0]![0] as Record<string, unknown>)["stamp"]).toBe(longStamp.slice(0, 64));
+  });
+});
+
+// ── Case 2 — a foreign session never reaches the Organization write ─────────
+
+describe("case 2 — a foreign session carrying metadata.organizationId", () => {
+  it("writes no Organization", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "samhenry", organizationId: ORG_ID }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectNoHubSideEffect();
+  });
+});
+
+// ── Case 3 — a foreign `expired` stamps no FlowCheckout (AC-3) ──────────────
+
+describe("case 3 — an expired session stamped for another site", () => {
+  it("answers 200 and never expires a hub FlowCheckout", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.expired", { site: "samhenry" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+    expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+    const lines = foreignSiteLogs();
+    expect(lines).toHaveLength(1);
+    expect(lines[0]![0]).toMatchObject({
+      eventType: "checkout.session.expired",
+      stamp: "samhenry",
+      ownSite: "default",
+    });
+  });
+});
+
+// ── Cases 4–7 — own and unstamped sessions are handled as today (AC-4) ──────
+
+describe("cases 4–7 — an unstamped, own-stamped or empty-stamped session is the hub's own", () => {
+  it("case 4 — an unstamped session runs every task, as today", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(sessionEvent("checkout.session.completed"));
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectHandledAsToday();
+  });
+
+  it("case 5 — a session stamped with the default alias, AILK_SITE_ID unset, runs every task", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "default" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectHandledAsToday();
+  });
+
+  it("case 6 — under AILK_SITE_ID=wksp_hub, a wksp_hub stamp is own", async () => {
+    process.env.AILK_SITE_ID = "wksp_hub";
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "wksp_hub" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectHandledAsToday();
+  });
+
+  it("case 6 — under AILK_SITE_ID=wksp_hub, a default stamp is foreign", async () => {
+    process.env.AILK_SITE_ID = "wksp_hub";
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "default" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectNoHubSideEffect();
+    const lines = foreignSiteLogs();
+    expect(lines).toHaveLength(1);
+    expect(lines[0]![0]).toMatchObject({ stamp: "default", ownSite: "wksp_hub" });
+  });
+
+  it("case 7 — an empty stamp is unstamped, and runs every task", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectHandledAsToday();
+  });
+});
+
+// ── Case 8 — the event-id dedup is unchanged ────────────────────────────────
+
+describe("case 8 — a foreign event delivered twice", () => {
+  it("is marked seen, so the redelivery takes the duplicate short-circuit", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "samhenry" }),
+    );
+    const first = await post();
+    expect(first.statusCode).toBe(200);
+    expect(foreignSiteLogs()).toHaveLength(1);
+
+    // Each delivery's lines are read on their own: the harness re-wraps the
+    // shared request logger per request, so a second request logs each line
+    // more than once.
+    logCalls.length = 0;
+    const second = await post();
+
+    expect(second.statusCode).toBe(200);
+    expect(JSON.parse(second.body)).toEqual({ received: true });
+    expect(foreignSiteLogs()).toHaveLength(0);
+    expect(logCalls.map(([, msg]) => msg)).toContain(
+      "duplicate stripe webhook event — idempotent short-circuit",
+    );
+    expectNoHubSideEffect();
+  });
+});

package/templates/apps/api/src/routes/webhooks/stripe.ts

@@ -31,6 +31,15 @@
  * Successful dispatch always 200s — including unknown event types.
  * Telemetry failures are caught, logged, and do NOT change the response.
  *
+ * Site filter (#7868):
+ *   The Stripe account is shared with spoke sites, so this endpoint receives
+ *   their Checkout sessions too. A `checkout.session.completed` or `.expired`
+ *   whose `metadata.site` is a non-empty string naming another site
+ *   (`isForeignSiteStamp`, lib/site.ts) takes no action: it logs
+ *   `outcome: "foreign_site"` and answers 200. An unstamped session is the
+ *   hub's own (roadmap D4) and is handled as before. The hub stamps its own
+ *   sessions through `siteStamp()`. See README.md § Site filter (#7868).
+ *
  * Billing upsert (customer.created / checkout.session.completed):
  *   Billing-entity routing (org-scoped billing, #3601, spec D2): a checkout
  *   carrying metadata.organizationId links the Organization (multi-tenant
@@ -83,7 +92,11 @@ import {
   LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS,
   LICENSE_UNDETERMINED_STATUS,
 } from "../../lib/require-commerce-claim.js";
-import { currentSiteId } from "../../lib/site.js";
+import {
+  currentSiteId,
+  isForeignSiteStamp,
+  SITE_STAMP_KEY,
+} from "../../lib/site.js";
 import {
   StripeWebhookSignatureError,
   toSubscriptionLifecycleStatus,
@@ -299,6 +312,14 @@ export const stripeWebhookHandler = async (
     }
     case "checkout.session.completed": {
       const session = event.data.object as CheckoutSessionObject;
+      if (isForeignSiteStamp(session.metadata)) {
+        logForeignSiteSkip(request, {
+          stamp: session.metadata?.[SITE_STAMP_KEY],
+          eventType: event.type,
+          eventIdPrefix,
+        });
+        break;
+      }
       const props = {
         amount: session.amount_total ?? undefined,
         currency: session.currency ?? undefined,
@@ -363,6 +384,14 @@ export const stripeWebhookHandler = async (
     }
     case "checkout.session.expired": {
       const session = event.data.object as CheckoutSessionObject;
+      if (isForeignSiteStamp(session.metadata)) {
+        logForeignSiteSkip(request, {
+          stamp: session.metadata?.[SITE_STAMP_KEY],
+          eventType: event.type,
+          eventIdPrefix,
+        });
+        break;
+      }
       if (!session.metadata?.["flowCheckoutId"]) {
         // Not a recommender session — the same low-noise line the default
         // arm emitted for this event before #4838 handled it.
@@ -432,6 +461,37 @@ type CheckoutSessionObject = {
   metadata?: Record<string, string> | null;
 };
 
+/**
+ * The one log line for a session another site stamped (#7868 D3). Carries the
+ * foreign stamp (first 64 characters) and this site's own alias, so a spoke
+ * event correctly skipped can be told from a hub event whose alias drifted —
+ * site labels only: it takes the stamp, never the session, so no buyer field
+ * or amount can reach it.
+ */
+function logForeignSiteSkip(
+  request: FastifyRequest,
+  {
+    stamp,
+    eventType,
+    eventIdPrefix,
+  }: {
+    stamp: string | undefined;
+    eventType: string;
+    eventIdPrefix: string;
+  },
+): void {
+  request.log.info(
+    {
+      eventType,
+      eventIdPrefix,
+      outcome: "foreign_site",
+      stamp: stamp?.slice(0, 64),
+      ownSite: currentSiteId(),
+    },
+    "checkout session stamped for another site — skipped",
+  );
+}
+
 /**
  * Minimal projected shape of a Stripe Invoice object for the dunning arms
  * (#6034 FR-1). `subscription` and `customer` are EXPANDABLE Stripe fields —

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

@@ -747,3 +747,202 @@ describe("#6730 — routeLead delivery modes", () => {
     });
   });
 });
+
+// ── #7869 — the Idempotency-Key on submit (spec D3–D5, D10 cases 9–14) ──────
+//
+// Cases 9–13 run on `inbox` delivery (DATABASE_URL set), where the key is
+// honoured; case 14 drops DATABASE_URL to prove a non-inbox delivery ignores
+// it. A keyed create that loses the race throws P2002 and is answered from a
+// re-read of the winner.
+describe("#7869 — routeLead with an idempotency key", () => {
+  const KEY = "fixture-retry-0000-0000-0001";
+  const WINNER_ID = "lead_00000000-0000-7000-8000-00000000f001";
+  const ENV_KEYS = [
+    "DATABASE_URL",
+    "NODE_ENV",
+    "AILK_INBOX_FALLBACK_DIR",
+    "LEAD_CAPTURE_FILE",
+    "AILK_LEAD_NOTIFICATION_TO",
+    "AILK_LEAD_NOTIFICATION_FROM",
+  ] as const;
+  let saved: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>>;
+  let tmpDir: string;
+
+  const p2002 = () =>
+    Object.assign(
+      new Error(
+        "Unique constraint failed on the fields: (`workspace_id`,`idempotency_key`)",
+      ),
+      { code: "P2002" },
+    );
+  const keyWhere = (workspaceId: string) => ({
+    where: { workspaceId_idempotencyKey: { workspaceId, idempotencyKey: KEY } },
+    select: { id: true, email: true, source: true, payload: true },
+  });
+  const createData = () =>
+    jest.mocked(prisma.lead.create).mock.calls[0]?.[0].data as Record<
+      string,
+      unknown
+    >;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    saved = {};
+    for (const k of ENV_KEYS) saved[k] = process.env[k];
+    for (const k of ENV_KEYS) delete process.env[k];
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "ailk-idem-test-"));
+    process.env.AILK_INBOX_FALLBACK_DIR = tmpDir;
+    process.env.DATABASE_URL = "postgres://stub";
+    process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+    (prisma.lead.create as jest.Mock).mockResolvedValue({ id: "lead_db_new" });
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue(null);
+    mockSendLeadNotification.mockResolvedValue({
+      ok: true,
+      messageId: "msg-1",
+    });
+  });
+
+  afterEach(async () => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("case 9 — a P2002 race whose winner matches answers the winner's id: no fallback, no persist_failed, no notification, no capture record", async () => {
+    // Positive control first: a keyed create with no race writes exactly one
+    // line to the capture file, so the negative assertion below is load-bearing.
+    const controlFile = path.join(tmpDir, "control.jsonl");
+    process.env.LEAD_CAPTURE_FILE = controlFile;
+    const control = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+    expect(control).toMatchObject({
+      ok: true,
+      id: "lead_db_new",
+      persisted: "db",
+    });
+    expect(
+      (await fs.readFile(controlFile, "utf8")).trim().split("\n"),
+    ).toHaveLength(1);
+    expect(createData()).toMatchObject({ idempotencyKey: KEY });
+
+    jest.clearAllMocks();
+    const raceFile = path.join(tmpDir, "race.jsonl");
+    process.env.LEAD_CAPTURE_FILE = raceFile;
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+    (prisma.lead.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null) // the pre-write lookup misses
+      .mockResolvedValueOnce({
+        id: WINNER_ID,
+        email: leadInput.email,
+        source: leadInput.source,
+        payload: { ...leadInput.payload },
+      });
+    const before = await fs.readdir(tmpDir);
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      replayed: true,
+      id: WINNER_ID,
+      persisted: "db",
+      email: { skipped: true, reason: "idempotent_replay" },
+    });
+    expect(prisma.lead.findUnique).toHaveBeenNthCalledWith(
+      2,
+      keyWhere(leadInput.siteId),
+    );
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+    await expect(fs.access(raceFile)).rejects.toThrow();
+    expect(await fs.readdir(tmpDir)).toEqual(before); // no file fallback
+  });
+
+  it("case 10 — a P2002 race whose winner carries a different email is idempotency_conflict", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+    (prisma.lead.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce({
+        id: WINNER_ID,
+        email: "someone-else@example.com",
+        source: leadInput.source,
+        payload: leadInput.payload,
+      });
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        kind: "idempotency_conflict",
+        message: "idempotency key reused",
+      },
+    });
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+  });
+
+  it("case 11 — a P2002 race whose re-read finds nothing takes the existing persist_failed path", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+
+    const result = (await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    })) as Extract<RouteLeadResult, { ok: false }>;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("persist_failed");
+    expect(prisma.lead.findUnique).toHaveBeenCalledTimes(2);
+  });
+
+  it("case 12 — a P2002 with no key passed is persist_failed, as today, with no key lookup", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+
+    const result = (await routeLead(leadInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: false }
+    >;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("persist_failed");
+    expect(prisma.lead.findUnique).not.toHaveBeenCalled();
+    expect(createData()).not.toHaveProperty("idempotencyKey");
+  });
+
+  it("case 13 — a lookup that throws still reaches the create (the existing path)", async () => {
+    (prisma.lead.findUnique as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({
+      ok: true,
+      id: "lead_db_new",
+      persisted: "db",
+    });
+  });
+
+  it("case 14 — a non-inbox delivery ignores the key: no lookup, no key on the create, the existing file path", async () => {
+    delete process.env.DATABASE_URL; // `local` delivery outside production
+    (prisma.lead.create as jest.Mock).mockRejectedValue(
+      new Error("connection refused"),
+    );
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(prisma.lead.findUnique).not.toHaveBeenCalled();
+    expect(createData()).not.toHaveProperty("idempotencyKey");
+    expect(result).toMatchObject({ ok: true, persisted: "file" });
+  });
+});