@omega.js/backend 0.1.0

package/test/events/payments/webhook-retry-sweep.test.js

@@ -0,0 +1,252 @@
+/**
+ * Test: a failed webhook is retried by the frequent cron, then dead-lettered
+ *
+ * The webhook route 200s the provider immediately and the trigger does the work,
+ * so a doc the trigger marked `failed` was terminal — a transient fault (a provider
+ * API blip, a Firestore write that lost a race) dropped the payment on the floor and
+ * nothing ever picked it up again ([#220]).
+ *
+ * Retrying is only safe if reprocessing the same event is safe, which the first two
+ * steps prove against the real pipeline before the sweep is exercised at all: the
+ * second pass writes the same state and detects NO transition, so nobody is emailed
+ * about the same subscription twice.
+ */
+const powertools = require('node-powertools');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// The suite's own seeded persona ([#406](https://github.com/Omega-JS-Stack/omega/issues/406)):
+// exclusive to this suite, declared in the seed roster, and the half the seed
+// owns here is the AUTH USER — the doc is deleted below on purpose.
+const PERSONA = 'webhook-retry-sweep';
+const ORDER_ID = '5150-5150-5150';
+
+// Written into `transition` before the doc is put back to pending — the completion
+// write overwrites it, so waiting on it gone is waiting on the SECOND pass, not the first
+const REPROCESS_SENTINEL = '_awaiting-reprocess';
+
+// The ceiling the sweep stops re-flipping at (retry-failed-webhooks.js MAX_RETRIES)
+const MAX_RETRIES = 5;
+
+module.exports = defineCases({
+  description: 'Failed webhooks retry on the frequent cron, then dead-letter',
+  type: 'suite',
+  timeout: 180000,
+
+  tests: [
+    {
+      name: 'reset-prior-state',
+      async run({ accounts, firestore, state }) {
+        state.uid = accounts[PERSONA].uid;
+
+        // The pipeline writes this subscriber's doc from scratch, so the seeded doc
+        // comes off first — the auth user behind it is what makes the write legal at
+        // all ([#399]) — and the fixed order/intent ids go with it, or a previous
+        // run's leftovers would make the first pass a plan change instead of a new
+        // subscription
+        await firestore.delete(`users/${state.uid}`);
+        await firestore.delete(`payments-orders/${ORDER_ID}`);
+        await firestore.delete(`payments-intents/${ORDER_ID}`);
+
+        state.orderId = ORDER_ID;
+      },
+    },
+
+    {
+      name: 'process-a-subscription-webhook',
+      async run({ http, firestore, assert, waitFor, state, config, payments, skip }) {
+        const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
+
+        state.productId = paidProduct.id;
+        state.resourceId = `_test-retry-sub-${Date.now()}`;
+        state.eventId = `_test-evt-retry-${Date.now()}`;
+
+        const response = await http.as('none').post(`backend-manager/payments/webhook?provider=test&key=${config.webhookKey}`, {
+          id: state.eventId,
+          type: 'customer.subscription.updated',
+          data: {
+            object: subscriptionResource({
+              resourceId: state.resourceId,
+              uid: state.uid,
+              orderId: ORDER_ID,
+              stripeProductId: payments.stripeProductIds[paidProduct.id],
+              interval: payments.products[paidProduct.id].interval,
+            }),
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook should be accepted');
+
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.eventId}`);
+          return doc?.status === 'completed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.eventId}`);
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        const orderDoc = await firestore.get(`payments-orders/${ORDER_ID}`);
+
+        assert.equal(webhookDoc.transition, 'new-subscription', 'The first pass is the one that emails the customer');
+        assert.equal(userDoc.subscription.status, 'active', 'The subscription is active');
+        assert.equal(userDoc.subscription.product.id, paidProduct.id, `The subscription is ${paidProduct.id}`);
+        assert.equal(orderDoc.owner, state.uid, 'The order was written');
+
+        state.orderCreatedUNIX = orderDoc.metadata.created.timestampUNIX;
+        state.expiresUNIX = userDoc.subscription.expires.timestampUNIX;
+      },
+    },
+
+    {
+      name: 'reprocessing-the-same-event-changes-nothing',
+      async run({ firestore, assert, waitFor, state }) {
+        // Exactly what a retry does: the same doc, put back to pending
+        await firestore.set(`payments-webhooks/${state.eventId}`, {
+          status: 'pending',
+          transition: REPROCESS_SENTINEL,
+        }, { merge: true });
+
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.eventId}`);
+          return doc?.status === 'completed' && doc?.transition !== REPROCESS_SENTINEL;
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.eventId}`);
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        const orderDoc = await firestore.get(`payments-orders/${ORDER_ID}`);
+
+        assert.equal(webhookDoc.transition, null, 'The second pass detects no transition — no second welcome email');
+        assert.equal(userDoc.subscription.status, 'active', 'The subscription is unchanged');
+        assert.equal(userDoc.subscription.product.id, state.productId, 'The product is unchanged');
+        assert.equal(userDoc.subscription.expires.timestampUNIX, state.expiresUNIX, 'The expiry is unchanged');
+        assert.equal(orderDoc.owner, state.uid, 'The order still belongs to the same user');
+        assert.equal(orderDoc.metadata.created.timestampUNIX, state.orderCreatedUNIX, 'The order is the SAME order, not a second one');
+      },
+    },
+
+    {
+      name: 'a-failing-webhook-counts-its-attempt',
+      async run({ http, firestore, assert, waitFor, state, config, payments }) {
+        state.failedEventId = `_test-evt-retry-fail-${Date.now()}`;
+        state.failedResourceId = `_test-retry-fail-sub-${Date.now()}`;
+        state.failedOrderId = '5151-5151-5151';
+
+        // No uid anywhere the pipeline can reach — the trigger throws on it
+        const response = await http.as('none').post(`backend-manager/payments/webhook?provider=test&key=${config.webhookKey}`, {
+          id: state.failedEventId,
+          type: 'customer.subscription.updated',
+          data: {
+            object: subscriptionResource({
+              resourceId: state.failedResourceId,
+              orderId: state.failedOrderId,
+              stripeProductId: payments.stripeProductIds[state.productId],
+              interval: payments.products[state.productId].interval,
+            }),
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook should be accepted (it fails during processing, not at the door)');
+
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.failedEventId}`);
+          return doc?.status === 'failed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.failedEventId}`);
+
+        assert.match(webhookDoc.error, /no UID/i, 'The webhook failed on the unresolvable UID');
+        assert.equal(webhookDoc.retryCount, 1, 'The failed attempt is counted');
+        assert.ok(!webhookDoc.deadLetter, 'One failure is nowhere near the ceiling');
+      },
+    },
+
+    {
+      name: 'the-sweep-recovers-it',
+      timeout: 120000,
+      async run({ firestore, assert, waitFor, pubsub, state }) {
+        // Heal what made it fail — the owner the payload never carried. This is the
+        // transient fault standing in for a provider blip: the next pass succeeds.
+        await firestore.set(`payments-webhooks/${state.failedEventId}`, { owner: state.uid }, { merge: true });
+
+        await pubsub.trigger('omega_cronFrequent');
+
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.failedEventId}`);
+          return doc?.status === 'completed';
+        }, 90000, 1000);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.failedEventId}`);
+
+        assert.equal(webhookDoc.status, 'completed', 'The sweep put it back to pending and the retry completed it');
+        assert.equal(webhookDoc.retryCount, 1, 'A successful retry does not count another attempt');
+        assert.equal(webhookDoc.owner, state.uid, 'It processed as the recovered owner');
+      },
+    },
+
+    {
+      name: 'the-ceiling-dead-letters-instead-of-retrying-forever',
+      timeout: 120000,
+      async run({ firestore, assert, waitFor, pubsub, state, payments }) {
+        const now = powertools.timestamp(new Date(), { output: 'string' });
+        state.deadEventId = `_test-evt-retry-dead-${Date.now()}`;
+
+        // A doc that already burned every retry — seeded failed, so nothing processes
+        // it until the sweep decides whether to
+        await firestore.set(`payments-webhooks/${state.deadEventId}`, {
+          id: state.deadEventId,
+          provider: 'test',
+          status: 'failed',
+          retryCount: MAX_RETRIES,
+          error: 'Webhook event has no UID',
+          raw: { id: state.deadEventId, type: 'customer.subscription.updated', data: { object: subscriptionResource({ resourceId: `_test-retry-dead-sub-${Date.now()}`, orderId: '5152-5152-5152', stripeProductId: payments.stripeProductIds[state.productId], interval: payments.products[state.productId].interval }) } },
+          owner: null,
+          event: { type: 'customer.subscription.updated', category: 'subscription', resourceType: 'subscription', resourceId: `_test-retry-dead-sub-${Date.now()}` },
+          metadata: {
+            created: {
+              timestamp: now,
+              timestampUNIX: powertools.timestamp(now, { output: 'unix' }),
+            },
+          },
+        });
+
+        await pubsub.trigger('omega_cronFrequent');
+
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.deadEventId}`);
+          return doc?.deadLetter === true;
+        }, 90000, 1000);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.deadEventId}`);
+
+        assert.equal(webhookDoc.deadLetter, true, 'The doc at the ceiling is dead-lettered');
+        assert.equal(webhookDoc.status, 'failed', 'It is NOT put back to pending');
+        assert.equal(webhookDoc.retryCount, MAX_RETRIES, 'Dead-lettering counts no further attempt');
+      },
+    },
+  ],
+});
+
+/**
+ * A Stripe-shaped active subscription — the shape the test provider speaks
+ * Omitting uid is what makes the pipeline fail on an unresolvable owner
+ */
+function subscriptionResource({ resourceId, uid, orderId, stripeProductId, interval }) {
+  const nowUNIX = Math.floor(Date.now() / 1000);
+
+  return {
+    id: resourceId,
+    object: 'subscription',
+    status: 'active',
+    metadata: uid ? { uid, orderId } : { orderId },
+    cancel_at_period_end: false,
+    canceled_at: null,
+    current_period_start: nowUNIX,
+    current_period_end: nowUNIX + 86400 * 30,
+    start_date: nowUNIX,
+    trial_start: null,
+    trial_end: null,
+    plan: { product: stripeProductId, interval: interval },
+  };
+}

package/test/events/payments/webhook-transition-claim.test.js

@@ -0,0 +1,389 @@
+/**
+ * Test: a transition is claimed per order, so concurrent webhooks dispatch it once
+ *
+ * Transition detection is a DIFF — the user's stored subscription against the
+ * unified state the event carries — so it is only correct while one webhook is in
+ * flight. Stripe sent `customer.subscription.created` and
+ * `invoice.payment_succeeded` one second apart for the same checkout: both runs
+ * read `users/{uid}` while it still said `basic` (the first run's write landed 11
+ * seconds later), both detected `subscription/new-subscription`, and both
+ * dispatched it — two order emails to one customer, two `trial_start` fires
+ * ([#665](https://github.com/Omega-JS-Stack/omega/issues/665)).
+ *
+ * The fix is a CLAIM on the order, taken in a transaction before the dispatch:
+ * `payments-orders/{orderId}.transitions.<name>`. Per order per transition NAME,
+ * so the order's own later transitions — a cancellation, a plan change — still
+ * fire; only a second run of the SAME transition on the SAME order is suppressed.
+ *
+ * Plain-node (no emulator, no network), for the reason the atomic-writes and
+ * sweep-staleness suites are: the emulator cannot run two triggers for one order
+ * interleaved on demand, and this bug only exists in the interleaving. The shared
+ * in-memory stand-in models Firestore's real transaction contract — versioned
+ * reads, staged writes, and a re-run of the whole block when a read document
+ * changed underneath — so the claim is genuinely contended rather than assumed.
+ *
+ * A claim gates all THREE things the transition drives — the handler, the analytics
+ * fire, and the marketing sync — because the live sighting duplicated all three: two
+ * order emails, two `trial_start`s (GA4 counted both), two marketing syncs.
+ *
+ * Each is counted through the runner's own testing-mode seam: `ctx.isTesting()` is
+ * true here, so the pipeline logs `… skipped (testing mode)` at exactly the point it
+ * would otherwise email a real customer, post a real conversion, or write to a real
+ * marketing list. Those lines ARE the three effects, counted.
+ *
+ * Run: npx omega test backend:events/payments/webhook-transition-claim
+ */
+const assert = require('node:assert');
+const onWrite = require('../../../dist/manager/events/firestore/payments-webhooks/on-write.js');
+const { CLAIM_WINDOW_MS } = require('../../../dist/manager/events/firestore/payments-webhooks/transitions/index.js');
+const { buildAdmin, CONFIG, subscriptionPayload } = require('./_webhook-harness.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const UID = '_test-claim-uid';
+const ORDER_ID = '_test-claim-order';
+const RESOURCE_ID = '_test-claim-sub';
+
+const CREATED_EVENT = '_test-claim-subscription-created';
+const INVOICE_EVENT = '_test-claim-invoice-succeeded';
+
+const nowUNIX = () => Math.floor(Date.now() / 1000);
+
+/** A `$timestamp` pair from a UNIX second */
+function stamp(unix) {
+  return { timestamp: new Date(unix * 1000).toISOString(), timestampUNIX: unix };
+}
+
+/** A brand-new subscriber, still on basic — what BOTH racing runs read */
+function basicUser() {
+  return {
+    auth: { email: 'claim@example.com' },
+    personal: { name: { first: 'Claim', last: 'Tester' } },
+    subscription: { product: { id: 'basic', name: 'Basic' }, status: 'active' },
+  };
+}
+
+/** An established paid subscriber, for the transition that comes AFTER the first one */
+function paidUser() {
+  return {
+    auth: { email: 'claim@example.com' },
+    personal: { name: { first: 'Claim', last: 'Tester' } },
+    subscription: {
+      product: { id: 'premium', name: 'Premium' },
+      status: 'active',
+      cancellation: { pending: false },
+      payment: { provider: 'test', resourceId: RESOURCE_ID, frequency: 'monthly', price: 4.99 },
+    },
+  };
+}
+
+/**
+ * A pending webhook doc for this order, as the webhook route writes one
+ *
+ * @param {string} eventId - The webhook doc id
+ * @param {string} eventType - The provider's event name
+ * @param {object} [overrides] - Overrides for the subscription resource it carries
+ * @returns {object}
+ */
+function webhookDoc(eventId, eventType, overrides = {}) {
+  const resource = { ...subscriptionPayload({ uid: UID, orderId: ORDER_ID, resourceId: RESOURCE_ID }), ...overrides };
+
+  return {
+    id: eventId,
+    provider: 'test',
+    status: 'pending',
+    raw: { id: eventId, type: eventType, data: { object: resource } },
+    owner: UID,
+    event: { type: eventType, category: 'subscription', resourceType: 'subscription', resourceId: RESOURCE_ID, refundId: null },
+    metadata: { created: { timestampUNIX: nowUNIX() } },
+  };
+}
+
+/**
+ * Run the real trigger over one or more webhook docs against ONE store — the whole
+ * point of this suite, which `runTrigger` cannot serve: it builds a store per call,
+ * and two events that never share an order can never contend for its claim.
+ *
+ * @param {object} options
+ * @param {object[]} options.events - The pending webhook docs to process
+ * @param {object} options.seed - Extra documents the run starts from
+ * @param {boolean} [options.concurrent] - Process them together (the race) or one after the other
+ * @param {string|function|null} [options.failPath] - The document path whose write rejects, so a
+ *   run can be made to fail AFTER it claimed — the state its own retry has to get past
+ * @returns {Promise<{ store: Map, logs: string[], run: function }>} `run` re-enters the trigger
+ *   against this same store, which is how a retry of an event is played
+ */
+async function runTriggers({ events, seed = {}, concurrent = true, failPath = null }) {
+  const webhooks = Object.fromEntries(events.map((event) => [`payments-webhooks/${event.id}`, event]));
+  const { admin, store } = buildAdmin({ seed: { ...webhooks, ...seed }, authUids: [UID], failPath: failPath });
+
+  const logs = [];
+  const Manager = { config: CONFIG, libraries: { admin, sentry: null } };
+  const ctx = {
+    Manager,
+    isTesting: () => true,
+    log: (...args) => logs.push(args.join(' ')),
+    warn: (...args) => logs.push(args.join(' ')),
+    error: (...args) => logs.push(args.join(' ')),
+  };
+
+  // The doc the trigger is handed is a point-in-time snapshot, exactly as a real
+  // trigger's `change` is — it stays `pending` even after the run flips the stored doc
+  const run = (event) => onWrite({
+    ctx,
+    change: { before: { data: () => event }, after: { data: () => event } },
+    context: { params: { eventId: event.id } },
+  });
+
+  if (concurrent) {
+    await Promise.all(events.map(run));
+  } else {
+    for (const event of events) {
+      await run(event);
+    }
+  }
+
+  return { store, logs, run };
+}
+
+/** How many times the pipeline reached the dispatch point for this transition */
+function dispatchCount(logs, transitionName) {
+  return logs.filter((line) => line.includes(`Transition handler skipped (testing mode): subscription/${transitionName}`)).length;
+}
+
+/** How many runs reached a testing-mode seam — the effect that would have gone out for real */
+function seamCount(logs, seam) {
+  return logs.filter((line) => line.includes(`${seam} skipped (testing mode)`)).length;
+}
+
+module.exports = defineCases({
+  description: 'Payment transitions: one claim per order per transition name gates the dispatch',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'two-concurrent-webhooks-for-one-order-dispatch-new-subscription-once',
+
+      async run() {
+        // The live sighting, reproduced: the subscription and the invoice event for
+        // ONE checkout, in flight together, both reading a user doc that still says
+        // basic. Detection is expected to fire twice — that is not the bug and is
+        // not what this fixes. Exactly one of them may ACT on it.
+        const { store, logs } = await runTriggers({
+          events: [
+            webhookDoc(CREATED_EVENT, 'customer.subscription.created'),
+            webhookDoc(INVOICE_EVENT, 'invoice.payment_succeeded'),
+          ],
+          seed: { [`users/${UID}`]: basicUser() },
+        });
+
+        const detected = logs.filter((line) => line.includes('Transition detected: subscription/new-subscription'));
+        assert.equal(detected.length, 2, `both runs must detect the transition — otherwise they never raced, got: ${logs.join(' | ')}`);
+
+        assert.equal(dispatchCount(logs, 'new-subscription'), 1, `exactly one run may dispatch new-subscription, got: ${logs.join(' | ')}`);
+
+        // The other two effects of the same transition, which the live sighting
+        // duplicated alongside the email: one conversion (GA4 deduplicates neither a
+        // custom `trial_start` nor a second event id) and one marketing sync.
+        assert.equal(seamCount(logs, 'Payment analytics'), 1, `exactly one run may fire payment analytics, got: ${logs.join(' | ')}`);
+        assert.equal(seamCount(logs, 'Marketing sync'), 1, `exactly one run may sync the marketing contact, got: ${logs.join(' | ')}`);
+        assert.ok(
+          logs.some((line) => line.includes('Payment analytics suppressed (claimed by')),
+          `the loser says why it tracked nothing, got: ${logs.join(' | ')}`,
+        );
+        assert.ok(
+          logs.some((line) => line.includes('Marketing sync suppressed (claimed by')),
+          `and why it synced nothing, got: ${logs.join(' | ')}`,
+        );
+
+        const claim = store.get(`payments-orders/${ORDER_ID}`).transitions['new-subscription'];
+        assert.ok([CREATED_EVENT, INVOICE_EVENT].includes(claim.eventId), 'the claim names the event that won it');
+        assert.ok(claim.timestampUNIX > 0, 'the claim is stamped');
+
+        const suppressed = logs.filter((line) => line.includes('Transition suppressed (claimed by'));
+        assert.equal(suppressed.length, 1, `the loser says so, once, got: ${logs.join(' | ')}`);
+        assert.ok(
+          suppressed[0].includes(`Transition suppressed (claimed by ${claim.eventId}): subscription/new-subscription on payments-orders/${ORDER_ID}`),
+          `the suppression names the winner and the order, got: ${suppressed[0]}`,
+        );
+
+        // Everything the claim does NOT change: both events are still acknowledged
+        // (a provider must stop redelivering them), both still record what they saw,
+        // and the subscriber is on the plan they paid for.
+        assert.equal(store.get(`payments-webhooks/${CREATED_EVENT}`).status, 'completed', 'the first event completes');
+        assert.equal(store.get(`payments-webhooks/${INVOICE_EVENT}`).status, 'completed', 'the second event completes too — suppression is not a failure');
+        assert.equal(store.get(`users/${UID}`).subscription.product.id, 'premium', 'the subscriber is on the plan they bought');
+        assert.deepEqual(
+          store.get(`payments-orders/${ORDER_ID}`).requests,
+          { cancellation: null, refund: null },
+          'the order still gets its requests node — the claim writes the order doc first, so a bare existence test would have skipped it',
+        );
+      },
+    },
+
+    {
+      name: 'a-claim-already-on-the-order-suppresses-a-later-detection',
+
+      async run() {
+        // The claim is durable, not just a tiebreaker for one instant: a redelivery
+        // that re-detects new-subscription (the user doc write never landed, so the
+        // diff still reads basic → premium) finds the claim and stays quiet. Taken a
+        // minute ago and still running, so it is well inside the claim window.
+        const claimedUNIX = nowUNIX() - 60;
+
+        const { store, logs } = await runTriggers({
+          events: [webhookDoc(INVOICE_EVENT, 'invoice.payment_succeeded')],
+          seed: {
+            [`users/${UID}`]: basicUser(),
+            [`payments-orders/${ORDER_ID}`]: {
+              id: ORDER_ID,
+              type: 'subscription',
+              owner: UID,
+              resourceId: RESOURCE_ID,
+              transitions: { 'new-subscription': { eventId: CREATED_EVENT, status: 'claimed', ...stamp(claimedUNIX) } },
+              metadata: { created: stamp(claimedUNIX), updated: stamp(claimedUNIX) },
+            },
+          },
+        });
+
+        assert.equal(dispatchCount(logs, 'new-subscription'), 0, `nothing may dispatch against a claim, got: ${logs.join(' | ')}`);
+        assert.equal(seamCount(logs, 'Payment analytics'), 0, `nor track against one, got: ${logs.join(' | ')}`);
+        assert.equal(seamCount(logs, 'Marketing sync'), 0, `nor sync against one, got: ${logs.join(' | ')}`);
+        assert.ok(
+          logs.some((line) => line.includes(`Transition suppressed (claimed by ${CREATED_EVENT})`)),
+          `the skip names the event holding the claim, got: ${logs.join(' | ')}`,
+        );
+        assert.equal(
+          store.get(`payments-orders/${ORDER_ID}`).transitions['new-subscription'].eventId,
+          CREATED_EVENT,
+          'the standing claim is left exactly as it was — a loser never overwrites the winner',
+        );
+      },
+    },
+
+    {
+      name: 'a-different-transition-on-the-same-order-still-fires',
+
+      async run() {
+        // The claim is per NAME, not per order. The same subscription's later life —
+        // a cancellation here — has its own transition to send, and a spent
+        // new-subscription claim must not swallow it.
+        const claimedUNIX = nowUNIX() - 3600;
+
+        const { store, logs } = await runTriggers({
+          events: [webhookDoc('_test-claim-subscription-deleted', 'customer.subscription.deleted', { status: 'canceled' })],
+          seed: {
+            [`users/${UID}`]: paidUser(),
+            [`payments-orders/${ORDER_ID}`]: {
+              id: ORDER_ID,
+              type: 'subscription',
+              owner: UID,
+              resourceId: RESOURCE_ID,
+              requests: { cancellation: null, refund: null },
+              transitions: { 'new-subscription': { eventId: CREATED_EVENT, ...stamp(claimedUNIX) } },
+              metadata: { created: stamp(claimedUNIX), updated: stamp(claimedUNIX) },
+            },
+          },
+        });
+
+        assert.equal(dispatchCount(logs, 'subscription-cancelled'), 1, `the cancellation dispatches on its own name, got: ${logs.join(' | ')}`);
+        assert.equal(seamCount(logs, 'Payment analytics'), 1, `and tracks, got: ${logs.join(' | ')}`);
+        assert.equal(seamCount(logs, 'Marketing sync'), 1, `and syncs — a spent claim gates only its own name, got: ${logs.join(' | ')}`);
+
+        const claims = store.get(`payments-orders/${ORDER_ID}`).transitions;
+        assert.equal(claims['subscription-cancelled'].eventId, '_test-claim-subscription-deleted', 'the cancellation takes its own claim');
+        assert.equal(claims['new-subscription'].eventId, CREATED_EVENT, 'and the earlier claim stands beside it');
+      },
+    },
+
+    {
+      name: 'a-claim-older-than-the-window-is-a-spent-one-and-the-transition-repeats',
+
+      async run() {
+        // The order id is stable for the subscription's LIFE, so every transition
+        // that can happen twice re-detects a name the order already carries: a
+        // second dunning cycle's payment-failed, a re-cancellation after an
+        // uncancel, a second plan change. Keyed on order + name alone, the first
+        // claim swallowed all of them — no dunning email, no analytics, no sync,
+        // for as long as the subscription lasted. The claim only speaks for its
+        // window; the race it settles is seconds wide.
+        const spentUNIX = nowUNIX() - (30 * 86400);
+
+        const { store, logs } = await runTriggers({
+          events: [webhookDoc('_test-claim-invoice-failed-2', 'invoice.payment_failed')],
+          seed: {
+            [`users/${UID}`]: paidUser(),
+            [`payments-orders/${ORDER_ID}`]: {
+              id: ORDER_ID,
+              type: 'subscription',
+              owner: UID,
+              resourceId: RESOURCE_ID,
+              requests: { cancellation: null, refund: null },
+              // What the FIRST dunning cycle left behind a month ago, finished
+              transitions: { 'payment-failed': { eventId: '_test-claim-invoice-failed-1', status: 'done', ...stamp(spentUNIX) } },
+              metadata: { created: stamp(spentUNIX), updated: stamp(spentUNIX) },
+            },
+          },
+        });
+
+        assert.equal(dispatchCount(logs, 'payment-failed'), 1, `the second dunning cycle dispatches, got: ${logs.join(' | ')}`);
+        assert.equal(seamCount(logs, 'Payment analytics'), 1, `and tracks, got: ${logs.join(' | ')}`);
+        assert.equal(seamCount(logs, 'Marketing sync'), 1, `and syncs, got: ${logs.join(' | ')}`);
+
+        const claim = store.get(`payments-orders/${ORDER_ID}`).transitions['payment-failed'];
+        assert.equal(claim.eventId, '_test-claim-invoice-failed-2', 'the spent claim is retaken by the event that repeated the transition');
+        assert.equal(claim.status, 'done', 'and settles like any other');
+        assert.ok(claim.timestampUNIX > spentUNIX, 'restamped, so it speaks for its own window and no longer for the first cycle');
+        assert.ok(CLAIM_WINDOW_MS < 30 * 86400 * 1000, 'the fixture has to be older than the window it is testing');
+      },
+    },
+
+    {
+      name: 'a-run-that-failed-after-claiming-is-not-refused-by-its-own-claim',
+
+      async run() {
+        // A claim can outlive the run that took it: the winner claims, then its state
+        // write fails. The webhook doc goes `failed` and the frequent cron re-runs
+        // THAT SAME event id (events/cron/frequent/retry-failed-webhooks.js) — and a
+        // claim carrying no outcome refused the retry forever, so the customer who
+        // paid got no order email, no conversion, no marketing sync, and no
+        // subscription. `failed` is the one reclaimable state, exactly as it is for
+        // the webhook doc itself and for a dispute alert.
+        const faulty = { writes: true };
+
+        const { store, logs, run } = await runTriggers({
+          events: [webhookDoc(CREATED_EVENT, 'customer.subscription.created')],
+          seed: { [`users/${UID}`]: basicUser() },
+          // The batch — everything the run writes AFTER it claimed
+          failPath: (path) => faulty.writes && path === `users/${UID}`,
+        });
+
+        assert.equal(store.get(`payments-webhooks/${CREATED_EVENT}`).status, 'failed', 'the run failed after it claimed');
+        assert.equal(store.get(`users/${UID}`).subscription.product.id, 'basic', 'and wrote no subscription — that is what the retry is for');
+
+        const claim = store.get(`payments-orders/${ORDER_ID}`).transitions['new-subscription'];
+        assert.equal(claim.status, 'failed', 'the claim records how the run ended, so a retry can tell abandoned from finished');
+        assert.equal(claim.eventId, CREATED_EVENT, 'and still names the event that took it');
+
+        // The sweep flips the failed doc back to pending, and the trigger sees the
+        // same event id a second time — with the fault cleared.
+        faulty.writes = false;
+        const mark = logs.length;
+        await run(webhookDoc(CREATED_EVENT, 'customer.subscription.created'));
+        const retryLogs = logs.slice(mark);
+
+        assert.equal(dispatchCount(retryLogs, 'new-subscription'), 1, `the retry reclaims and dispatches once, got: ${retryLogs.join(' | ')}`);
+        assert.equal(seamCount(retryLogs, 'Payment analytics'), 1, `and tracks once, got: ${retryLogs.join(' | ')}`);
+        assert.equal(seamCount(retryLogs, 'Marketing sync'), 1, `and syncs once, got: ${retryLogs.join(' | ')}`);
+
+        assert.equal(store.get(`users/${UID}`).subscription.product.id, 'premium', 'the subscriber ends up on the plan they paid for');
+        assert.equal(store.get(`payments-webhooks/${CREATED_EVENT}`).status, 'completed', 'and the event completes');
+        assert.equal(
+          store.get(`payments-orders/${ORDER_ID}`).transitions['new-subscription'].status,
+          'done',
+          'the claim that finished says so — a third run finds it spent, not retakeable',
+        );
+      },
+    },
+  ],
+});