create-ailk 0.1.1 → 0.3.0

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

@@ -1,835 +0,0 @@
-/**
- * @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 };
-}