create-ailk 0.23.0 → 0.25.1

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

@@ -1,1372 +0,0 @@
-/**
- * @file lead-routing.ts
- * @description Cross-namespace lead orchestration service (ADR 0009 D3).
- *
- * Pipeline: validate → delivery guard → enrich → persist (DB with file
- * fallback) → email. Where a lead may go is `resolveLeadDelivery()`
- * (`lib/lead-delivery.ts`, #6730 D1): with no database but the email vars set,
- * the owner email IS the delivery; in production with neither, nothing is
- * accepted. A lead is reported sent only for a durable row or an email the
- * provider accepted — never for the non-durable file fallback in production.
- * This is the first implementation of ADR 0009 D3's service-layer pattern.
- * Future cross-namespace orchestrators in apps/api/src/services/ should mirror
- * this shape: type-result returns, mocked-dep tests, non-transactional secondary
- * effects, PII-safe logging.
- *
- * PII boundary: only { siteId, kind, ip, persisted, emailKind } appear in logs.
- * Never log email, phone, name, or payload values.
- *
- * TENANCY (#6203). `input.siteId` is the caller's RESOLVED workspace id —
- * `routes/leads/index.ts` resolves it server-side before calling `routeLead`
- * and never a client-supplied value (see that file's header). `Lead` gets a
- * `workspaceId` stamp of the same value, and since #6374 so do `Subscriber`
- * and `Callback` — both gained a required `workspaceId` column in the fence
- * fan-out, stamped from the same resolved id by the three `create` sites
- * below. (This line previously said those two models had no such column;
- * that stopped being true when the keystone migration landed, and the code
- * under it already contradicted it.) The one READ in this file — the
- * duplicate-subscriber lookup on the P2002 arm — is scoped by it too
- * (#6257).
- *
- * IDEMPOTENCY KEY (#7869, roadmap D5). A `submit` may carry a caller's
- * `Idempotency-Key` (`routes/leads/index.ts` reads and validates the header;
- * it travels beside the input as `routeLead`'s third argument, never inside
- * the `.strict()` input). On `inbox` delivery only, a key already stored on a
- * `Lead` of THIS workspace short-circuits the write: the same `email`,
- * `source` and `payload` is a replay (the first lead's id, nothing written,
- * no capture record, no notification); anything else is an
- * `idempotency_conflict` (nothing written). The two reads — the lookup
- * before the write and the re-read after a `P2002` race — are both keyed on
- * `(workspaceId, idempotencyKey)`, so a key can never reach another tenant's
- * row. `email`, `local` and `none` deliveries ignore the key: there is no
- * row to dedupe against. The key itself is never logged.
- *
- * PERSON (#852 D6). Before a `submit` writes its `Lead`, `findOrCreatePerson`
- * (`services/person.ts`, the only Person creator) resolves the client of
- * this workspace for the lead's email, and its id joins the create as
- * `personId`. Lead capture is a never-gate surface, so the Person step never
- * throws, never refuses the lead and never changes `routeLead`'s result: an
- * unstorable address or a failed step writes the lead with `personId: null`
- * and logs one bare line (`person-skipped` / `person-failed`, never the
- * email). The `email`, `local` and `none` deliveries never reach
- * `persistToDb`.
- *
- * CONTACT AND LINKS (#8435 D5). A `submit` may carry `options.contact` (the
- * magnet's tagged answers): `findOrCreatePerson` fills the Person's BLANK
- * contact fields from it while the Person is uncurated, and the lead's own
- * `payload` is unchanged. A `subscribe` and a `callback` with a storable email
- * (a callback's is `payload.email`) now also resolve a Person and stamp its id
- * 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, #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 — 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.
- *
- * 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 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
- * replay, a test-mode or relayed checkout, or a lead with no Person — the
- * buyer gets one outbound `member` `Interaction` on that Person
- * (`createdBy: "system:checkout"`, subject "Your purchase", no link, payload
- * or attachment) and, fired with `void`, one `sendPurchaseConfirmationEmail`.
- * Both name the offering only when its stripped key is one
- * `listPlanOfferings` lists for the workspace, else "your purchase" — never
- * the spoke-supplied `payload.offering` (SEC-8757-G) — and both bodies are
- * stripped of control and bidi characters. The email's "Open your account"
- * link is `options.accountOrigin` (the route resolves it, as for the invite
- * email) plus the hub sign-in path: a marked lead is always a registered
- * spoke's. With no origin the email goes without the link. The email is
- * capped per recipient: more than `PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY`
- * marked leads of this workspace for the address (any case) in the last 24
- * hours, this one included, skips it; and per workspace: more than
- * `PURCHASE_EMAILS_PER_SITE_PER_HOUR` marked leads in the last hour skips
- * it. The message is still written. Neither
- * step ever throws or changes the lead's result, and their one log line,
- * `{ event: "checkout-purchase", step, outcome }`, names no address or
- * offering.
- *
- * CHECKOUT CONSENT GRANT (#8778). After the same first write of a marked
- * lead with a Person, a lead whose `payload.termsAccepted` equals the current
- * `account_terms@<version>` stamp (`currentAccountTermsStamp`) — the spoke's
- * fulfilment sends the stamp of the terms the buyer ticked in Stripe's box,
- * else `null` — records the buyer's checkout `ConsentGrant` through #8765's
- * `recordCheckoutConsent`: one `account_terms` row for that Person, source
- * `checkout`, `sourceRef` the Checkout Session id (the lead's
- * `Idempotency-Key`), at most once per Person and session. A `null` or absent
- * value writes nothing (`consent_absent`), as does any other value
- * (`terms_unstamped`). A replay never reaches it, and the key is left out of
- * the replay comparison (`comparablePayload`). Never throws and never
- * changes the lead's result; its one log line,
- * `{ event: "checkout-consent", outcome, siteId }` (plus `errName` on
- * `failed`), names no address or Person.
- *
- * VISITOR LINK (#8438 D11). When the request carried a valid consent visitor
- * id (`SourceMeta.consentVisitorId`, set by the leads and flows routes from
- * `x-ailk-consent-visitor` only when it is a v4 UUID) and the submit resolved
- * a Person, `linkConsentVisitor` joins the two — source `magnet` for a
- * `flow:` source, else `api`. A link never fails a lead and is never
- * returned: `RouteLeadResult.personId` is internal, for the flow engine's
- * consent write. A subscribe or callback resolves no Person, so it links
- * nothing. The header is never echoed and never logged.
- */
-
-import { randomUUID } from "node:crypto";
-import { isDeepStrictEqual } from "node:util";
-
-import type { Prisma } from "@working-theory/database";
-import { sendLeadNotification, sendPurchaseConfirmationEmail } from "@working-theory/email";
-import { logger } from "@working-theory/observability";
-import {
-  accountInvitePath,
-  isConsentLeadSource,
-  LEAD_SITE_MARKER_KEY,
-  leadInputSchema,
-  parseLookupKey,
-  PURCHASE_EMAIL_DEFAULTS,
-  PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY,
-  stripPlainText,
-} from "@working-theory/validation";
-
-import { writeLeadFallback } from "../lib/file-fallback.js";
-import { appendLeadRecord } from "../lib/lead-capture-store.js";
-import { acceptsKind, resolveLeadDelivery } from "../lib/lead-delivery.js";
-import { prisma } from "../lib/prisma.js";
-
-import {
-  currentAccountTermsStamp,
-  linkConsentVisitor,
-  recordCheckoutConsent,
-  type RecordCheckoutConsentOutcome,
-} from "./consent.js";
-import { enrichLead } from "./enrichment-shim.js";
-import {
-  checkoutPlanKey,
-  findOrCreatePerson,
-  normalizeCapturedContact,
-  normalizeTelephone,
-} from "./person.js";
-import type { LeadContact, PersonContact } from "./person.js";
-import { listPlanOfferings } from "./plan-offerings.js";
-import { requestConfirmSupersedesNotification } from "./request-confirm.js";
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-export type LeadKind = "submit" | "subscribe" | "callback";
-
-export type RouteLeadInput =
-  | {
-      kind: "submit";
-      siteId: string;
-      source: string;
-      email: string;
-      payload: Record<string, unknown>;
-    }
-  | { kind: "subscribe"; siteId: string; email: string; source: string }
-  | {
-      kind: "callback";
-      siteId: string;
-      name: string;
-      phone: string;
-      preferredTime?: string;
-      payload: Record<string, unknown>;
-    };
-
-export type SourceMeta = {
-  ip: string;
-  userAgent: string | undefined;
-  receivedAt: string; // ISO
-  /**
-   * The lead came from a registered spoke of a hub (#7532 D4). Absent reads as
-   * `false`. Never persisted — `captureRecordFor` copies fields by name.
-   */
-  viaSpoke?: boolean;
-  /**
-   * The request carried `x-ailk-relayed`, i.e. it was forwarded for a
-   * visitor by a spoke's same-origin relay (#8185 D3). Absent reads as
-   * `false`. Never persisted. It can only REMOVE the spoke-checkout marker,
-   * never grant it.
-   */
-  relayed?: boolean;
-  /**
-   * The cookie banner's visitor id from the request's `x-ailk-consent-visitor`
-   * header, set only when it is a v4 UUID (#8438 D11). Used to link the
-   * visitor to the lead's Person; never persisted, echoed or logged.
-   */
-  consentVisitorId?: string;
-};
-
-/** Where the lead landed: a database row, the local file fallback, or the owner's inbox by email (#6730). */
-export type Persisted = "db" | "file" | "email";
-
-/** Per-call options carried beside the input (#7869 D2). */
-export type RouteLeadOptions = {
-  /** The caller's validated `Idempotency-Key`; honoured for `submit` only. */
-  idempotencyKey?: string;
-  /**
-   * The contact the capture offers (#8435 D5) — the magnet's tagged answers —
-   * honoured for `submit` only and never persisted as such: the lead's
-   * `payload` stays the raw answers.
-   */
-  contact?: LeadContact;
-  /**
-   * Where the buyer's account lives (#8757 D14): the origin the purchase
-   * email's "Open your account" link starts sign-in on, resolved by the route
-   * 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 =
-  | {
-      ok: true;
-      /**
-       * The answer to a repeat of an already-stored idempotency key (#7869
-       * D4): nothing was written. Never on the wire — the route builds its
-       * 201 body from `id`, `persisted` and `email` only.
-       */
-      replayed?: true;
-      id: string;
-      /**
-       * The Person a `submit` resolved (#8438 D11), `null`/absent when none.
-       * Internal only — the route builds its 201 body from `id`, `persisted`
-       * and `email`, so this never reaches a wire.
-       */
-      personId?: string | null;
-      persisted: Persisted;
-      email:
-        | { ok: true; messageId: string }
-        | { ok: false; error: string }
-        | { skipped: true; reason: string };
-    }
-  | {
-      ok: false;
-      error: {
-        kind:
-          | "invalid_input"
-          | "persist_failed"
-          | "config_missing"
-          | "delivery_failed"
-          | "idempotency_conflict";
-        message: string;
-      };
-    };
-
-// ─── Validation ───────────────────────────────────────────────────────────────
-
-function validateInput(
-  input: RouteLeadInput,
-): { ok: true } | { ok: false; message: string } {
-  const result = leadInputSchema.safeParse(input);
-  if (!result.success) {
-    return {
-      ok: false,
-      message: result.error.issues[0]?.message ?? "invalid input",
-    };
-  }
-  return { ok: true };
-}
-
-// ─── Idempotency key (#7869) ─────────────────────────────────────────────────
-
-type SubmitInput = Extract<RouteLeadInput, { kind: "submit" }>;
-type KeyedRow = { id: string; email: string; source: string; payload: unknown };
-/** What a stored key means for this request (#7869 D4). */
-type KeyedOutcome = { kind: "replay"; id: string } | { kind: "conflict" };
-
-/**
- * The one read of `Lead.idempotencyKey` (#7869 D3, reused by D5's re-read).
- * The compound unique carries `workspaceId`, so the lookup can only ever
- * reach this workspace's rows.
- */
-async function findLeadByKey(
-  workspaceId: string,
-  idempotencyKey: string,
-): Promise<KeyedRow | null> {
-  return (await prisma.lead.findUnique({
-    where: { workspaceId_idempotencyKey: { workspaceId, idempotencyKey } },
-    select: { id: true, email: true, source: true, payload: true },
-  })) as KeyedRow | null;
-}
-
-/**
- * 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
- * stored body lacks, and a conflict there would fail every retry. A replay
- * writes no grant, so the key decides nothing on one.
- */
-function comparablePayload(payload: unknown, source: string): unknown {
-  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
-    return payload;
-  }
-  const record = payload as Record<string, unknown>;
-  if (isConsentLeadSource(source)) {
-    const { consent: _serverWritten, ...rest } = record;
-    return rest;
-  }
-  if (record["page"] === "checkout") {
-    const { termsAccepted: _addedByUpdate, ...rest } = record;
-    return rest;
-  }
-  return payload;
-}
-
-/**
- * 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 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 &&
-    row.source === input.source &&
-    isDeepStrictEqual(
-      comparablePayload(row.payload, row.source),
-      comparablePayload(input.payload, input.source),
-    )
-    ? { kind: "replay", id: row.id }
-    : { kind: "conflict" };
-}
-
-function keyedResult(outcome: KeyedOutcome): RouteLeadResult {
-  if (outcome.kind === "conflict") {
-    return {
-      ok: false,
-      error: { kind: "idempotency_conflict", message: "idempotency key reused" },
-    };
-  }
-  return {
-    ok: true,
-    replayed: true,
-    id: outcome.id,
-    persisted: "db",
-    email: { skipped: true, reason: "idempotent_replay" },
-  };
-}
-
-/** The structural `P2002` test `recommender-capture.ts` already uses. */
-function isUniqueViolation(err: unknown): boolean {
-  return (
-    typeof err === "object" && err !== null && (err as { code?: unknown }).code === "P2002"
-  );
-}
-
-// ─── DB persist ───────────────────────────────────────────────────────────────
-
-type DbRow = { id: string };
-type PersistResult =
-  | {
-      ok: true;
-      id: string;
-      source: "db";
-      skipEmail: boolean;
-      skipReason?: string;
-      /** The Person a `submit` resolved (#8438 D11). */
-      personId?: string | null;
-    }
-  // #7869 D5 — a keyed create lost a race to a row it now answers with.
-  | { ok: "keyed"; outcome: KeyedOutcome }
-  | { ok: false; error: string };
-
-/**
- * The Person of a submitted lead (#852 D6) — its id, or `null` when the email
- * is not a storable address or the step failed. Never throws: a Person step
- * must never refuse, lose or delay a lead. Logs the outcome kind and the
- * site only.
- */
-async function resolveCapturePersonId(
-  siteId: string,
-  capture: { email: string; name?: string | null; contact?: Partial<PersonContact> },
-): Promise<string | null> {
-  try {
-    const person = await findOrCreatePerson(siteId, capture);
-    if (person.ok) return person.value.personId;
-    if (person.error.kind === "invalid_email") {
-      logger.warn(
-        { event: "person-skipped", kind: person.error.kind, siteId },
-        "lead person skipped",
-      );
-    } else {
-      logger.error({ event: "person-failed", siteId }, "lead person failed");
-    }
-  } catch {
-    logger.error({ event: "person-failed", siteId }, "lead person failed");
-  }
-  return null;
-}
-
-async function resolveLeadPersonId(input: SubmitInput, contact?: LeadContact): Promise<string | null> {
-  const payloadName = typeof input.payload["name"] === "string" ? input.payload["name"] : null;
-  if (contact === undefined) {
-    return resolveCapturePersonId(input.siteId, { email: input.email, name: payloadName });
-  }
-  // #8435 D5 — an explicit contact name wins over the payload's.
-  const name = typeof contact.name === "string" ? contact.name : payloadName;
-  return resolveCapturePersonId(input.siteId, {
-    email: input.email,
-    name,
-    contact: normalizeCapturedContact(contact),
-  });
-}
-
-/** 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}$/;
-
-/**
- * The raw offering of a lead that qualifies for the checkout plan rule, or
- * `null` when it does not (#7877 D10). Reads the lead's own fields only.
- */
-function checkoutPlanCandidate(
-  input: SubmitInput,
-  idempotencyKey: string | undefined,
-  viaSpoke: boolean,
-): CheckoutCandidate | null {
-  if (viaSpoke !== true) return null;
-  if (idempotencyKey === undefined || !LIVE_CHECKOUT_SESSION_KEY.test(idempotencyKey)) {
-    return null;
-  }
-  const { payload } = input;
-  const amountTotal = payload["amountTotal"];
-  if (
-    amountTotal !== undefined &&
-    amountTotal !== null &&
-    !(typeof amountTotal === "number" && Number.isInteger(amountTotal) && amountTotal > 0)
-  ) {
-    return null;
-  }
-  if (input.source !== "web" || payload["page"] !== "checkout") return null;
-  const offering = payload["offering"];
-  const site = payload[LEAD_SITE_MARKER_KEY];
-  if (typeof offering !== "string" || typeof site !== "string" || !SITE_SLUG.test(site)) {
-    return null;
-  }
-  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: CheckoutCandidate): string {
-  const prefix = `${candidate.site}_`;
-  return candidate.offering.startsWith(prefix)
-    ? candidate.offering.slice(prefix.length)
-    : candidate.offering;
-}
-
-/**
- * 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.
- */
-function applyCheckoutPlan(
-  input: SubmitInput,
-  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) ────────────────────────────
-
-const DAY_MS = 24 * 60 * 60 * 1000;
-const HOUR_MS = 60 * 60 * 1000;
-/**
- * A workspace's purchase emails per hour, whatever the address (SEC review of
- * #8770, M1): a marked lead's inputs are all the spoke's own, so the
- * per-recipient cap alone would let a spoke key mail any number of distinct
- * addresses. The invite email's per-site cap
- * (`INVITE_EMAILS_PER_SITE_PER_HOUR`) has the same value.
- */
-const PURCHASE_EMAILS_PER_SITE_PER_HOUR = 50;
-const GENERIC_PURCHASE_BODY = "Thanks for your purchase.";
-/** How long the lead write waits on the offering's name before it says "your purchase". */
-const OFFERING_NAME_BUDGET_MS = 1500;
-/**
- * Stripe's special-case currencies, whose minor units differ from the ISO
- * decimals `Intl` formats with: the amount is left out rather than misstated.
- */
-const AMOUNT_UNSTATED_CURRENCIES = new Set(["HUF", "ISK", "TWD", "UGX"]);
-
-/**
- * The purchase email's sender: every completion email's rule
- * (`AILK_DELIVERABLE_EMAIL_FROM`, else `AILK_LEAD_NOTIFICATION_FROM`; `||`, so
- * "" names none), the same as `magnet-completion.ts`'s `inviteSenderAddress`,
- * kept here so the lead path does not load that module's graph.
- */
-function purchaseSenderAddress(): string | undefined {
-  return (
-    process.env.AILK_DELIVERABLE_EMAIL_FROM ||
-    process.env.AILK_LEAD_NOTIFICATION_FROM ||
-    undefined
-  );
-}
-
-type PurchaseStep = "message" | "email";
-
-function logPurchase(siteId: string, step: PurchaseStep, outcome: string): void {
-  const line = { event: "checkout-purchase", step, outcome, siteId };
-  if (outcome === "failed") logger.error(line, "checkout purchase step failed");
-  else logger.info(line, "checkout purchase step");
-}
-
-/**
- * The offering's listed name, or `null` when its stripped key is not listed,
- * the read fails, or it outlasts `OFFERING_NAME_BUDGET_MS`.
- */
-async function listedOfferingName(siteId: string, offering: string): Promise<string | null> {
-  let timer: NodeJS.Timeout | undefined;
-  const budget = new Promise<null>((resolve) => {
-    timer = setTimeout(() => resolve(null), OFFERING_NAME_BUDGET_MS);
-  });
-  try {
-    const listed = await Promise.race([listPlanOfferings(siteId), budget]);
-    if (!Array.isArray(listed)) return null;
-    const name = listed.find((item) => item.key === offering)?.name;
-    const clean = name === undefined ? "" : stripPlainText(name).trim();
-    return clean === "" ? null : clean;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/** `amountTotal` (minor units) in `currency`, formatted, or `null` when either is unusable. */
-function formattedAmount(amountTotal: unknown, currency: unknown): string | null {
-  if (typeof amountTotal !== "number" || !Number.isInteger(amountTotal) || amountTotal <= 0) {
-    return null;
-  }
-  if (typeof currency !== "string" || !/^[A-Za-z]{3}$/.test(currency)) return null;
-  const code = currency.toUpperCase();
-  if (AMOUNT_UNSTATED_CURRENCIES.has(code)) return null;
-  try {
-    const format = new Intl.NumberFormat("en", { style: "currency", currency: code });
-    const digits = format.resolvedOptions().maximumFractionDigits ?? 2;
-    return format.format(amountTotal / 10 ** digits);
-  } catch {
-    return null;
-  }
-}
-
-/** The one plain-text body the email and the message share. */
-function purchaseBody(name: string | null, amount: string | null): string {
-  const sentence =
-    name === null ? GENERIC_PURCHASE_BODY : PURCHASE_EMAIL_DEFAULTS.body.replaceAll("{offering}", name);
-  return stripPlainText(amount === null ? sentence : `${sentence} Total: ${amount}.`);
-}
-
-/** The purchase email, capped per recipient (D14). Never throws; fired with `void`. */
-async function sendPurchaseEmail(
-  input: SubmitInput,
-  body: string,
-  accountOrigin: string | undefined,
-): Promise<void> {
-  let outcome: string;
-  try {
-    const recent = await prisma.lead.count({
-      where: {
-        workspaceId: input.siteId,
-        spokeCheckout: true,
-        email: { equals: input.email, mode: "insensitive" },
-        createdAt: { gte: new Date(Date.now() - DAY_MS) },
-      },
-    });
-    const siteHour = await prisma.lead.count({
-      where: {
-        workspaceId: input.siteId,
-        spokeCheckout: true,
-        createdAt: { gte: new Date(Date.now() - HOUR_MS) },
-      },
-    });
-    const fromAddress = purchaseSenderAddress();
-    if (recent > PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY) {
-      outcome = "capped_recipient";
-    } else if (siteHour > PURCHASE_EMAILS_PER_SITE_PER_HOUR) {
-      outcome = "capped_site";
-    } else if (!fromAddress) {
-      outcome = "sender_unconfigured";
-    } else {
-      let accountLink: string | undefined;
-      if (accountOrigin !== undefined) {
-        try {
-          accountLink = accountOrigin + accountInvitePath("hub", input.email);
-        } catch {
-          // An address the sign-in hint refuses: the email goes without the link.
-        }
-      }
-      const result = await sendPurchaseConfirmationEmail({
-        to: input.email,
-        fromAddress,
-        subject: PURCHASE_EMAIL_DEFAULTS.subject,
-        body,
-        cta: PURCHASE_EMAIL_DEFAULTS.cta,
-        ...(accountLink !== undefined && { accountLink }),
-      });
-      outcome = result.ok ? "sent" : "failed";
-    }
-  } catch {
-    outcome = "failed";
-  }
-  logPurchase(input.siteId, "email", outcome);
-}
-
-/**
- * The buyer's Inbox message and purchase email for a marked checkout lead
- * just written (D14). Never throws and never changes the lead's result.
- */
-async function recordPurchase(
-  input: SubmitInput,
-  personId: string,
-  candidate: CheckoutCandidate,
-  accountOrigin: string | undefined,
-): Promise<void> {
-  // One guard around the whole step: it runs inside `routeLead`'s persist
-  // `try`, where a throw after the row is written would be read as a failed
-  // write and the lead captured a second time.
-  let body: string;
-  try {
-    const name = await listedOfferingName(input.siteId, stripSitePrefix(candidate));
-    body = purchaseBody(name, formattedAmount(input.payload["amountTotal"], input.payload["currency"]));
-  } catch {
-    logPurchase(input.siteId, "message", "failed");
-    return;
-  }
-  try {
-    await prisma.interaction.create({
-      data: {
-        workspaceId: input.siteId,
-        personId,
-        channel: "member",
-        direction: "outbound",
-        subject: PURCHASE_EMAIL_DEFAULTS.subject,
-        body,
-        createdBy: "system:checkout",
-      },
-    });
-    logPurchase(input.siteId, "message", "written");
-  } catch {
-    logPurchase(input.siteId, "message", "failed");
-  }
-  void sendPurchaseEmail(input, body, accountOrigin);
-}
-
-/**
- * The buyer's checkout consent grant for a marked checkout lead just written
- * (#8778). Never throws and never changes the lead's result.
- */
-async function recordSpokeCheckoutConsent(
-  input: SubmitInput,
-  personId: string,
-  sessionId: string,
-): Promise<void> {
-  const accepted = input.payload["termsAccepted"];
-  let outcome:
-    | RecordCheckoutConsentOutcome
-    | "consent_absent"
-    | "terms_unstamped"
-    | "failed";
-  let errName: string | undefined;
-  try {
-    const expected = currentAccountTermsStamp();
-    if (accepted === undefined || accepted === null) {
-      outcome = "consent_absent";
-    } else if (expected === null || accepted !== expected.stamp) {
-      outcome = "terms_unstamped";
-    } else {
-      outcome = await recordCheckoutConsent({
-        workspaceId: input.siteId,
-        personId,
-        sessionId,
-        policyVersion: expected.policyVersion,
-      });
-    }
-  } catch (err) {
-    // The error's class only (a Prisma error's message can carry values).
-    outcome = "failed";
-    errName = err instanceof Error ? err.name : "UnknownError";
-  }
-  const line = {
-    event: "checkout-consent",
-    outcome,
-    siteId: input.siteId,
-    ...(errName !== undefined && { errName }),
-  };
-  if (outcome === "failed") logger.error(line, "checkout terms grant failed");
-  else logger.info(line, "checkout terms grant");
-}
-
-async function persistToDb(
-  input: RouteLeadInput,
-  idempotencyKey?: string,
-  viaSpoke = false,
-  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). #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 {
-      row = (await prisma.lead.create({
-        data: {
-          siteId: input.siteId,
-          // #6203/#6254 — the isolation key, equal to `siteId` by
-          // construction. `input.siteId` is the RESOLVED workspace id at
-          // EVERY `routeLead(kind: "submit")` caller now — the primary route
-          // (`routes/leads/index.ts`, never reads it from the body — see that
-          // file's header) and the three service-layer callers
-          // (`flow-engine.ts`'s `completeSubmission`,
-          // `recommender-capture.ts`'s `captureRecommenderChoice`,
-          // `project-listings.ts`'s `submitProjectListingDraft`) all resolve
-          // the site alias before calling in (#6254 AC-6/AC-10). `workspaceId`
-          // is NOT NULL as of
-          // database/migrations/20260922120000_tenancy_fence, so this can no
-          // longer stamp `null` for an unresolved alias the way it once did
-          // (spec D2's old rule) — a caller that somehow still passed one
-          // would instead hit the pre-existing `<table>_workspace_id_format`
-          // CHECK loudly, via the AC-11 re-raise below, rather than landing a
-          // silently-unfenced row.
-          workspaceId: input.siteId,
-          source: input.source,
-          email: input.email,
-          payload: input.payload as Prisma.InputJsonValue,
-          // #852 D6 — the Person `resolveLeadPersonId` found or created.
-          personId,
-          ...(idempotencyKey !== undefined && { idempotencyKey }),
-          // #8185 D4 — only a marked create names the column.
-          ...(spokeCheckout && { spokeCheckout: true }),
-        },
-        select: { id: true },
-      })) as DbRow;
-    } catch (err) {
-      // #7869 D5 — two keyed requests both missed the lookup and both
-      // created; the unique index refused the second. Answer with the
-      // winner. Anything else — no key, another error, a winner that cannot
-      // be read back — is rethrown untouched, so `routeLead`'s existing
-      // constraint and outage handling decide it exactly as before.
-      if (idempotencyKey === undefined || !isUniqueViolation(err)) throw err;
-      const winner = await findLeadByKey(input.siteId, idempotencyKey).catch(() => null);
-      if (!winner) throw err;
-      return { ok: "keyed", outcome: classifyKeyedRow(winner, input) };
-    }
-    // #7877 D10 — only after THIS request's own write, so a replay holds nothing.
-    if (candidate !== null && personId !== null) {
-      // #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;
-        // #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);
-        }
-      }
-    }
-    return { ok: true, id: row.id, source: "db", skipEmail: false, personId };
-  }
-
-  if (input.kind === "subscribe") {
-    // #8435 D5 — the subscriber's Person; `null` when the step skips or fails.
-    const personId = await resolveCapturePersonId(input.siteId, { email: input.email });
-    try {
-      const row = (await prisma.subscriber.create({
-        data: {
-          siteId: input.siteId,
-          // #6374 — the isolation key, equal to `siteId` by construction,
-          // exactly as `lead.create` above stamps it. `input.siteId` is the
-          // RESOLVED workspace id at every `routeLead` caller (see the
-          // `submit` branch's own note); a caller that somehow passed a raw
-          // alias would hit `subscribers_workspace_id_format` loudly rather
-          // than landing a silently-unfenced row. Never from a request body.
-          workspaceId: input.siteId,
-          email: input.email,
-          source: input.source,
-          personId,
-        },
-        select: { id: true },
-      })) as DbRow;
-      return { ok: true, id: row.id, source: "db", skipEmail: false };
-    } catch (err) {
-      // Handle unique constraint violation (duplicate subscriber)
-      if (
-        err != null &&
-        typeof err === "object" &&
-        "code" in err &&
-        (err as { code: string }).code === "P2002"
-      ) {
-        // #6257 — the duplicate lookup is scoped by the same resolved
-        // workspace id the `create` above stamps (`input.siteId` is the
-        // RESOLVED id at every caller — see the `submit` branch's note), so a
-        // P2002 on another tenant's row can never resolve to its id.
-        const existing = (await prisma.subscriber.findUnique({
-          where: {
-            siteId_email: { siteId: input.siteId, email: input.email },
-            workspaceId: input.siteId,
-          },
-          select: { id: true },
-        })) as DbRow | null;
-        const existingId = existing?.id ?? "duplicate-no-id";
-        return {
-          ok: true,
-          id: existingId,
-          source: "db",
-          skipEmail: true,
-          skipReason: "duplicate",
-        };
-      }
-      throw err; // re-throw non-P2002 errors to trigger fallback
-    }
-  }
-
-  // kind === "callback"
-  // #8435 D5 — a callback with a string `payload.email` resolves a Person; one
-  // without makes no call and writes no `personId`.
-  const callbackEmail = input.payload["email"];
-  const telephone = normalizeTelephone(input.phone);
-  const callbackPersonId =
-    typeof callbackEmail === "string"
-      ? await resolveCapturePersonId(input.siteId, {
-          email: callbackEmail,
-          name: input.name,
-          contact: telephone === null ? {} : { telephone },
-        })
-      : undefined;
-  const row = (await prisma.callback.create({
-    data: {
-      siteId: input.siteId,
-      // #6374 — the isolation key, equal to `siteId` by construction; same
-      // resolution guarantee and same loud-failure posture as the two
-      // branches above. Never from a request body (AC-6).
-      workspaceId: input.siteId,
-      name: input.name,
-      phone: input.phone,
-      ...(input.preferredTime !== undefined && {
-        preferredTime: input.preferredTime,
-      }),
-      payload: input.payload as Prisma.InputJsonValue,
-      ...(callbackPersonId !== undefined && { personId: callbackPersonId }),
-    },
-    select: { id: true },
-  })) as DbRow;
-  return { ok: true, id: row.id, source: "db", skipEmail: false };
-}
-
-// ─── Constraint-violation detection (#6254 AC-11) ──────────────────────────────
-
-/**
- * SQLSTATE class 23 — "integrity constraint violation" — covers a NOT NULL
- * (23502), a CHECK (23514), a unique (23505) or a foreign-key (23503)
- * violation. Two of Prisma's own mapped codes correspond to a class-23
- * violation on a `.create()` call: P2002 (unique) and P2011 (null
- * constraint) — both `PrismaClientKnownRequestError`s Prisma classifies
- * from its OWN schema knowledge. The new `<table>_workspace_site_agree`
- * CHECK (database/migrations/20260922120000_tenancy_fence) has no such
- * schema-level representation — Prisma cannot classify a raw CHECK it does
- * not know about, so the raw Postgres SQLSTATE is read defensively from
- * wherever the error actually carries it: `error.meta.code` (some engine/
- * adapter combinations thread it through there) or the error message text
- * (every Postgres client library's message includes the SQLSTATE and/or the
- * words "constraint"/"null value" verbatim).
- */
-// P2000 (value too long) is deliberately excluded — a data-length validation
-// error, not a SQLSTATE class-23 integrity-constraint violation (security
-// review finding, PR #6360): it doesn't correspond to 23502/23503/23505/
-// 23514, so treating it as one would take this path for a case AC-11 does
-// not target.
-const PRISMA_CLASS_23_CODES = new Set(["P2002", "P2003", "P2004", "P2011"]);
-
-function isConstraintViolation(error: unknown): boolean {
-  if (error == null || typeof error !== "object") return false;
-
-  const code = (error as { code?: unknown }).code;
-  if (typeof code === "string" && PRISMA_CLASS_23_CODES.has(code)) return true;
-
-  const metaCode = (error as { meta?: { code?: unknown } }).meta?.code;
-  if (typeof metaCode === "string" && /^23\d{3}$/.test(metaCode)) return true;
-
-  const message = (error as { message?: unknown }).message;
-  if (typeof message === "string") {
-    // Labeled SQLSTATE only — "code: '23514'", "(SQLSTATE 23502)", etc. A
-    // bare `\b23\d{3}\b` anywhere in the message (security review finding,
-    // PR #6360) would also match a coincidental 5-digit number in a genuine
-    // outage's own text (a port, a byte count, a timeout in ms), stealing
-    // that case away from the file fallback it should still take.
-    if (/\b(?:sqlstate|code)[:\s]*['"]?23\d{3}['"]?/i.test(message)) return true;
-    if (/violates (check|not-null|unique|foreign key) constraint/i.test(message)) {
-      return true;
-    }
-    if (/null value in column/i.test(message)) return true;
-  }
-
-  return false;
-}
-
-// ─── Email ────────────────────────────────────────────────────────────────────
-
-type EmailResult =
-  | { ok: true; messageId: string }
-  | { ok: false; error: string }
-  | { skipped: true; reason: string };
-
-async function sendEmail(
-  input: RouteLeadInput,
-  id: string,
-  persisted: Persisted,
-  viaSpoke = false,
-): Promise<EmailResult> {
-  // Request-and-confirm SUPERSEDES this notification for a callback (#5970
-  // D6). AC-1 requires the tenant to receive exactly one email, and the
-  // confirm message carries strictly more than this one does — the same
-  // request details, plus the link that confirms a time and a price. Sending
-  // both would be two; sending this one and not that one would lose the
-  // feature. `submit` and `subscribe` are untouched.
-  //
-  // The predicate lives in request-confirm.ts and is read by both sides, so
-  // the two cannot both fire. It does NOT by itself rule out zero — see that
-  // function's header for what the coupling does and does not guarantee, and
-  // for the `persisted` term below, which is what closed the one zero case
-  // that was reachable in production. With the feature unconfigured — the
-  // default, and what every existing leads suite runs under — this is false
-  // and every byte below is reached as before.
-  // `persisted === "db"` is load-bearing, not decoration (#5970 security
-  // review round 3, M1). The confirm message can only supersede this one if it
-  // is actually going to be sent, and it can only be sent against a ROW: the
-  // credential is minted by an `updateMany` on `callbacks`. On the FILE
-  // FALLBACK path — a DB outage, an unset DATABASE_URL, an exhausted pool —
-  // there is no row, so suppressing here would have produced ZERO operator
-  // emails for every callback captured during the outage, on the one surface
-  // whose whole purpose is that an outage must not lose a lead.
-  //
-  // `!viaSpoke` (#7532 D4, SEC-7532-2): request-and-confirm mints a Payment
-  // Link on the deployment's ONE Stripe account and mails the deployment's ONE
-  // address, so a spoke's callback never takes it — the route does not send
-  // the confirm link for a spoke, and this keeps the generic notification.
-  if (
-    input.kind === "callback" &&
-    !viaSpoke &&
-    persisted === "db" &&
-    requestConfirmSupersedesNotification()
-  ) {
-    return { skipped: true, reason: "request_confirm" };
-  }
-
-  const to = process.env.AILK_LEAD_NOTIFICATION_TO;
-  const from = process.env.AILK_LEAD_NOTIFICATION_FROM;
-
-  if (!to || !from) {
-    return { skipped: true, reason: "env_unset" };
-  }
-
-  const leadForEmail = {
-    id,
-    siteId: input.siteId,
-    source: input.kind === "callback" ? "callback" : input.source,
-    email: input.kind === "callback" ? "" : input.email,
-    // A callback's contact details are top-level fields, not payload keys
-    // (#6730): with no database the email is the only record of the
-    // request, so it must carry the name and number to call back.
-    payload:
-      input.kind === "subscribe"
-        ? {}
-        : input.kind === "callback"
-          ? {
-              ...input.payload,
-              name: input.name,
-              phone: input.phone,
-              ...(input.preferredTime !== undefined && {
-                preferredTime: input.preferredTime,
-              }),
-            }
-          : input.payload,
-    createdAt: new Date().toISOString(),
-  };
-
-  const emailResult = await sendLeadNotification({
-    lead: leadForEmail,
-    recipientEmail: to,
-    fromAddress: from,
-    // A callback has no visitor address to reply to; an empty Reply-To is
-    // not a valid header, so reply to the owner instead.
-    ...(input.kind === "callback" && { replyToOverride: to }),
-  });
-
-  if (emailResult.ok) {
-    return { ok: true, messageId: emailResult.messageId };
-  }
-
-  const { kind, message } = emailResult.error;
-  if (kind === "config_missing") {
-    return { skipped: true, reason: "resend_key_unset" };
-  }
-  return { ok: false, error: `${kind}: ${message}` };
-}
-
-// ─── Email delivery (#6730 D2) ────────────────────────────────────────────────
-
-type EmailDelivery =
-  | { ok: true; id: string; email: { ok: true; messageId: string } }
-  | { ok: false; message: string };
-
-/**
- * Deliver a lead as the owner email alone — success only when the provider
- * accepted it. The id matches the file-fallback id format
- * (`/^[a-z0-9_-]{8,64}$/i`).
- */
-async function deliverByEmail(input: RouteLeadInput): Promise<EmailDelivery> {
-  const id = `email-${Date.now()}-${randomUUID().slice(0, 8)}`;
-  const result = await sendEmail(input, id, "email");
-  if ("ok" in result && result.ok) return { ok: true, id, email: result };
-  return {
-    ok: false,
-    message: "error" in result ? result.error : `email skipped: ${result.reason}`,
-  };
-}
-
-// ─── Lead-capture record ─────────────────────────────────────────────────────
-
-function captureRecordFor(input: RouteLeadInput, id: string, sourceMeta: SourceMeta) {
-  return {
-    id,
-    createdAt: sourceMeta.receivedAt,
-    source: input.kind === "callback" ? "callback" : input.source,
-    data:
-      input.kind === "callback"
-        ? { name: input.name, phone: input.phone, ...(input.payload ?? {}) }
-        : input.kind === "subscribe"
-          ? { email: input.email }
-          : { email: input.email, ...(input.payload ?? {}) },
-    metadata: {
-      ip: sourceMeta.ip,
-      userAgent: sourceMeta.userAgent,
-    },
-  };
-}
-
-// ─── Main export ──────────────────────────────────────────────────────────────
-
-export async function routeLead(
-  input: RouteLeadInput,
-  sourceMeta: SourceMeta,
-  options: RouteLeadOptions = {},
-): Promise<RouteLeadResult> {
-  // 1. Validate
-  const validation = validateInput(input);
-  if (!validation.ok) {
-    return {
-      ok: false,
-      error: { kind: "invalid_input", message: validation.message },
-    };
-  }
-
-  // 2. Guard: where can this lead go (#6730 D1)? A kind the configured
-  // delivery cannot take — anything in production with neither a database
-  // nor the email vars, a newsletter signup with no database — is refused
-  // before any write, so no visitor is told a message was sent when it
-  // reached nobody.
-  const delivery = resolveLeadDelivery();
-  if (!acceptsKind(delivery, input.kind)) {
-    return {
-      ok: false,
-      error: {
-        kind: "config_missing",
-        message: "Lead capture is not configured.",
-      },
-    };
-  }
-
-  // 2a. Idempotency key (#7869 D3/D7) — submit, a key, and a database to
-  // dedupe against. A stored key answers before any enrichment or write. A
-  // failed read is not an answer: the create below meets the same database
-  // and takes the existing outage path.
-  const idempotencyKey =
-    input.kind === "submit" && delivery === "inbox" ? options.idempotencyKey : undefined;
-  if (idempotencyKey !== undefined && input.kind === "submit") {
-    const stored = await findLeadByKey(input.siteId, idempotencyKey).catch(() => null);
-    if (stored) return keyedResult(classifyKeyedRow(stored, input));
-  }
-
-  // 3. Enrich (reserved for Phase 3 — today returns lead unchanged).
-  // Cast via unknown: enrichLead accepts CreateLead (B3 shim type) but the
-  // pass-through contract means RouteLeadInput is safe here until Phase 3 wires
-  // the real enrichment call with proper type alignment.
-  await enrichLead(input as unknown as Parameters<typeof enrichLead>[0]);
-
-  // Email delivery — no database: the owner email is the delivery, so skip
-  // the DB and the (non-durable) file fallback entirely.
-  if (delivery === "email") {
-    const emailed = await deliverByEmail(input);
-    if (!emailed.ok) {
-      return {
-        ok: false,
-        error: { kind: "delivery_failed", message: emailed.message },
-      };
-    }
-    await appendLeadRecord(captureRecordFor(input, emailed.id, sourceMeta));
-    return {
-      ok: true,
-      id: emailed.id,
-      persisted: "email",
-      email: emailed.email,
-    };
-  }
-
-  // 4. Persist primary (DB), fallback to file on error
-  let id: string;
-  let persisted: Persisted;
-  let skipEmail = false;
-  let skipReason: string | undefined;
-  let personId: string | null = null;
-
-  try {
-    const dbResult = await persistToDb(
-      input,
-      idempotencyKey,
-      sourceMeta.viaSpoke === true,
-      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.
-    if (dbResult.ok === "keyed") return keyedResult(dbResult.outcome);
-    if (!dbResult.ok) {
-      // persistToDb returned ok:false — defensive guard; current impl doesn't reach this
-      return {
-        ok: false,
-        error: { kind: "persist_failed", message: dbResult.error },
-      };
-    }
-    id = dbResult.id;
-    persisted = "db";
-    skipEmail = dbResult.skipEmail;
-    skipReason = dbResult.skipReason;
-    personId = dbResult.personId ?? null;
-    // #8438 D11 — only after THIS request's own write (a keyed replay
-    // returned above), and only when a Person was resolved.
-    if (sourceMeta.consentVisitorId !== undefined && personId !== null) {
-      await linkConsentVisitor({
-        workspaceId: input.siteId,
-        visitorId: sourceMeta.consentVisitorId,
-        personId,
-        source:
-          input.kind === "submit" && input.source.startsWith("flow:")
-            ? "magnet"
-            : "api",
-      });
-    }
-  } catch (dbErr) {
-    // #6254 AC-11 (spec D6, SEC-02) — a constraint violation is OUR OWN
-    // derivation producing a row Postgres itself refuses (an unresolved
-    // workspaceId hitting NOT NULL, or a site<->workspace disagreement
-    // hitting the new equality CHECK) — a bug to surface, never an outage
-    // to degrade through. Falling back here would return a silent 201 while
-    // the Lead never lands in Postgres, invisible to the Inbox forever —
-    // the exact silent data loss AC-7 exists to close, merely relocated
-    // onto this never-gate surface.
-    //
-    // A DELIBERATE error response, not a bare re-raise (spec § 7's
-    // api-versioning waiver is conditioned on exactly this: "a documented
-    // error body, never a bare re-raise surfacing as an unhandled throw").
-    // `persist_failed` already maps to a 503 with a documented body
-    // (`routes/leads/index.ts`) — the SAME shape a genuine DB-outage
-    // failure (both DB and file fail) already returns, so this adds no new
-    // response shape, only a new path that reaches the existing one
-    // WITHOUT first trying — and losing time to — a file write for an
-    // error the file fallback can never fix.
-    //
-    // A GENUINE infrastructure failure (an unreachable DB, an exhausted
-    // pool, an unset DATABASE_URL) is NOT a constraint violation and still
-    // takes the file fallback below, unchanged.
-    if (isConstraintViolation(dbErr)) {
-      const dbMsg = dbErr instanceof Error ? dbErr.message : String(dbErr);
-      return {
-        ok: false,
-        error: { kind: "persist_failed", message: `db: ${dbMsg}` },
-      };
-    }
-
-    // In production the file fallback is not durable (a serverless instance
-    // does not outlive the request), so reporting it as success would lose
-    // the lead silently. Deliver by email when that is configured; otherwise
-    // fail loudly (#6730 D2). A newsletter signup is never emailed — one
-    // owner email per address is not a list (`acceptsKind`).
-    if (process.env.NODE_ENV === "production") {
-      const dbMsg = dbErr instanceof Error ? dbErr.message : String(dbErr);
-      if (input.kind === "subscribe") {
-        return {
-          ok: false,
-          error: { kind: "persist_failed", message: `db: ${dbMsg}` },
-        };
-      }
-      const emailed = await deliverByEmail(input);
-      if (!emailed.ok) {
-        return {
-          ok: false,
-          error: {
-            kind: "persist_failed",
-            // Not the provider's text: it can echo an address, and this
-            // message is logged (spec D5).
-            message: `db: ${dbMsg}; email delivery failed`,
-          },
-        };
-      }
-      await appendLeadRecord(captureRecordFor(input, emailed.id, sourceMeta));
-      return {
-        ok: true,
-        id: emailed.id,
-        persisted: "email",
-        email: emailed.email,
-      };
-    }
-
-    // 5. File fallback (outside production only)
-    // Include a UUID suffix so concurrent fallbacks produce unique IDs even
-    // within the same millisecond. Format still matches /^[a-z0-9_-]{8,64}$/i.
-    const fallbackLead = {
-      id: `fallback-${Date.now()}-${randomUUID().slice(0, 8)}`,
-      siteId: input.siteId,
-      source: input.kind === "callback" ? "callback" : input.source,
-      email: input.kind === "callback" ? "" : input.email,
-      payload: input.kind === "subscribe" ? {} : input.payload,
-      createdAt: sourceMeta.receivedAt,
-    };
-
-    let fallbackResult;
-    try {
-      fallbackResult = await writeLeadFallback(fallbackLead);
-    } catch {
-      const dbMsg = dbErr instanceof Error ? dbErr.message : String(dbErr);
-      return {
-        ok: false,
-        error: {
-          kind: "persist_failed",
-          message: `db: ${dbMsg}; fallback threw`,
-        },
-      };
-    }
-
-    if (!fallbackResult.ok) {
-      const dbMsg = dbErr instanceof Error ? dbErr.message : String(dbErr);
-      return {
-        ok: false,
-        error: {
-          kind: "persist_failed",
-          message: `db: ${dbMsg}; fallback: ${fallbackResult.error.message}`,
-        },
-      };
-    }
-
-    id = fallbackLead.id;
-    persisted = "file";
-  }
-
-  // 6. Write to lead-capture JSONL (always-on canonical AX surface).
-  // Best-effort — a write failure does NOT roll back persistence or block email.
-  // The file is the agent-readable surface; DB is the transactional record.
-  await appendLeadRecord(captureRecordFor(input, id!, sourceMeta));
-
-  // 7. Email notification (best-effort — never rolls back persistence)
-  let emailResult: EmailResult;
-  if (skipEmail) {
-    emailResult = { skipped: true, reason: skipReason ?? "skipped" };
-  } else {
-    emailResult = await sendEmail(input, id!, persisted!, sourceMeta.viaSpoke);
-  }
-
-  return { ok: true, id: id!, personId, persisted, email: emailResult };
-}