create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,835 @@
+/**
+ * @file recommender-capture.ts
+ * @description The recommender's "email moment" service (#4837 — Epic #4760
+ * C1). One write path for everything the PRD's purchase CTA requires (L111):
+ * the FlowSession + Lead at the moment the visitor chooses save or checkout,
+ * the plan minted as a DeliverableGrant through the EXISTING T+0 path
+ * (`fulfillDeliverable`, #3961 D5), and — for checkout — the `FlowCheckout`
+ * buyer record at a SERVER-recomputed price (D6: MAJOR units × 100).
+ *
+ * Four exports (spec §6):
+ *   - `captureRecommenderChoice` — resolve the served config + register,
+ *     recompute `recommend()` exactly as the browser ran it (D3: no flags),
+ *     create-or-resume a completed session (D1), `routeLead` (D2/D5),
+ *     T+0 grant (opt-in, fail-soft).
+ *   - `recordCheckout` — `price()` over the SERVED register, refuse the
+ *     unpriceable cases (D7), write the row.
+ *   - `attachStripeSession` — the stamp the route child (#4841) calls after the
+ *     Stripe call (the session id and, since #4912, the hosted-page URL a
+ *     replay is served from).
+ *   - `expireFlowCheckout` — the row half of #4912's attach-miss compensation.
+ *   - `findRegisterForSlug` — the slug → register read (the
+ *     `flow-aggregate.ts:135–175` shape, as a named export) the route child's
+ *     `stripeConfigRef` gate calls.
+ *
+ * The config read mirrors `serveFlow` (`flow-engine.ts:228–262`) — one
+ * `flowDefinition.findUnique` + `flowConfigSchema.safeParse` — rather than
+ * calling it, because `serveFlow` returns the parsed config only and
+ * `FlowSession.flowId` needs the definition's id (`resolveSession`'s own
+ * create shape, `flow-engine.ts:629–650`). Still one definition read.
+ *
+ * Lives in `apps/api/src/services/` (ADR 0009 D3): it composes the `inbox`
+ * rows (FlowDefinition / FlowSession / WaitlistExperiment / FlowCheckout)
+ * with `routeLead` (Lead) and `fulfillDeliverable` (DeliverableGrant).
+ *
+ * #4912 (REL-013.2 H2) hardens three things here: resume ownership (a session
+ * carrying a Lead is resumable only by the email stamped on it, and its Lead is
+ * reused rather than duplicated), `/checkout` idempotency (a server-derived
+ * fingerprint under `@@unique([siteId, idempotencyKey])`, replayed within the
+ * TTL and reconciled past it), and the attach-miss row compensation.
+ *
+ * PII boundary: every log line carries only
+ * `{ siteId, flowSlug, sessionId, leadId, choice, outcome }` (+ a terse `err`
+ * message on a caught rejection) — never the email, the answers, or the
+ * payload (the `flow-engine.ts` / `deliverable-fulfillment.ts` boundary).
+ */
+
+import { createHash } from "node:crypto";
+
+import type { Prisma } from "@working-theory/database";
+import { logger } from "@working-theory/observability";
+import {
+  flowConfigSchema,
+  price,
+  recommend,
+  waitlistExperimentConfigSchema,
+  WaitlistPricingError,
+  type FlowConfig,
+  type RecommendRegister,
+  type WaitlistAnswers,
+  type WaitlistBillingPeriod,
+  type WaitlistCreditStop,
+  type WaitlistExperimentConfig,
+  type WaitlistPriceQuote,
+  type WaitlistRecommendation,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+import { MAX_AGGREGATION_ROWS } from "./answer-distributions.js";
+import { fulfillDeliverable } from "./deliverable-fulfillment.js";
+import { routeLead, type SourceMeta } from "./lead-routing.js";
+
+// ─── Types (spec §6) ────────────────────────────────────────────────────────
+
+export type RecommenderChoice = "save" | "checkout";
+
+/** The permalink's answer map (`flow-permalink.ts:38`) — answers only, never identity. */
+export type RecommenderAnswers = Record<string, string | string[]>;
+
+export type CaptureRecommenderChoiceInput = {
+  siteId: string;
+  flowSlug: string;
+  answers: RecommenderAnswers;
+  email: string;
+  locale?: string;
+  /** The visitor's own walk session to resume (D1); absent on a cold load. */
+  sessionId?: string;
+  choice: RecommenderChoice;
+  sourceMeta: SourceMeta;
+};
+
+export type RecommenderCaptureErrorKind =
+  | "flows_not_configured"
+  | "flow_not_found"
+  | "not_recommending"
+  | "invalid_input"
+  | "lead_failed";
+
+export type RecommenderCaptureError = {
+  kind: RecommenderCaptureErrorKind;
+  message: string;
+};
+
+export type CaptureRecommenderChoiceResult =
+  | {
+      ok: true;
+      sessionId: string;
+      leadId: string;
+      recommendation: WaitlistRecommendation;
+      config: FlowConfig;
+      register: WaitlistExperimentConfig | undefined;
+    }
+  | { ok: false; error: RecommenderCaptureError };
+
+export type RecordCheckoutInput = {
+  siteId: string;
+  flowSlug: string;
+  experimentKey: string;
+  sessionId: string;
+  leadId: string;
+  /** The visitor's own email — hashed into the idempotency key (D5), never stored or logged in the clear. */
+  email: string;
+  offerKey: string;
+  seats: number;
+  period: WaitlistBillingPeriod;
+  creditStop: WaitlistCreditStop;
+  /** The answers-only payload string the recommendation was rendered from (#4770). */
+  permalink: string;
+};
+
+export type RecordCheckoutErrorKind =
+  | "no_register"
+  | "session_mismatch"
+  | "unknown_offer"
+  | "no_seat_rate"
+  | "no_rate_table"
+  | "invalid_seats"
+  | "unknown_credit_stop"
+  | "custom_stop"
+  | "no_currency";
+
+type RecordCheckoutQuoted = {
+  flowCheckoutId: string;
+  amountMinor: number;
+  currency: string;
+  quote: WaitlistPriceQuote;
+};
+
+/**
+ * #4912 FR5 — DISCRIMINATED on `replayed`, so a replay can never be handed to
+ * the caller with a null session or URL. The route branches on this one field;
+ * modelling the two Stripe columns as `string | null` on a single arm would
+ * make the impossible state representable and let a mis-narrowed branch open a
+ * SECOND Stripe session for a request the service already replayed.
+ */
+export type RecordCheckoutResult =
+  | ({ ok: true; replayed: false } & RecordCheckoutQuoted)
+  | ({ ok: true; replayed: true; stripeSessionId: string; checkoutUrl: string } & RecordCheckoutQuoted)
+  | { ok: false; error: { kind: RecordCheckoutErrorKind; message: string } };
+
+// ─── Row shapes ──────────────────────────────────────────────────────────────
+
+const FLOW_DEFINITION_SELECT = {
+  id: true,
+  config: true,
+} as const satisfies Prisma.FlowDefinitionSelect;
+type FlowDefinitionRow = { id: string; config: unknown };
+
+const EXPERIMENT_CONFIG_SELECT = {
+  id: true,
+  config: true,
+} as const satisfies Prisma.WaitlistExperimentSelect;
+type ExperimentConfigRow = { id: string; config: unknown };
+
+const SESSION_RESUME_SELECT = {
+  id: true,
+  siteId: true,
+  flowSlug: true,
+  // #4912 FR3 — resume ownership is decided on these two columns; without them
+  // the resume path could not tell a visitor's own second call from a caller
+  // naming somebody else's session id (#4859).
+  leadId: true,
+  email: true,
+} as const satisfies Prisma.FlowSessionSelect;
+const SESSION_OWNER_SELECT = { siteId: true, flowSlug: true, leadId: true } as const;
+type SessionOwnerRow = { siteId: string; flowSlug: string; leadId: string | null };
+type SessionResumeRow = {
+  id: string;
+  siteId: string;
+  flowSlug: string;
+  leadId: string | null;
+  email: string | null;
+};
+
+/** #4912 FR5 — the columns a keyed lookup needs to decide replay vs reconcile. */
+const CHECKOUT_KEY_SELECT = {
+  id: true,
+  status: true,
+  stripeSessionId: true,
+  checkoutUrl: true,
+  createdAt: true,
+} as const satisfies Prisma.FlowCheckoutSelect;
+type CheckoutKeyRow = {
+  id: string;
+  status: string;
+  stripeSessionId: string | null;
+  checkoutUrl: string | null;
+  createdAt: Date;
+};
+
+// ─── PII-safe logging ───────────────────────────────────────────────────────
+
+type CaptureOutcome =
+  | "captured"
+  | "lead_failed"
+  | "grant_failed"
+  | "checkout_recorded";
+
+type LogCtx = {
+  siteId: string;
+  flowSlug: string;
+  sessionId?: string;
+  leadId?: string;
+  choice?: RecommenderChoice;
+};
+
+function logOutcome(ctx: LogCtx, outcome: CaptureOutcome, err?: unknown): void {
+  const line = { ...ctx, outcome, ...(err !== undefined && { err: errorName(err) }) };
+  if (outcome === "lead_failed" || outcome === "grant_failed") {
+    logger.warn(line, `[recommender-capture] ${outcome}`);
+  } else {
+    logger.info(line, `[recommender-capture] ${outcome}`);
+  }
+}
+
+/**
+ * The error's NAME, never its message — an email-provider rejection can embed
+ * the recipient address in `message`, and this module's log lines carry no
+ * PII (spec §5.2; PR #4851 security review, condition (c)).
+ */
+function errorName(err: unknown): string {
+  return err instanceof Error && err.name ? err.name : "UnknownError";
+}
+
+/** The zod `flowCheckoutInputSchema` ceiling, enforced here too: `amountMinor` is INT4 (PR #4851 security review, condition (b)). */
+export const MAX_CHECKOUT_SEATS = 999;
+
+// ─── DB-required guard (mirrors flow-engine.ts's private `requireDb`) ────────
+
+function requireDb(): RecommenderCaptureError | null {
+  if (!process.env.DATABASE_URL) {
+    return { kind: "flows_not_configured", message: "Flows are not configured." };
+  }
+  return null;
+}
+
+// ─── findRegisterForSlug (FR7) ───────────────────────────────────────────────
+
+/**
+ * Resolve a flow slug to its backing `WaitlistExperiment` register for one
+ * site — the `flow-aggregate.ts:135–175` read as a named export: one
+ * `siteId`-scoped `findMany`, oldest first, matched on `waitlists[].flowSlug`.
+ * A corrupt row is skipped and logged, never thrown; more than one match
+ * resolves to the oldest (the aggregate service's own documented posture).
+ */
+export async function findRegisterForSlug(
+  siteId: string,
+  slug: string,
+): Promise<WaitlistExperimentConfig | undefined> {
+  const rows: ExperimentConfigRow[] = await prisma.waitlistExperiment.findMany({
+    where: { siteId },
+    select: EXPERIMENT_CONFIG_SELECT,
+    orderBy: { createdAt: "asc" },
+    take: MAX_AGGREGATION_ROWS,
+  });
+
+  let match: WaitlistExperimentConfig | undefined;
+  for (const row of rows) {
+    const parsed = waitlistExperimentConfigSchema.safeParse(row.config);
+    if (!parsed.success) {
+      logger.warn(
+        { siteId, flowSlug: slug, outcome: "register_parse_skipped" },
+        "[recommender-capture] experiment config failed to parse — skipped",
+      );
+      continue;
+    }
+    if (parsed.data.waitlists.some((w) => w.flowSlug === slug)) {
+      match = parsed.data;
+      break;
+    }
+  }
+  return match;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * FR3 — key the permalink's flat answers by the segmentation step each
+ * question `name` belongs to (`{ [stepKey]: { [name]: value } }`, the
+ * `FlowSession.state` shape `flow-engine.ts:730–733` writes). An answer no
+ * segmentation step declares is dropped — it is not part of the config.
+ */
+function stateFromAnswers(
+  config: FlowConfig,
+  answers: RecommenderAnswers,
+): Record<string, Record<string, string | string[]>> {
+  const state: Record<string, Record<string, string | string[]>> = {};
+  for (const step of config.steps) {
+    if (step.type !== "segmentation") continue;
+    for (const question of step.questions) {
+      const value = answers[question.name];
+      if (value === undefined) continue;
+      (state[step.key] ??= {})[question.name] = value;
+    }
+  }
+  return state;
+}
+
+/** D3 — the identical `recommend()` register `ResultsClient.tsx:47–56` builds. */
+function registerFromConfig(config: FlowConfig): RecommendRegister {
+  return {
+    key: config.experiment?.key ?? config.slug,
+    offers: config.offers,
+    pairings: config.pairings,
+    rateTable: config.rateTable,
+    scoring: config.scoring,
+  };
+}
+
+/**
+ * #4912 D3 — resume ownership.
+ *
+ * A walk session that carries no `leadId` is nobody's yet: the first email to
+ * name it takes it, which is the cold-load path this service has always had.
+ * Once a Lead is stamped on it the session belongs to that email, and only
+ * that email may resume it — a caller naming somebody else's high-entropy id
+ * gets a fresh session instead of overwriting theirs (#4859). Compared
+ * case-insensitively after trimming, the same normalization the Lead's own
+ * email validation applies.
+ */
+function resumeIsOwned(row: SessionResumeRow, email: string): boolean {
+  if (row.leadId === null) return true;
+  if (row.email === null) return false;
+  return row.email.trim().toLowerCase() === email.trim().toLowerCase();
+}
+
+// ─── captureRecommenderChoice (FR2–FR5) ──────────────────────────────────────
+
+export async function captureRecommenderChoice(
+  input: CaptureRecommenderChoiceInput,
+): Promise<CaptureRecommenderChoiceResult> {
+  const dbError = requireDb();
+  if (dbError) return { ok: false, error: dbError };
+
+  const { siteId, flowSlug, answers, email, choice, sourceMeta } = input;
+  const logCtx: LogCtx = { siteId, flowSlug, choice };
+
+  // The served config — one definition read + the same parse `serveFlow` does.
+  const definition: FlowDefinitionRow | null = await prisma.flowDefinition.findUnique({
+    where: { siteId_slug: { siteId, slug: flowSlug } },
+    select: FLOW_DEFINITION_SELECT,
+  });
+  if (!definition) {
+    return { ok: false, error: { kind: "flow_not_found", message: "Flow not found." } };
+  }
+  const parsedConfig = flowConfigSchema.safeParse(definition.config);
+  if (!parsedConfig.success) {
+    return {
+      ok: false,
+      error: { kind: "invalid_input", message: "Stored flow config failed validation." },
+    };
+  }
+  const config = parsedConfig.data;
+  if (config.mode !== "recommending" || config.offers === undefined) {
+    return {
+      ok: false,
+      error: { kind: "not_recommending", message: "Flow is not a recommending flow." },
+    };
+  }
+  if (!config.experiment) {
+    // A compiled recommending flow always carries its binding
+    // (`compileWaitlistFlow` sets it unconditionally); its absence is a
+    // register-integrity fault, not a branch to invent (spec §5.3).
+    return {
+      ok: false,
+      error: { kind: "invalid_input", message: "Flow carries no experiment binding." },
+    };
+  }
+
+  const register = await findRegisterForSlug(siteId, flowSlug);
+
+  // D3 — the browser's exact call: no flags.
+  const recommendation = recommend(registerFromConfig(config), answers as WaitlistAnswers);
+
+  const state = stateFromAnswers(config, answers);
+  const locale = input.locale ?? config.defaultLocale;
+  const now = new Date();
+
+  // D1 — resume the visitor's own walk session, else create.
+  // #4912 FR3 — and only when the session is theirs to resume.
+  let sessionId: string | undefined;
+  let ownedLeadId: string | undefined;
+  if (input.sessionId) {
+    const existing: SessionResumeRow | null = await prisma.flowSession.findUnique({
+      where: { id: input.sessionId },
+      select: SESSION_RESUME_SELECT,
+    });
+    if (
+      existing &&
+      existing.siteId === siteId &&
+      existing.flowSlug === flowSlug &&
+      resumeIsOwned(existing, email)
+    ) {
+      await prisma.flowSession.update({
+        where: { id: existing.id },
+        data: {
+          email,
+          state: state as unknown as Prisma.InputJsonValue,
+          locale,
+          completedAt: now,
+        },
+      });
+      sessionId = existing.id;
+      if (existing.leadId !== null) ownedLeadId = existing.leadId;
+    }
+  }
+  if (sessionId === undefined) {
+    const created = (await prisma.flowSession.create({
+      data: {
+        siteId,
+        flowId: definition.id,
+        flowSlug,
+        configSnapshot: config as unknown as Prisma.InputJsonValue,
+        state: state as unknown as Prisma.InputJsonValue,
+        email,
+        locale,
+        completedAt: now,
+      },
+      select: { id: true },
+    })) as { id: string };
+    sessionId = created.id;
+  }
+  logCtx.sessionId = sessionId;
+
+  // #4912 FR4 — the visitor's own resubmission of a session that already
+  // carries its Lead. `routeLead` writes a new Lead on every call, so calling
+  // it again is exactly the duplicate #4860 reports; the T+0 grant was minted
+  // with that Lead too, so it is not re-minted either. The session's answers,
+  // locale and completion stamp were refreshed by the resume update above.
+  if (ownedLeadId !== undefined) {
+    logCtx.leadId = ownedLeadId;
+    logOutcome(logCtx, "captured");
+    return { ok: true, sessionId, leadId: ownedLeadId, recommendation, config, register };
+  }
+
+  // FR4 / D2 — the flow-engine completion payload shape + the recommender block.
+  const payload: Record<string, unknown> = {};
+  for (const stepData of Object.values(state)) Object.assign(payload, stepData);
+  payload["flowSlug"] = flowSlug;
+  payload["locale"] = locale;
+  payload["experimentKey"] = config.experiment.key;
+  payload["waitlistKey"] = config.experiment.waitlist;
+  payload["recommender"] = {
+    choice,
+    fits: recommendation.fits.map((f) => f.offerKey),
+    ...(recommendation.pairing !== undefined && { pairing: recommendation.pairing.offers }),
+  };
+
+  const leadResult = await routeLead(
+    { kind: "submit", siteId, source: `flow:${flowSlug}`, email, payload },
+    sourceMeta,
+  );
+
+  if (!leadResult.ok) {
+    // D5 — the purchase path needs a Lead; the session stays the record
+    // (the engine's own fallback, `flow-engine.ts:925–939`). Idempotent — the
+    // create/resume above already set `completedAt` — so no branch on which
+    // path we took.
+    await prisma.flowSession.update({
+      where: { id: sessionId },
+      data: { completedAt: now },
+    });
+    logOutcome(logCtx, "lead_failed");
+    return {
+      ok: false,
+      error: { kind: "lead_failed", message: "Lead could not be recorded." },
+    };
+  }
+
+  const leadId = leadResult.id;
+  logCtx.leadId = leadId;
+  await prisma.flowSession.update({ where: { id: sessionId }, data: { leadId } });
+
+  // FR5 — the T+0 grant: opt-in on the block, fail-soft on any rejection.
+  if (config.deliverables) {
+    try {
+      await fulfillDeliverable({
+        siteId,
+        flowSlug,
+        configSnapshot: config,
+        leadId,
+        sessionId,
+        email,
+        locale,
+      });
+    } catch (err) {
+      logOutcome(logCtx, "grant_failed", err);
+    }
+  }
+
+  logOutcome(logCtx, "captured");
+  return { ok: true, sessionId, leadId, recommendation, config, register };
+}
+
+// ─── Checkout idempotency (#4912 FR5/FR6, D5/D8) ─────────────────────────────
+
+/**
+ * The window in which a repeat `/checkout` submission is still the SAME
+ * attempt — and, with the same value, the age past which a `created` row that
+ * never took a Stripe session id is dead (#4912 D8). Thirty minutes covers a
+ * double click, a retried request and a back-button resubmit, and sits well
+ * inside Stripe's own 24-hour session expiry, so a replayed row's session is
+ * never already gone.
+ */
+export const FLOW_CHECKOUT_IDEMPOTENCY_TTL_MS = 30 * 60_000;
+
+/**
+ * The request's fingerprint (#4912 D5) — a SHA-256 over the fields that make
+ * two submissions the same purchase, JSON-encoded in a fixed order.
+ *
+ * ENCODED, never delimiter-joined: a joined key forges, since `["a","b"]` and
+ * `["a:b"]` collide under any separator. `creditStop` is projected field by
+ * field (its schema is `{kind}` or `{kind, index}`) so JSON key order cannot
+ * vary between two otherwise-identical requests.
+ *
+ * The email is hashed here and never leaves this function in the clear: the
+ * digest is what reaches the database, and no log line carries it.
+ */
+function checkoutIdempotencyKey(
+  input: RecordCheckoutInput,
+  priced: { amountMinor: number; currency: string },
+): string {
+  const stop = input.creditStop;
+  return createHash("sha256")
+    .update(
+      JSON.stringify([
+        input.siteId,
+        input.flowSlug,
+        input.sessionId,
+        input.email.trim().toLowerCase(),
+        input.offerKey,
+        input.seats,
+        input.period,
+        stop.kind,
+        stop.kind === "tier" ? stop.index : null,
+        input.permalink,
+        // The SERVER's resolved price is part of what makes two submissions the
+        // same purchase: a replay hands back a Stripe session opened at the
+        // stored amount, so a register edit between the two must mint a new
+        // session rather than replay the pre-edit price (PRD L104 in effect,
+        // not only in letter).
+        priced.amountMinor,
+        priced.currency,
+      ]),
+    )
+    .digest("hex");
+}
+
+/**
+ * What a keyed row means for the attempt that just hashed to its key.
+ *
+ *   - `replayable` — a live `created` row inside the TTL whose Stripe session
+ *     and hosted-page URL are both stamped. This is the double-submit AC-3
+ *     names: hand back what the first attempt got.
+ *   - `in_flight` — a `created` row inside the TTL with no session stamped yet.
+ *     Its own request is between `create` and `attachStripeSession`; touching it
+ *     would strand a session the #4838 webhook could then never join, because
+ *     that webhook's update is guarded on `status: "created"`.
+ *   - `dead` — past the TTL, or no longer `created` (the webhook completed or
+ *     expired it). Its key is not this attempt's to collide with.
+ */
+function classifyKeyedRow(row: CheckoutKeyRow): "replayable" | "in_flight" | "dead" {
+  const fresh = Date.now() - row.createdAt.getTime() <= FLOW_CHECKOUT_IDEMPOTENCY_TTL_MS;
+  if (!fresh || row.status !== "created") return "dead";
+  return row.stripeSessionId !== null && row.checkoutUrl !== null ? "replayable" : "in_flight";
+}
+
+/**
+ * A Prisma unique-constraint violation, recognised structurally rather than by
+ * importing the runtime error class — the `waitlist-followup.ts:429` and
+ * `tenant-context.ts:448` idiom.
+ */
+function isUniqueViolation(err: unknown): boolean {
+  return (
+    typeof err === "object" && err !== null && (err as { code?: unknown }).code === "P2002"
+  );
+}
+
+/**
+ * A stale keyed row is logged with the row-id prefix and an outcome, and
+ * nothing else (#4912 AC-4) — no email, no permalink, no URL.
+ */
+function logCheckoutReconciled(flowCheckoutId: string): void {
+  logger.warn(
+    { flowCheckoutIdPrefix: flowCheckoutId.substring(0, 8), outcome: "checkout_reconciled" },
+    "[recommender-capture] stale checkout row reconciled",
+  );
+}
+
+// ─── recordCheckout (FR6, D6/D7) ─────────────────────────────────────────────
+
+export async function recordCheckout(input: RecordCheckoutInput): Promise<RecordCheckoutResult> {
+  const { siteId, flowSlug, offerKey, seats, period, creditStop } = input;
+  const fail = (kind: RecordCheckoutErrorKind, message: string): RecordCheckoutResult => ({
+    ok: false,
+    error: { kind, message },
+  });
+
+  // The register is resolved HERE, from the DB, never taken from a caller —
+  // so no route can price against a client-derived register (PR #4851
+  // security review, condition (a)).
+  const register = await findRegisterForSlug(siteId, flowSlug);
+  if (!register) return fail("no_register", "No register names this flow.");
+
+  if (!Number.isInteger(seats) || seats < 1 || seats > MAX_CHECKOUT_SEATS) {
+    return fail("invalid_seats", `seats must be an integer between 1 and ${MAX_CHECKOUT_SEATS}.`);
+  }
+
+  // The session + lead ids must be THIS site's, and the lead must be the one
+  // stamped on that session — never ids a caller threaded through (condition (d)).
+  const session: SessionOwnerRow | null = await prisma.flowSession.findUnique({
+    where: { id: input.sessionId },
+    select: SESSION_OWNER_SELECT,
+  });
+  if (
+    !session ||
+    session.siteId !== siteId ||
+    session.flowSlug !== flowSlug ||
+    session.leadId !== input.leadId
+  ) {
+    return fail("session_mismatch", "The session does not belong to this site, flow and lead.");
+  }
+
+  const rateTable = register.rateTable;
+  if (!rateTable) return fail("no_rate_table", "The register carries no rateTable.");
+  const currency = rateTable.currency;
+  if (!currency) return fail("no_currency", "The register's rateTable declares no currency.");
+  if (creditStop.kind === "custom") {
+    return fail("custom_stop", "A custom credit stop carries no total to charge.");
+  }
+
+  let quote: WaitlistPriceQuote;
+  try {
+    quote = price(register, offerKey, seats, period, creditStop);
+  } catch (err) {
+    if (err instanceof WaitlistPricingError) return fail(err.code, err.message);
+    throw err;
+  }
+  if (quote.kind !== "quoted") {
+    // Unreachable — the `custom` stop was refused above — but it is the TS
+    // narrowing that lets `quote.total` be read below; not a second policy check.
+    return fail("custom_stop", "A custom credit stop carries no total to charge.");
+  }
+
+  // D6 — the register is MAJOR units; Stripe and the row take MINOR units.
+  const amountMinor = Math.round(quote.total * 100);
+
+  // #4912 FR5 — the keyed lookup runs AFTER the gates and the price, so a
+  // replay is still a fully validated request and the amount is still the
+  // server's own; only the row write and the Stripe call are skipped.
+  const priced = { amountMinor, currency };
+  const idempotencyKey = checkoutIdempotencyKey(input, priced);
+  const existing: CheckoutKeyRow | null = await prisma.flowCheckout.findUnique({
+    where: { siteId_idempotencyKey: { siteId, idempotencyKey } },
+    select: CHECKOUT_KEY_SELECT,
+  });
+
+  // `true` once this attempt must write an UNKEYED row: the key belongs to an
+  // attempt that is still in flight, and stealing it would kill a row whose own
+  // Stripe session is about to be stamped on it (see `keyOwner` below).
+  let keyHeldByAnother = false;
+
+  if (existing) {
+    const state = classifyKeyedRow(existing);
+    if (state === "replayable") {
+      return {
+        ok: true,
+        replayed: true,
+        flowCheckoutId: existing.id,
+        amountMinor,
+        currency,
+        quote,
+        stripeSessionId: existing.stripeSessionId as string,
+        checkoutUrl: existing.checkoutUrl as string,
+      };
+    }
+    if (state === "in_flight") {
+      // The keyed row was created moments ago and has not been stamped yet —
+      // an identical request is between its own `create` and its Stripe call.
+      // Releasing or expiring that row here would strand its session and leave
+      // a payment the #4838 webhook could never join (its update is guarded on
+      // `status: "created"`), so it is left completely alone and THIS attempt
+      // takes a row of its own, unkeyed.
+      keyHeldByAnother = true;
+    } else {
+      // #4912 FR6 — the keyed row is past the TTL, or the webhook already
+      // completed/expired it. Either way it is not this attempt's, so its key
+      // is released. A row that never took a Stripe session id can never be
+      // joined by the webhook, so it is also marked expired and its stored URL
+      // dropped; a row that HAS one is otherwise left untouched, because the
+      // webhook may still legitimately stamp a payment onto it.
+      const unjoinable = existing.status === "created" && existing.stripeSessionId === null;
+      await prisma.flowCheckout.updateMany({
+        where: { id: existing.id, siteId },
+        data: unjoinable
+          ? { status: "expired", idempotencyKey: null, checkoutUrl: null }
+          : { idempotencyKey: null },
+      });
+      logCheckoutReconciled(existing.id);
+    }
+  }
+
+  const writeRow = async (key: string | null): Promise<{ id: string }> =>
+    (await prisma.flowCheckout.create({
+      data: {
+        siteId: input.siteId,
+        flowSlug: input.flowSlug,
+        experimentKey: input.experimentKey,
+        sessionId: input.sessionId,
+        leadId: input.leadId,
+        offerKey,
+        seats,
+        period,
+        creditStop: creditStop as unknown as Prisma.InputJsonValue,
+        amountMinor,
+        currency,
+        quote: quote as unknown as Prisma.InputJsonValue,
+        permalink: input.permalink,
+        stripeSessionId: null,
+        checkoutUrl: null,
+        idempotencyKey: key,
+        status: "created",
+      },
+      select: { id: true },
+    })) as { id: string };
+
+  let row: { id: string };
+  if (keyHeldByAnother) {
+    row = await writeRow(null);
+  } else {
+    try {
+      row = await writeRow(idempotencyKey);
+    } catch (err) {
+      // Two identical requests cleared the lookup above before either write
+      // landed, and the unique caught the loser. The `waitlist-followup.ts`
+      // idiom: recognise the violation, do not let it surface as a 500 on the
+      // payment path. Re-read once — the winner may already be replayable —
+      // and otherwise take an unkeyed row, exactly as the in-flight case does.
+      if (!isUniqueViolation(err)) throw err;
+      const winner: CheckoutKeyRow | null = await prisma.flowCheckout.findUnique({
+        where: { siteId_idempotencyKey: { siteId, idempotencyKey } },
+        select: CHECKOUT_KEY_SELECT,
+      });
+      if (winner && classifyKeyedRow(winner) === "replayable") {
+        return {
+          ok: true,
+          replayed: true,
+          flowCheckoutId: winner.id,
+          amountMinor,
+          currency,
+          quote,
+          stripeSessionId: winner.stripeSessionId as string,
+          checkoutUrl: winner.checkoutUrl as string,
+        };
+      }
+      row = await writeRow(null);
+    }
+  }
+
+  logOutcome(
+    { siteId: input.siteId, flowSlug: input.flowSlug, sessionId: input.sessionId, leadId: input.leadId, choice: "checkout" },
+    "checkout_recorded",
+  );
+
+  return { ok: true, replayed: false, flowCheckoutId: row.id, amountMinor, currency, quote };
+}
+
+// ─── attachStripeSession ─────────────────────────────────────────────────────
+
+/**
+ * The one-column stamp the route child calls after the Stripe call (#4841).
+ * Tenant-scoped: the update matches on `siteId` too, so a row id alone can
+ * never reach another site's record (PR #4851 security review, condition (e)).
+ * Returns the matched-row count so the caller can refuse to hand out a
+ * session whose row the #4838 webhook could never join (`count !== 1`).
+ */
+export async function attachStripeSession(
+  siteId: string,
+  flowCheckoutId: string,
+  stripeSessionId: string,
+  checkoutUrl: string,
+): Promise<{ count: number }> {
+  const result = await prisma.flowCheckout.updateMany({
+    // #4912 — `status: "created"` is the third leg, matching the #4838
+    // webhook's own join. A row something else already finished or expired must
+    // NOT take this stamp: handing the visitor a URL for a row the webhook can
+    // no longer update would produce a real payment nobody records. A miss
+    // routes into the caller's attach-miss compensation, which expires the
+    // session instead of returning it.
+    where: { id: flowCheckoutId, siteId, status: "created" },
+    data: { stripeSessionId, checkoutUrl },
+  });
+  return { count: result.count };
+}
+
+/**
+ * The row half of the attach-miss compensation (#4912 FR7). The Stripe session
+ * is being expired, so the row is dead: it is marked `expired` and its
+ * idempotency key released, so the visitor's own retry writes a fresh row
+ * instead of colliding on the unique. Tenant-scoped like the stamp above.
+ */
+export async function expireFlowCheckout(
+  siteId: string,
+  flowCheckoutId: string,
+): Promise<{ count: number }> {
+  const result = await prisma.flowCheckout.updateMany({
+    // Guarded on `status: "created"` like the stamp above: a row the webhook
+    // already completed must never be downgraded to `expired` by a compensation
+    // for a DIFFERENT attempt. A zero count means the row was no longer this
+    // attempt's to kill — the caller reports that rather than claiming it acted.
+    where: { id: flowCheckoutId, siteId, status: "created" },
+    data: { status: "expired", idempotencyKey: null, checkoutUrl: null },
+  });
+  return { count: result.count };
+}