@saasicat/persistence-testing 1.0.0-rc.16 → 1.0.0-rc.18

package/README.md

@@ -25,6 +25,12 @@ Verified scenarios:
 - one promo redemption per subscription (unique guard)
 - audit write → query roundtrip incl. `actorTag` wildcard filters
 - MFA secret roundtrip
+- a gateway event is claimed once per account, a session is confirmed once however many events
+  report it, an event that changed nothing gives its session back while staying claimed itself, and
+  a claim rolled back with its transaction is free for the retry
+- a confirmed payment method replaces the one in use and keeps it as history, per subscriber
+- a change of payment method a tenant started is completed once, and only for the account, session
+  and subscriber it was started for
 - the applied settings: one row per installation, replaced only by a writer that
   read its current fingerprint — so replicas starting together record one change,
   concurrently — with the change and the record it supersedes landing together;
@@ -94,7 +100,14 @@ persistenceAdapterContract({
     }),
     // The parts this adapter deliberately does not provide. A part named here
     // that the harness does provide fails the suite as well.
-    gaps: ['subscriptionContracts', 'subscribers', 'checkoutOffers', 'appliedSettings'],
+    gaps: [
+        'subscriptionContracts',
+        'subscribers',
+        'paymentEventLog',
+        'subscriberPaymentMethods',
+        'checkoutOffers',
+        'appliedSettings',
+    ],
 });
 ```
 

package/dist/.build-stamp

@@ -1 +1 @@
-1ca79840c535585e92be3594dc7e1b240dfd47e78e98d7577fe19a1cd7e51faf
+ec457c9ef09c51121503a82c971c3de2ba82aead3348d11c442cc6018f83d99e

package/dist/index.cjs

@@ -79,6 +79,39 @@ function partiesWith(subscriberId, legalName) {
     }
   };
 }
+function eventAt(gatewayAccount, eventId, about = {}) {
+  return {
+    gatewayAccount,
+    eventId,
+    provider: "stripe",
+    sessionId: `cs_${eventId}`,
+    kind: "payment-method-confirmed",
+    summary: { type: "card", last4: "4242" },
+    ...about
+  };
+}
+var CARD = {
+  type: "card",
+  brand: "visa",
+  last4: "4242",
+  expiryMonth: 12,
+  expiryYear: 2030,
+  country: null,
+  bankCode: null,
+  mandateReference: null,
+  customerRef: "cus_1",
+  paymentMethodRef: "pm_card"
+};
+function paymentMethodFor(subscriberId, paymentMethodRef, confirmedAt, gatewayAccount = "stripe-main") {
+  return {
+    ...CARD,
+    paymentMethodRef,
+    subscriberId,
+    gatewayAccount,
+    provider: "stripe",
+    confirmedAt: new Date(confirmedAt)
+  };
+}
 function subscriberFor(tenantId, legalName) {
   return {
     tenantId,
@@ -236,6 +269,14 @@ var CONTRACT_GAPS = {
     reason: "adapter provides no SubscriberRepository",
     present: ({ adapter }) => Boolean(adapter.subscriberRepository)
   },
+  paymentEventLog: {
+    reason: "adapter provides no PaymentEventLog",
+    present: ({ adapter }) => Boolean(adapter.paymentEventLog)
+  },
+  subscriberPaymentMethods: {
+    reason: "adapter provides no SubscriberPaymentMethodRepository, or no subscriber seed for it",
+    present: ({ adapter, seed }) => Boolean(adapter.subscriberPaymentMethodRepository && seed.createSubscriber)
+  },
   checkoutOffers: {
     reason: "adapter provides no CheckoutOfferRepository",
     present: ({ adapter }) => Boolean(adapter.checkoutOfferRepository)
@@ -2144,6 +2185,484 @@ function persistenceAdapterContract(options) {
         "the contract followed a correction of the live record"
       );
     });
+    (0, import_node_test.test)("a gateway event is claimed once per account, and a duplicate leaves the transaction usable", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      const claims = await adapter.transactionRunner.run(async (tx) => [
+        await log.claim(eventAt("stripe-main", "evt_1"), tx),
+        await log.claim(eventAt("stripe-main", "evt_1"), tx),
+        // The same identifier from another account is another event.
+        await log.claim(eventAt("stripe-old", "evt_1"), tx),
+        // A duplicate that raised would have aborted the transaction here.
+        await log.claim(eventAt("stripe-main", "evt_2"), tx)
+      ]);
+      import_strict.default.deepEqual(claims, [true, false, true, true]);
+      const later = await adapter.transactionRunner.run(
+        (tx) => log.claim(eventAt("stripe-main", "evt_1"), tx)
+      );
+      import_strict.default.equal(later, false, "a committed claim was claimed again");
+    });
+    (0, import_node_test.test)("one gateway session is confirmed once, however many events report it", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      const session = "cs_reported_twice";
+      const claims = await adapter.transactionRunner.run(async (tx) => [
+        await log.claim(
+          eventAt("stripe-main", "evt_form_done", { sessionId: session }),
+          tx
+        ),
+        // The same session, reported again under another identifier:
+        // recording it would set the session's payment method up twice.
+        await log.claim(
+          eventAt("stripe-main", "evt_method_on", { sessionId: session }),
+          tx
+        ),
+        // Another account's session of that name is another session.
+        await log.claim(eventAt("stripe-old", "evt_elsewhere", { sessionId: session }), tx),
+        // A kind that says nothing about the session being confirmed.
+        await log.claim(
+          eventAt("stripe-main", "evt_gave_up", {
+            sessionId: session,
+            kind: "payment-method-setup-failed"
+          }),
+          tx
+        ),
+        // Events about no session at all do not collide with each other.
+        await log.claim(
+          eventAt("stripe-main", "evt_other_1", { sessionId: null, kind: "unhandled" }),
+          tx
+        ),
+        await log.claim(
+          eventAt("stripe-main", "evt_other_2", { sessionId: null, kind: "unhandled" }),
+          tx
+        )
+      ]);
+      import_strict.default.deepEqual(claims, [true, false, true, true, true, true]);
+      const later = await adapter.transactionRunner.run(
+        (tx) => log.claim(eventAt("stripe-main", "evt_late", { sessionId: session }), tx)
+      );
+      import_strict.default.equal(later, false, "a session already confirmed was confirmed again");
+    });
+    (0, import_node_test.test)("a claim rolled back with its transaction is free for the retry", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      await import_strict.default.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          import_strict.default.equal(await log.claim(eventAt("stripe-main", "evt_retry"), tx), true);
+          throw new Error("recording what the event changes failed");
+        }),
+        /recording what the event changes failed/
+      );
+      const retry = await adapter.transactionRunner.run(
+        (tx) => log.claim(eventAt("stripe-main", "evt_retry"), tx)
+      );
+      import_strict.default.equal(retry, true, "the retry was discarded as a duplicate");
+    });
+    (0, import_node_test.test)("a delivery that meets a claim still open waits for it, and answers by its outcome", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      if (!adapter.capabilities.pessimisticLocking) {
+        t.skip(
+          "adapter declares no pessimistic locking: an open claim cannot be waited on"
+        );
+        return;
+      }
+      const [committed, afterCommit] = await Promise.all([
+        adapter.transactionRunner.run(async (tx) => {
+          const claimed = await log.claim(eventAt("stripe-main", "evt_race"), tx);
+          await sleep(LOCK_HOLD_MS);
+          return claimed;
+        }),
+        sleep(LOCK_HOLD_MS / 3).then(
+          () => adapter.transactionRunner.run(
+            (tx) => log.claim(eventAt("stripe-main", "evt_race"), tx)
+          )
+        )
+      ]);
+      import_strict.default.deepEqual([committed, afterCommit], [true, false]);
+      const [rolledBack, afterRollback] = await Promise.allSettled([
+        adapter.transactionRunner.run(async (tx) => {
+          await log.claim(eventAt("stripe-main", "evt_race_back"), tx);
+          await sleep(LOCK_HOLD_MS);
+          throw new Error("the first delivery failed");
+        }),
+        sleep(LOCK_HOLD_MS / 3).then(
+          () => adapter.transactionRunner.run(
+            (tx) => log.claim(eventAt("stripe-main", "evt_race_back"), tx)
+          )
+        )
+      ]);
+      import_strict.default.equal(rolledBack.status, "rejected");
+      import_strict.default.deepEqual(afterRollback, { status: "fulfilled", value: true });
+    });
+    (0, import_node_test.test)("an event that changed nothing gives its session back, and stays claimed itself", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      const session = "cs_nothing_to_do";
+      const released = await adapter.transactionRunner.run(async (tx) => {
+        await log.claim(eventAt("stripe-main", "evt_missed", { sessionId: session }), tx);
+        await log.releaseSession("stripe-main", "evt_missed", tx);
+        return [
+          // The next event about that session is handled …
+          await log.claim(
+            eventAt("stripe-main", "evt_correct", { sessionId: session }),
+            tx
+          ),
+          // … while the event that released it stays claimed.
+          await log.claim(eventAt("stripe-main", "evt_missed", { sessionId: null }), tx)
+        ];
+      });
+      import_strict.default.deepEqual(released, [true, false]);
+      const again = await adapter.transactionRunner.run(
+        (tx) => log.claim(eventAt("stripe-main", "evt_after_correct", { sessionId: session }), tx)
+      );
+      import_strict.default.equal(again, false, "the session was confirmed and is not free again");
+    });
+    (0, import_node_test.test)("two events confirming one session at once end with one claim", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      if (!adapter.capabilities.pessimisticLocking) {
+        t.skip(
+          "adapter declares no pessimistic locking: an open claim cannot be waited on"
+        );
+        return;
+      }
+      const session = "cs_at_once";
+      const [first, second] = await Promise.all([
+        adapter.transactionRunner.run(async (tx) => {
+          const claimed = await log.claim(
+            eventAt("stripe-main", "evt_at_once_a", { sessionId: session }),
+            tx
+          );
+          await sleep(LOCK_HOLD_MS);
+          return claimed;
+        }),
+        sleep(LOCK_HOLD_MS / 3).then(
+          () => adapter.transactionRunner.run(
+            (tx) => log.claim(
+              eventAt("stripe-main", "evt_at_once_b", { sessionId: session }),
+              tx
+            )
+          )
+        )
+      ]);
+      import_strict.default.deepEqual([first, second], [true, false]);
+    });
+    (0, import_node_test.test)("a confirmed payment method becomes the subscriber's, with its references and masked details", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Karte GmbH" });
+      const debit = {
+        ...paymentMethodFor(subscriberId, "pm_sepa", "2026-09-01T10:00:00.000Z"),
+        type: "sepa_debit",
+        brand: null,
+        last4: "3000",
+        expiryMonth: null,
+        expiryYear: null,
+        country: "DE",
+        bankCode: "37040044",
+        mandateReference: "MANDATE-1"
+      };
+      const result = await methods.recordConfirmed(debit);
+      import_strict.default.equal(result.outcome, "activated");
+      const { id, createdAt, ...stored } = result.method;
+      import_strict.default.ok(id);
+      import_strict.default.ok(createdAt instanceof Date);
+      import_strict.default.deepEqual(stored, { ...debit, status: "ACTIVE", replacedAt: null });
+      import_strict.default.deepEqual(await methods.findActive(subscriberId), result.method);
+      import_strict.default.deepEqual(
+        await methods.findByReference("stripe-main", "pm_sepa"),
+        result.method
+      );
+      import_strict.default.equal(await methods.findByReference("stripe-old", "pm_sepa"), null);
+      const other = await createSubscriber({ legalName: "Second Customer GmbH" });
+      import_strict.default.equal(await methods.findActive(other.subscriberId), null);
+    });
+    (0, import_node_test.test)("a newer payment method takes over, and the one it replaced stays as history", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Wechsel GmbH" });
+      await methods.recordConfirmed(
+        paymentMethodFor(subscriberId, "pm_first", "2026-09-01T10:00:00.000Z")
+      );
+      const second = await methods.recordConfirmed(
+        paymentMethodFor(subscriberId, "pm_second", "2026-09-02T10:00:00.000Z")
+      );
+      import_strict.default.equal(second.outcome, "activated");
+      import_strict.default.equal((await methods.findActive(subscriberId))?.paymentMethodRef, "pm_second");
+      const first = await methods.findByReference("stripe-main", "pm_first");
+      import_strict.default.equal(first?.status, "REPLACED");
+      import_strict.default.equal(first?.replacedAt?.toISOString(), "2026-09-02T10:00:00.000Z");
+    });
+    (0, import_node_test.test)("a confirmation recorded again is recognised, and changes nothing", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Doppelt GmbH" });
+      const confirmation = paymentMethodFor(
+        subscriberId,
+        "pm_twice",
+        "2026-09-01T10:00:00.000Z"
+      );
+      const first = await methods.recordConfirmed(confirmation);
+      const again = await methods.recordConfirmed({
+        ...confirmation,
+        confirmedAt: /* @__PURE__ */ new Date("2026-09-03T10:00:00.000Z")
+      });
+      import_strict.default.equal(again.outcome, "already-recorded");
+      import_strict.default.deepEqual(again.method, first.method);
+      import_strict.default.deepEqual(await methods.findActive(subscriberId), first.method);
+    });
+    (0, import_node_test.test)("a confirmation older than the payment method in use is recorded as already replaced", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Reihenfolge GmbH" });
+      await methods.recordConfirmed(
+        paymentMethodFor(subscriberId, "pm_later", "2026-09-02T10:00:00.000Z")
+      );
+      const earlier = await methods.recordConfirmed(
+        paymentMethodFor(subscriberId, "pm_earlier", "2026-09-01T10:00:00.000Z")
+      );
+      import_strict.default.equal(earlier.outcome, "superseded");
+      import_strict.default.equal(earlier.method.status, "REPLACED");
+      import_strict.default.equal(earlier.method.replacedAt?.toISOString(), "2026-09-02T10:00:00.000Z");
+      import_strict.default.equal((await methods.findActive(subscriberId))?.paymentMethodRef, "pm_later");
+    });
+    (0, import_node_test.test)("two confirmations for one subscriber at once leave one payment method in use", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Gleichzeitig GmbH" });
+      const results = await Promise.all([
+        methods.recordConfirmed(
+          paymentMethodFor(subscriberId, "pm_at_once_a", "2026-09-01T10:00:00.000Z")
+        ),
+        methods.recordConfirmed(
+          paymentMethodFor(subscriberId, "pm_at_once_b", "2026-09-01T10:00:01.000Z")
+        )
+      ]);
+      for (const result of results) {
+        import_strict.default.ok(
+          result.outcome === "activated" || result.outcome === "superseded",
+          result.outcome
+        );
+      }
+      const statuses = await Promise.all(
+        ["pm_at_once_a", "pm_at_once_b"].map(
+          async (ref) => (await methods.findByReference("stripe-main", ref))?.status
+        )
+      );
+      import_strict.default.deepEqual(statuses, ["REPLACED", "ACTIVE"]);
+      import_strict.default.equal(
+        (await methods.findActive(subscriberId))?.paymentMethodRef,
+        "pm_at_once_b"
+      );
+    });
+    (0, import_node_test.test)("a payment method written on a transaction is undone with it", async (t) => {
+      const { adapter } = harness;
+      const methods = adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Rolled Back GmbH" });
+      await import_strict.default.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await methods.recordConfirmed(
+            paymentMethodFor(
+              subscriberId,
+              "pm_rolled_back",
+              "2026-09-01T10:00:00.000Z"
+            ),
+            tx
+          );
+          throw new Error("the activation failed after all");
+        }),
+        /the activation failed after all/
+      );
+      import_strict.default.equal(await methods.findActive(subscriberId), null);
+      import_strict.default.equal(await methods.findByReference("stripe-main", "pm_rolled_back"), null);
+    });
+    (0, import_node_test.test)("a payment method for a subscriber that does not exist is refused", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      if (!methods || !harness.seed.createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      await import_strict.default.rejects(
+        methods.recordConfirmed(
+          paymentMethodFor(
+            "subscriber-nobody-created",
+            "pm_nobody",
+            "2026-09-01T10:00:00.000Z"
+          )
+        )
+      );
+      import_strict.default.equal(await methods.findByReference("stripe-main", "pm_nobody"), null);
+    });
+    (0, import_node_test.test)("the accounts in use are those holding a payment method in use, each once", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      import_strict.default.deepEqual(await methods.accountsInUse(), []);
+      const moved = await createSubscriber({ legalName: "Umgezogen GmbH" });
+      const stayed = await createSubscriber({ legalName: "Geblieben GmbH" });
+      await methods.recordConfirmed(
+        paymentMethodFor(
+          moved.subscriberId,
+          "pm_old_account",
+          "2026-09-01T10:00:00.000Z",
+          "stripe-old"
+        )
+      );
+      await methods.recordConfirmed(
+        paymentMethodFor(
+          moved.subscriberId,
+          "pm_new_account",
+          "2026-09-02T10:00:00.000Z",
+          "stripe-main"
+        )
+      );
+      await methods.recordConfirmed(
+        paymentMethodFor(
+          stayed.subscriberId,
+          "pm_main",
+          "2026-09-02T10:00:00.000Z",
+          "stripe-main"
+        )
+      );
+      import_strict.default.deepEqual(await methods.accountsInUse(), ["stripe-main"]);
+    });
+    (0, import_node_test.test)("a setup is completed once, and only by the account, session and subscriber it was started with", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Setup GmbH" });
+      const other = await createSubscriber({ legalName: "Other Tenant GmbH" });
+      await methods.recordSetup({
+        subscriberId,
+        gatewayAccount: "stripe-main",
+        sessionRef: "cs_setup",
+        customerRef: "cus_setup",
+        startedAt: /* @__PURE__ */ new Date("2026-09-15T10:00:00.000Z")
+      });
+      const at = /* @__PURE__ */ new Date("2026-09-15T10:05:00.000Z");
+      const match = { gatewayAccount: "stripe-main", sessionRef: "cs_setup", subscriberId };
+      import_strict.default.equal(
+        await methods.completeSetup({ ...match, subscriberId: other.subscriberId }, at),
+        false
+      );
+      import_strict.default.equal(
+        await methods.completeSetup({ ...match, gatewayAccount: "stripe-old" }, at),
+        false
+      );
+      import_strict.default.equal(
+        await methods.completeSetup({ ...match, sessionRef: "cs_nobody_opened" }, at),
+        false
+      );
+      import_strict.default.equal(await methods.completeSetup(match, at), true);
+      import_strict.default.equal(
+        await methods.completeSetup(match, at),
+        false,
+        "a setup was completed twice"
+      );
+    });
+    (0, import_node_test.test)("a setup completed on a transaction that rolls back is open again", async (t) => {
+      const { adapter } = harness;
+      const methods = adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Retry GmbH" });
+      const match = { gatewayAccount: "stripe-main", sessionRef: "cs_retry", subscriberId };
+      await methods.recordSetup({
+        ...match,
+        customerRef: "cus_retry",
+        startedAt: /* @__PURE__ */ new Date("2026-09-15T10:00:00.000Z")
+      });
+      const at = /* @__PURE__ */ new Date("2026-09-15T10:05:00.000Z");
+      await import_strict.default.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          import_strict.default.equal(await methods.completeSetup(match, at, tx), true);
+          throw new Error("recording the payment method failed");
+        }),
+        /recording the payment method failed/
+      );
+      import_strict.default.equal(
+        await methods.completeSetup(match, at),
+        true,
+        "the rollback kept the completion"
+      );
+    });
+    (0, import_node_test.test)("one session is one setup, however often it is recorded", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Once GmbH" });
+      const setup = {
+        subscriberId,
+        gatewayAccount: "stripe-main",
+        sessionRef: "cs_once",
+        customerRef: "cus_once",
+        startedAt: /* @__PURE__ */ new Date("2026-09-15T10:00:00.000Z")
+      };
+      await methods.recordSetup(setup);
+      await import_strict.default.rejects(methods.recordSetup(setup));
+    });
     (0, import_node_test.test)("an offer is consumed once, whoever asks first", async (t) => {
       const offers = harness.adapter.checkoutOfferRepository;
       if (!offers) {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, SubscriberRepository, CheckoutOfferRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleRepository, PlanRepository, PromoSubscriptionLookup, AppliedSettingsPort } from '@saasicat/core';
+import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, SubscriberRepository, PaymentEventLog, SubscriberPaymentMethodRepository, CheckoutOfferRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleRepository, PlanRepository, PromoSubscriptionLookup, AppliedSettingsPort } from '@saasicat/core';
 
 /**
  * Port instances under test. Required members define the minimum an adapter
@@ -26,6 +26,19 @@ interface ContractAdapterInstances {
      * through `seed.createSubscriber` rather than through this port.
      */
     subscriberRepository?: SubscriberRepository;
+    /**
+     * Enables the gateway event scenarios: an event is claimed once per
+     * account, a duplicate leaves the caller's transaction usable, and a claim
+     * rolled back with its transaction is free for the gateway's retry.
+     */
+    paymentEventLog?: PaymentEventLog;
+    /**
+     * Enables the payment method scenarios: one payment method in use per
+     * subscriber however many confirmations arrive at once, the one it
+     * replaced kept as history, and a confirmation recorded twice recognised.
+     * Its subscribers come from `seed.createSubscriber`.
+     */
+    subscriberPaymentMethodRepository?: SubscriberPaymentMethodRepository;
     /**
      * Enables the checkout offer scenarios: an offer is consumed once, and a
      * consume on a transaction that rolls back leaves it open. Neither shipped
@@ -160,7 +173,7 @@ interface PersistenceContractHarness {
  * Each names the members its scenarios need; `contract.ts` holds the list with
  * what each one checks.
  */
-type ContractGap = 'atomicPlanBinding' | 'atomicOnboarding' | 'promoCodes' | 'promoCodeRedemptions' | 'promoSubscriptionLookup' | 'planRepository' | 'planLifecycle' | 'planRetirement' | 'planVersionReads' | 'planVersionRetirement' | 'bundleRepository' | 'bundleValidity' | 'bundleDraftDiscard' | 'bundleDraftPublish' | 'bundleRetirement' | 'bundleBookings' | 'halfCancelledBookingSeed' | 'countByPlanVersionId' | 'audit' | 'mfa' | 'subscriptionContracts' | 'subscribers' | 'checkoutOffers' | 'appliedSettings';
+type ContractGap = 'atomicPlanBinding' | 'atomicOnboarding' | 'promoCodes' | 'promoCodeRedemptions' | 'promoSubscriptionLookup' | 'planRepository' | 'planLifecycle' | 'planRetirement' | 'planVersionReads' | 'planVersionRetirement' | 'bundleRepository' | 'bundleValidity' | 'bundleDraftDiscard' | 'bundleDraftPublish' | 'bundleRetirement' | 'bundleBookings' | 'halfCancelledBookingSeed' | 'countByPlanVersionId' | 'audit' | 'mfa' | 'subscriptionContracts' | 'subscribers' | 'paymentEventLog' | 'subscriberPaymentMethods' | 'checkoutOffers' | 'appliedSettings';
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, SubscriberRepository, CheckoutOfferRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleRepository, PlanRepository, PromoSubscriptionLookup, AppliedSettingsPort } from '@saasicat/core';
+import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, SubscriberRepository, PaymentEventLog, SubscriberPaymentMethodRepository, CheckoutOfferRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleRepository, PlanRepository, PromoSubscriptionLookup, AppliedSettingsPort } from '@saasicat/core';
 
 /**
  * Port instances under test. Required members define the minimum an adapter
@@ -26,6 +26,19 @@ interface ContractAdapterInstances {
      * through `seed.createSubscriber` rather than through this port.
      */
     subscriberRepository?: SubscriberRepository;
+    /**
+     * Enables the gateway event scenarios: an event is claimed once per
+     * account, a duplicate leaves the caller's transaction usable, and a claim
+     * rolled back with its transaction is free for the gateway's retry.
+     */
+    paymentEventLog?: PaymentEventLog;
+    /**
+     * Enables the payment method scenarios: one payment method in use per
+     * subscriber however many confirmations arrive at once, the one it
+     * replaced kept as history, and a confirmation recorded twice recognised.
+     * Its subscribers come from `seed.createSubscriber`.
+     */
+    subscriberPaymentMethodRepository?: SubscriberPaymentMethodRepository;
     /**
      * Enables the checkout offer scenarios: an offer is consumed once, and a
      * consume on a transaction that rolls back leaves it open. Neither shipped
@@ -160,7 +173,7 @@ interface PersistenceContractHarness {
  * Each names the members its scenarios need; `contract.ts` holds the list with
  * what each one checks.
  */
-type ContractGap = 'atomicPlanBinding' | 'atomicOnboarding' | 'promoCodes' | 'promoCodeRedemptions' | 'promoSubscriptionLookup' | 'planRepository' | 'planLifecycle' | 'planRetirement' | 'planVersionReads' | 'planVersionRetirement' | 'bundleRepository' | 'bundleValidity' | 'bundleDraftDiscard' | 'bundleDraftPublish' | 'bundleRetirement' | 'bundleBookings' | 'halfCancelledBookingSeed' | 'countByPlanVersionId' | 'audit' | 'mfa' | 'subscriptionContracts' | 'subscribers' | 'checkoutOffers' | 'appliedSettings';
+type ContractGap = 'atomicPlanBinding' | 'atomicOnboarding' | 'promoCodes' | 'promoCodeRedemptions' | 'promoSubscriptionLookup' | 'planRepository' | 'planLifecycle' | 'planRetirement' | 'planVersionReads' | 'planVersionRetirement' | 'bundleRepository' | 'bundleValidity' | 'bundleDraftDiscard' | 'bundleDraftPublish' | 'bundleRetirement' | 'bundleBookings' | 'halfCancelledBookingSeed' | 'countByPlanVersionId' | 'audit' | 'mfa' | 'subscriptionContracts' | 'subscribers' | 'paymentEventLog' | 'subscriberPaymentMethods' | 'checkoutOffers' | 'appliedSettings';
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;

package/dist/index.js

@@ -43,6 +43,39 @@ function partiesWith(subscriberId, legalName) {
     }
   };
 }
+function eventAt(gatewayAccount, eventId, about = {}) {
+  return {
+    gatewayAccount,
+    eventId,
+    provider: "stripe",
+    sessionId: `cs_${eventId}`,
+    kind: "payment-method-confirmed",
+    summary: { type: "card", last4: "4242" },
+    ...about
+  };
+}
+var CARD = {
+  type: "card",
+  brand: "visa",
+  last4: "4242",
+  expiryMonth: 12,
+  expiryYear: 2030,
+  country: null,
+  bankCode: null,
+  mandateReference: null,
+  customerRef: "cus_1",
+  paymentMethodRef: "pm_card"
+};
+function paymentMethodFor(subscriberId, paymentMethodRef, confirmedAt, gatewayAccount = "stripe-main") {
+  return {
+    ...CARD,
+    paymentMethodRef,
+    subscriberId,
+    gatewayAccount,
+    provider: "stripe",
+    confirmedAt: new Date(confirmedAt)
+  };
+}
 function subscriberFor(tenantId, legalName) {
   return {
     tenantId,
@@ -200,6 +233,14 @@ var CONTRACT_GAPS = {
     reason: "adapter provides no SubscriberRepository",
     present: ({ adapter }) => Boolean(adapter.subscriberRepository)
   },
+  paymentEventLog: {
+    reason: "adapter provides no PaymentEventLog",
+    present: ({ adapter }) => Boolean(adapter.paymentEventLog)
+  },
+  subscriberPaymentMethods: {
+    reason: "adapter provides no SubscriberPaymentMethodRepository, or no subscriber seed for it",
+    present: ({ adapter, seed }) => Boolean(adapter.subscriberPaymentMethodRepository && seed.createSubscriber)
+  },
   checkoutOffers: {
     reason: "adapter provides no CheckoutOfferRepository",
     present: ({ adapter }) => Boolean(adapter.checkoutOfferRepository)
@@ -2108,6 +2149,484 @@ function persistenceAdapterContract(options) {
         "the contract followed a correction of the live record"
       );
     });
+    test("a gateway event is claimed once per account, and a duplicate leaves the transaction usable", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      const claims = await adapter.transactionRunner.run(async (tx) => [
+        await log.claim(eventAt("stripe-main", "evt_1"), tx),
+        await log.claim(eventAt("stripe-main", "evt_1"), tx),
+        // The same identifier from another account is another event.
+        await log.claim(eventAt("stripe-old", "evt_1"), tx),
+        // A duplicate that raised would have aborted the transaction here.
+        await log.claim(eventAt("stripe-main", "evt_2"), tx)
+      ]);
+      assert.deepEqual(claims, [true, false, true, true]);
+      const later = await adapter.transactionRunner.run(
+        (tx) => log.claim(eventAt("stripe-main", "evt_1"), tx)
+      );
+      assert.equal(later, false, "a committed claim was claimed again");
+    });
+    test("one gateway session is confirmed once, however many events report it", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      const session = "cs_reported_twice";
+      const claims = await adapter.transactionRunner.run(async (tx) => [
+        await log.claim(
+          eventAt("stripe-main", "evt_form_done", { sessionId: session }),
+          tx
+        ),
+        // The same session, reported again under another identifier:
+        // recording it would set the session's payment method up twice.
+        await log.claim(
+          eventAt("stripe-main", "evt_method_on", { sessionId: session }),
+          tx
+        ),
+        // Another account's session of that name is another session.
+        await log.claim(eventAt("stripe-old", "evt_elsewhere", { sessionId: session }), tx),
+        // A kind that says nothing about the session being confirmed.
+        await log.claim(
+          eventAt("stripe-main", "evt_gave_up", {
+            sessionId: session,
+            kind: "payment-method-setup-failed"
+          }),
+          tx
+        ),
+        // Events about no session at all do not collide with each other.
+        await log.claim(
+          eventAt("stripe-main", "evt_other_1", { sessionId: null, kind: "unhandled" }),
+          tx
+        ),
+        await log.claim(
+          eventAt("stripe-main", "evt_other_2", { sessionId: null, kind: "unhandled" }),
+          tx
+        )
+      ]);
+      assert.deepEqual(claims, [true, false, true, true, true, true]);
+      const later = await adapter.transactionRunner.run(
+        (tx) => log.claim(eventAt("stripe-main", "evt_late", { sessionId: session }), tx)
+      );
+      assert.equal(later, false, "a session already confirmed was confirmed again");
+    });
+    test("a claim rolled back with its transaction is free for the retry", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      await assert.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          assert.equal(await log.claim(eventAt("stripe-main", "evt_retry"), tx), true);
+          throw new Error("recording what the event changes failed");
+        }),
+        /recording what the event changes failed/
+      );
+      const retry = await adapter.transactionRunner.run(
+        (tx) => log.claim(eventAt("stripe-main", "evt_retry"), tx)
+      );
+      assert.equal(retry, true, "the retry was discarded as a duplicate");
+    });
+    test("a delivery that meets a claim still open waits for it, and answers by its outcome", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      if (!adapter.capabilities.pessimisticLocking) {
+        t.skip(
+          "adapter declares no pessimistic locking: an open claim cannot be waited on"
+        );
+        return;
+      }
+      const [committed, afterCommit] = await Promise.all([
+        adapter.transactionRunner.run(async (tx) => {
+          const claimed = await log.claim(eventAt("stripe-main", "evt_race"), tx);
+          await sleep(LOCK_HOLD_MS);
+          return claimed;
+        }),
+        sleep(LOCK_HOLD_MS / 3).then(
+          () => adapter.transactionRunner.run(
+            (tx) => log.claim(eventAt("stripe-main", "evt_race"), tx)
+          )
+        )
+      ]);
+      assert.deepEqual([committed, afterCommit], [true, false]);
+      const [rolledBack, afterRollback] = await Promise.allSettled([
+        adapter.transactionRunner.run(async (tx) => {
+          await log.claim(eventAt("stripe-main", "evt_race_back"), tx);
+          await sleep(LOCK_HOLD_MS);
+          throw new Error("the first delivery failed");
+        }),
+        sleep(LOCK_HOLD_MS / 3).then(
+          () => adapter.transactionRunner.run(
+            (tx) => log.claim(eventAt("stripe-main", "evt_race_back"), tx)
+          )
+        )
+      ]);
+      assert.equal(rolledBack.status, "rejected");
+      assert.deepEqual(afterRollback, { status: "fulfilled", value: true });
+    });
+    test("an event that changed nothing gives its session back, and stays claimed itself", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      const session = "cs_nothing_to_do";
+      const released = await adapter.transactionRunner.run(async (tx) => {
+        await log.claim(eventAt("stripe-main", "evt_missed", { sessionId: session }), tx);
+        await log.releaseSession("stripe-main", "evt_missed", tx);
+        return [
+          // The next event about that session is handled …
+          await log.claim(
+            eventAt("stripe-main", "evt_correct", { sessionId: session }),
+            tx
+          ),
+          // … while the event that released it stays claimed.
+          await log.claim(eventAt("stripe-main", "evt_missed", { sessionId: null }), tx)
+        ];
+      });
+      assert.deepEqual(released, [true, false]);
+      const again = await adapter.transactionRunner.run(
+        (tx) => log.claim(eventAt("stripe-main", "evt_after_correct", { sessionId: session }), tx)
+      );
+      assert.equal(again, false, "the session was confirmed and is not free again");
+    });
+    test("two events confirming one session at once end with one claim", async (t) => {
+      const { adapter } = harness;
+      const log = adapter.paymentEventLog;
+      if (!log) {
+        missing(t, "paymentEventLog");
+        return;
+      }
+      if (!adapter.capabilities.pessimisticLocking) {
+        t.skip(
+          "adapter declares no pessimistic locking: an open claim cannot be waited on"
+        );
+        return;
+      }
+      const session = "cs_at_once";
+      const [first, second] = await Promise.all([
+        adapter.transactionRunner.run(async (tx) => {
+          const claimed = await log.claim(
+            eventAt("stripe-main", "evt_at_once_a", { sessionId: session }),
+            tx
+          );
+          await sleep(LOCK_HOLD_MS);
+          return claimed;
+        }),
+        sleep(LOCK_HOLD_MS / 3).then(
+          () => adapter.transactionRunner.run(
+            (tx) => log.claim(
+              eventAt("stripe-main", "evt_at_once_b", { sessionId: session }),
+              tx
+            )
+          )
+        )
+      ]);
+      assert.deepEqual([first, second], [true, false]);
+    });
+    test("a confirmed payment method becomes the subscriber's, with its references and masked details", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Karte GmbH" });
+      const debit = {
+        ...paymentMethodFor(subscriberId, "pm_sepa", "2026-09-01T10:00:00.000Z"),
+        type: "sepa_debit",
+        brand: null,
+        last4: "3000",
+        expiryMonth: null,
+        expiryYear: null,
+        country: "DE",
+        bankCode: "37040044",
+        mandateReference: "MANDATE-1"
+      };
+      const result = await methods.recordConfirmed(debit);
+      assert.equal(result.outcome, "activated");
+      const { id, createdAt, ...stored } = result.method;
+      assert.ok(id);
+      assert.ok(createdAt instanceof Date);
+      assert.deepEqual(stored, { ...debit, status: "ACTIVE", replacedAt: null });
+      assert.deepEqual(await methods.findActive(subscriberId), result.method);
+      assert.deepEqual(
+        await methods.findByReference("stripe-main", "pm_sepa"),
+        result.method
+      );
+      assert.equal(await methods.findByReference("stripe-old", "pm_sepa"), null);
+      const other = await createSubscriber({ legalName: "Second Customer GmbH" });
+      assert.equal(await methods.findActive(other.subscriberId), null);
+    });
+    test("a newer payment method takes over, and the one it replaced stays as history", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Wechsel GmbH" });
+      await methods.recordConfirmed(
+        paymentMethodFor(subscriberId, "pm_first", "2026-09-01T10:00:00.000Z")
+      );
+      const second = await methods.recordConfirmed(
+        paymentMethodFor(subscriberId, "pm_second", "2026-09-02T10:00:00.000Z")
+      );
+      assert.equal(second.outcome, "activated");
+      assert.equal((await methods.findActive(subscriberId))?.paymentMethodRef, "pm_second");
+      const first = await methods.findByReference("stripe-main", "pm_first");
+      assert.equal(first?.status, "REPLACED");
+      assert.equal(first?.replacedAt?.toISOString(), "2026-09-02T10:00:00.000Z");
+    });
+    test("a confirmation recorded again is recognised, and changes nothing", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Doppelt GmbH" });
+      const confirmation = paymentMethodFor(
+        subscriberId,
+        "pm_twice",
+        "2026-09-01T10:00:00.000Z"
+      );
+      const first = await methods.recordConfirmed(confirmation);
+      const again = await methods.recordConfirmed({
+        ...confirmation,
+        confirmedAt: /* @__PURE__ */ new Date("2026-09-03T10:00:00.000Z")
+      });
+      assert.equal(again.outcome, "already-recorded");
+      assert.deepEqual(again.method, first.method);
+      assert.deepEqual(await methods.findActive(subscriberId), first.method);
+    });
+    test("a confirmation older than the payment method in use is recorded as already replaced", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Reihenfolge GmbH" });
+      await methods.recordConfirmed(
+        paymentMethodFor(subscriberId, "pm_later", "2026-09-02T10:00:00.000Z")
+      );
+      const earlier = await methods.recordConfirmed(
+        paymentMethodFor(subscriberId, "pm_earlier", "2026-09-01T10:00:00.000Z")
+      );
+      assert.equal(earlier.outcome, "superseded");
+      assert.equal(earlier.method.status, "REPLACED");
+      assert.equal(earlier.method.replacedAt?.toISOString(), "2026-09-02T10:00:00.000Z");
+      assert.equal((await methods.findActive(subscriberId))?.paymentMethodRef, "pm_later");
+    });
+    test("two confirmations for one subscriber at once leave one payment method in use", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Gleichzeitig GmbH" });
+      const results = await Promise.all([
+        methods.recordConfirmed(
+          paymentMethodFor(subscriberId, "pm_at_once_a", "2026-09-01T10:00:00.000Z")
+        ),
+        methods.recordConfirmed(
+          paymentMethodFor(subscriberId, "pm_at_once_b", "2026-09-01T10:00:01.000Z")
+        )
+      ]);
+      for (const result of results) {
+        assert.ok(
+          result.outcome === "activated" || result.outcome === "superseded",
+          result.outcome
+        );
+      }
+      const statuses = await Promise.all(
+        ["pm_at_once_a", "pm_at_once_b"].map(
+          async (ref) => (await methods.findByReference("stripe-main", ref))?.status
+        )
+      );
+      assert.deepEqual(statuses, ["REPLACED", "ACTIVE"]);
+      assert.equal(
+        (await methods.findActive(subscriberId))?.paymentMethodRef,
+        "pm_at_once_b"
+      );
+    });
+    test("a payment method written on a transaction is undone with it", async (t) => {
+      const { adapter } = harness;
+      const methods = adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Rolled Back GmbH" });
+      await assert.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await methods.recordConfirmed(
+            paymentMethodFor(
+              subscriberId,
+              "pm_rolled_back",
+              "2026-09-01T10:00:00.000Z"
+            ),
+            tx
+          );
+          throw new Error("the activation failed after all");
+        }),
+        /the activation failed after all/
+      );
+      assert.equal(await methods.findActive(subscriberId), null);
+      assert.equal(await methods.findByReference("stripe-main", "pm_rolled_back"), null);
+    });
+    test("a payment method for a subscriber that does not exist is refused", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      if (!methods || !harness.seed.createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      await assert.rejects(
+        methods.recordConfirmed(
+          paymentMethodFor(
+            "subscriber-nobody-created",
+            "pm_nobody",
+            "2026-09-01T10:00:00.000Z"
+          )
+        )
+      );
+      assert.equal(await methods.findByReference("stripe-main", "pm_nobody"), null);
+    });
+    test("the accounts in use are those holding a payment method in use, each once", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      assert.deepEqual(await methods.accountsInUse(), []);
+      const moved = await createSubscriber({ legalName: "Umgezogen GmbH" });
+      const stayed = await createSubscriber({ legalName: "Geblieben GmbH" });
+      await methods.recordConfirmed(
+        paymentMethodFor(
+          moved.subscriberId,
+          "pm_old_account",
+          "2026-09-01T10:00:00.000Z",
+          "stripe-old"
+        )
+      );
+      await methods.recordConfirmed(
+        paymentMethodFor(
+          moved.subscriberId,
+          "pm_new_account",
+          "2026-09-02T10:00:00.000Z",
+          "stripe-main"
+        )
+      );
+      await methods.recordConfirmed(
+        paymentMethodFor(
+          stayed.subscriberId,
+          "pm_main",
+          "2026-09-02T10:00:00.000Z",
+          "stripe-main"
+        )
+      );
+      assert.deepEqual(await methods.accountsInUse(), ["stripe-main"]);
+    });
+    test("a setup is completed once, and only by the account, session and subscriber it was started with", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Setup GmbH" });
+      const other = await createSubscriber({ legalName: "Other Tenant GmbH" });
+      await methods.recordSetup({
+        subscriberId,
+        gatewayAccount: "stripe-main",
+        sessionRef: "cs_setup",
+        customerRef: "cus_setup",
+        startedAt: /* @__PURE__ */ new Date("2026-09-15T10:00:00.000Z")
+      });
+      const at = /* @__PURE__ */ new Date("2026-09-15T10:05:00.000Z");
+      const match = { gatewayAccount: "stripe-main", sessionRef: "cs_setup", subscriberId };
+      assert.equal(
+        await methods.completeSetup({ ...match, subscriberId: other.subscriberId }, at),
+        false
+      );
+      assert.equal(
+        await methods.completeSetup({ ...match, gatewayAccount: "stripe-old" }, at),
+        false
+      );
+      assert.equal(
+        await methods.completeSetup({ ...match, sessionRef: "cs_nobody_opened" }, at),
+        false
+      );
+      assert.equal(await methods.completeSetup(match, at), true);
+      assert.equal(
+        await methods.completeSetup(match, at),
+        false,
+        "a setup was completed twice"
+      );
+    });
+    test("a setup completed on a transaction that rolls back is open again", async (t) => {
+      const { adapter } = harness;
+      const methods = adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Retry GmbH" });
+      const match = { gatewayAccount: "stripe-main", sessionRef: "cs_retry", subscriberId };
+      await methods.recordSetup({
+        ...match,
+        customerRef: "cus_retry",
+        startedAt: /* @__PURE__ */ new Date("2026-09-15T10:00:00.000Z")
+      });
+      const at = /* @__PURE__ */ new Date("2026-09-15T10:05:00.000Z");
+      await assert.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          assert.equal(await methods.completeSetup(match, at, tx), true);
+          throw new Error("recording the payment method failed");
+        }),
+        /recording the payment method failed/
+      );
+      assert.equal(
+        await methods.completeSetup(match, at),
+        true,
+        "the rollback kept the completion"
+      );
+    });
+    test("one session is one setup, however often it is recorded", async (t) => {
+      const methods = harness.adapter.subscriberPaymentMethodRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!methods || !createSubscriber) {
+        missing(t, "subscriberPaymentMethods");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Once GmbH" });
+      const setup = {
+        subscriberId,
+        gatewayAccount: "stripe-main",
+        sessionRef: "cs_once",
+        customerRef: "cus_once",
+        startedAt: /* @__PURE__ */ new Date("2026-09-15T10:00:00.000Z")
+      };
+      await methods.recordSetup(setup);
+      await assert.rejects(methods.recordSetup(setup));
+    });
     test("an offer is consumed once, whoever asks first", async (t) => {
       const offers = harness.adapter.checkoutOfferRepository;
       if (!offers) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/persistence-testing",
-  "version": "1.0.0-rc.16",
+  "version": "1.0.0-rc.18",
   "description": "Contract test kit for SaaSiCat persistence adapters: one node:test suite that every adapter (Prisma, Drizzle, ...) must pass against a real database — locks, transaction rollback, atomic promo claims, tenant isolation, audit/MFA roundtrips.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,7 +23,7 @@
     "dist"
   ],
   "dependencies": {
-    "@saasicat/core": "^1.0.0-rc.16"
+    "@saasicat/core": "^1.0.0-rc.18"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",