create-ailk 0.24.0 → 0.26.0

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

@@ -1,2028 +0,0 @@
-/**
- * POST /api/webhooks/stripe
- *
- * Receives Stripe webhook events. Verifies the signature on the raw
- * request body using the secret from STRIPE_WEBHOOK_SECRET. Dispatches
- * verified events through a `switch (event.type)` statement.
- *
- * Error mapping (in priority order):
- *   1. STRIPE_WEBHOOK_SECRET missing      → 503 webhook-not-configured
- *   2. Body is not a Buffer (parser miss) → 400 invalid-request
- *   3. Stripe-Signature header missing    → 400 signature-missing
- *   4. Signature verification fails       → 400 signature-invalid
- *
- * Commerce claim (D-64, #5796): the receiver is a base-tree primitive, so it
- * registers on every build and gates on the JWT `commerce` claim at call time.
- * The signature is settled FIRST (D3), then the claim is read as a TRI-STATE:
- *   - claimed      → every mapping below is byte-for-byte what it was
- *   - unclaimed    → a SIGNED event is acked 200 and dropped with a `warn`
- *                    log line so Stripe stops retrying; an unsigned or
- *                    unverifiable body gets the module-disabled 404,
- *                    indistinguishable from a build without commerce
- *   - undetermined → 503 + `Retry-After: 300`, so Stripe QUEUES and
- *                    redelivers. The read established no "no" (it threw, the
- *                    licence is revoked mid-window, or one is configured yet
- *                    no longer verifies), so this may be a live commerce site
- *                    whose buyer was already charged; dropping on such a read
- *                    loses the event permanently (security review 2026-09-16,
- *                    High, widened by the operator in round 2).
- * See README.md § Commerce claim.
- *
- * Successful dispatch always 200s — including unknown event types.
- * Telemetry failures are caught, logged, and do NOT change the response.
- *
- * Site filter (#7868):
- *   The Stripe account is shared with spoke sites, so this endpoint receives
- *   their Checkout sessions too. A `checkout.session.completed` or `.expired`
- *   whose `metadata.site` is a non-empty string naming another site
- *   (`isForeignSiteStamp`, lib/site.ts) takes no action: it logs
- *   `outcome: "foreign_site"` and answers 200. An unstamped session is the
- *   hub's own (roadmap D4) and is handled as before. The hub stamps its own
- *   sessions through `siteStamp()`. See README.md § Site filter (#7868).
- *   Since #8024 one gate before the switch does the same for every
- *   `customer.*`, `customer.subscription.*` and `invoice.*` event, reading the
- *   stamp from the Customer's or Subscription's own metadata — for an invoice,
- *   its own metadata and then the subscription snapshot under
- *   `parent.subscription_details` or (pre-`basil`) `subscription_details` —
- *   and only when `data.object.object` is the family's own type.
- *
- * Billing upsert (customer.created / checkout.session.completed):
- *   Billing-entity routing (org-scoped billing, #3601, spec D2): a checkout
- *   carrying metadata.organizationId takes the Organization path (multi-tenant
- *   module); absent → the User path (single-tenant).
- *
- *   Organization path (metadata.organizationId present) — proof-based since
- *   #9067 D13: the metadata names the target, the recorded session proves it.
- *     1. Typed composite match already pointing at this org → idempotent no-op
- *     2. A checkout.session.completed binds only when the Organization's
- *        `planCheckoutSessionId` is this session's id and no customer is
- *        bound yet (one guarded updateMany, which also clears the session)
- *     3. Anything else — an unrecorded session, a bound customer, any
- *        customer.created — logs org_bind_unproven and writes nothing
- *
- *   User path (no organizationId):
- *     1. Typed composite match: (billingProvider="stripe", billingCustomerId=customer)
- *     2. Verified user signal: metadata.ailk_user_id →
- *        User.findUnique({ where: { id } }) → bind only when the row's
- *        billingCustomerId is empty; otherwise log billing_identity_conflict
- *        and write nothing (#6113). No signal → log billing_identity_unverified,
- *        write nothing (#6852) — the payer-typed Checkout email never binds.
- *     3. Signal names no User → warn billing_identity_unknown_user; no row created
- *
- * Recommender purchase stamp (checkout.session.completed / .expired, #4838):
- *   A session carrying metadata.flowCheckoutId (the FlowCheckout buyer row
- *   #4841 opened it with) is stamped `completed` / `expired` by ONE guarded
- *   `updateMany` on `{ id, status: "created" }` — the durable idempotency key
- *   (D1): a replay, a restart between deliveries, or a late `expired` after a
- *   `completed` all match zero rows and log `stale_or_unknown`. Runs BESIDE the
- *   telemetry + billing tasks (D4), never instead of them; a charged/quoted
- *   mismatch is logged, never reconciled by overwrite (D2). Always 200. A
- *   `completed` session stamps only when `payment_status` is `"paid"` or
- *   `"no_payment_required"` (a 100%-off promo code, #4862) — anything else
- *   logs `outcome: "unpaid"` and leaves the row `created`.
- *
- * Proposal paid stamp (checkout.session.completed, #8516 D13):
- *   A session carrying the server-written `metadata.ailk_proposal` and
- *   `ailk_workspace` (the client's proposal Checkout,
- *   `services/proposal-payments.ts`) stamps that proposal's `paid_at` and
- *   `paid_session_id` once, through the base-tree boundary
- *   `lib/proposal-paid-store.ts` (this file names no `piece` delegate), and
- *   writes one `people.proposal.paid` audit row as the Stripe system actor
- *   keyed by the event id: `succeeded` when stamped, `failed`
- *   (`already_paid`) when a different session already paid it, none on a
- *   same-session replay, a `warn` when no such proposal exists, and `failed`
- *   (`not_paid`) with no stamp for a session that is not paid. A session
- *   without both keys makes no query. Runs BESIDE the other stamps; never
- *   throws; logs an 8-character prefix and the outcome only.
- *
- * Checkout Person (checkout.session.completed, #852 D6):
- *   Chained after that stamp, `recordFlowCheckoutPerson` finds or creates the
- *   Person of the checkout row THIS session completed (matched on its own
- *   `stripeSessionId`), with `session.customer` as the customer id only on a
- *   live-mode event. Logs an outcome kind only; never fails the 200.
- *
- * Checkout terms grant (checkout.session.completed, #8765 D14):
- *   Chained after the Person step, `recordCheckoutTermsGrant` records the
- *   buyer's acceptance of the session's terms box as one `checkout` row of
- *   the consent ledger — only for a session whose `consent.terms_of_service`
- *   is `accepted` and whose server-written `metadata.ailk_terms` names
- *   `account_terms` at its current version (a Payment Link, invoice or older
- *   session carries none), for the Person `checkoutBuyerPerson` resolves.
- *   Logs `{ event: "checkout-consent", outcome, eventIdPrefix }` only; never
- *   fails the 200.
- *
- * Dunning (invoice.payment_failed / customer.subscription.updated, #6034):
- *   Records a per-subscriber lifecycle state in a `UserData` row behind a
- *   reserved-key guard (routes/auth/user.ts). `invoice.payment_failed` arms
- *   dunning (`status: "past_due"`) and never revokes; `customer.subscription
- *   .updated` maps the narrowed status onto the same record, and `canceled`
- *   revokes access only once a per-tenant grace period (SiteSetting-backed,
- *   `services/dunning-policy.ts`) has lazily expired. See README.md
- *   § Dunning for the full state machine.
- */
-import { track } from "@working-theory/analytics/server";
-import type { Prisma } from "@working-theory/database";
-import { isId } from "@working-theory/ids";
-import {
-  ACCOUNT_TERMS_PURPOSE_ID,
-  consentPurposeById,
-  SITE_CONSENT_CONFIG_DEFAULTS,
-} from "@working-theory/validation";
-import type { FastifyReply, FastifyRequest } from "fastify";
-
-import { config } from "../../config/index.js";
-import { prisma } from "../../lib/prisma.js";
-import { stampProposalPaid as writeProposalPaid } from "../../lib/proposal-paid-store.js";
-import {
-  resolveCommerceClaim,
-  commerceDisabledResponse,
-  LICENSE_UNDETERMINED_BODY,
-  LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS,
-  LICENSE_UNDETERMINED_STATUS,
-} from "../../lib/require-commerce-claim.js";
-import {
-  currentSiteId,
-  isForeignSiteStamp,
-  SITE_STAMP_KEY,
-} from "../../lib/site.js";
-import {
-  stripeKeyMode,
-  StripeWebhookSignatureError,
-  toSubscriptionLifecycleStatus,
-  verifyWebhookSignature,
-} from "../../lib/stripe.js";
-import { hasSeen, markSeen } from "../../lib/webhook-idempotency.js";
-import { recordWorkspaceAuditAction } from "../../services/audit-log.js";
-import { checkoutBuyerPerson } from "../../services/checkout-buyer.js";
-import { recordCheckoutConsent } from "../../services/consent.js";
-import { isUniqueViolation } from "../../services/default-tenant.js";
-import {
-  DUNNING_MAX_SUBSCRIPTIONS,
-  DUNNING_USER_DATA_KEY,
-  dunningPolicyFor,
-  type DunningEntry,
-  type DunningRecord,
-} from "../../services/dunning-policy.js";
-import {
-  resolveCheckoutPerson,
-  type CheckoutPersonResult,
-} from "../../services/person.js";
-
-const TELEMETRY_TIMEOUT_MS = 2000;
-const DUNNING_WRITE_MAX_ATTEMPTS = 3;
-
-/**
- * Everything that must be true before an event is dispatched, evaluated as a
- * value rather than as an early `reply.send` — so the caller can settle the
- * signature BEFORE consulting the commerce claim (D3, #5796) without
- * duplicating any of the four rejections. The log lines ride along so a
- * held rejection still logs exactly what it logged before, and only when it
- * is the response actually sent.
- */
-type SettledSignature =
-  | { ok: true; event: ReturnType<typeof verifyWebhookSignature> }
-  | {
-      ok: false;
-      status: number;
-      body: { error: string };
-      log: (request: FastifyRequest) => void;
-    };
-
-function settleSignature(request: FastifyRequest): SettledSignature {
-  const secret = config.STRIPE_WEBHOOK_SECRET;
-  if (!secret) {
-    return {
-      ok: false,
-      status: 503,
-      body: { error: "webhook-not-configured" },
-      log: (req) =>
-        req.log.warn("stripe webhook hit but STRIPE_WEBHOOK_SECRET is not set"),
-    };
-  }
-
-  const rawBody = request.body;
-  if (!Buffer.isBuffer(rawBody)) {
-    return {
-      ok: false,
-      status: 400,
-      body: { error: "invalid-request" },
-      log: (req) =>
-        req.log.error(
-          "stripe webhook body is not a Buffer — content-type parser misconfigured",
-        ),
-    };
-  }
-
-  const signature = request.headers["stripe-signature"];
-  if (typeof signature !== "string" || signature.length === 0) {
-    return {
-      ok: false,
-      status: 400,
-      body: { error: "signature-missing" },
-      log: () => undefined,
-    };
-  }
-
-  try {
-    return {
-      ok: true,
-      event: verifyWebhookSignature(rawBody, signature, secret),
-    };
-  } catch (err) {
-    if (err instanceof StripeWebhookSignatureError) {
-      const reason = err.message;
-      return {
-        ok: false,
-        status: 400,
-        body: { error: "signature-invalid" },
-        log: (req) =>
-          req.log.warn(
-            { reason },
-            "stripe webhook signature verification failed",
-          ),
-      };
-    }
-    throw err;
-  }
-}
-
-export const stripeWebhookHandler = async (
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> => {
-  // ── Signature first, claim second (D3, #5796) ────────────────────────────
-  //
-  // The four pre-dispatch rejections above are SETTLED before the licence is
-  // consulted, so an unsigned or unverifiable body never decides anything on
-  // the strength of the claim. Their replies are held rather than sent, so
-  // the unclaimed branch below can answer the module-disabled 404 instead of
-  // leaking a configured-but-off shape.
-  const settled = settleSignature(request);
-  const claim = await resolveCommerceClaim();
-
-  if (claim === "undetermined") {
-    // The licence read established no "no" — it threw, the licence is revoked
-    // mid-window, or one IS configured yet no longer verifies. Any of those
-    // may be a live commerce site whose buyer was already charged. Never drop
-    // on a guess: 503 + `Retry-After` so Stripe QUEUES the event and
-    // redelivers it once the read succeeds (security review 2026-09-16, High,
-    // widened by the operator in round 2). Applies to a signed event and an
-    // unsigned body alike; the unsigned one was going to be refused either way.
-    request.log.warn(
-      {
-        outcome: "license_undetermined",
-        signatureVerified: settled.ok,
-        ...(settled.ok
-          ? {
-              eventType: settled.event.type,
-              eventIdPrefix: settled.event.id.substring(0, 8),
-            }
-          : {}),
-      },
-      "stripe webhook held — commerce licence could not be read; asking Stripe to retry",
-    );
-    await reply
-      .code(LICENSE_UNDETERMINED_STATUS)
-      .header("Retry-After", String(LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS))
-      .send(LICENSE_UNDETERMINED_BODY);
-    return;
-  }
-
-  if (claim === "unclaimed") {
-    if (settled.ok) {
-      // The licence was READ and positively does not carry `commerce`. Ack
-      // 200 and DROP: a 4xx here would have Stripe retry this event for days
-      // against a site that will never handle it. `warn`, not `info` — a
-      // discarded Stripe event is never routine.
-      request.log.warn(
-        {
-          eventType: settled.event.type,
-          eventIdPrefix: settled.event.id.substring(0, 8),
-          outcome: "dropped_no_commerce_claim",
-        },
-        "stripe webhook event dropped — deployment licence carries no commerce claim",
-      );
-      await reply.code(200).send({ received: true });
-      return;
-    }
-    // Unsigned / unverifiable AND unclaimed: answer exactly as a build
-    // without the commerce module did — the module-disabled 404.
-    const err = commerceDisabledResponse();
-    await reply.code(err.status).send(err.body);
-    return;
-  }
-
-  if (!settled.ok) {
-    settled.log(request);
-    await reply.code(settled.status).send(settled.body);
-    return;
-  }
-
-  const event = settled.event;
-  const eventIdPrefix = event.id.substring(0, 8);
-
-  // #8450 D10 (#6852 SEC-03) — an event whose livemode is not the key class
-  // this process admitted is never one of its own: a live hub must not act on
-  // a test-mode event anyone with the test key can forge, nor a test hub on a
-  // live one. Dropped before the idempotency check and any write; 200 so
-  // Stripe stops retrying, and NOT marked seen, so a corrected deployment
-  // still accepts a redelivery.
-  if ((event.livemode === true) !== (stripeKeyMode() === "live")) {
-    request.log.warn(
-      { eventType: event.type, eventIdPrefix, outcome: "livemode_mismatch" },
-      "stripe webhook event dropped — livemode differs from the admitted key class",
-    );
-    await reply.code(200).send({ received: true });
-    return;
-  }
-
-  // #8932 D9 (contract W8) — an Offerings-stamped event belongs to the
-  // per-Organization endpoint, which must still be able to act on it, so it
-  // is acked here BEFORE `markSeen` and nothing is written. Presence decides,
-  // whatever the value; any other event takes the path below unchanged.
-  if (
-    offeringsStampSourcesOf(event).some((source) =>
-      Object.hasOwn(source, OFFERINGS_STAMP_KEY),
-    )
-  ) {
-    request.log.info(
-      { eventType: event.type, eventIdPrefix, outcome: "offerings_path" },
-      "stripe webhook event left to the per-Organization endpoint",
-    );
-    await reply.code(200).send({ received: true });
-    return;
-  }
-
-  request.log.info(
-    { eventType: event.type, eventIdPrefix },
-    "stripe webhook event received",
-  );
-
-  // AILK-layer idempotency. Stripe guarantees at-least-once delivery and
-  // dashboard "resend" replays a previously-delivered event verbatim. Skip
-  // side effects on the second arrival; still 200 so Stripe stops retrying.
-  if (hasSeen(event.id)) {
-    request.log.info(
-      { eventType: event.type, eventIdPrefix },
-      "duplicate stripe webhook event — idempotent short-circuit",
-    );
-    await reply.code(200).send({ received: true });
-    return;
-  }
-  markSeen(event.id);
-
-  // #8024 — the billing families' site filter, after `markSeen` as #7868's
-  // in-arm check is, so a foreign redelivery is a duplicate. One gate rather
-  // than a check per arm: the `default` arm's types are filtered too.
-  const foreignStamp = siteStampSourcesOf(event).find(isForeignSiteStamp);
-  if (foreignStamp) {
-    logForeignSiteSkip(request, {
-      stamp: foreignStamp[SITE_STAMP_KEY],
-      eventType: event.type,
-      eventIdPrefix,
-    });
-    await reply.code(200).send({ received: true });
-    return;
-  }
-
-  switch (event.type) {
-    case "customer.created": {
-      const customer = event.data.object as {
-        id: string;
-        email?: string | null;
-        metadata?: Record<string, string> | null;
-      };
-      // Billing-entity routing (spec D2): metadata.organizationId present →
-      // the Organization path, which a customer's own metadata can never
-      // prove (#9067 D13: only a recorded plan session binds), so it writes
-      // nothing; absent → the User path (single-tenant, degrade-clean).
-      const organizationId = customer.metadata?.["organizationId"] ?? null;
-      if (organizationId) {
-        await upsertOrgBillingIdentity(request, {
-          organizationId,
-          customerId: customer.id,
-          sessionId: null,
-          eventIdPrefix,
-        });
-      } else {
-        await upsertBillingIdentity(request, {
-          customerId: customer.id,
-          userId: signalOf(customer.metadata),
-          eventType: event.type,
-          eventIdPrefix,
-        });
-      }
-      break;
-    }
-    case "checkout.session.completed": {
-      const session = event.data.object as CheckoutSessionObject;
-      if (isForeignSiteStamp(session.metadata)) {
-        logForeignSiteSkip(request, {
-          stamp: session.metadata?.[SITE_STAMP_KEY],
-          eventType: event.type,
-          eventIdPrefix,
-        });
-        break;
-      }
-      const props = {
-        amount: session.amount_total ?? undefined,
-        currency: session.currency ?? undefined,
-        productId:
-          session.metadata?.["productId"] ??
-          session.metadata?.["product_id"] ??
-          undefined,
-        eventType: event.type,
-        eventIdPrefix,
-      };
-
-      // Billing-entity routing (spec D2): metadata.organizationId → Organization
-      // path; absent → the User path (single-tenant).
-      const organizationId = session.metadata?.["organizationId"] ?? null;
-      let billingTask: Promise<void> = Promise.resolve();
-      if (session.customer) {
-        billingTask = organizationId
-          ? upsertOrgBillingIdentity(request, {
-              organizationId,
-              customerId: session.customer,
-              sessionId: session.id ?? null,
-              eventIdPrefix,
-            })
-          : upsertBillingIdentity(request, {
-              customerId: session.customer,
-              userId: signalOf(session.metadata),
-              eventType: event.type,
-              eventIdPrefix,
-            });
-      }
-
-      // Telemetry, billing upsert and the recommender stamp are independent —
-      // run in parallel (the stamp is a no-op without metadata.flowCheckoutId).
-      // Telemetry, billing upsert, the recommender stamp and the
-      // request-and-confirm stamp are independent — run in parallel. The
-      // request stamp is BESIDE the existing three, never instead of them,
-      // and is a no-op without `session.payment_link` (#5970).
-      await Promise.all([
-        fireTelemetryWithTimeout(request, "purchase-completed", props),
-        billingTask,
-        // #852 D6 — the Person step runs only after the stamp has settled,
-        // so it reads the row this very session completed.
-        stampFlowCheckout(request, {
-          session,
-          eventIdPrefix,
-          outcome: "completed",
-        })
-          .then(() =>
-            recordFlowCheckoutPerson(request, {
-              session,
-              livemode: event.livemode === true,
-              eventIdPrefix,
-            }),
-          )
-          // #8765 D14 — after the Person step, whose Person is a flow
-          // checkout's grant subject.
-          .then((flowPerson) =>
-            recordCheckoutTermsGrant(request, {
-              session,
-              livemode: event.livemode === true,
-              eventIdPrefix,
-              flowPerson,
-            }),
-          ),
-        stampRequestPaid(request, { session, eventIdPrefix }),
-        stampProposalPaid(request, { session, eventId: event.id, eventIdPrefix }),
-      ]);
-      break;
-    }
-    case "invoice.paid": {
-      // #5970 — the hosted-invoice rung of request-and-confirm. Nothing writes
-      // `stripeInvoiceId` at this issue's boundary (the invoice path needs a
-      // `createCustomer` export the stripe-client does not have), so this arm
-      // is INERT today and exists so that rung lands additively: no second
-      // migration, no second webhook change. It carries the same guarded
-      // stamp, so it is already correct when a writer appears.
-      const invoice = event.data.object as { id?: string };
-      await stampRequestPaidByInvoice(request, {
-        invoiceId: invoice.id ?? null,
-        eventIdPrefix,
-      });
-      break;
-    }
-    case "checkout.session.expired": {
-      const session = event.data.object as CheckoutSessionObject;
-      if (isForeignSiteStamp(session.metadata)) {
-        logForeignSiteSkip(request, {
-          stamp: session.metadata?.[SITE_STAMP_KEY],
-          eventType: event.type,
-          eventIdPrefix,
-        });
-        break;
-      }
-      if (!session.metadata?.["flowCheckoutId"]) {
-        // Not a recommender session — the same low-noise line the default
-        // arm emitted for this event before #4838 handled it.
-        request.log.info(
-          { eventType: event.type, eventIdPrefix },
-          "unhandled webhook event",
-        );
-        break;
-      }
-      await stampFlowCheckout(request, {
-        session,
-        eventIdPrefix,
-        outcome: "expired",
-      });
-      break;
-    }
-    case "invoice.payment_failed": {
-      // Dunning arm 1 of 2 (#6034 FR-1) — arms dunning for the matched
-      // subscriber; never revokes on its own. See README.md § Dunning.
-      const invoice = event.data.object as InvoiceObject;
-      await armDunning(request, {
-        invoice,
-        eventId: event.id,
-        eventCreated: event.created,
-        eventIdPrefix,
-      });
-      break;
-    }
-    case "customer.subscription.updated": {
-      // Dunning arm 2 of 2 (#6034 FR-2/FR-4) — maps the narrowed Stripe
-      // status onto the recorded lifecycle state; `canceled` revokes access
-      // only once the tenant's grace period has expired. See README.md
-      // § Dunning.
-      const subscription = event.data.object as SubscriptionObject;
-      await applySubscriptionStatus(request, {
-        subscription,
-        eventId: event.id,
-        eventCreated: event.created,
-        eventIdPrefix,
-      });
-      break;
-    }
-    default:
-      request.log.info(
-        { eventType: event.type, eventIdPrefix },
-        "unhandled webhook event",
-      );
-      break;
-  }
-
-  await reply.code(200).send({ received: true });
-};
-
-type CheckoutSessionObject = {
-  id?: string;
-  /**
-   * Set when the session was opened UNDER a Payment Link — which is how a
-   * request-and-confirm purchase arrives (#5970 D8). It is the artifact id
-   * AC-3 matches on, and it is absent on an ordinary checkout.
-   */
-  payment_link?: string | null;
-  payment_status?: string | null;
-  amount_total?: number | null;
-  currency?: string | null;
-  customer?: string | null;
-  customer_details?: { email?: string | null } | null;
-  /** The terms box's answer (#8765 D14): `accepted` when the buyer ticked it. */
-  consent?: { terms_of_service?: string | null } | null;
-  metadata?: Record<string, string> | null;
-};
-
-/**
- * The one log line for an event another site stamped (#7868 D3, #8024 D3).
- * Carries the foreign stamp (first 64 characters) and this site's own alias,
- * so a spoke event correctly skipped can be told from a hub event whose alias
- * drifted — site labels only: it takes the stamp, never the object, so no
- * buyer field, customer id or amount can reach it.
- */
-function logForeignSiteSkip(
-  request: FastifyRequest,
-  {
-    stamp,
-    eventType,
-    eventIdPrefix,
-  }: {
-    stamp: string | undefined;
-    eventType: string;
-    eventIdPrefix: string;
-  },
-): void {
-  request.log.info(
-    {
-      eventType,
-      eventIdPrefix,
-      outcome: "foreign_site",
-      stamp: stamp?.slice(0, 64),
-      ownSite: currentSiteId(),
-    },
-    "stripe event stamped for another site — skipped",
-  );
-}
-
-/** The object type whose metadata carries the site for each billing family (#8024 D2). */
-function stampedObjectTypeOf(eventType: string): "subscription" | "customer" | "invoice" | null {
-  if (eventType.startsWith("customer.subscription.")) return "subscription";
-  if (eventType.startsWith("customer.")) return "customer";
-  if (eventType.startsWith("invoice.")) return "invoice";
-  return null;
-}
-
-/** `value` when it is a non-null object, else `null` — every step of a stamp read is guarded (NF1). */
-function objectOrNull(value: unknown): Record<string, unknown> | null {
-  return typeof value === "object" && value !== null
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
-/**
- * The metadata objects that may carry an event's site stamp (#8024 D2), in the
- * order they are checked: a Subscription's or a Customer's own metadata; an
- * invoice's own metadata, then the subscription snapshot at the pinned API
- * version (`parent.subscription_details.metadata`), then at a pre-`basil` one
- * (`subscription_details.metadata`). Empty for every other event type, and
- * when `data.object.object` is not the family's own type — a
- * `customer.source.*` card, say. Reads the payload alone and never throws on
- * any shape: an absent, `null` or non-object step yields no source, and
- * `isForeignSiteStamp` treats a non-string stamp as unstamped.
- */
-function siteStampSourcesOf(event: {
-  type: string;
-  data?: unknown;
-}): Record<string, string>[] {
-  const objectType = stampedObjectTypeOf(event.type);
-  const object = objectOrNull(objectOrNull(event.data)?.["object"]);
-  if (objectType === null || object?.["object"] !== objectType) return [];
-
-  const candidates =
-    objectType === "invoice"
-      ? [
-          object["metadata"],
-          objectOrNull(objectOrNull(object["parent"])?.["subscription_details"])?.[
-            "metadata"
-          ],
-          objectOrNull(object["subscription_details"])?.["metadata"],
-        ]
-      : [object["metadata"]];
-  // The cast only narrows the value type for `isForeignSiteStamp`, which
-  // reads the stamp as `unknown` and `typeof`-checks it.
-  return candidates
-    .map(objectOrNull)
-    .filter((source) => source !== null) as Record<string, string>[];
-}
-
-/** The metadata key the hub's Offerings checkout stamps on its sessions (contract A6, #8932 D9). */
-const OFFERINGS_STAMP_KEY = "ailk_offering";
-
-/**
- * Where an Offerings stamp may sit (#8932 D9): every site-stamp source
- * (`siteStampSourcesOf` — the Subscription, the Customer and an invoice's
- * three) plus, for a `checkout.session.*` event whose object is a session,
- * the session's own metadata.
- */
-function offeringsStampSourcesOf(event: {
-  type: string;
-  data?: unknown;
-}): Record<string, string>[] {
-  const sources = siteStampSourcesOf(event);
-  const object = objectOrNull(objectOrNull(event.data)?.["object"]);
-  if (event.type.startsWith("checkout.session.") && object?.["object"] === "checkout.session") {
-    const metadata = objectOrNull(object["metadata"]);
-    if (metadata !== null) sources.push(metadata as Record<string, string>);
-  }
-  return sources;
-}
-
-/**
- * Minimal projected shape of a Stripe Invoice object for the dunning arms
- * (#6034 FR-1). `subscription` and `customer` are EXPANDABLE Stripe fields —
- * like `CheckoutSessionObject.payment_link` above, either can arrive as an
- * object rather than a string on a future `expand` or API-version change, so
- * both are `typeof`-guarded at the call site (§ D9) and never trusted from
- * this cast.
- */
-type InvoiceObject = {
-  subscription?: string | null;
-  customer?: string | null;
-};
-
-/**
- * Minimal projected shape of a Stripe Subscription object for the dunning
- * arms (#6034 FR-2). `customer` carries the same expandable-field risk as
- * `InvoiceObject.customer` and is guarded the same way.
- */
-type SubscriptionObject = {
-  id?: string;
-  customer?: string | null;
-  status?: string;
-  canceled_at?: number | null;
-  ended_at?: number | null;
-};
-
-/**
- * Stamp the recommender's FlowCheckout buyer row from a terminal Checkout
- * Session event (#4838).
- *
- * The `status: "created"` guard on the update IS the idempotency key (D1):
- * `count === 1` → stamped; `count === 0` → the row is already terminal, or the
- * id is unknown — a warning, never a retry (Stripe would re-fire telemetry +
- * billing on eventual success). A `completed` session whose
- * `payment_status` is not `"paid"` logs `unpaid` and leaves the row `created`. A charged amount that differs from the quoted
- * `amountMinor` is logged with both integers and the stamp proceeds (D2). Log
- * lines carry only `eventIdPrefix`, an 8-char `flowCheckoutIdPrefix`, an
- * `outcome`, and the two integers — never the email, customer id, or permalink.
- *
- * Never throws — the handler's "always 200 for a verified event" contract.
- */
-async function stampFlowCheckout(
-  request: FastifyRequest,
-  {
-    session,
-    eventIdPrefix,
-    outcome,
-  }: {
-    session: CheckoutSessionObject;
-    eventIdPrefix: string;
-    outcome: "completed" | "expired";
-  },
-): Promise<void> {
-  const flowCheckoutId = session.metadata?.["flowCheckoutId"];
-  if (!flowCheckoutId) return;
-  const flowCheckoutIdPrefix = flowCheckoutId.substring(0, 8);
-
-  // A `completed` session is only a purchase once Stripe reports it paid, OR
-  // reports nothing was due (`no_payment_required` — a 100%-off promo code,
-  // #4862, still a Stripe-confirmed completion). A delayed-notification or
-  // genuinely unpaid completion leaves the row `created` (code + security
-  // review, PR #4855).
-  if (
-    outcome === "completed" &&
-    session.payment_status !== "paid" &&
-    session.payment_status !== "no_payment_required"
-  ) {
-    request.log.warn(
-      { eventIdPrefix, flowCheckoutIdPrefix, outcome: "unpaid" },
-      "flow checkout: completed session is not paid — not stamping",
-    );
-    return;
-  }
-
-  try {
-    if (outcome === "completed" && typeof session.amount_total === "number") {
-      const row = await prisma.flowCheckout.findUnique({
-        where: { id: flowCheckoutId },
-        select: { amountMinor: true },
-      });
-      if (row && row.amountMinor !== session.amount_total) {
-        request.log.warn(
-          {
-            eventIdPrefix,
-            flowCheckoutIdPrefix,
-            outcome: "amount_mismatch",
-            expected: row.amountMinor,
-            received: session.amount_total,
-          },
-          "flow checkout: charged amount differs from the quoted amount — stamping anyway",
-        );
-      }
-    }
-
-    const result = await prisma.flowCheckout.updateMany({
-      where: { id: flowCheckoutId, status: "created" },
-      data:
-        outcome === "completed"
-          ? {
-              status: "completed",
-              completedAt: new Date(),
-              stripeSessionId: session.id ?? null,
-              stripeCustomerId: session.customer ?? null,
-            }
-          : { status: "expired" },
-    });
-
-    if (result.count === 1) {
-      request.log.info(
-        { eventIdPrefix, flowCheckoutIdPrefix, outcome },
-        "flow checkout stamped",
-      );
-    } else {
-      request.log.warn(
-        { eventIdPrefix, flowCheckoutIdPrefix, outcome: "stale_or_unknown" },
-        "flow checkout: no created row matched — replay, late terminal event, or unknown id",
-      );
-    }
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        flowCheckoutIdPrefix,
-        outcome: "stamp_failed",
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "flow checkout stamp failed — continuing",
-    );
-  }
-}
-
-/**
- * The hub checkout's Person (#852 D6): after `stampFlowCheckout`, find or
- * create the Person of the completed checkout's lead
- * (`services/person.ts`'s `resolveCheckoutPerson`). Runs only for a paid (or
- * nothing-due) session of THIS site — the foreign-site filter has already
- * returned — that carries `metadata.flowCheckoutId`. The customer id's ONE
- * source is `session.customer`, written onto the Person only for a
- * live-mode event (SEC-852-A). A replay matches the same completed row, so a
- * delivery whose Person step failed is repaired by the next one.
- *
- * Logs `{ eventIdPrefix, flowCheckoutIdPrefix, outcome }` only — never the
- * email or the customer id. Answers the Person, or `null` when the step did
- * not run or found none (#8765 D14). Never throws: the response stays 200.
- */
-async function recordFlowCheckoutPerson(
-  request: FastifyRequest,
-  {
-    session,
-    livemode,
-    eventIdPrefix,
-  }: {
-    session: CheckoutSessionObject;
-    livemode: boolean;
-    eventIdPrefix: string;
-  },
-): Promise<CheckoutPersonResult["person"]> {
-  const flowCheckoutId = session.metadata?.["flowCheckoutId"];
-  if (!flowCheckoutId) return null;
-  if (
-    session.payment_status !== "paid" &&
-    session.payment_status !== "no_payment_required"
-  ) {
-    return null;
-  }
-  const flowCheckoutIdPrefix = flowCheckoutId.substring(0, 8);
-  let result: CheckoutPersonResult;
-  try {
-    result = await resolveCheckoutPerson({
-      flowCheckoutId,
-      stripeSessionId: session.id,
-      customer: session.customer,
-      livemode,
-    });
-  } catch {
-    result = { outcome: "person_failed", person: null };
-  }
-  const line = { eventIdPrefix, flowCheckoutIdPrefix, outcome: result.outcome };
-  if (result.outcome === "person_failed") {
-    request.log.error(line, "flow checkout person failed — continuing");
-  } else {
-    request.log.info(line, "flow checkout person");
-  }
-  return result.person;
-}
-
-/** The metadata key the Checkout creators stamp with the terms the box showed (#8765 D12). */
-const TERMS_STAMP_KEY = "ailk_terms";
-
-/**
- * `<purposeId>@<policyVersion>` of the account terms as the registry reads
- * them now — the only stamp a grant is recorded for (SEC-8765-E) — and that
- * version, which `recordCheckoutConsent` checks against the site's registry.
- * Derived, never written down, so a version bump retires every older stamp.
- */
-function currentTermsStamp(): { stamp: string; policyVersion: number } | null {
-  const purpose = consentPurposeById(
-    SITE_CONSENT_CONFIG_DEFAULTS,
-    ACCOUNT_TERMS_PURPOSE_ID,
-  );
-  return purpose
-    ? {
-        stamp: `${purpose.id}@${purpose.policyVersion}`,
-        policyVersion: purpose.policyVersion,
-      }
-    : null;
-}
-
-/**
- * The buyer's terms grant (#8765 D14). Writes nothing — and logs why — for a
- * session whose box was not accepted (`consent_absent`: Stripe enforced the
- * box, so the order completes regardless), one that does not carry the
- * current `ailk_terms` stamp (`terms_unstamped`: a Payment Link, an invoice,
- * an older session or other terms), or one whose buyer has no Person
- * (`person_unresolved`). Otherwise `recordCheckoutConsent` writes at most one
- * row per Person and session (`recorded` / `unchanged`), or none when the
- * site's registry has moved past the stamped version (`version_changed`).
- *
- * Logs `{ event, outcome, eventIdPrefix }` only (plus `errName` on `failed`)
- * — never an email or a Person id. Never throws: the response stays 200.
- */
-async function recordCheckoutTermsGrant(
-  request: FastifyRequest,
-  {
-    session,
-    livemode,
-    eventIdPrefix,
-    flowPerson,
-  }: {
-    session: CheckoutSessionObject;
-    livemode: boolean;
-    eventIdPrefix: string;
-    /** A flow checkout's Person, from `recordFlowCheckoutPerson`. */
-    flowPerson: CheckoutPersonResult["person"];
-  },
-): Promise<void> {
-  const line = (outcome: string) => ({
-    event: "checkout-consent",
-    outcome,
-    eventIdPrefix,
-  });
-  try {
-    if (session.consent?.terms_of_service !== "accepted") {
-      request.log.info(
-        line("consent_absent"),
-        "checkout terms grant: box not accepted",
-      );
-      return;
-    }
-    const stamp: unknown = session.metadata?.[TERMS_STAMP_KEY];
-    const expected = currentTermsStamp();
-    if (expected === null || stamp !== expected.stamp) {
-      request.log.info(
-        line("terms_unstamped"),
-        "checkout terms grant: session carries no current terms stamp",
-      );
-      return;
-    }
-    const sessionId = session.id;
-    const buyer =
-      typeof sessionId === "string" && sessionId !== ""
-        ? await checkoutBuyerPerson(session, livemode, flowPerson)
-        : null;
-    if (buyer === null || typeof sessionId !== "string") {
-      request.log.info(
-        line("person_unresolved"),
-        "checkout terms grant: no Person for this buyer",
-      );
-      return;
-    }
-    const outcome = await recordCheckoutConsent({
-      workspaceId: buyer.workspaceId,
-      personId: buyer.personId,
-      sessionId,
-      policyVersion: expected.policyVersion,
-    });
-    request.log.info(line(outcome), "checkout terms grant");
-  } catch (err) {
-    // The error's class only (a Prisma error's message can carry values).
-    request.log.error(
-      {
-        ...line("failed"),
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "checkout terms grant failed — continuing",
-    );
-  }
-}
-
-/**
- * Stamp `paidAt` on a request-and-confirm callback row (#5970 AC-3).
- *
- * THE MATCH KEY IS THE ARTIFACT ID, not metadata. Paying a Payment Link opens
- * a Checkout Session under that link, so the paid event is the ordinary
- * `checkout.session.completed` — and the session carries
- * `payment_link: "plink_…"`, which is exactly the id the confirm route stored
- * on the row. A session with no `payment_link` is an ordinary checkout and is
- * skipped BEFORE any query, so the existing checkout suites see no new DB
- * traffic whatsoever.
- *
- * TWO IDEMPOTENCY LAYERS, and only the second is durable. A replayed event
- * never reaches here at all — `hasSeen` short-circuits it upstream. But that
- * store is an in-process TTL `Map`: restart the process and the id is gone. So
- * the `paidAt: null` guard on the update IS the idempotency key, the same way
- * `status: "created"` is `stampFlowCheckout`'s. `count === 1` ⇒ stamped once;
- * `count === 0` ⇒ already paid, or an id this deployment never minted — a
- * warning, never a throw and never a retry (Stripe would re-fire the sibling
- * telemetry and billing tasks on eventual success).
- *
- * A `completed` session stamps only when Stripe reports it `paid`, or reports
- * nothing was due (`no_payment_required` — a 100%-off promotion is still a
- * Stripe-confirmed completion). The same two values `stampFlowCheckout`
- * accepts, for the same reason.
- *
- * `stripeCheckoutSessionId` is written from the same event for support
- * lookups. Nothing ever matches on it.
- *
- * Never throws — the handler's "always 200 for a verified event" contract.
- */
-async function stampRequestPaid(
-  request: FastifyRequest,
-  {
-    session,
-    eventIdPrefix,
-  }: { session: CheckoutSessionObject; eventIdPrefix: string },
-): Promise<void> {
-  const paymentLinkId = session.payment_link;
-  // `typeof`, not just truthiness (#5970 security review, finding 7):
-  // `payment_link` is an EXPANDABLE Stripe field, so a future `expand` or an
-  // API-version change could deliver it as an object — on which `.substring`
-  // throws a TypeError that would escape this function, reject the
-  // `Promise.all` above, and turn a verified event into a 500 that Stripe then
-  // retries, taking the sibling telemetry and billing tasks down with it. This
-  // function's contract is that it never throws.
-  if (typeof paymentLinkId !== "string" || paymentLinkId === "") return;
-  const paymentLinkIdPrefix = paymentLinkId.substring(0, 8);
-
-  if (
-    session.payment_status !== "paid" &&
-    session.payment_status !== "no_payment_required"
-  ) {
-    request.log.warn(
-      { eventIdPrefix, paymentLinkIdPrefix, outcome: "unpaid" },
-      "request-confirm: completed session is not paid — not stamping",
-    );
-    return;
-  }
-
-  try {
-    const result = await prisma.callback.updateMany({
-      where: { stripePaymentLinkId: paymentLinkId, paidAt: null },
-      data: {
-        paidAt: new Date(),
-        stripeCheckoutSessionId: session.id ?? null,
-      },
-    });
-
-    if (result.count === 1) {
-      request.log.info(
-        { eventIdPrefix, paymentLinkIdPrefix, outcome: "paid" },
-        "request-confirm stamped paid",
-      );
-    } else {
-      request.log.warn(
-        { eventIdPrefix, paymentLinkIdPrefix, outcome: "stale_or_unknown" },
-        "request-confirm: no unpaid row matched — replay, late event, or an unknown payment link",
-      );
-    }
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        paymentLinkIdPrefix,
-        outcome: "stamp_failed",
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "request-confirm stamp failed — continuing",
-    );
-  }
-}
-
-/**
- * #8516 D13 — stamp a client's proposal paid from its own Checkout Session,
- * and audit the outcome as Stripe. The two ids come only from the session's
- * metadata, which this server wrote when it opened the session — a payer can
- * never set it — and the stamp is scoped by both. Never throws.
- */
-async function stampProposalPaid(
-  request: FastifyRequest,
-  {
-    session,
-    eventId,
-    eventIdPrefix,
-  }: { session: CheckoutSessionObject; eventId: string; eventIdPrefix: string },
-): Promise<void> {
-  const pieceId = session.metadata?.["ailk_proposal"];
-  const workspaceId = session.metadata?.["ailk_workspace"];
-  const sessionId = session.id;
-  if (
-    typeof pieceId !== "string" ||
-    typeof workspaceId !== "string" ||
-    typeof sessionId !== "string" ||
-    !isId("piece", pieceId) ||
-    !isId("workspace", workspaceId)
-  ) {
-    return;
-  }
-  const ref = pieceId.substring(6, 14);
-
-  const audit = async (outcome: { ok: true } | { ok: false; reason: string }) => {
-    const result = await recordWorkspaceAuditAction({
-      workspaceId,
-      actor: { type: "system", systemId: "stripe" },
-      domain: "people",
-      tool: "proposal.paid",
-      outcome: outcome.ok ? "succeeded" : "failed",
-      ...(!outcome.ok && { failureReason: outcome.reason }),
-      idempotencyKey: eventId,
-      targetType: "piece",
-      targetId: pieceId,
-    });
-    if (!result.ok) {
-      request.log.error(
-        { eventIdPrefix, ref, error: result.error.kind },
-        "proposal paid: audit write failed",
-      );
-    }
-  };
-
-  if (
-    session.payment_status !== "paid" &&
-    session.payment_status !== "no_payment_required"
-  ) {
-    request.log.warn(
-      { eventIdPrefix, ref, outcome: "not_paid" },
-      "proposal paid: completed session is not paid — not stamping",
-    );
-    await audit({ ok: false, reason: "not_paid" });
-    return;
-  }
-
-  try {
-    const outcome = await writeProposalPaid(workspaceId, pieceId, sessionId, new Date());
-    if (outcome === "stamped") {
-      request.log.info({ eventIdPrefix, ref, outcome }, "proposal stamped paid");
-      await audit({ ok: true });
-    } else if (outcome === "already_paid") {
-      request.log.warn(
-        { eventIdPrefix, ref, outcome },
-        "proposal paid: already paid by another session — a second charge",
-      );
-      await audit({ ok: false, reason: "already_paid" });
-    } else if (outcome === "not_found") {
-      request.log.warn({ eventIdPrefix, ref, outcome }, "proposal paid: no such proposal");
-    } else {
-      request.log.info({ eventIdPrefix, ref, outcome }, "proposal paid: replay");
-    }
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        ref,
-        outcome: "stamp_failed",
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "proposal paid stamp failed — continuing",
-    );
-  }
-}
-
-/**
- * The hosted-invoice twin of `stampRequestPaid` (#5970 D4/D8).
- *
- * Inert at this issue's boundary — nothing writes `stripeInvoiceId` yet — and
- * deliberately present anyway, carrying the identical guarded update, so the
- * invoice rung is a writer away rather than a migration and a webhook change
- * away.
- */
-async function stampRequestPaidByInvoice(
-  request: FastifyRequest,
-  {
-    invoiceId,
-    eventIdPrefix,
-  }: { invoiceId: string | null; eventIdPrefix: string },
-): Promise<void> {
-  // The same `typeof` guard its Payment-Link sibling carries, for the same
-  // reason (#5970 security review round 2, L1): this arm is explicitly
-  // forward-looking, so the hardening has to travel with it rather than be
-  // added when a writer appears and the shape stops being guaranteed.
-  if (typeof invoiceId !== "string" || invoiceId === "") return;
-  const invoiceIdPrefix = invoiceId.substring(0, 8);
-
-  try {
-    const result = await prisma.callback.updateMany({
-      where: { stripeInvoiceId: invoiceId, paidAt: null },
-      data: { paidAt: new Date() },
-    });
-
-    if (result.count === 1) {
-      request.log.info(
-        { eventIdPrefix, invoiceIdPrefix, outcome: "paid" },
-        "request-confirm stamped paid from invoice",
-      );
-      return;
-    }
-    // An unmatched `invoice.paid` is the ORDINARY case today and for every
-    // deployment using Stripe invoices for anything else, so this is `info`
-    // rather than the `warn` its Payment-Link sibling emits.
-    request.log.info(
-      { eventIdPrefix, invoiceIdPrefix, outcome: "not_a_request_invoice" },
-      "request-confirm: invoice.paid matched no request row",
-    );
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        invoiceIdPrefix,
-        outcome: "stamp_failed",
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "request-confirm invoice stamp failed — continuing",
-    );
-  }
-}
-
-/**
- * The verified user signal (#6852): `metadata.ailk_user_id` on the Checkout
- * session or the Stripe customer, when it is a non-empty string. Never
- * `client_reference_id` (a Payment Link accepts it from the payer's URL) and
- * never the payer-typed email.
- */
-function signalOf(
-  metadata: Record<string, string> | null | undefined,
-): string | null {
-  const value: unknown = metadata?.["ailk_user_id"];
-  return typeof value === "string" && value !== "" ? value : null;
-}
-
-/**
- * Link User.billingProvider + User.billingCustomerId for a Stripe customer.
- *
- * Lookup priority:
- *   1. Typed composite match: (billingProvider="stripe", billingCustomerId=customerId)
- *      → already linked; no-op (idempotent)
- *   2. Verified user signal (#6852): `metadata.ailk_user_id` →
- *      User.findUnique({ where: { id } }) → bind only when the row's
- *      billingCustomerId is empty; otherwise log billing_identity_conflict and
- *      write nothing (#6113). The write is guarded on `billingCustomerId: null`;
- *      a P2025 means a concurrent event bound the row first — the same customer
- *      is a no-op, any other is a conflict.
- *      No signal → log billing_identity_unverified and write nothing. The payer
- *      types the Checkout email and Stripe never verifies it, so an email
- *      never makes a binding, first or otherwise.
- *      Trust boundary: Checkout-session and customer `metadata` can be written
- *      only by a principal the seller authorised on their Stripe account (our
- *      server's key, a write-capable restricted key, a connected app, the
- *      dashboard, a Payment Link's own metadata) — never by the payer. A
- *      producer sets the key only from an authenticated server session, never
- *      from request input.
- *   3. Signal names no User → warn billing_identity_unknown_user; do NOT
- *      create a User row (pre-signup state preserved for Phase B #852)
- *
- * No line logs the email, the Stripe customer id, or an unresolved signal.
- *
- * DB failures are caught and logged — a broken DB link should not cause Stripe to retry
- * the event (which would fire analytics + billing again on eventual success).
- */
-async function upsertBillingIdentity(
-  request: FastifyRequest,
-  {
-    customerId,
-    userId,
-    eventType,
-    eventIdPrefix,
-  }: {
-    customerId: string;
-    userId: string | null;
-    eventType: string;
-    eventIdPrefix: string;
-  },
-): Promise<void> {
-  try {
-    const existingByBilling = await prisma.user.findFirst({
-      where: {
-        billingProvider: "stripe",
-        billingCustomerId: customerId,
-      },
-      select: { id: true },
-    });
-
-    if (existingByBilling) {
-      request.log.info(
-        { eventIdPrefix },
-        "billing identity already linked — idempotent no-op",
-      );
-      return;
-    }
-
-    if (!userId) {
-      // A customer Checkout creates never carries session metadata, so a
-      // no-signal customer.created is every ordinary purchase — info, not warn.
-      const fields = {
-        eventIdPrefix,
-        eventType,
-        outcome: "billing_identity_unverified",
-      };
-      const msg =
-        "stripe webhook: no verified user signal — billing identity not bound";
-      if (eventType === "customer.created") request.log.info(fields, msg);
-      else request.log.warn(fields, msg);
-      return;
-    }
-
-    const row = await prisma.user.findUnique({
-      where: { id: userId },
-      select: { id: true, billingProvider: true, billingCustomerId: true },
-    });
-
-    if (!row) {
-      request.log.warn(
-        { eventIdPrefix, eventType, outcome: "billing_identity_unknown_user" },
-        "stripe webhook: user signal names no User — pre-signup state preserved",
-      );
-      return;
-    }
-
-    const isSameBinding = (r: {
-      billingProvider: string | null;
-      billingCustomerId: string | null;
-    }) => r.billingProvider === "stripe" && r.billingCustomerId === customerId;
-    const logAlreadyLinked = () =>
-      request.log.info(
-        { eventIdPrefix, outcome: "billing_identity_already_linked" },
-        "billing identity already linked — idempotent no-op",
-      );
-    const logConflict = () =>
-      request.log.warn(
-        {
-          eventIdPrefix,
-          outcome: "billing_identity_conflict",
-          userId: row.id,
-        },
-        "stripe webhook: user already bound to a different billing customer — not re-pointed",
-      );
-
-    if (row.billingCustomerId !== null) {
-      if (isSameBinding(row)) logAlreadyLinked();
-      else logConflict();
-      return;
-    }
-
-    try {
-      await prisma.user.update({
-        where: { id: row.id, billingCustomerId: null },
-        data: {
-          billingProvider: "stripe",
-          billingCustomerId: customerId,
-        },
-      });
-    } catch (err) {
-      if ((err as { code?: unknown }).code !== "P2025") throw err;
-      const now = await prisma.user.findUnique({
-        where: { id: row.id },
-        select: { billingProvider: true, billingCustomerId: true },
-      });
-      if (now && isSameBinding(now)) logAlreadyLinked();
-      else logConflict();
-      return;
-    }
-    request.log.info(
-      { eventIdPrefix },
-      "billing identity linked via verified user signal",
-    );
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        error: err instanceof Error ? err.message : String(err),
-      },
-      "billing identity upsert failed — continuing",
-    );
-  }
-}
-
-/**
- * Link Organization.billingProvider + billingCustomerId for a Stripe customer
- * (org-scoped billing, #3601, spec D2/D3), only on proof (#9067 D13,
- * SEC-9067-1 to -3). `metadata.organizationId` names the target; the proof
- * is the session id POST /v1/billing/plan-checkout recorded on that
- * Organization. The bind is one guarded `updateMany` on `{ id,
- * planCheckoutSessionId: sessionId, billingCustomerId: null }`, which also
- * clears the recorded session — so a session no route recorded, a session
- * recorded by another deployment's database, a re-point of a bound customer
- * and a `customer.created` (`sessionId` null: a customer's metadata proves
- * nothing) all bind nothing and log `org_bind_unproven`.
- *
- * Idempotent: a typed-composite match (billingProvider="stripe",
- * billingCustomerId=customerId) already pointing at THIS org is a no-op on
- * replay.
- *
- * DB failures are caught and logged (never re-thrown) — a broken link must not
- * make Stripe retry (which would re-fire analytics + billing on eventual
- * success), matching the User-path contract above.
- */
-async function upsertOrgBillingIdentity(
-  request: FastifyRequest,
-  {
-    organizationId,
-    customerId,
-    sessionId,
-    eventIdPrefix,
-  }: {
-    organizationId: string;
-    customerId: string;
-    sessionId: string | null;
-    eventIdPrefix: string;
-  },
-): Promise<void> {
-  const unproven = () =>
-    request.log.warn(
-      { eventIdPrefix, outcome: "org_bind_unproven" },
-      "org billing identity not linked — no recorded plan checkout proves it",
-    );
-  if (sessionId === null) {
-    unproven();
-    return;
-  }
-  try {
-    const existingByBilling = await prisma.organization.findFirst({
-      where: {
-        billingProvider: "stripe",
-        billingCustomerId: customerId,
-      },
-      select: { id: true },
-    });
-
-    if (existingByBilling && existingByBilling.id === organizationId) {
-      request.log.info(
-        { eventIdPrefix },
-        "org billing identity already linked — idempotent no-op",
-      );
-      return;
-    }
-
-    const { count } = await prisma.organization.updateMany({
-      where: { id: organizationId, planCheckoutSessionId: sessionId, billingCustomerId: null },
-      data: {
-        billingProvider: "stripe",
-        billingCustomerId: customerId,
-        planCheckoutSessionId: null,
-      },
-    });
-    if (count !== 1) {
-      unproven();
-      return;
-    }
-    request.log.info(
-      { eventIdPrefix },
-      "org billing identity linked from the recorded plan checkout",
-    );
-  } catch (err) {
-    // #9067 FR-6 — the name and Prisma code only: some Prisma messages
-    // print the call's arguments, which here carry the session and customer ids.
-    request.log.error(
-      {
-        eventIdPrefix,
-        errName: err instanceof Error ? err.name : "unknown",
-        code: (err as { code?: unknown } | null)?.code,
-      },
-      "org billing identity upsert failed — continuing",
-    );
-  }
-}
-
-async function fireTelemetryWithTimeout(
-  request: FastifyRequest,
-  name: string,
-  props: Record<string, unknown>,
-): Promise<void> {
-  let timeoutId!: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<void>((resolve) => {
-    timeoutId = setTimeout(() => {
-      request.log.warn(
-        { telemetryEvent: name },
-        "telemetry call exceeded timeout; continuing",
-      );
-      resolve();
-    }, TELEMETRY_TIMEOUT_MS);
-  });
-
-  try {
-    await Promise.race([track(name, props), timeout]);
-  } catch (err) {
-    request.log.error(
-      {
-        telemetryEvent: name,
-        error: err instanceof Error ? err.message : String(err),
-      },
-      "telemetry call threw",
-    );
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
-
-// ── Dunning (#6034) ──────────────────────────────────────────────────────
-//
-// Arms and applies the per-tenant dunning record documented in
-// README.md § Dunning. Both arms below share one write primitive
-// (`writeDunningRecord`) that enforces § D6's ordering/tie/durable-replay
-// admission rule and its compare-and-swap over the FULL observed read-set
-// (`value` as well as `updatedAt`) — never a `$transaction`, following
-// `usage-credits.ts:20-33`'s reasoning: a single conditional `UPDATE` IS the
-// atomic compare-and-swap.
-
-/**
- * The "past_due" candidate both arms compute identically (FR-1's
- * `invoice.payment_failed` arm, and `customer.subscription.updated`'s own
- * `past_due`/`unpaid` branch) — one shared shape rather than two copies that
- * could drift: never revokes, `dunningArmedAt` is stamped once and never
- * moved while the subscription stays failing (§ D5), and `accessRevokesAt`
- * is cleared so a re-arm after a prior cancellation carries no stale
- * revocation schedule.
- *
- * Callers differ on whether a recorded `canceled` entry may be relaxed by
- * this candidate — see `armDunning`'s own guard, which is deliberately NOT
- * folded in here (code review finding, #6034): `customer.subscription
- * .updated` is the SUBSCRIPTION-level authoritative source and a strictly
- * newer transition to `past_due` is a real signal worth admitting (§ D6
- * rule 4), while `invoice.payment_failed` is only ever about ONE invoice and
- * must never outrank a subscription-level cancellation already recorded.
- */
-function computeArmedEntry(
-  current: DunningEntry | undefined,
-  event: { id: string; created: number },
-): DunningEntry {
-  return {
-    status: "past_due",
-    accessState: "granted",
-    dunningArmedAt: current?.dunningArmedAt ?? new Date().toISOString(),
-    accessRevokesAt: null,
-    lastEventAt: event.created,
-    lastEventId: event.id,
-  };
-}
-
-/**
- * `invoice.payment_failed` (#6034 FR-1). Arms dunning for the `User` matched
- * by the invoice's Stripe customer id — the recorded state becomes
- * `past_due`, `dunningArmedAt` is stamped once (never moved while the
- * subscription stays failing), and `accessState` stays `granted`. This arm
- * never revokes — and, just as importantly, never UN-revokes: it must never
- * clear a subscription-level `canceled` recording, because it is only ever
- * about ONE invoice, not the subscription's current status (code review
- * finding, #6034). Stripe's Smart Retries schedule can still fire a queued
- * retry's failure webhook for an invoice that predates a cancellation, with
- * an `event.created` genuinely NEWER than the cancellation's own — which
- * § D6's admission rule alone does not reject (rule 4 admits a strictly
- * newer event unconditionally, by design, so that a genuine reactivation via
- * `customer.subscription.updated` is never blocked). Only ANOTHER
- * `customer.subscription.updated` may clear a canceled record.
- *
- * Never throws — the handler's "always 200 for a verified event" contract
- * (NFR-1). Every rejection below returns BEFORE any query (§ D9).
- */
-async function armDunning(
-  request: FastifyRequest,
-  {
-    invoice,
-    eventId,
-    eventCreated,
-    eventIdPrefix,
-  }: {
-    invoice: InvoiceObject;
-    eventId: string;
-    eventCreated: number;
-    eventIdPrefix: string;
-  },
-): Promise<void> {
-  const subscriptionId = invoice.subscription;
-  if (typeof subscriptionId !== "string" || subscriptionId === "") {
-    request.log.info(
-      { eventIdPrefix, outcome: "not_a_subscription_invoice" },
-      "dunning: invoice.payment_failed carries no subscription — not a subscription invoice",
-    );
-    return;
-  }
-
-  const customerId = invoice.customer;
-  if (typeof customerId !== "string" || customerId === "") {
-    request.log.warn(
-      { eventIdPrefix, outcome: "unresolvable_customer" },
-      "dunning: invoice.payment_failed has no resolvable customer",
-    );
-    return;
-  }
-
-  const userId = await findSubscriberUserId(request, {
-    customerId,
-    eventIdPrefix,
-  });
-  if (!userId) return;
-
-  await writeDunningRecord(request, {
-    userId,
-    subscriptionId,
-    eventId,
-    eventCreated,
-    eventIdPrefix,
-    computeCandidate: (current) => {
-      // A subscription already recorded `canceled` (by the SUBSCRIPTION-level
-      // authoritative `customer.subscription.updated` arm) is left untouched
-      // by an invoice-level signal — see this function's own doc comment.
-      if (current?.status === "canceled") return current;
-      return computeArmedEntry(current, { id: eventId, created: eventCreated });
-    },
-  });
-}
-
-/**
- * `customer.subscription.updated` (#6034 FR-2/FR-4). Maps the narrowed
- * Stripe status (§ D3's `toSubscriptionLifecycleStatus`) onto the recorded
- * lifecycle state:
- *
- *   - `active` / `trialing` → § D7's clean recovery (both narrow to a
- *     recorded `status: "active"`; #6038's read shows nothing for it).
- *   - `past_due` (incl. `unpaid`, narrowed) → arms exactly as `armDunning` does.
- *   - `canceled` → § D5: grace runs from the FIRST failure, lazily evaluated,
- *     never scheduled.
- *
- * Never throws (NFR-1); every identifier is guarded before use (§ D9).
- */
-async function applySubscriptionStatus(
-  request: FastifyRequest,
-  {
-    subscription,
-    eventId,
-    eventCreated,
-    eventIdPrefix,
-  }: {
-    subscription: SubscriptionObject;
-    eventId: string;
-    eventCreated: number;
-    eventIdPrefix: string;
-  },
-): Promise<void> {
-  const customerId = subscription.customer;
-  if (typeof customerId !== "string" || customerId === "") {
-    request.log.warn(
-      { eventIdPrefix, outcome: "unresolvable_customer" },
-      "dunning: customer.subscription.updated has no resolvable customer",
-    );
-    return;
-  }
-
-  const subscriptionId = subscription.id;
-  if (typeof subscriptionId !== "string" || subscriptionId === "") {
-    request.log.warn(
-      { eventIdPrefix, outcome: "unresolvable_subscription" },
-      "dunning: customer.subscription.updated has no resolvable subscription id",
-    );
-    return;
-  }
-
-  // toSubscriptionLifecycleStatus's own default arm is already "canceled" —
-  // never an implied grant (§ D3) — so a non-string status maps the same
-  // conservative way rather than being silently ignored (§ D9).
-  const statusRaw = subscription.status;
-  const narrowedStatus =
-    typeof statusRaw === "string"
-      ? toSubscriptionLifecycleStatus(statusRaw)
-      : "canceled";
-
-  const userId = await findSubscriberUserId(request, {
-    customerId,
-    eventIdPrefix,
-  });
-  if (!userId) return;
-
-  if (narrowedStatus === "active" || narrowedStatus === "trialing") {
-    await writeDunningRecord(request, {
-      userId,
-      subscriptionId,
-      eventId,
-      eventCreated,
-      eventIdPrefix,
-      computeCandidate: () => ({
-        status: "active",
-        accessState: "granted",
-        dunningArmedAt: null,
-        accessRevokesAt: null,
-        lastEventAt: eventCreated,
-        lastEventId: eventId,
-      }),
-    });
-    return;
-  }
-
-  if (narrowedStatus === "past_due") {
-    await writeDunningRecord(request, {
-      userId,
-      subscriptionId,
-      eventId,
-      eventCreated,
-      eventIdPrefix,
-      computeCandidate: (current) =>
-        computeArmedEntry(current, { id: eventId, created: eventCreated }),
-    });
-    return;
-  }
-
-  // narrowedStatus === "canceled" — § D5's grace computation. The policy read
-  // never throws (dunning-policy.ts AC-3), so this can be awaited unguarded.
-  const policy = await dunningPolicyFor(currentSiteId());
-
-  await writeDunningRecord(request, {
-    userId,
-    subscriptionId,
-    eventId,
-    eventCreated,
-    eventIdPrefix,
-    computeCandidate: (current) => {
-      const armedAtIso =
-        current?.dunningArmedAt ??
-        new Date(
-          resolveCancellationInstantMs(subscription, eventCreated),
-        ).toISOString();
-      const revokeAtMs =
-        Date.parse(armedAtIso) + policy.graceDays * 24 * 60 * 60 * 1000;
-      const revoked = Date.now() >= revokeAtMs;
-      return {
-        status: "canceled",
-        accessState: revoked ? "revoked" : "granted",
-        dunningArmedAt: armedAtIso,
-        accessRevokesAt: new Date(revokeAtMs).toISOString(),
-        lastEventAt: eventCreated,
-        lastEventId: eventId,
-      };
-    },
-  });
-}
-
-/**
- * The cancellation instant, taken from the verified event in § D5's order —
- * `canceled_at` → `ended_at` → `event.created` → `Date.now()` — each
- * accepted only when `Number.isFinite()` holds (Stripe epoch SECONDS; the
- * final fallback is milliseconds already).
- */
-function resolveCancellationInstantMs(
-  subscription: SubscriptionObject,
-  eventCreatedSec: number,
-): number {
-  const candidatesSec = [
-    subscription.canceled_at,
-    subscription.ended_at,
-    eventCreatedSec,
-  ];
-  for (const candidate of candidatesSec) {
-    if (typeof candidate === "number" && Number.isFinite(candidate)) {
-      return candidate * 1000;
-    }
-  }
-  return Date.now();
-}
-
-/**
- * D10 — no matching `User` is a warn-and-continue, not an error. Matches
- * `upsertBillingIdentity`'s pre-signup posture: a customer id with no linked
- * `User` row is expected (a buyer who purchased without an account), so no
- * `User` row is ever created here.
- */
-async function findSubscriberUserId(
-  request: FastifyRequest,
-  { customerId, eventIdPrefix }: { customerId: string; eventIdPrefix: string },
-): Promise<string | null> {
-  let user: { id: string } | null;
-  try {
-    user = await prisma.user.findUnique({
-      where: {
-        billingProvider_billingCustomerId: {
-          billingProvider: "stripe",
-          billingCustomerId: customerId,
-        },
-      },
-      select: { id: true },
-    });
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        outcome: "subscriber_lookup_failed",
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "dunning: subscriber lookup failed — continuing",
-    );
-    return null;
-  }
-
-  if (!user) {
-    request.log.warn(
-      { eventIdPrefix, outcome: "no_subscriber_match" },
-      "dunning: no User matched this Stripe customer — pre-signup state, no write",
-    );
-    return null;
-  }
-
-  return user.id;
-}
-
-type DunningAdmission =
-  | { admit: true }
-  | { admit: false; outcome: "duplicate_event" | "stale_event" | "stale_tie" };
-
-/**
- * A write is a DE-ESCALATION when it would move the entry toward LESS
- * restriction relative to what is currently recorded: setting `status` to
- * `active` (§ D7's `trialing`-collapses-to-`active` shape), clearing
- * `accessRevokesAt`, or moving `accessState` from `revoked` to `granted`
- * (§ D6 rule 3). All three are checked independently — the earlier draft
- * keyed terminality on `accessState === "revoked"` alone, which left the
- * in-grace cancellation (`status: "canceled"`, `accessState: "granted"`,
- * `accessRevokesAt` non-null) unprotected (§ 9 SEC-03).
- */
-function isDeEscalation(current: DunningEntry, candidate: DunningEntry): boolean {
-  const statusRelaxed =
-    candidate.status === "active" && current.status !== "active";
-  const revokesAtCleared =
-    current.accessRevokesAt !== null && candidate.accessRevokesAt === null;
-  const accessStateRelaxed =
-    current.accessState === "revoked" && candidate.accessState === "granted";
-  return statusRelaxed || revokesAtCleared || accessStateRelaxed;
-}
-
-/**
- * § D6's five-rule admission ladder, folded to what actually needs checking:
- * no current entry → admit (first event for this subscription); the SAME
- * event id replayed → the durable twin of `hasSeen` (rule 1); a strictly
- * OLDER event → stale (rule 2); an EQUAL-timestamp de-escalation → stale tie
- * (rule 3, § D6's "terminal-state monotonicity" folded in — a de-escalating
- * write is rejected at a tie regardless of which of the three terminal
- * disjuncts made it terminal); anything else (a genuinely newer event,
- * unconditionally per rule 4/5) → admit.
- */
-function admitDunningWrite(
-  current: DunningEntry | undefined,
-  candidate: DunningEntry,
-  event: { id: string; created: number },
-): DunningAdmission {
-  if (!current) return { admit: true };
-
-  if (event.id === current.lastEventId) {
-    return { admit: false, outcome: "duplicate_event" };
-  }
-  if (event.created < current.lastEventAt) {
-    return { admit: false, outcome: "stale_event" };
-  }
-  if (event.created === current.lastEventAt && isDeEscalation(current, candidate)) {
-    return { admit: false, outcome: "stale_tie" };
-  }
-  return { admit: true };
-}
-
-function parseDunningRecord(value: unknown): DunningRecord {
-  const obj = value as { subscriptions?: unknown } | null | undefined;
-  const subscriptions =
-    obj &&
-    typeof obj === "object" &&
-    obj.subscriptions &&
-    typeof obj.subscriptions === "object" &&
-    !Array.isArray(obj.subscriptions)
-      ? (obj.subscriptions as Record<string, DunningEntry>)
-      : {};
-  return { v: 1, subscriptions };
-}
-
-/**
- * The map cap (§ D2) — evicts the oldest SETTLED entries (`status: "active"`,
- * `accessState: "granted"`) first, never an entry still being dunned, so a
- * per-event read-and-rewrite never grows unbounded with a customer's whole
- * subscription history.
- */
-function applyCandidateWithCap(
-  record: DunningRecord,
-  subscriptionId: string,
-  candidate: DunningEntry,
-): DunningRecord {
-  const subscriptions: Record<string, DunningEntry> = {
-    ...record.subscriptions,
-    [subscriptionId]: candidate,
-  };
-
-  let overflow = Object.keys(subscriptions).length - DUNNING_MAX_SUBSCRIPTIONS;
-  if (overflow <= 0) {
-    return { v: 1, subscriptions };
-  }
-
-  const evictionOrder = Object.keys(subscriptions)
-    .filter((key) => {
-      const entry = subscriptions[key]!;
-      return entry.status === "active" && entry.accessState === "granted";
-    })
-    .sort((a, b) => subscriptions[a]!.lastEventAt - subscriptions[b]!.lastEventAt);
-
-  for (const key of evictionOrder) {
-    if (overflow <= 0) break;
-    delete subscriptions[key];
-    overflow -= 1;
-  }
-
-  return { v: 1, subscriptions };
-}
-
-/**
- * The shared write primitive (§ D6). Reads the FULL record, applies the
- * admission rule, and writes back a compare-and-swap whose `where` restates
- * BOTH `updatedAt` AND the observed `value` (read-set ≡ CAS-set — NFR-9;
- * `updatedAt` alone lets two writes inside the same millisecond silently
- * overwrite each other, § 9 SEC-07). Bounded at `DUNNING_WRITE_MAX_ATTEMPTS`
- * — an honest `write_conflict` log beats an unbounded spin on an access
- * decision. Never throws (NFR-1) — the outer `catch` is the same
- * never-throw contract every other helper in this file carries.
- */
-async function writeDunningRecord(
-  request: FastifyRequest,
-  {
-    userId,
-    subscriptionId,
-    eventId,
-    eventCreated,
-    eventIdPrefix,
-    computeCandidate,
-  }: {
-    userId: string;
-    subscriptionId: string;
-    eventId: string;
-    eventCreated: number;
-    eventIdPrefix: string;
-    computeCandidate: (current: DunningEntry | undefined) => DunningEntry;
-  },
-): Promise<void> {
-  const subscriptionIdPrefix = subscriptionId.substring(0, 8);
-
-  try {
-    for (let attempt = 1; attempt <= DUNNING_WRITE_MAX_ATTEMPTS; attempt++) {
-      const row = await prisma.userData.findUnique({
-        where: { userId_key: { userId, key: DUNNING_USER_DATA_KEY } },
-        select: { value: true, updatedAt: true },
-      });
-
-      const observedValue: unknown = row ? row.value : null;
-      const record = parseDunningRecord(observedValue);
-      const current = record.subscriptions[subscriptionId];
-      const candidate = computeCandidate(current);
-
-      const admission = admitDunningWrite(current, candidate, {
-        id: eventId,
-        created: eventCreated,
-      });
-      if (!admission.admit) {
-        request.log.info(
-          { eventIdPrefix, subscriptionIdPrefix, outcome: admission.outcome },
-          "dunning: event not admitted — record unchanged",
-        );
-        return;
-      }
-
-      const nextRecord = applyCandidateWithCap(record, subscriptionId, candidate);
-      const nextValue = nextRecord as unknown as Prisma.InputJsonValue;
-
-      if (!row) {
-        try {
-          await prisma.userData.create({
-            data: { userId, key: DUNNING_USER_DATA_KEY, value: nextValue },
-          });
-          request.log.info(
-            {
-              eventIdPrefix,
-              subscriptionIdPrefix,
-              outcome: "written",
-              status: candidate.status,
-            },
-            "dunning: record created",
-          );
-          return;
-        } catch (err) {
-          if (isUniqueViolation(err)) {
-            // Another delivery won the create race — re-read and retry.
-            continue;
-          }
-          throw err;
-        }
-      }
-
-      const { count } = await prisma.userData.updateMany({
-        where: {
-          userId,
-          key: DUNNING_USER_DATA_KEY,
-          updatedAt: row.updatedAt,
-          value: { equals: observedValue as Prisma.InputJsonValue },
-        },
-        data: { value: nextValue },
-      });
-
-      if (count > 0) {
-        request.log.info(
-          {
-            eventIdPrefix,
-            subscriptionIdPrefix,
-            outcome: "written",
-            status: candidate.status,
-          },
-          "dunning: record updated",
-        );
-        return;
-      }
-      // count === 0 — a concurrent writer moved the row. Re-read and retry.
-    }
-
-    request.log.error(
-      { eventIdPrefix, subscriptionIdPrefix, outcome: "write_conflict" },
-      "dunning: record write exhausted its retries — continuing",
-    );
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        subscriptionIdPrefix,
-        outcome: "stamp_failed",
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "dunning: record write failed — continuing",
-    );
-  }
-}