@saasicat/persistence-testing 1.0.0-rc.15 → 1.0.0-rc.17

package/dist/index.js

@@ -17,9 +17,84 @@ var OFFER = {
     effectiveGross: 58.31
   }
 };
-function contractFromOffer(offerId) {
+function partiesWith(subscriberId, legalName) {
+  return {
+    subscriberId,
+    subscriber: {
+      customerNumber: "K-10001",
+      legalName,
+      vatId: "DE123456789",
+      taxNumber: null,
+      addressLine1: "Hauptstra\xDFe 1",
+      addressLine2: null,
+      postalCode: "10115",
+      city: "Berlin",
+      country: "DE"
+    },
+    issuer: {
+      legalName: "Example Software GmbH",
+      vatId: "DE987654321",
+      taxNumber: "12/345/67890",
+      addressLine1: "Werkstra\xDFe 5",
+      addressLine2: null,
+      postalCode: "80331",
+      city: "M\xFCnchen",
+      country: "DE"
+    }
+  };
+}
+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,
+    legalName,
+    vatId: null,
+    taxNumber: null,
+    addressLine1: null,
+    addressLine2: null,
+    postalCode: null,
+    city: null,
+    country: null,
+    invoiceEmail: null,
+    customerNumberPrefix: ""
+  };
+}
+function contractFromOffer(offerId, parties) {
   return {
     tenantId: `tenant-${offerId}`,
+    parties,
     effectiveFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
     originalOfferId: offerId,
     priceSnapshot: {
@@ -151,8 +226,20 @@ var CONTRACT_GAPS = {
     present: ({ adapter }) => Boolean(adapter.mfa)
   },
   subscriptionContracts: {
-    reason: "adapter provides no SubscriptionContractRepository",
-    present: ({ adapter }) => Boolean(adapter.subscriptionContractRepository)
+    reason: "adapter provides no SubscriptionContractRepository, or no subscriber seed for it",
+    present: ({ adapter, seed }) => Boolean(adapter.subscriptionContractRepository && seed.createSubscriber)
+  },
+  subscribers: {
+    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",
@@ -1347,14 +1434,18 @@ function persistenceAdapterContract(options) {
     });
     test("a contract keeps what was agreed, and ending it does not rewrite it", async (t) => {
       const contracts = harness.adapter.subscriptionContractRepository;
-      if (!contracts) {
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!contracts || !createSubscriber) {
         missing(t, "subscriptionContracts");
         return;
       }
       const tenantId = "tenant-contract-lifecycle";
       const signedAt = /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z");
+      const { subscriberId } = await createSubscriber({ legalName: "Meier GmbH" });
+      const parties = partiesWith(subscriberId, "Meier GmbH");
       const created = await contracts.create({
         tenantId,
+        parties,
         effectiveFrom: signedAt,
         priceSnapshot: {
           currency: "EUR",
@@ -1415,6 +1506,10 @@ function persistenceAdapterContract(options) {
       });
       assert.equal(created.status, "active");
       assert.equal(created.tenantId, tenantId);
+      assert.equal(created.subscriberId, subscriberId);
+      assert.deepEqual(created.subscriber, parties.subscriber);
+      assert.deepEqual(created.issuer, parties.issuer);
+      assert.equal(created.partiesMigrated, false);
       assert.equal(created.lineItems.length, 2);
       assert.deepEqual(created.originalBundleVersionIds, ["bundle-version-1"]);
       assert.deepEqual(created.termsSnapshot, { noticePeriodDays: 30 });
@@ -1447,6 +1542,8 @@ function persistenceAdapterContract(options) {
       assert.equal(bundleLine.metadata, null);
       const readBack = await contracts.findById(created.id);
       assert.ok(readBack, "contract expected by id");
+      assert.deepEqual(readBack.subscriber, parties.subscriber, "the copy is stored");
+      assert.deepEqual(readBack.issuer, parties.issuer);
       assert.equal(
         readBack.lineItems.length,
         2,
@@ -1503,11 +1600,14 @@ function persistenceAdapterContract(options) {
     });
     test("a successor takes over without erasing the contract it replaces", async (t) => {
       const contracts = harness.adapter.subscriptionContractRepository;
-      if (!contracts) {
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!contracts || !createSubscriber) {
         missing(t, "subscriptionContracts");
         return;
       }
       const tenantId = "tenant-contract-succession";
+      const { subscriberId } = await createSubscriber({ legalName: "Nachfolger KG" });
+      const parties = partiesWith(subscriberId, "Nachfolger KG");
       const handover = /* @__PURE__ */ new Date("2026-04-01T00:00:00.000Z");
       const lineAt = (priceNet, priceGross) => ({
         kind: "plan",
@@ -1539,6 +1639,7 @@ function persistenceAdapterContract(options) {
       });
       const first = await contracts.create({
         tenantId,
+        parties,
         effectiveFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
         priceSnapshot: priceAt(19.9, 23.68),
         lineItems: [lineAt(19.9, 23.68)]
@@ -1556,6 +1657,7 @@ function persistenceAdapterContract(options) {
       });
       const second = await contracts.create({
         tenantId,
+        parties,
         effectiveFrom: handover,
         priceSnapshot: priceAt(24.9, 29.63),
         lineItems: [lineAt(24.9, 29.63)]
@@ -1605,13 +1707,17 @@ function persistenceAdapterContract(options) {
     });
     test("a line keeps the currency and the tax it was booked with", async (t) => {
       const contracts = harness.adapter.subscriptionContractRepository;
-      if (!contracts) {
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!contracts || !createSubscriber) {
         missing(t, "subscriptionContracts");
         return;
       }
       const tenantId = "tenant-contract-money-facts";
+      const { subscriberId } = await createSubscriber({ legalName: "Z\xFCrich AG" });
+      const parties = { ...partiesWith(subscriberId, "Z\xFCrich AG"), issuer: null };
       const created = await contracts.create({
         tenantId,
+        parties,
         effectiveFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
         priceSnapshot: {
           currency: "CHF",
@@ -1686,9 +1792,9 @@ function persistenceAdapterContract(options) {
       }
     });
     test("a contract written on a transaction is undone with it, and found by its offer", async (t) => {
-      const { adapter } = harness;
+      const { adapter, seed } = harness;
       const contracts = adapter.subscriptionContractRepository;
-      if (!contracts) {
+      if (!contracts || !seed.createSubscriber) {
         missing(t, "subscriptionContracts");
         return;
       }
@@ -1696,9 +1802,11 @@ function persistenceAdapterContract(options) {
         t.skip("adapter declares no transaction capability");
         return;
       }
+      const { subscriberId } = await seed.createSubscriber({ legalName: "Angebot GmbH" });
+      const parties = partiesWith(subscriberId, "Angebot GmbH");
       await assert.rejects(
         adapter.transactionRunner.run(async (tx) => {
-          await contracts.create(contractFromOffer("offer-rolled-back"), tx);
+          await contracts.create(contractFromOffer("offer-rolled-back", parties), tx);
           throw new Error("the conclusion fails after the contract is written");
         })
       );
@@ -1708,13 +1816,817 @@ function persistenceAdapterContract(options) {
         "the contract outlived its transaction"
       );
       const kept = await adapter.transactionRunner.run(
-        (tx) => contracts.create(contractFromOffer("offer-kept"), tx)
+        (tx) => contracts.create(contractFromOffer("offer-kept", parties), tx)
       );
       const found = await contracts.findByOriginalOfferId("offer-kept");
       assert.equal(found?.id, kept.id);
       assert.equal(found?.lineItems.length, 1, "with its lines");
       assert.equal(await contracts.findByOriginalOfferId("offer-nobody-concluded"), null);
     });
+    test("a subscriber is created live for its tenant, and numbered by the database", async (t) => {
+      const subscribers = harness.adapter.subscriberRepository;
+      if (!subscribers) {
+        missing(t, "subscribers");
+        return;
+      }
+      const first = await subscribers.createForTenant({
+        ...subscriberFor("tenant-subscriber-first", "Erste Autohaus GmbH"),
+        vatId: "DE123456789",
+        addressLine1: "Hauptstra\xDFe 1",
+        postalCode: "10115",
+        city: "Berlin",
+        country: "DE",
+        invoiceEmail: "rechnung@erste.example",
+        customerNumberPrefix: "K-"
+      });
+      const second = await subscribers.createForTenant(
+        subscriberFor("tenant-subscriber-second", "Zweiter Verein e.V.")
+      );
+      assert.ok(first && second, "both tenants had no subscriber");
+      const numberOf = (customerNumber) => Number(customerNumber.replace("K-", ""));
+      assert.ok(first.customerNumber.startsWith("K-"), first.customerNumber);
+      assert.equal(numberOf(second.customerNumber), numberOf(first.customerNumber) + 1);
+      assert.ok(numberOf(first.customerNumber) >= 10001, first.customerNumber);
+      const found = await subscribers.findByTenantId("tenant-subscriber-first");
+      assert.deepEqual(
+        found && {
+          id: found.id,
+          customerNumber: found.customerNumber,
+          tenantId: found.tenantId,
+          legalName: found.legalName,
+          vatId: found.vatId,
+          taxNumber: found.taxNumber,
+          addressLine1: found.addressLine1,
+          addressLine2: found.addressLine2,
+          postalCode: found.postalCode,
+          city: found.city,
+          country: found.country,
+          invoiceEmail: found.invoiceEmail,
+          migrated: found.migrated
+        },
+        {
+          id: first.id,
+          customerNumber: first.customerNumber,
+          tenantId: "tenant-subscriber-first",
+          legalName: "Erste Autohaus GmbH",
+          vatId: "DE123456789",
+          // The nullable half, so an adapter writing '' is caught too.
+          taxNumber: null,
+          addressLine1: "Hauptstra\xDFe 1",
+          addressLine2: null,
+          postalCode: "10115",
+          city: "Berlin",
+          country: "DE",
+          invoiceEmail: "rechnung@erste.example",
+          migrated: false
+        }
+      );
+      assert.equal(
+        (await subscribers.findById(second.id))?.tenantId,
+        "tenant-subscriber-second"
+      );
+      assert.equal(await subscribers.findByTenantId("tenant-without-subscriber"), null);
+      assert.equal(await subscribers.findById("subscriber-nobody-created"), null);
+    });
+    test("a tenant has one live subscriber: a second is refused, and the transaction survives it", async (t) => {
+      const { adapter } = harness;
+      const subscribers = adapter.subscriberRepository;
+      if (!subscribers) {
+        missing(t, "subscribers");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        t.skip("adapter declares no transaction capability");
+        return;
+      }
+      const first = await subscribers.createForTenant(
+        subscriberFor("tenant-one-subscriber", "Einzig GmbH")
+      );
+      const afterRefusal = await adapter.transactionRunner.run(async (tx) => {
+        const refused = await subscribers.createForTenant(
+          subscriberFor("tenant-one-subscriber", "Doppelt GmbH"),
+          tx
+        );
+        assert.equal(refused, null, "a second live subscriber was created");
+        return subscribers.createForTenant(
+          subscriberFor("tenant-after-refusal", "Danach GmbH"),
+          tx
+        );
+      });
+      assert.equal(
+        (await subscribers.findByTenantId("tenant-one-subscriber"))?.id,
+        first?.id
+      );
+      assert.equal(
+        (await subscribers.findByTenantId("tenant-after-refusal"))?.id,
+        afterRefusal?.id,
+        "the transaction did not survive the refusal"
+      );
+    });
+    test("creating a subscriber for one tenant twice at once ends with one", async (t) => {
+      const subscribers = harness.adapter.subscriberRepository;
+      if (!subscribers) {
+        missing(t, "subscribers");
+        return;
+      }
+      const results = await Promise.all([
+        subscribers.createForTenant(subscriberFor("tenant-at-once", "Gleichzeitig A")),
+        subscribers.createForTenant(subscriberFor("tenant-at-once", "Gleichzeitig B"))
+      ]);
+      const created = results.filter((result) => result !== null);
+      assert.equal(created.length, 1, `${created.length} subscribers were created`);
+      assert.equal((await subscribers.findByTenantId("tenant-at-once"))?.id, created[0].id);
+    });
+    test("a subscriber written on a transaction is undone with it", async (t) => {
+      const { adapter } = harness;
+      const subscribers = adapter.subscriberRepository;
+      if (!subscribers) {
+        missing(t, "subscribers");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        t.skip("adapter declares no transaction capability");
+        return;
+      }
+      await assert.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await subscribers.createForTenant(
+            subscriberFor("tenant-rolled-back", "Zur\xFCckgerollt GmbH"),
+            tx
+          );
+          throw new Error("the tenant is not created after all");
+        })
+      );
+      assert.equal(await subscribers.findByTenantId("tenant-rolled-back"), null);
+      assert.ok(
+        await subscribers.createForTenant(
+          subscriberFor("tenant-rolled-back", "Zur\xFCckgerollt GmbH")
+        )
+      );
+    });
+    test("a contact change writes what it names and keeps the rest", async (t) => {
+      const subscribers = harness.adapter.subscriberRepository;
+      if (!subscribers) {
+        missing(t, "subscribers");
+        return;
+      }
+      const created = await subscribers.createForTenant({
+        ...subscriberFor("tenant-contact", "Kontakt GmbH"),
+        addressLine2: "Hinterhaus",
+        city: "Hamburg"
+      });
+      assert.ok(created);
+      const changed = await subscribers.updateContact(created.id, {
+        city: "Bremen",
+        addressLine2: null,
+        invoiceEmail: "buchhaltung@kontakt.example"
+      });
+      assert.deepEqual(
+        changed && [
+          changed.city,
+          changed.addressLine2,
+          changed.invoiceEmail,
+          changed.legalName,
+          changed.tenantId
+        ],
+        ["Bremen", null, "buchhaltung@kontakt.example", "Kontakt GmbH", "tenant-contact"]
+      );
+      assert.equal((await subscribers.findById(created.id))?.city, "Bremen");
+      assert.equal(
+        await subscribers.updateContact("subscriber-nobody-created", { city: "Kiel" }),
+        null
+      );
+    });
+    test("a correction records the values it replaced, and nothing when nothing moves", async (t) => {
+      const subscribers = harness.adapter.subscriberRepository;
+      if (!subscribers) {
+        missing(t, "subscribers");
+        return;
+      }
+      const created = await subscribers.createForTenant(
+        subscriberFor("tenant-correction", "Mueller GmbH")
+      );
+      assert.ok(created);
+      const at = (day) => new Date(Date.UTC(2026, 8, day));
+      const first = await subscribers.correctIdentity(created.id, {
+        corrected: { legalName: "M\xFCller GmbH", vatId: "DE123456789", taxNumber: null },
+        reason: "Umlaut lost when the registration was typed",
+        correctedBy: "operator:anna",
+        correctedAt: at(1)
+      });
+      assert.deepEqual(
+        first?.correction && {
+          previous: first.correction.previous,
+          corrected: first.correction.corrected,
+          reason: first.correction.reason,
+          correctedBy: first.correction.correctedBy,
+          correctedAt: first.correction.correctedAt.getTime()
+        },
+        {
+          previous: { legalName: "Mueller GmbH", vatId: null },
+          corrected: { legalName: "M\xFCller GmbH", vatId: "DE123456789" },
+          reason: "Umlaut lost when the registration was typed",
+          correctedBy: "operator:anna",
+          correctedAt: at(1).getTime()
+        }
+      );
+      assert.equal(first?.subscriber.legalName, "M\xFCller GmbH");
+      assert.equal((await subscribers.findById(created.id))?.vatId, "DE123456789");
+      const unchanged = await subscribers.correctIdentity(created.id, {
+        corrected: { legalName: "M\xFCller GmbH" },
+        reason: "Clicked twice",
+        correctedBy: "operator:anna",
+        correctedAt: at(2)
+      });
+      assert.equal(
+        unchanged?.correction,
+        null,
+        "a correction that moved nothing was recorded"
+      );
+      await subscribers.correctIdentity(created.id, {
+        corrected: { vatId: "DE999999999" },
+        reason: "Wrong VAT id on the first correction",
+        correctedBy: "operator:ben",
+        correctedAt: at(3)
+      });
+      const listed = await subscribers.listCorrections(created.id);
+      assert.deepEqual(
+        listed.map((correction) => correction.reason),
+        [
+          "Wrong VAT id on the first correction",
+          "Umlaut lost when the registration was typed"
+        ],
+        "corrections come back the latest first, and only the two that moved something"
+      );
+      assert.equal(
+        await subscribers.correctIdentity("subscriber-nobody-created", {
+          corrected: { legalName: "Niemand" },
+          reason: "none",
+          correctedBy: "operator:anna",
+          correctedAt: at(4)
+        }),
+        null
+      );
+    });
+    test("two corrections at once each record the value the other left behind", async (t) => {
+      const { adapter } = harness;
+      const subscribers = adapter.subscriberRepository;
+      if (!subscribers) {
+        missing(t, "subscribers");
+        return;
+      }
+      if (!adapter.capabilities.transactions || !adapter.capabilities.pessimisticLocking) {
+        t.skip("adapter declares no transactions or no row locks");
+        return;
+      }
+      const created = await subscribers.createForTenant(
+        subscriberFor("tenant-corrected-twice", "Original GmbH")
+      );
+      assert.ok(created);
+      const correctTo = (legalName) => adapter.transactionRunner.run(async (tx) => {
+        await subscribers.correctIdentity(
+          created.id,
+          {
+            corrected: { legalName },
+            reason: `to ${legalName}`,
+            correctedBy: "operator:anna",
+            correctedAt: /* @__PURE__ */ new Date()
+          },
+          tx
+        );
+        await sleep(LOCK_HOLD_MS);
+      });
+      await Promise.all([
+        correctTo("Erste Korrektur GmbH"),
+        correctTo("Zweite Korrektur GmbH")
+      ]);
+      const listed = await subscribers.listCorrections(created.id);
+      assert.equal(listed.length, 2);
+      const replaced = listed.map((correction) => correction.previous.legalName).sort();
+      const written = listed.map((correction) => correction.corrected.legalName);
+      const current = (await subscribers.findById(created.id))?.legalName;
+      assert.ok(replaced.includes("Original GmbH"), JSON.stringify(listed));
+      const secondReplaced = replaced.find((name) => name !== "Original GmbH");
+      assert.ok(
+        secondReplaced !== void 0 && written.includes(secondReplaced),
+        `a correction recorded a value it did not replace: ${JSON.stringify(listed)}`
+      );
+      assert.ok(current !== void 0 && written.includes(current));
+      assert.notEqual(secondReplaced, current);
+    });
+    test("a contract keeps its subscriber's copy after the subscriber is corrected", async (t) => {
+      const { adapter } = harness;
+      const subscribers = adapter.subscriberRepository;
+      const contracts = adapter.subscriptionContractRepository;
+      if (!subscribers) {
+        missing(t, "subscribers");
+        return;
+      }
+      if (!contracts || !harness.seed.createSubscriber) {
+        missing(t, "subscriptionContracts");
+        return;
+      }
+      const subscriber = await subscribers.createForTenant(
+        subscriberFor("tenant-copy-kept", "Vorher GmbH")
+      );
+      assert.ok(subscriber);
+      const parties = partiesWith(subscriber.id, "Vorher GmbH");
+      const contract = await contracts.create({
+        ...contractFromOffer("offer-copy-kept", parties),
+        tenantId: "tenant-copy-kept"
+      });
+      await subscribers.correctIdentity(subscriber.id, {
+        corrected: { legalName: "Nachher GmbH" },
+        reason: "Change of name of the same company",
+        correctedBy: "operator:anna",
+        correctedAt: /* @__PURE__ */ new Date()
+      });
+      const readBack = await contracts.findById(contract.id);
+      assert.equal(readBack?.subscriberId, subscriber.id);
+      assert.equal(
+        readBack?.subscriber.legalName,
+        "Vorher GmbH",
+        "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) {