create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/routes/flows/index.ts

@@ -0,0 +1,202 @@
+/**
+ * Flows route group (#3956 D4).
+ *
+ * Routes:
+ *   GET  /v1/flows/:slug            — serve a validated flow config
+ *   POST /v1/flows/:slug/steps      — submit one step's answers; persists
+ *                                     server-side on landing
+ *   GET  /v1/flows/:slug/aggregate  — anonymous, PII-free per-question
+ *                                     response counts across all completed
+ *                                     respondents (#4771), for the results
+ *                                     reveal
+ *
+ * `siteId` is not carried in the URL or the request body — flows follow the
+ * same anonymous single-site default `apps/mcp/src/tools/capture_lead.ts`
+ * already established for agent-facing anonymous surfaces
+ * (`process.env.AILK_SITE_ID ?? "default"`), rather than the leads routes'
+ * explicit client-supplied `siteId` (spec D4 documents no siteId field for
+ * either flows route — this is the design decision that fills that gap).
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, never 200-with-ok:false.
+ */
+import {
+  flowSlugSchema,
+  submitFlowStepInputSchema,
+} from "@working-theory/validation";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+
+import { currentSiteId } from "../../lib/site.js";
+import { getFlowAggregate } from "../../services/flow-aggregate.js";
+import {
+  serveFlow,
+  submitStep,
+  type FlowEngineError,
+  type FlowEngineErrorKind,
+} from "../../services/flow-engine.js";
+
+const FLOW_ERROR_STATUS: Record<FlowEngineErrorKind, number> = {
+  invalid_input: 400,
+  flow_not_found: 404,
+  step_conflict: 409,
+  flows_not_configured: 503,
+};
+
+function sendFlowError(reply: FastifyReply, error: FlowEngineError) {
+  return reply
+    .status(FLOW_ERROR_STATUS[error.kind])
+    .send({ ok: false, error: { code: error.kind, message: error.message } });
+}
+
+export const getFlowRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get<{ Params: { slug: string } }>(
+    "/v1/flows/:slug",
+    async (request, reply) => {
+      const parsedSlug = flowSlugSchema.safeParse(request.params.slug);
+      if (!parsedSlug.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "invalid_input", message: "Invalid flow slug." },
+        });
+      }
+
+      const result = await serveFlow(currentSiteId(), parsedSlug.data);
+      if (!result.ok) return sendFlowError(reply, result.error);
+
+      return reply.send({ ok: true, data: result.config });
+    },
+  );
+};
+
+export const getFlowAggregateRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get<{ Params: { slug: string } }>(
+    "/v1/flows/:slug/aggregate",
+    async (request, reply) => {
+      const parsedSlug = flowSlugSchema.safeParse(request.params.slug);
+      if (!parsedSlug.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "invalid_input", message: "Invalid flow slug." },
+        });
+      }
+
+      const result = await getFlowAggregate(currentSiteId(), parsedSlug.data);
+      if (!result.ok) return sendFlowError(reply, result.error);
+
+      return reply.send({ ok: true, data: result.data });
+    },
+  );
+};
+
+export const submitFlowStepRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post<{ Params: { slug: string } }>(
+    "/v1/flows/:slug/steps",
+    async (request, reply) => {
+      const parsedSlug = flowSlugSchema.safeParse(request.params.slug);
+      if (!parsedSlug.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "invalid_input", message: "Invalid flow slug." },
+        });
+      }
+
+      // Validate the RAW body directly against the .strict() schema — an
+      // unexpected top-level key (e.g. attacker-supplied `siteId`) is
+      // rejected here rather than silently dropped by a pre-filter, so the
+      // 400 invalid_input D4 documents for "schema validation" actually
+      // fires on it.
+      const body = request.body as Record<string, unknown>;
+      const parsedBody = submitFlowStepInputSchema.safeParse(body);
+      if (!parsedBody.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: {
+            code: "invalid_input",
+            message:
+              parsedBody.error.issues[0]?.message ?? "Invalid step submission.",
+          },
+        });
+      }
+
+      const sourceMeta = {
+        ip: request.ip,
+        userAgent: request.headers["user-agent"],
+        receivedAt: new Date().toISOString(),
+      };
+
+      const result = await submitStep(
+        {
+          siteId: currentSiteId(),
+          slug: parsedSlug.data,
+          ...(parsedBody.data.sessionId !== undefined && {
+            sessionId: parsedBody.data.sessionId,
+          }),
+          stepKey: parsedBody.data.stepKey,
+          values: parsedBody.data.values,
+          ...(parsedBody.data.locale !== undefined && {
+            locale: parsedBody.data.locale,
+          }),
+        },
+        sourceMeta,
+      );
+
+      if (!result.ok) {
+        if (result.error.kind === "invalid_input") {
+          // Client-fixable — no server-side log needed.
+        } else if (result.error.kind !== "flows_not_configured") {
+          // step_conflict / flow_not_found — PII-safe operational visibility.
+          request.log.warn(
+            {
+              slug: parsedSlug.data,
+              stepKey: body["stepKey"],
+              kind: result.error.kind,
+            },
+            "flow step submission rejected",
+          );
+        }
+        return sendFlowError(reply, result.error);
+      }
+
+      // PII-safe structured log — mirrors leads route: no email/values/payload.
+      request.log.info(
+        {
+          slug: parsedSlug.data,
+          sessionId: result.sessionId,
+          stepKey: result.landed,
+          completed: result.completed,
+        },
+        "flow step landed",
+      );
+
+      if (result.leadRoutingFailed) {
+        // Completion ran but routeLead's own db+file fallback both failed —
+        // the session (not a Lead row) is the durable record for this
+        // completion. PII-safe: no email/payload, matches the shape above.
+        request.log.warn(
+          {
+            slug: parsedSlug.data,
+            sessionId: result.sessionId,
+          },
+          "flow completed but lead routing failed — session is the record",
+        );
+      }
+
+      const { sessionId, landed, nextStepKey, completed, leadId, segment, aeoScore } =
+        result;
+      return reply.send({
+        ok: true,
+        data: {
+          sessionId,
+          landed,
+          nextStepKey,
+          completed,
+          ...(leadId !== undefined && { leadId }),
+          ...(segment !== undefined && { segment }),
+          // D9 (#4663) — forward the aeo_score step's own result, or the
+          // persisted result on the completion response.
+          ...(aeoScore !== undefined && { aeoScore }),
+        },
+      });
+    },
+  );
+};

package/templates/apps/api/src/routes/flows/recommender.ts

@@ -0,0 +1,443 @@
+/**
+ * Recommender email-moment routes — #4841 (Epic #4760 C2).
+ *
+ * Routes (both anonymous, registered inside server.ts's `flowsScope` beside
+ * the three existing flow routes, so they inherit the per-IP rate limiter):
+ *   POST /v1/flows/:slug/save      — "email me this plan": FlowSession + Lead
+ *                                    (+ the T+0 grant) for the permalink's
+ *                                    answers. No Stripe call.
+ *   POST /v1/flows/:slug/checkout  — the purchase moment: the email moment
+ *                                    above, then the buyer row at a
+ *                                    SERVER-recomputed price, then a Stripe
+ *                                    TEST-mode Checkout Session whose metadata
+ *                                    carries the permalink + offer key.
+ *
+ * The body carries NO amount of any name (`flowCheckoutInputSchema` is
+ * `.strict()`): the server recomputes `price()` from the register it served
+ * (PRD L104) and `#4837`'s `recordCheckout` is the authority — it resolves
+ * the register from the DB itself and verifies the session + lead ids are
+ * this site's before writing (the PR #4851 security-review conditions).
+ *
+ * Gate order on checkout (spec FR5, + #4912 FR1): sandbox key → body →
+ * redirect origin (400) → register (404) → `stripeConfigRef` +
+ * `rateTable.currency` (409) → `offerKey` (400) → the capture → the row →
+ * Stripe. A Stripe failure lands AFTER the session, lead and row exist, so the
+ * buyer record survives a Stripe outage (FR6); a foreign redirect origin lands
+ * BEFORE all of them, so a refused redirect writes nothing at all.
+ *
+ * `siteId` is `currentSiteId()` — the anonymous single-site default every
+ * flows route takes (`index.ts`); `sourceMeta` is the same triple
+ * `submitFlowStepRoute` hands `routeLead`.
+ *
+ * Security invariants (the `checkout/sessions.ts` posture, inherited):
+ *   - Test mode only: a key outside the `sk_test_` allow-list is refused at
+ *     request time, before any DB or Stripe call.
+ *   - No PII in logs: only `slug`, 8-char id prefixes, and an outcome.
+ *   - No user input echoed in any error body.
+ *   - The two redirect URLs must be on the site's own origin (#4912 D1) — the
+ *     shared `flowRedirectUrlSchema` pins only `http(s)` + a host, so without
+ *     this gate a direct API caller could aim a real Checkout Session's
+ *     post-payment redirect at a host they control.
+ *   - The `X-Internal-Auth` gate is deliberately NOT applied — these are the
+ *     visitor's own anonymous moment (spec Clarifications).
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, never 200-with-ok:false.
+ *
+ * API↔MCP parity: no MCP twin — recorded exception (apps/api/CLAUDE.md): an
+ * agent walking a flow has no email to give and no card to pay with.
+ */
+import {
+  encodePermalink,
+  flowCheckoutInputSchema,
+  flowSaveInputSchema,
+  flowSlugSchema,
+  PERMALINK_VERSION,
+  resolveLocalizedString,
+} from "@working-theory/validation";
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
+
+import { currentSiteId } from "../../lib/site.js";
+import {
+  assertSandboxKey,
+  createQuotedCheckoutSession,
+  expireCheckoutSession,
+  StripeConfigError,
+} from "../../lib/stripe.js";
+import {
+  attachStripeSession,
+  captureRecommenderChoice,
+  expireFlowCheckout,
+  findRegisterForSlug,
+  recordCheckout,
+  type RecommenderCaptureError,
+  type RecordCheckoutErrorKind,
+} from "../../services/recommender-capture.js";
+
+// ─── Error mapping ───────────────────────────────────────────────────────────
+
+const CAPTURE_ERROR_STATUS: Record<RecommenderCaptureError["kind"], number> = {
+  invalid_input: 400,
+  flow_not_found: 404,
+  not_recommending: 409,
+  lead_failed: 502,
+  flows_not_configured: 503,
+};
+
+/** #4837 §6's `RecordCheckoutResult.kind` vocabulary → this unit's 400/409 split (spec Clarifications — provenance). */
+const RECORD_CHECKOUT_STATUS: Record<RecordCheckoutErrorKind, { status: number; code: string }> = {
+  no_register: { status: 404, code: "flow_not_found" },
+  session_mismatch: { status: 400, code: "invalid_input" },
+  unknown_offer: { status: 400, code: "invalid_input" },
+  no_seat_rate: { status: 400, code: "invalid_input" },
+  invalid_seats: { status: 400, code: "invalid_input" },
+  unknown_credit_stop: { status: 400, code: "invalid_input" },
+  custom_stop: { status: 400, code: "invalid_input" },
+  no_rate_table: { status: 409, code: "checkout_not_configured" },
+  no_currency: { status: 409, code: "checkout_not_configured" },
+};
+
+function sendError(reply: FastifyReply, status: number, code: string, message: string) {
+  return reply.status(status).send({ ok: false, error: { code, message } });
+}
+
+function sendCaptureError(reply: FastifyReply, error: RecommenderCaptureError) {
+  const code = error.kind === "not_recommending" ? "checkout_not_configured" : error.kind;
+  // Never echo user input — the service's messages are fixed strings.
+  return sendError(reply, CAPTURE_ERROR_STATUS[error.kind], code, error.message);
+}
+
+/** Stripe caps a metadata value at 500 characters; a long permalink is chunked, never truncated (spec D5). */
+export const METADATA_VALUE_MAX = 500;
+
+export function permalinkMetadata(permalink: string): Record<string, string> {
+  if (permalink.length <= METADATA_VALUE_MAX) return { permalink };
+  const out: Record<string, string> = {};
+  for (let i = 0, n = 1; i < permalink.length; i += METADATA_VALUE_MAX, n++) {
+    out[n === 1 ? "permalink" : `permalink_${n}`] = permalink.slice(i, i + METADATA_VALUE_MAX);
+  }
+  return out;
+}
+
+/**
+ * The site's own origin — the ONLY origin a checkout redirect may resolve to
+ * (#4912 FR1/D1).
+ *
+ * `FRONTEND_URL` is the single site-origin contract this API already carries:
+ * the CORS origin (`server.ts`), the origin check in `middleware/auth.ts`, and
+ * the billing-portal return URL (`routes/billing/portal.ts`) all read it. The
+ * fallback is byte-identical to the one `config/index.ts` applies, and it is
+ * read per request for the same reason `STRIPE_SECRET_KEY` is: this route's
+ * environment-sourced security inputs are resolved at request time, not frozen
+ * at import.
+ *
+ * Returns `null` when the value is set but unparseable — a misconfiguration
+ * the route reports as a config error rather than silently widening.
+ */
+function siteRedirectOrigin(): string | null {
+  const raw = process.env["FRONTEND_URL"] || "http://localhost:3000";
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return null;
+  }
+  // A non-http(s) value parses without throwing and yields the literal origin
+  // `"null"` (`mailto:…`, `javascript:…`, a bare `host:port`). That would deny
+  // every redirect — fail-closed, but undiagnosable — so it is reported as the
+  // misconfiguration it is rather than as a 400 the operator cannot explain.
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
+  return parsed.origin;
+}
+
+/**
+ * Exact origin equality — scheme + host + port. A prefix or suffix comparison
+ * would accept `https://<site-origin>.evil.example`; a scheme check keeps
+ * `javascript:` and `data:` out even though the shared schema already refuses
+ * them.
+ */
+function isSameOriginRedirect(raw: string, siteOrigin: string): boolean {
+  let resolved: URL;
+  try {
+    resolved = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (resolved.protocol !== "https:" && resolved.protocol !== "http:") return false;
+  return resolved.origin === siteOrigin;
+}
+
+function sourceMetaOf(request: FastifyRequest) {
+  return {
+    ip: request.ip,
+    userAgent: request.headers["user-agent"],
+    receivedAt: new Date().toISOString(),
+  };
+}
+
+function prefix(id: string): string {
+  return id.substring(0, 8);
+}
+
+// ─── POST /v1/flows/:slug/save ───────────────────────────────────────────────
+
+export const saveRecommendationRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post<{ Params: { slug: string } }>("/v1/flows/:slug/save", async (request, reply) => {
+    const parsedSlug = flowSlugSchema.safeParse(request.params.slug);
+    if (!parsedSlug.success) return sendError(reply, 400, "invalid_input", "Invalid flow slug.");
+
+    const parsedBody = flowSaveInputSchema.safeParse(request.body);
+    if (!parsedBody.success) {
+      return sendError(
+        reply,
+        400,
+        "invalid_input",
+        parsedBody.error.issues[0]?.message ?? "Invalid save request.",
+      );
+    }
+    const body = parsedBody.data;
+
+    const result = await captureRecommenderChoice({
+      siteId: currentSiteId(),
+      flowSlug: parsedSlug.data,
+      answers: body.answers,
+      email: body.email,
+      ...(body.locale !== undefined && { locale: body.locale }),
+      ...(body.sessionId !== undefined && { sessionId: body.sessionId }),
+      choice: "save",
+      sourceMeta: sourceMetaOf(request),
+    });
+    if (!result.ok) return sendCaptureError(reply, result.error);
+
+    request.log.info(
+      { slug: parsedSlug.data, sessionIdPrefix: prefix(result.sessionId), outcome: "saved" },
+      "[recommender] plan saved",
+    );
+    return reply.send({ ok: true, data: { leadId: result.leadId, sessionId: result.sessionId } });
+  });
+};
+
+// ─── POST /v1/flows/:slug/checkout ───────────────────────────────────────────
+
+export const checkoutRecommendationRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post<{ Params: { slug: string } }>("/v1/flows/:slug/checkout", async (request, reply) => {
+    // 1. Test mode only — before any DB or Stripe call (the sessions.ts posture).
+    const secretKey = process.env["STRIPE_SECRET_KEY"];
+    if (!secretKey) return sendError(reply, 500, "config-error", "Stripe is not configured.");
+    try {
+      assertSandboxKey(secretKey);
+    } catch {
+      return sendError(reply, 500, "live-mode-forbidden", "Stripe live mode is not permitted.");
+    }
+
+    // 2. Body — strict; an amount of any name is a 400 here, never read.
+    const parsedSlug = flowSlugSchema.safeParse(request.params.slug);
+    if (!parsedSlug.success) return sendError(reply, 400, "invalid_input", "Invalid flow slug.");
+    const slug = parsedSlug.data;
+    const parsedBody = flowCheckoutInputSchema.safeParse(request.body);
+    if (!parsedBody.success) {
+      return sendError(
+        reply,
+        400,
+        "invalid_input",
+        parsedBody.error.issues[0]?.message ?? "Invalid checkout request.",
+      );
+    }
+    const body = parsedBody.data;
+    const siteId = currentSiteId();
+
+    // 2b. #4912 FR1 — both redirect URLs must land on this site's own origin.
+    //     Before every gate below, so a refused redirect creates no session,
+    //     no lead and no row, and never reaches Stripe.
+    const siteOrigin = siteRedirectOrigin();
+    if (siteOrigin === null) {
+      request.log.error({ slug }, "[recommender] FRONTEND_URL is not a valid absolute URL");
+      return sendError(reply, 500, "config-error", "The site origin is not configured.");
+    }
+    if (
+      !isSameOriginRedirect(body.successUrl, siteOrigin) ||
+      !isSameOriginRedirect(body.cancelUrl, siteOrigin)
+    ) {
+      // Never echo the offending URL back.
+      request.log.warn({ slug, outcome: "redirect_origin_refused" }, "[recommender] redirect origin refused");
+      return sendError(reply, 400, "invalid_input", "Redirect URLs must be on this site's origin.");
+    }
+
+    // 3. Register gates — 404 unknown, 409 not set up to sell, 400 unknown offer.
+    const register = await findRegisterForSlug(siteId, slug);
+    if (!register) return sendError(reply, 404, "flow_not_found", "Flow not found.");
+    if (register.stripeConfigRef === null || !register.rateTable?.currency) {
+      return sendError(
+        reply,
+        409,
+        "checkout_not_configured",
+        "This flow is not configured for checkout.",
+      );
+    }
+    const offer = register.offers?.find((o) => o.key === body.offerKey);
+    if (!offer) return sendError(reply, 400, "invalid_input", "Unknown offer.");
+
+    // 4. The email moment — session + lead (+ grant).
+    const capture = await captureRecommenderChoice({
+      siteId,
+      flowSlug: slug,
+      answers: body.answers,
+      email: body.email,
+      ...(body.locale !== undefined && { locale: body.locale }),
+      ...(body.sessionId !== undefined && { sessionId: body.sessionId }),
+      choice: "checkout",
+      sourceMeta: sourceMetaOf(request),
+    });
+    if (!capture.ok) return sendCaptureError(reply, capture.error);
+
+    // 5. The buyer row at the SERVER's price — the request carried no amount.
+    const permalink = encodePermalink({ version: PERMALINK_VERSION, flowSlug: slug, answers: body.answers });
+    const recorded = await recordCheckout({
+      siteId,
+      flowSlug: slug,
+      experimentKey: register.key,
+      sessionId: capture.sessionId,
+      leadId: capture.leadId,
+      email: body.email,
+      offerKey: body.offerKey,
+      seats: body.seats,
+      period: body.period,
+      creditStop: body.creditStop,
+      permalink,
+    });
+    if (!recorded.ok) {
+      const mapped = RECORD_CHECKOUT_STATUS[recorded.error.kind];
+      return sendError(reply, mapped.status, mapped.code, recorded.error.message);
+    }
+
+    // 5b. #4912 FR5 — an identical resubmission inside the idempotency window
+    //     replays the first attempt's session instead of opening a second one.
+    //     `replayed` is the union's discriminant, so the two Stripe fields are
+    //     non-null by construction here — there is no fall-through that could
+    //     open a second session for a request the service already replayed.
+    if (recorded.replayed) {
+      request.log.info(
+        {
+          slug,
+          flowCheckoutIdPrefix: prefix(recorded.flowCheckoutId),
+          stripeSessionIdPrefix: prefix(recorded.stripeSessionId),
+          outcome: "checkout_session_replayed",
+        },
+        "[recommender] checkout session replayed",
+      );
+      return reply
+        .status(201)
+        .send({ ok: true, data: { url: recorded.checkoutUrl, sessionId: recorded.stripeSessionId } });
+    }
+
+    // 6. Stripe — after the record exists, so an outage never loses it (FR6).
+    const locale = body.locale ?? capture.config.defaultLocale;
+    const productName = resolveLocalizedString(offer.copy.name, locale, capture.config.defaultLocale);
+    let session: { sessionId: string; url: string };
+    try {
+      session = await createQuotedCheckoutSession({
+        currency: recorded.currency,
+        unitAmount: recorded.amountMinor,
+        productName,
+        period: body.period,
+        customerEmail: body.email,
+        successUrl: body.successUrl,
+        cancelUrl: body.cancelUrl,
+        metadata: {
+          flowCheckoutId: recorded.flowCheckoutId,
+          flowSlug: slug,
+          offerKey: body.offerKey,
+          sessionId: capture.sessionId,
+          leadId: capture.leadId,
+          ...permalinkMetadata(permalink),
+        },
+      });
+    } catch (err) {
+      const logCtx = {
+        slug,
+        flowCheckoutIdPrefix: prefix(recorded.flowCheckoutId),
+        errName: err instanceof Error ? err.name : "unknown",
+      };
+      if (err instanceof StripeConfigError) {
+        request.log.error(logCtx, "[recommender] stripe config error");
+        return sendError(reply, 500, "config-error", "Stripe is not configured.");
+      }
+      request.log.error(logCtx, "[recommender] stripe error; checkout-unavailable");
+      return sendError(reply, 502, "checkout-unavailable", "Checkout is temporarily unavailable.");
+    }
+
+    const attached = await attachStripeSession(
+      siteId,
+      recorded.flowCheckoutId,
+      session.sessionId,
+      session.url,
+    );
+    if (attached.count !== 1) {
+      // The Stripe session exists but the row it must join on did not take
+      // the stamp — handing the visitor that URL would produce a payment the
+      // #4838 webhook cannot attribute. Refuse rather than 201.
+      //
+      // #4912 FR7 — and the session is live and payable until somebody closes
+      // it, so it is expired and the row marked dead BEFORE the 502 returns
+      // (#4863). Both compensations are best-effort: a failure is logged and
+      // the 502 still returns, because the visitor's answer does not change.
+      let sessionCompensation = "expired";
+      try {
+        await expireCheckoutSession(session.sessionId);
+      } catch (err) {
+        sessionCompensation = "expire_failed";
+        request.log.error(
+          {
+            slug,
+            flowCheckoutIdPrefix: prefix(recorded.flowCheckoutId),
+            errName: err instanceof Error ? err.name : "unknown",
+            outcome: "attach_miss_expire_failed",
+          },
+          "[recommender] could not expire the orphaned stripe session",
+        );
+      }
+      // The row mark uses the same `{ id, siteId }` match that just failed to
+      // attach, so it can legitimately match nothing — a zero count is not a
+      // throw, and reporting it as "expired" would make the audit trail lie.
+      let rowCompensation = "marked_expired";
+      try {
+        const marked = await expireFlowCheckout(siteId, recorded.flowCheckoutId);
+        if (marked.count !== 1) rowCompensation = "row_mark_missed";
+      } catch (err) {
+        rowCompensation = "row_mark_failed";
+        request.log.error(
+          {
+            slug,
+            flowCheckoutIdPrefix: prefix(recorded.flowCheckoutId),
+            errName: err instanceof Error ? err.name : "unknown",
+            outcome: "attach_miss_row_mark_failed",
+          },
+          "[recommender] could not mark the orphaned checkout row expired",
+        );
+      }
+      request.log.warn(
+        {
+          slug,
+          flowCheckoutIdPrefix: prefix(recorded.flowCheckoutId),
+          outcome: "attach_miss",
+          sessionCompensation,
+          rowCompensation,
+        },
+        "[recommender] stripe session id did not attach to the checkout row",
+      );
+      return sendError(reply, 502, "checkout-unavailable", "Checkout is temporarily unavailable.");
+    }
+
+    request.log.info(
+      {
+        slug,
+        sessionIdPrefix: prefix(capture.sessionId),
+        flowCheckoutIdPrefix: prefix(recorded.flowCheckoutId),
+        stripeSessionIdPrefix: prefix(session.sessionId),
+        outcome: "checkout_session_created",
+      },
+      "[recommender] checkout session created",
+    );
+    return reply.status(201).send({ ok: true, data: { url: session.url, sessionId: session.sessionId } });
+  });
+};