create-ailk 0.4.0 → 0.6.0

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

@@ -0,0 +1,1399 @@
+/**
+ * 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.
+ *
+ * Billing upsert (customer.created / checkout.session.completed):
+ *   Billing-entity routing (org-scoped billing, #3601, spec D2): a checkout
+ *   carrying metadata.organizationId links the Organization (multi-tenant
+ *   module); absent → the existing User path (single-tenant), byte-for-byte.
+ *
+ *   Organization path (metadata.organizationId present):
+ *     1. Typed composite match already pointing at this org → idempotent no-op
+ *     2. Else link the target Organization (by id) billing fields
+ *
+ *   User path (no organizationId — unchanged):
+ *     1. Typed composite match: (billingProvider="stripe", billingCustomerId=customer)
+ *     2. Email fallback: User.findUnique({ where: { email } }) → update billing fields
+ *     3. No match → 200 + warn log; no User row created (pre-signup state)
+ *
+ * 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`.
+ *
+ * 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 type { FastifyReply, FastifyRequest } from "fastify";
+
+import { config } from "../../config/index.js";
+import { prisma } from "../../lib/prisma.js";
+import {
+  resolveCommerceClaim,
+  commerceDisabledResponse,
+  LICENSE_UNDETERMINED_BODY,
+  LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS,
+  LICENSE_UNDETERMINED_STATUS,
+} from "../../lib/require-commerce-claim.js";
+import { currentSiteId } from "../../lib/site.js";
+import {
+  StripeWebhookSignatureError,
+  toSubscriptionLifecycleStatus,
+  verifyWebhookSignature,
+} from "../../lib/stripe.js";
+import { hasSeen, markSeen } from "../../lib/webhook-idempotency.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";
+
+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);
+  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);
+
+  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): a multi-tenant checkout stamps the
+      // target Organization id in metadata.organizationId (an individual → their
+      // sentinel default org). Present → link the Organization; absent → the
+      // existing User path, byte-for-byte (single-tenant, degrade-clean).
+      const organizationId = customer.metadata?.["organizationId"] ?? null;
+      if (organizationId) {
+        await upsertOrgBillingIdentity(request, {
+          organizationId,
+          customerId: customer.id,
+          eventIdPrefix,
+        });
+      } else {
+        await upsertBillingIdentity(request, {
+          customerId: customer.id,
+          email: customer.email ?? null,
+          eventIdPrefix,
+        });
+      }
+      break;
+    }
+    case "checkout.session.completed": {
+      const session = event.data.object as CheckoutSessionObject;
+      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 existing User path, unchanged (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,
+              eventIdPrefix,
+            })
+          : upsertBillingIdentity(request, {
+              customerId: session.customer,
+              email: session.customer_details?.email ?? null,
+              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,
+        stampFlowCheckout(request, {
+          session,
+          eventIdPrefix,
+          outcome: "completed",
+        }),
+        stampRequestPaid(request, { session, 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 (!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;
+  metadata?: Record<string, string> | null;
+};
+
+/**
+ * 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",
+    );
+  }
+}
+
+/**
+ * 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",
+    );
+  }
+}
+
+/**
+ * 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",
+    );
+  }
+}
+
+/**
+ * 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. Email fallback: User.findUnique({ where: { email } }) → update billing fields
+ *   3. No match → warn; do NOT create a User row (pre-signup state preserved for Phase B #852)
+ *
+ * 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,
+    email,
+    eventIdPrefix,
+  }: { customerId: string; email: string | null; eventIdPrefix: string },
+): Promise<void> {
+  try {
+    const existingByBilling = await prisma.user.findFirst({
+      where: {
+        billingProvider: "stripe",
+        billingCustomerId: customerId,
+      },
+    });
+
+    if (existingByBilling) {
+      request.log.info(
+        { eventIdPrefix },
+        "billing identity already linked — idempotent no-op",
+      );
+      return;
+    }
+
+    if (email) {
+      const existingByEmail = await prisma.user.findUnique({
+        where: { email },
+      });
+
+      if (existingByEmail) {
+        await prisma.user.update({
+          where: { id: existingByEmail.id },
+          data: {
+            billingProvider: "stripe",
+            billingCustomerId: customerId,
+          },
+        });
+        request.log.info(
+          { eventIdPrefix },
+          "billing identity linked via email fallback",
+        );
+        return;
+      }
+    }
+
+    request.log.warn(
+      { eventIdPrefix },
+      "stripe webhook: no User match for billing identity — pre-signup state preserved",
+    );
+  } 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). Called when a checkout carries
+ * metadata.organizationId — for a real org, or an individual's sentinel default
+ * Organization (orgs-of-one; AC2 — ONE billing path inside the module).
+ *
+ * Idempotent: a typed-composite match (billingProvider="stripe",
+ * billingCustomerId=customerId) already pointing at THIS org is a no-op on
+ * replay. Otherwise the target Organization (by id from checkout metadata) is
+ * linked.
+ *
+ * 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,
+    eventIdPrefix,
+  }: { organizationId: string; customerId: string; eventIdPrefix: string },
+): Promise<void> {
+  try {
+    const existingByBilling = await prisma.organization.findFirst({
+      where: {
+        billingProvider: "stripe",
+        billingCustomerId: customerId,
+      },
+    });
+
+    if (existingByBilling && existingByBilling.id === organizationId) {
+      request.log.info(
+        { eventIdPrefix },
+        "org billing identity already linked — idempotent no-op",
+      );
+      return;
+    }
+
+    await prisma.organization.update({
+      where: { id: organizationId },
+      data: {
+        billingProvider: "stripe",
+        billingCustomerId: customerId,
+      },
+    });
+    request.log.info(
+      { eventIdPrefix },
+      "org billing identity linked from checkout metadata.organizationId",
+    );
+  } catch (err) {
+    request.log.error(
+      {
+        eventIdPrefix,
+        error: err instanceof Error ? err.message : String(err),
+      },
+      "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",
+    );
+  }
+}