@omega.js/backend 0.1.0

package/test/events/payments/trial-lapse-sweep-staleness.test.js

@@ -0,0 +1,173 @@
+/**
+ * Test: the trial-lapse sweep never writes over a newer webhook
+ *
+ * The sweep is a BACKSTOP for a trial-end webhook that never landed — so the one
+ * thing it must never do is undo a webhook that DID. Its guard re-reads the
+ * subscription and compares the write stamp against the second the run took its
+ * snapshot, and the Stage 1 review found two holes in that
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)):
+ *
+ *   1. The stamp is a whole SECOND. A webhook that wrote inside the same second as
+ *      the sweep's read carries an EQUAL number, and a strict `>` read equal as
+ *      older — so the exact write the guard exists to protect was the one it let
+ *      through.
+ *   2. A bare read followed by a separate `set` leaves a window between them. A
+ *      webhook landing IN that window was clobbered anyway: the guard proved
+ *      freshness at a moment that had already passed.
+ *
+ * Plain-node control-flow test (no emulator, no network), for the same reason the
+ * atomic-writes suite is one: the emulator cannot land a contending write inside
+ * another client's transaction on demand. 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 retry
+ * is exercised rather than assumed. The emulator suite (trial-lapse-sweep.test.js)
+ * stays the integration surface for the sweep's happy paths.
+ *
+ * Run: npx omega test backend:events/payments/trial-lapse-sweep-staleness
+ */
+const assert = require('node:assert');
+const sweep = require('../../../dist/manager/events/cron/daily/trial-lapse-sweep.js');
+const { buildAdmin, CONFIG } = require('./_webhook-harness.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const DAY = 24 * 60 * 60;
+
+const UID = '_test-sweep-staleness-uid';
+const RESOURCE_ID = '_test-sweep-staleness-sub';
+
+/** A `$timestamp` pair from a UNIX second */
+function stamp(unix) {
+  return { timestamp: new Date(unix * 1000).toISOString(), timestampUNIX: unix };
+}
+
+/**
+ * A candidate the sweep will select and decide to LAPSE: its trial ended 5 days ago
+ * (inside the window, past the grace), it is still active on a paid product, and the
+ * provider has no record of the subscription (no payments-orders doc to answer from).
+ */
+function candidate(extraSubscription = {}) {
+  const expiredUNIX = Math.floor(Date.now() / 1000) - 5 * DAY;
+
+  return {
+    subscription: {
+      product: { id: 'premium', name: 'Premium' },
+      status: 'active',
+      expires: stamp(expiredUNIX),
+      trial: { claimed: true, expires: stamp(expiredUNIX) },
+      cancellation: { pending: false },
+      payment: { provider: 'test', orderId: null, resourceId: RESOURCE_ID, frequency: 'monthly', price: 4.99 },
+      ...extraSubscription,
+    },
+  };
+}
+
+/**
+ * Run the real sweep against the in-memory stand-in
+ *
+ * @param {object} options
+ * @param {object} options.user - The seeded users/{uid} document
+ * @param {function|null} options.onRead - The contention seam
+ * @returns {Promise<{ store: Map, logs: string[] }>}
+ */
+async function runSweep({ user, onRead = null } = {}) {
+  const { admin, store } = buildAdmin({
+    seed: { [`users/${UID}`]: user },
+    authUids: [UID],
+    onRead: onRead,
+  });
+
+  const logs = [];
+  const Manager = { config: CONFIG, libraries: { admin } };
+  const ctx = {
+    Manager,
+    isTesting: () => true,
+    log: (...args) => logs.push(args.join(' ')),
+    warn: (...args) => logs.push(args.join(' ')),
+    error: (...args) => logs.push(args.join(' ')),
+  };
+
+  await sweep({ Manager, ctx, context: {}, libraries: { admin } });
+
+  return { store, logs };
+}
+
+module.exports = defineCases({
+  description: 'Trial-lapse sweep: the staleness guard and its write are one transaction',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'a-write-in-the-same-second-as-the-read-counts-as-newer',
+
+      async run() {
+        // The guard's whole predicate, at the resolution the stamps actually carry.
+        // Under the strict `>` this replaced, the equal case answered false — the
+        // sweep called a webhook from its own second "older" and wrote over it.
+        assert.equal(sweep.isNewerThanSweep(1000, 1000), true, 'a write inside the sweep read\'s own second is NEWER, not older');
+        assert.equal(sweep.isNewerThanSweep(1001, 1000), true, 'a later write is newer');
+        assert.equal(sweep.isNewerThanSweep(999, 1000), false, 'a write from before the read is genuinely older');
+        assert.equal(sweep.isNewerThanSweep(0, 1000), false, 'a subscription nobody has stamped is not newer');
+        assert.equal(sweep.isNewerThanSweep(undefined, 1000), false, 'an unstamped subscription reads as 0, not NaN');
+      },
+    },
+
+    {
+      name: 'an-uncontended-candidate-still-lapses',
+
+      async run() {
+        const { store } = await runSweep({ user: candidate() });
+        const swept = store.get(`users/${UID}`);
+
+        assert.equal(swept.subscription.trial.outcome, 'lapsed', 'the provider has no such subscription — the trial lapsed');
+        assert.equal(swept.subscription.status, 'cancelled', 'a lapsed trial ends cancelled');
+        assert.equal(swept.subscription.product.id, 'basic', 'a lapsed trial ends on basic');
+      },
+    },
+
+    {
+      name: 'a-webhook-landing-between-the-guard-and-the-write-is-never-clobbered',
+
+      async run() {
+        // The window the transaction closes: the sweep re-reads a candidate that is
+        // still a candidate, and the provider's own trial-end webhook commits before
+        // the sweep's write goes out. Written THROUGH the stand-in, so the document
+        // version moves and the transaction is genuinely contended.
+        let contended = false;
+
+        const { store, logs } = await runSweep({
+          user: candidate(),
+          onRead: (path, { write }) => {
+            if (contended || path !== `users/${UID}`) {
+              return;
+            }
+
+            contended = true;
+
+            // What the webhook pipeline writes when it converts the trial itself:
+            // the term moved out past the trial end, and the write is stamped.
+            write(path, {
+              subscription: {
+                status: 'active',
+                product: { id: 'premium', name: 'Premium' },
+                expires: stamp(Math.floor(Date.now() / 1000) + 25 * DAY),
+                payment: { updatedBy: { date: stamp(Math.floor(Date.now() / 1000) + 5) } },
+              },
+            }, { merge: true });
+          },
+        });
+
+        const swept = store.get(`users/${UID}`);
+
+        assert.ok(contended, 'the contending write must actually have run — otherwise this proves nothing');
+        assert.equal(swept.subscription.status, 'active', 'the webhook\'s state survives: the subscriber is still active');
+        assert.equal(swept.subscription.product.id, 'premium', 'the webhook\'s product survives — the sweep did not reset it to basic');
+        assert.equal(swept.subscription.trial.outcome, undefined, 'and no lapse was stamped over it');
+        assert.ok(
+          logs.some((line) => line.includes('a newer subscription write landed')),
+          `the re-run must SAY it skipped on staleness, got: ${logs.join(' | ')}`,
+        );
+      },
+    },
+  ],
+});

package/test/events/payments/trial-lapse-sweep.test.js

@@ -0,0 +1,359 @@
+/**
+ * Test: the daily trial-lapse sweep
+ *
+ * A trial that ends without converting should leave the user on basic. The providers
+ * say so with a webhook, and when that webhook is missed the user keeps a paid product
+ * they never paid for — invisibly, because `trial.claimed` means "this subscription HAD
+ * a trial", never "it converted" ([#212]).
+ *
+ * The sweep is a BACKSTOP, so what it must NOT do matters as much as what it does: it
+ * never infers a lapse from dates alone (every candidate is confirmed against live
+ * provider state), it leaves the 24h grace window and everything older than 30 days
+ * alone, and a second run changes nothing.
+ *
+ * The test provider answers `fetchResource` from `payments-orders`, so "the provider
+ * says X" is seeded as an order doc — or, for "the subscription is gone", as no order
+ * doc at all.
+ */
+const sweep = require('../../../dist/manager/events/cron/daily/trial-lapse-sweep.js');
+const analytics = require('../../../dist/manager/events/firestore/payments-webhooks/analytics.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const DAY = 24 * 60 * 60;
+
+const GONE_UID = '_test-trial-lapse-gone';
+const CANCELLED_UID = '_test-trial-lapse-cancelled';
+const CONVERTED_UID = '_test-trial-lapse-converted';
+const GRACE_UID = '_test-trial-lapse-grace';
+const AGED_UID = '_test-trial-lapse-aged';
+
+const CANCELLED_ORDER = '_test-order-trial-lapse-cancelled';
+const CONVERTED_ORDER = '_test-order-trial-lapse-converted';
+
+module.exports = defineCases({
+  description: 'Trial-lapse sweep: confirms with the provider, then corrects state',
+  type: 'suite',
+  timeout: 180000,
+
+  tests: [
+    {
+      // The sweep is the ONLY path that ever sees a PayPal trial's outcome: PayPal
+      // fires no trial-end event, so nothing else in the pipeline is told. Before
+      // [#407](https://github.com/Omega-JS-Stack/omega/issues/407) the state was
+      // corrected here and the analytics signal was never sent at all.
+      name: 'the-sweep-reports-a-lapse-no-webhook-will-ever-announce',
+      async run({ assert }) {
+        const nowUNIX = Math.floor(Date.now() / 1000);
+        const trialEndUNIX = nowUNIX - 5 * DAY;
+
+        // PayPal's in-trial shape: `expires` is next_billing_time, which during a
+        // trial IS the trial's end.
+        const paypalTrial = {
+          product: { id: 'premium', name: 'Premium' },
+          status: 'active',
+          expires: stamp(trialEndUNIX),
+          trial: { claimed: true, expires: stamp(trialEndUNIX) },
+          payment: { provider: 'paypal', resourceId: 'I-PAYPAL-TRIAL', frequency: 'monthly', price: 9.99 },
+        };
+
+        const conversion = sweep.resolveTrialOutcomeConversion(paypalTrial, 'lapsed', 'USD');
+
+        assert.ok(conversion, 'a lapse the sweep decided should be reported');
+        assert.equal(conversion.event, 'trial_lapse');
+        assert.equal(conversion.params.value, 9.99, 'the value is the subscription that never started paying');
+        assert.equal(conversion.params.is_trial, true);
+        assert.equal(conversion.params.is_recurring, false, 'nothing was ever charged');
+        assert.equal(
+          conversion.eventId,
+          'trial_lapse.I-PAYPAL-TRIAL',
+          'the dedupe id is keyed to the SUBSCRIPTION, which is the one thing this sweep and the payment webhook both know',
+        );
+
+        const converted = sweep.resolveTrialOutcomeConversion({ ...paypalTrial }, 'converted', 'USD');
+
+        assert.equal(converted.event, 'trial_convert');
+        assert.equal(converted.eventId, 'trial_convert.I-PAYPAL-TRIAL');
+      },
+    },
+
+    {
+      // A trial whose outcome a payment webhook already resolved was already
+      // reported at the moment it happened. The sweep still stamps the outcome —
+      // that is state correction — but reporting it again would be a second
+      // conversion: GA4 deduplicates a `purchase` on `transaction_id`, and this
+      // path has no invoice to name, so the two reports would arrive under two
+      // different ids ([#656]).
+      name: 'the-sweep-never-reports-an-outcome-a-webhook-already-resolved',
+      async run({ assert }) {
+        const nowUNIX = Math.floor(Date.now() / 1000);
+        const trialEndUNIX = nowUNIX - 5 * DAY;
+
+        // The conversion charge moved `expires` out to the end of the first paid
+        // period — the webhook saw it, and fired trial_convert then.
+        const alreadyReported = {
+          product: { id: 'premium', name: 'Premium' },
+          status: 'active',
+          expires: stamp(nowUNIX + 25 * DAY),
+          trial: { claimed: true, expires: stamp(trialEndUNIX) },
+          payment: { provider: 'stripe', resourceId: 'sub_stripe_converted', frequency: 'monthly', price: 9.99 },
+        };
+
+        assert.equal(
+          sweep.resolveTrialOutcomeConversion(alreadyReported, 'converted', 'USD'),
+          null,
+          'the term has already moved past the trial, so a payment webhook reported this conversion',
+        );
+      },
+    },
+
+    {
+      // The two paths that can report a trial outcome derive their dedupe id in
+      // two different files, and the whole no-double-count guarantee rests on the
+      // two strings being IDENTICAL. Nothing else would notice them drifting, so
+      // this compares the real output of both derivations for one subscription
+      // ([#407](https://github.com/Omega-JS-Stack/omega/issues/407)).
+      name: 'the-sweep-and-the-webhook-derive-the-same-trial-dedupe-id',
+      async run({ assert }) {
+        const nowUNIX = Math.floor(Date.now() / 1000);
+        const trialEndUNIX = nowUNIX - 5 * DAY;
+        const RESOURCE_ID = 'sub_shared_trial';
+
+        const inTrial = {
+          product: { id: 'premium', name: 'Premium' },
+          status: 'active',
+          expires: stamp(trialEndUNIX),
+          trial: { claimed: true, expires: stamp(trialEndUNIX) },
+          payment: { provider: 'stripe', resourceId: RESOURCE_ID, frequency: 'monthly', price: 9.99 },
+        };
+
+        // The same subscription, one charge later — what the webhook resolves.
+        const converted = { ...inTrial, expires: stamp(nowUNIX + 25 * DAY) };
+
+        for (const [outcome, transition, eventType, after] of [
+          ['converted', null, 'invoice.payment_succeeded', converted],
+          ['lapsed', 'payment-failed', 'invoice.payment_failed', { ...inTrial, status: 'suspended' }],
+        ]) {
+          const resolved = analytics.resolvePaymentEvent('subscription', transition, eventType, after, {}, null, inTrial);
+          const webhookId = analytics.resolveEventId(resolved, { id: '_test-order', metadata: { updatedBy: { event: { id: 'evt_whatever' } } } });
+          const sweepId = sweep.resolveTrialOutcomeConversion(inTrial, outcome, 'USD').eventId;
+
+          assert.equal(webhookId, sweepId, `both paths must call a ${outcome} trial the same conversion`);
+          assert.equal(webhookId.endsWith(`.${RESOURCE_ID}`), true, 'and both must key it on the subscription');
+        }
+      },
+    },
+
+    {
+      name: 'seed-expired-trials',
+      async run({ firestore, assert, state, config, skip }) {
+        const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.type === 'subscription' && p.prices);
+
+        if (!paidProduct) {
+          skip('No paid subscription product configured in this brand');
+        }
+
+        state.paidProductId = paidProduct.id;
+
+        // Five candidates, one per branch the sweep has to get right
+        state.seeds = {
+          // Trial ended 5 days ago; NO order doc → the provider has no such subscription
+          [GONE_UID]: { expiredAgo: 5 * DAY, resourceId: 'sub_test_trial_gone', orderId: null },
+          // Trial ended 5 days ago; the order says the provider cancelled it
+          [CANCELLED_UID]: { expiredAgo: 5 * DAY, resourceId: 'sub_test_trial_cancelled', orderId: CANCELLED_ORDER },
+          // Trial ended 5 days ago; the order says the subscription is live — it converted
+          [CONVERTED_UID]: { expiredAgo: 5 * DAY, resourceId: 'sub_test_trial_converted', orderId: CONVERTED_ORDER },
+          // Trial ended 2 hours ago — inside the grace window that absorbs webhook lag
+          [GRACE_UID]: { expiredAgo: 2 * 60 * 60, resourceId: 'sub_test_trial_grace', orderId: null },
+          // Trial ended 40 days ago — aged out below the sweep's floor
+          [AGED_UID]: { expiredAgo: 40 * DAY, resourceId: 'sub_test_trial_aged', orderId: null },
+        };
+
+        const nowUNIX = Math.floor(Date.now() / 1000);
+
+        for (const [uid, seed] of Object.entries(state.seeds)) {
+          const expiredUNIX = nowUNIX - seed.expiredAgo;
+
+          await firestore.delete(`users/${uid}`);
+          await firestore.set(`users/${uid}`, {
+            subscription: {
+              product: { id: paidProduct.id, name: paidProduct.name || paidProduct.id },
+              status: 'active',
+              expires: stamp(expiredUNIX),
+              trial: { claimed: true, expires: stamp(expiredUNIX) },
+              cancellation: { pending: false, date: stamp(0) },
+              payment: { provider: 'test', orderId: seed.orderId, resourceId: seed.resourceId, frequency: 'monthly' },
+            },
+          });
+        }
+
+        // The provider's answers for the two candidates that have a subscription:
+        // an order whose `unified` the test library reconstructs a resource from
+        await firestore.delete(`payments-orders/${CANCELLED_ORDER}`);
+        await firestore.set(`payments-orders/${CANCELLED_ORDER}`, order({
+          id: CANCELLED_ORDER,
+          owner: CANCELLED_UID,
+          productId: paidProduct.id,
+          resourceId: 'sub_test_trial_cancelled',
+          status: 'cancelled',
+        }));
+
+        await firestore.delete(`payments-orders/${CONVERTED_ORDER}`);
+        await firestore.set(`payments-orders/${CONVERTED_ORDER}`, order({
+          id: CONVERTED_ORDER,
+          owner: CONVERTED_UID,
+          productId: paidProduct.id,
+          resourceId: 'sub_test_trial_converted',
+          status: 'active',
+        }));
+
+        const seeded = await firestore.get(`users/${GONE_UID}`);
+        assert.equal(seeded.subscription.status, 'active', 'Every candidate starts active on a paid product');
+      },
+    },
+
+    {
+      name: 'the-sweep-lapses-what-the-provider-no-longer-has',
+      timeout: 150000,
+      async run({ firestore, assert, waitFor, pubsub, state }) {
+        await pubsub.trigger('omega_cronDaily');
+
+        await waitFor(async () => {
+          const doc = await firestore.get(`users/${GONE_UID}`);
+          return !!doc?.subscription?.trial?.outcome;
+        }, 120000, 1000);
+
+        const gone = await firestore.get(`users/${GONE_UID}`);
+
+        assert.equal(gone.subscription.trial.outcome, 'lapsed', 'The provider has no such subscription — the trial lapsed');
+        assert.equal(gone.subscription.status, 'cancelled', 'A lapsed trial ends cancelled');
+        assert.equal(gone.subscription.product.id, 'basic', 'A lapsed trial ends on basic');
+        assert.equal(gone.subscription.cancellation.pending, false, 'Nothing is left pending');
+        assert.equal(gone.subscription.trial.claimed, true, 'claimed still means "a trial happened" — the sweep never repurposes it');
+
+        state.lapsedCancelledAtUNIX = gone.subscription.cancellation.date.timestampUNIX;
+      },
+    },
+
+    {
+      name: 'a-cancelled-subscription-lapses-the-same-way',
+      timeout: 60000,
+      async run({ firestore, assert, waitFor }) {
+        await waitFor(async () => {
+          const doc = await firestore.get(`users/${CANCELLED_UID}`);
+          return !!doc?.subscription?.trial?.outcome;
+        }, 30000, 500);
+
+        const cancelled = await firestore.get(`users/${CANCELLED_UID}`);
+
+        assert.equal(cancelled.subscription.trial.outcome, 'lapsed', 'The provider says cancelled — the trial lapsed');
+        assert.equal(cancelled.subscription.status, 'cancelled', 'A lapsed trial ends cancelled');
+        assert.equal(cancelled.subscription.product.id, 'basic', 'A lapsed trial ends on basic');
+      },
+    },
+
+    {
+      name: 'a-converted-trial-is-stamped-and-otherwise-untouched',
+      timeout: 60000,
+      async run({ firestore, assert, waitFor, state }) {
+        await waitFor(async () => {
+          const doc = await firestore.get(`users/${CONVERTED_UID}`);
+          return !!doc?.subscription?.trial?.outcome;
+        }, 30000, 500);
+
+        const converted = await firestore.get(`users/${CONVERTED_UID}`);
+
+        assert.equal(converted.subscription.trial.outcome, 'converted', 'The provider says active — the trial converted');
+        assert.equal(converted.subscription.status, 'active', 'A converted trial keeps its active subscription');
+        assert.equal(converted.subscription.product.id, state.paidProductId, 'A converted trial keeps its paid product');
+        assert.equal(converted.subscription.cancellation.pending, false, 'Nothing was cancelled');
+      },
+    },
+
+    {
+      name: 'the-window-edges-are-left-alone',
+      async run({ firestore, assert, state }) {
+        const grace = await firestore.get(`users/${GRACE_UID}`);
+        const aged = await firestore.get(`users/${AGED_UID}`);
+
+        assert.equal(grace.subscription.trial.outcome, undefined, 'A trial that ended 2h ago is inside the grace window — webhook lag gets its chance first');
+        assert.equal(grace.subscription.status, 'active', 'The grace candidate is untouched');
+        assert.equal(grace.subscription.product.id, state.paidProductId, 'The grace candidate keeps its product');
+
+        assert.equal(aged.subscription.trial.outcome, undefined, 'A trial that ended 40 days ago is below the floor — history is not the sweep\'s job');
+        assert.equal(aged.subscription.status, 'active', 'The aged candidate is untouched');
+      },
+    },
+
+    {
+      name: 'a-second-run-changes-nothing',
+      timeout: 150000,
+      async run({ firestore, assert, waitFor, pubsub, state }) {
+        // A run that skips every stamped candidate produces no signal of its own, so
+        // the grace candidate becomes the marker: aged past the grace window, the
+        // SECOND run must lapse it — and its stamp is proof the sweep ran to the end.
+        const expiredUNIX = Math.floor(Date.now() / 1000) - 5 * DAY;
+        await firestore.set(`users/${GRACE_UID}`, {
+          subscription: { trial: { expires: stamp(expiredUNIX) } },
+        }, { merge: true });
+
+        await pubsub.trigger('omega_cronDaily');
+
+        await waitFor(async () => {
+          const doc = await firestore.get(`users/${GRACE_UID}`);
+          return !!doc?.subscription?.trial?.outcome;
+        }, 120000, 1000);
+
+        const grace = await firestore.get(`users/${GRACE_UID}`);
+        const gone = await firestore.get(`users/${GONE_UID}`);
+        const converted = await firestore.get(`users/${CONVERTED_UID}`);
+
+        assert.equal(grace.subscription.trial.outcome, 'lapsed', 'The second run reached the sweep and lapsed the newly-eligible candidate');
+        assert.equal(gone.subscription.trial.outcome, 'lapsed', 'The already-lapsed candidate is still lapsed');
+        assert.equal(
+          gone.subscription.cancellation.date.timestampUNIX,
+          state.lapsedCancelledAtUNIX,
+          'The cancellation date is the FIRST run\'s — the second run skipped it instead of writing again',
+        );
+        assert.equal(converted.subscription.trial.outcome, 'converted', 'The converted candidate is still converted');
+        assert.equal(converted.subscription.status, 'active', 'The converted candidate is still active');
+      },
+    },
+
+  ],
+});
+
+/**
+ * A `$timestamp` pair from a UNIX second
+ */
+function stamp(unix) {
+  return { timestamp: new Date(unix * 1000).toISOString(), timestampUNIX: unix };
+}
+
+/**
+ * The purchase record the test provider answers `fetchResource` from — its `unified`
+ * status IS what the provider reports for the subscription
+ */
+function order({ id, owner, productId, resourceId, status }) {
+  const nowUNIX = Math.floor(Date.now() / 1000);
+
+  return {
+    id: id,
+    type: 'subscription',
+    owner: owner,
+    productId: productId,
+    provider: 'test',
+    resourceId: resourceId,
+    unified: {
+      product: { id: productId },
+      status: status,
+      expires: stamp(nowUNIX + 30 * DAY),
+      trial: { claimed: true, expires: stamp(nowUNIX - 5 * DAY) },
+      cancellation: { pending: false },
+      payment: { provider: 'test', orderId: id, resourceId: resourceId, frequency: 'monthly' },
+    },
+    metadata: {
+      created: stamp(nowUNIX - 20 * DAY),
+      updated: stamp(nowUNIX - 20 * DAY),
+    },
+  };
+}

package/test/events/payments/webhook-atomic-writes.test.js

@@ -0,0 +1,69 @@
+/**
+ * Test: the webhook pipeline's three writes land together or not at all
+ *
+ * Processing a subscription event writes users/{uid}.subscription, then
+ * payments-orders/{orderId}, then payments-intents/{orderId}. As three separate
+ * awaits, a throw between them left the user PAID with no order behind it — the
+ * order page, the cancel endpoint and the refund lane all read the order, so the
+ * split state is invisible until a support ticket ([#219]).
+ *
+ * Plain-node control-flow test (no emulator, no network): the real trigger module
+ * runs against the shared in-memory Firestore stand-in (_webhook-harness.js) whose
+ * payments-orders write rejects. The emulator cannot produce this fault at all —
+ * the admin SDK bypasses rules, and all three writes are legal — so the split is
+ * only reachable by making one write fail, which is exactly what the stand-in
+ * does. The emulator suites stay the integration surface for the happy paths.
+ */
+const assert = require('node:assert');
+const { runTrigger } = require('./_webhook-harness.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const UID = '_test-atomic-uid';
+const ORDER_ID = '4242-4242-4242';
+const RESOURCE_ID = '_test-atomic-sub';
+const EVENT_ID = '_test-atomic-evt';
+
+/** The event this suite is about, with only the failing write left to choose */
+function runEvent({ failPath } = {}) {
+  return runTrigger({
+    uid: UID,
+    orderId: ORDER_ID,
+    resourceId: RESOURCE_ID,
+    eventId: EVENT_ID,
+    failPath: failPath,
+  });
+}
+
+module.exports = defineCases({
+  description: 'Webhook pipeline writes are atomic (no split payment state)',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'a healthy event writes the subscription, the order and the intent',
+
+      async run() {
+        const { store } = await runEvent();
+
+        assert.equal(store.get(`users/${UID}`)?.subscription?.status, 'active', 'the subscription lands');
+        assert.equal(store.get(`payments-orders/${ORDER_ID}`)?.owner, UID, 'the order lands');
+        assert.equal(store.get(`payments-intents/${ORDER_ID}`)?.status, 'completed', 'the intent is closed out');
+        assert.equal(store.get(`payments-webhooks/${EVENT_ID}`)?.status, 'completed', 'the webhook completes');
+      },
+    },
+
+    {
+      name: 'a failed order write leaves NO subscription behind it',
+
+      async run() {
+        const { store } = await runEvent({ failPath: `payments-orders/${ORDER_ID}` });
+
+        assert.ok(!store.get(`users/${UID}`)?.subscription, 'the user must not be left paid with no order');
+        assert.ok(!store.get(`payments-orders/${ORDER_ID}`), 'the order write is the one that failed');
+        assert.equal(store.get(`payments-intents/${ORDER_ID}`)?.status, 'failed', 'the failure path still closes the intent');
+        assert.equal(store.get(`payments-webhooks/${EVENT_ID}`)?.status, 'failed', 'the webhook is marked failed');
+      },
+    },
+  ],
+});