@saasicat/persistence-testing 1.0.0-rc.2 → 1.0.0-rc.20

package/dist/index.js

@@ -2,12 +2,276 @@
 import assert from "node:assert/strict";
 import { after, before, beforeEach, describe, test } from "node:test";
 var LOCK_HOLD_MS = 150;
+var OFFER = {
+  planKey: "STANDARD",
+  planVersionId: null,
+  billingCycle: "monthly",
+  priceBreakdown: {
+    currency: "EUR",
+    billingCycle: "monthly",
+    planNet: 49,
+    bundlesNet: 0,
+    regularNet: 49,
+    effectiveNet: 49,
+    vatRate: 19,
+    effectiveGross: 58.31
+  }
+};
+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: {
+      currency: "EUR",
+      billingCycle: "monthly",
+      subtotalNet: 49,
+      discountNet: 0,
+      totalNet: 49,
+      vatRate: 19,
+      totalGross: 58.31
+    },
+    lineItems: [
+      {
+        kind: "plan",
+        sourceKey: "STANDARD",
+        sourceVersionId: null,
+        titleSnapshot: "Standard",
+        descriptionSnapshot: null,
+        quantity: 1,
+        unit: null,
+        priceNet: 49,
+        priceGross: 58.31,
+        billingCycle: "monthly",
+        currency: "EUR",
+        taxRate: 19,
+        taxAmount: 9.31,
+        minimumTermUntil: null,
+        featuresSnapshot: [],
+        quotaEffectsSnapshot: {},
+        metadata: null
+      }
+    ]
+  };
+}
+var CONTRACT_GAPS = {
+  atomicPlanBinding: {
+    reason: "adapter does not expose atomic plan-binding writes",
+    present: ({ adapter }) => Boolean(adapter.tenantSubscriptionWrite)
+  },
+  atomicOnboarding: {
+    reason: "adapter does not expose atomic onboarding writes",
+    present: ({ adapter }) => Boolean(adapter.tenantSubscriptionWrite?.applyOnboardingSelection)
+  },
+  promoCodes: {
+    reason: "adapter provides no PromoCodeRepository",
+    present: ({ adapter }) => Boolean(adapter.promoCodeRepository)
+  },
+  promoCodeRedemptions: {
+    reason: "adapter provides no PromoCodeRedemptionRepository",
+    present: ({ adapter }) => Boolean(adapter.promoCodeRedemptionRepository)
+  },
+  promoSubscriptionLookup: {
+    reason: "adapter provides no PromoSubscriptionLookup",
+    present: ({ adapter }) => Boolean(adapter.promoSubscriptionLookup)
+  },
+  planRepository: {
+    reason: "adapter provides no PlanRepository",
+    present: ({ adapter }) => Boolean(adapter.planRepository)
+  },
+  planLifecycle: {
+    reason: "adapter provides no time-aware PlanRepository lifecycle",
+    present: ({ adapter }) => {
+      const repository = adapter.planRepository;
+      return Boolean(
+        repository?.createPlanVersionDraft && repository.publishPlanVersionDraft && repository.findVersionById && repository.findActivePlanVersion
+      );
+    }
+  },
+  planRetirement: {
+    reason: "adapter provides no PlanRepository that retires and finds plans by key",
+    present: ({ adapter }) => Boolean(adapter.planRepository?.softDelete && adapter.planRepository.findByKey)
+  },
+  planVersionReads: {
+    reason: "adapter provides no PlanRepository that reads versions by plan key",
+    present: ({ adapter }) => {
+      const repository = adapter.planRepository;
+      return Boolean(
+        repository?.listVersions && repository.findCurrentDraft && repository.findLatestLivePlanVersion
+      );
+    }
+  },
+  planVersionRetirement: {
+    reason: "adapter provides no PlanRepository that reads versions and retires plans",
+    present: ({ adapter }) => {
+      const repository = adapter.planRepository;
+      return Boolean(
+        repository?.createPlanVersionDraft && repository.publishPlanVersionDraft && repository.listVersions && repository.findCurrentDraft && repository.findLatestLivePlanVersion && repository.softDelete
+      );
+    }
+  },
+  bundleRepository: {
+    reason: "adapter provides no BundleRepository",
+    present: ({ adapter }) => Boolean(adapter.bundleRepository)
+  },
+  bundleValidity: {
+    reason: "adapter provides no time-aware BundleRepository",
+    present: ({ adapter }) => Boolean(adapter.bundleRepository?.findActiveBundleVersion)
+  },
+  bundleDraftDiscard: {
+    reason: "adapter provides no BundleRepository that discards drafts",
+    present: ({ adapter }) => Boolean(adapter.bundleRepository?.deleteDraft)
+  },
+  bundleDraftPublish: {
+    reason: "adapter provides no BundleRepository that publishes drafts",
+    present: ({ adapter }) => Boolean(adapter.bundleRepository?.publishDraft)
+  },
+  bundleRetirement: {
+    reason: "adapter provides no BundleRepository that retires and finds bundles by key",
+    present: ({ adapter }) => Boolean(adapter.bundleRepository?.softDelete && adapter.bundleRepository.findByKey)
+  },
+  bundleBookings: {
+    reason: "adapter provides no SubscriptionBundleRepository or bundle catalog",
+    present: ({ adapter, seed }) => Boolean(adapter.subscriptionBundleRepository && seed.createBundleVersion)
+  },
+  halfCancelledBookingSeed: {
+    reason: "adapter harness cannot write the half-cancelled shape",
+    present: ({ seed }) => Boolean(seed.clearBookingRequestDate)
+  },
+  countByPlanVersionId: {
+    reason: "adapter does not implement countByPlanVersionId (fail-closed fallback)",
+    present: ({ adapter }) => Boolean(adapter.subscriptionRepository.countByPlanVersionId)
+  },
+  audit: {
+    reason: "adapter provides no AuditPort/AuditQueryPort pair",
+    present: ({ adapter }) => Boolean(adapter.audit && adapter.auditQuery)
+  },
+  mfa: {
+    reason: "adapter provides no MfaPort",
+    present: ({ adapter }) => Boolean(adapter.mfa)
+  },
+  subscriptionContracts: {
+    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",
+    present: ({ adapter }) => Boolean(adapter.checkoutOfferRepository)
+  },
+  appliedSettings: {
+    reason: "adapter provides no AppliedSettingsPort",
+    present: ({ adapter }) => Boolean(adapter.appliedSettings)
+  }
+};
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function persistenceAdapterContract(options) {
+  const declaredGaps = new Set(options.gaps ?? []);
+  let harness;
+  function missing(t, gap) {
+    const { reason, present } = CONTRACT_GAPS[gap];
+    if (present(harness)) {
+      assert.fail(
+        `'${gap}' counts as provided, yet this scenario found a member it needs missing or not callable. Check that the harness wires the port itself; if it does, the contract's check for '${gap}' and this scenario disagree, which is a defect in @saasicat/persistence-testing.`
+      );
+    }
+    if (declaredGaps.has(gap)) {
+      t.skip(reason);
+      return;
+    }
+    assert.fail(
+      `${reason}. Wire it into the harness, or declare \`gaps: ['${gap}']\` in persistenceAdapterContract if the adapter deliberately does not provide it.`
+    );
+  }
   describe(`persistence adapter contract: ${options.name}`, () => {
-    let harness;
     before(async () => {
       harness = await options.create();
     });
@@ -17,6 +281,20 @@ function persistenceAdapterContract(options) {
     beforeEach(async () => {
       await harness.reset();
     });
+    test("the declared gaps are exactly the parts the harness does not provide", () => {
+      const gaps = Object.keys(CONTRACT_GAPS);
+      const absent = gaps.filter((gap) => !CONTRACT_GAPS[gap].present(harness));
+      const known = (gap) => Object.prototype.hasOwnProperty.call(CONTRACT_GAPS, gap);
+      const unknown = [...declaredGaps].filter((gap) => !known(gap));
+      const stale = [...declaredGaps].filter((gap) => known(gap) && !absent.includes(gap));
+      const undeclared = absent.filter((gap) => !declaredGaps.has(gap));
+      const problems = [
+        unknown.length > 0 && `declared as gaps but not parts of the contract: ${unknown.join(", ")} (ContractGap lists the names)`,
+        stale.length > 0 && `declared as gaps but wired into the harness: ${stale.join(", ")}`,
+        undeclared.length > 0 && `not wired into the harness and not declared as gaps: ${undeclared.join(", ")}`
+      ].filter(Boolean);
+      assert.deepEqual(problems, [], problems.join("; "));
+    });
     test("findByTenantId returns the tenant subscription with plan-version limits", async () => {
       const { seed, adapter } = harness;
       const { planVersionId } = await seed.createPlanVersion({
@@ -91,7 +369,7 @@ function persistenceAdapterContract(options) {
     test("immediate plan change binds plan and active PlanVersion consistently", async (t) => {
       const { seed, adapter } = harness;
       if (!adapter.tenantSubscriptionWrite) {
-        t.skip("adapter does not expose atomic plan-binding writes");
+        missing(t, "atomicPlanBinding");
         return;
       }
       const oldVersion = await seed.createPlanVersion({
@@ -113,13 +391,19 @@ function persistenceAdapterContract(options) {
         plan: "STARTER",
         planVersionId: oldVersion.planVersionId
       });
-      await adapter.tenantSubscriptionWrite.changePlanImmediate("tenant-plan-change", {
-        planId: "PRO",
-        cycle: "YEARLY",
-        periodStart: null,
-        periodEnd: null,
-        nextStatus: null
-      });
+      const change = await adapter.tenantSubscriptionWrite.changePlanImmediate(
+        "tenant-plan-change",
+        {
+          planId: "PRO",
+          cycle: "YEARLY",
+          periodStart: null,
+          periodEnd: null,
+          nextStatus: null,
+          // The row has no cancellation, so this claims it.
+          expectedCanceledAt: null
+        }
+      );
+      assert.equal(change.claimed, true, "the plan write did not claim the row");
       const changed = await adapter.subscriptionRepository.findByTenantId("tenant-plan-change");
       assert.ok(changed, "changed subscription expected");
       assert.equal(changed.plan, "PRO");
@@ -130,12 +414,12 @@ function persistenceAdapterContract(options) {
       const { seed, adapter } = harness;
       const writer = adapter.tenantSubscriptionWrite;
       if (!writer?.applyOnboardingSelection) {
-        t.skip("adapter does not expose atomic onboarding writes");
+        missing(t, "atomicOnboarding");
         return;
       }
       const redemptions = adapter.promoCodeRedemptionRepository;
       if (!redemptions) {
-        t.skip("adapter provides no PromoCodeRedemptionRepository");
+        missing(t, "promoCodeRedemptions");
         return;
       }
       const oldVersion = await seed.createPlanVersion({
@@ -170,7 +454,8 @@ function persistenceAdapterContract(options) {
             cycle: "MONTHLY",
             periodStart: null,
             periodEnd: null,
-            nextStatus: null
+            nextStatus: null,
+            expectedCanceledAt: null
           },
           async (tx, callbackSubscriptionId) => {
             assert.equal(callbackSubscriptionId, subscriptionId);
@@ -213,15 +498,14 @@ function persistenceAdapterContract(options) {
     test("plan lifecycle keeps semantic identity and auto-succeeds validity windows", async (t) => {
       const repository = harness.adapter.planRepository;
       if (!repository?.createPlanVersionDraft || !repository.publishPlanVersionDraft || !repository.findVersionById || !repository.findActivePlanVersion) {
-        t.skip("adapter provides no time-aware PlanRepository lifecycle");
+        missing(t, "planLifecycle");
         return;
       }
       const plan = await repository.create({
-        projectKey: options.projectKey,
         planKey: "STANDARD",
         label: "Standard"
       });
-      assert.equal(plan.projectKey, options.projectKey);
+      assert.equal(plan.planKey, "STANDARD");
       const firstDraft = await repository.createPlanVersionDraft({
         planId: "STANDARD",
         features: ["CORE"],
@@ -278,15 +562,14 @@ function persistenceAdapterContract(options) {
     test("bundle lifecycle roundtrips validity and auto-succeeds atomically", async (t) => {
       const repository = harness.adapter.bundleRepository;
       if (!repository?.findActiveBundleVersion) {
-        t.skip("adapter provides no time-aware BundleRepository");
+        missing(t, "bundleValidity");
         return;
       }
       const bundle = await repository.create({
-        projectKey: options.projectKey,
         bundleKey: "REPORTING",
         label: "Reporting"
       });
-      assert.equal(bundle.projectKey, options.projectKey);
+      assert.equal(bundle.bundleKey, "REPORTING");
       const firstDraft = await repository.createDraft({
         bundleId: bundle.id,
         features: ["REPORTS"],
@@ -334,10 +617,457 @@ function persistenceAdapterContract(options) {
         second.id
       );
     });
+    test("a booking keeps the rhythm and the window it was made in", async (t) => {
+      const repository = harness.adapter.subscriptionBundleRepository;
+      const { seed } = harness;
+      if (!repository || !seed.createBundleVersion) {
+        missing(t, "bundleBookings");
+        return;
+      }
+      const { planVersionId } = await seed.createPlanVersion({
+        planKey: "PRO",
+        version: 1,
+        quotas: {},
+        features: ["CORE"],
+        published: true
+      });
+      const { subscriptionId } = await seed.createSubscription({
+        tenantId: "tenant-bundle-period",
+        plan: "PRO",
+        planVersionId,
+        billingCycle: "YEARLY"
+      });
+      const { bundleVersionId } = await seed.createBundleVersion({
+        bundleKey: "ANALYTICS",
+        features: ["REPORTS"]
+      });
+      const booked = await repository.add({
+        subscriptionId,
+        bundleVersionId,
+        startedAt: /* @__PURE__ */ new Date("2026-02-21T00:00:00.000Z"),
+        minimumTermEndsAt: null,
+        billingCycle: "MONTHLY",
+        currentPeriodStart: /* @__PURE__ */ new Date("2026-02-21T00:00:00.000Z"),
+        currentPeriodEnd: /* @__PURE__ */ new Date("2026-02-28T00:00:00.000Z")
+      });
+      assert.equal(booked.billingCycle, "MONTHLY");
+      const [readBack] = await repository.listBySubscription(subscriptionId);
+      assert.ok(readBack, "the booking must be readable back");
+      assert.equal(readBack.billingCycle, "MONTHLY");
+      assert.equal(
+        readBack.currentPeriodEnd?.toISOString(),
+        "2026-02-28T00:00:00.000Z",
+        "the period end must survive the round trip"
+      );
+      assert.equal(readBack.currentPeriodStart?.toISOString(), "2026-02-21T00:00:00.000Z");
+      const legacy = await repository.add({
+        subscriptionId,
+        bundleVersionId,
+        startedAt: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        minimumTermEndsAt: null
+      });
+      const legacyReadBack = await repository.findById(legacy.id);
+      assert.ok(legacyReadBack, "the legacy booking must be readable back");
+      assert.equal(legacyReadBack.billingCycle, null);
+      assert.equal(legacyReadBack.currentPeriodStart, null);
+      assert.equal(legacyReadBack.currentPeriodEnd, null);
+    });
+    test("a second cancellation of one booking is refused, not applied", async (t) => {
+      const repository = harness.adapter.subscriptionBundleRepository;
+      const { seed } = harness;
+      if (!repository || !seed.createBundleVersion) {
+        missing(t, "bundleBookings");
+        return;
+      }
+      const { planVersionId } = await seed.createPlanVersion({
+        planKey: "PRO",
+        version: 1,
+        quotas: {},
+        features: ["CORE"],
+        published: true
+      });
+      const { subscriptionId } = await seed.createSubscription({
+        tenantId: "tenant-double-cancel",
+        plan: "PRO",
+        planVersionId
+      });
+      const { bundleVersionId } = await seed.createBundleVersion({
+        bundleKey: "ANALYTICS",
+        features: ["REPORTS"]
+      });
+      const booking = await repository.add({
+        subscriptionId,
+        bundleVersionId,
+        startedAt: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        minimumTermEndsAt: null
+      });
+      const first = await repository.cancel(booking.id, {
+        canceledAt: /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z"),
+        canceledEffectiveAt: /* @__PURE__ */ new Date("2026-04-01T00:00:00.000Z")
+      });
+      assert.equal(first.canceledEffectiveAt?.toISOString(), "2026-04-01T00:00:00.000Z");
+      await assert.rejects(
+        () => repository.cancel(booking.id, {
+          canceledAt: /* @__PURE__ */ new Date("2026-03-02T00:00:00.000Z"),
+          canceledEffectiveAt: /* @__PURE__ */ new Date("2026-09-01T00:00:00.000Z")
+        }),
+        "a second cancellation must be refused"
+      );
+      const readBack = await repository.findById(booking.id);
+      assert.equal(
+        readBack?.canceledEffectiveAt?.toISOString(),
+        "2026-04-01T00:00:00.000Z",
+        "the first cancellation must still stand"
+      );
+      await repository.reactivate(booking.id);
+      const again = await repository.cancel(booking.id, {
+        canceledAt: /* @__PURE__ */ new Date("2026-03-02T00:00:00.000Z"),
+        canceledEffectiveAt: /* @__PURE__ */ new Date("2026-09-01T00:00:00.000Z")
+      });
+      assert.equal(again.canceledEffectiveAt?.toISOString(), "2026-09-01T00:00:00.000Z");
+    });
+    test("a subscription's bookings come back newest first", async (t) => {
+      const repository = harness.adapter.subscriptionBundleRepository;
+      const { seed } = harness;
+      if (!repository || !seed.createBundleVersion) {
+        missing(t, "bundleBookings");
+        return;
+      }
+      const { planVersionId } = await seed.createPlanVersion({
+        planKey: "PRO",
+        version: 1,
+        quotas: {},
+        features: ["CORE"],
+        published: true
+      });
+      const { subscriptionId } = await seed.createSubscription({
+        tenantId: "tenant-booking-order",
+        plan: "PRO",
+        planVersionId
+      });
+      for (const [key, startedAt] of [
+        ["OLDEST", "2026-01-01T00:00:00.000Z"],
+        ["MIDDLE", "2026-02-01T00:00:00.000Z"],
+        ["NEWEST", "2026-03-01T00:00:00.000Z"]
+      ]) {
+        const { bundleVersionId } = await seed.createBundleVersion({
+          bundleKey: key,
+          features: ["REPORTS"]
+        });
+        await repository.add({
+          subscriptionId,
+          bundleVersionId,
+          startedAt: new Date(startedAt),
+          minimumTermEndsAt: null
+        });
+      }
+      const listed = await repository.listBySubscription(subscriptionId);
+      assert.deepEqual(
+        listed.map((row) => row.startedAt.toISOString()),
+        [
+          "2026-03-01T00:00:00.000Z",
+          "2026-02-01T00:00:00.000Z",
+          "2026-01-01T00:00:00.000Z"
+        ]
+      );
+    });
+    test("a booking with no request date is active, whatever its effective date says", async (t) => {
+      const repository = harness.adapter.subscriptionBundleRepository;
+      const { seed } = harness;
+      if (!repository || !seed.createBundleVersion) {
+        missing(t, "bundleBookings");
+        return;
+      }
+      const { planVersionId } = await seed.createPlanVersion({
+        planKey: "PRO",
+        version: 1,
+        quotas: {},
+        features: ["CORE"],
+        published: true
+      });
+      const { subscriptionId } = await seed.createSubscription({
+        tenantId: "tenant-half-cancelled",
+        plan: "PRO",
+        planVersionId
+      });
+      const { bundleVersionId } = await seed.createBundleVersion({
+        bundleKey: "ANALYTICS",
+        features: ["REPORTS"]
+      });
+      const booking = await repository.add({
+        subscriptionId,
+        bundleVersionId,
+        startedAt: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        minimumTermEndsAt: null
+      });
+      await repository.cancel(booking.id, {
+        canceledAt: /* @__PURE__ */ new Date("2026-02-01T00:00:00.000Z"),
+        canceledEffectiveAt: /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z")
+      });
+      const clearRequestDate = harness.seed.clearBookingRequestDate;
+      if (!clearRequestDate) {
+        missing(t, "halfCancelledBookingSeed");
+        return;
+      }
+      await clearRequestDate(booking.id);
+      const active = await repository.listActiveBySubscription(
+        subscriptionId,
+        /* @__PURE__ */ new Date("2026-06-01T00:00:00.000Z")
+      );
+      assert.equal(active.length, 1, "no request date means nobody asked to cancel it");
+      assert.equal(
+        await repository.countActiveByBundleVersionId(
+          bundleVersionId,
+          /* @__PURE__ */ new Date("2026-06-01T00:00:00.000Z")
+        ),
+        1
+      );
+    });
+    test("discarding a draft cannot remove a version published meanwhile", async (t) => {
+      const catalog = harness.adapter.bundleRepository;
+      const discardDraft = catalog?.deleteDraft?.bind(catalog);
+      if (!catalog || !discardDraft) {
+        missing(t, "bundleDraftDiscard");
+        return;
+      }
+      const bundle = await catalog.create({
+        bundleKey: "RACE",
+        label: "Race"
+      });
+      const draft = await catalog.createDraft({
+        bundleId: bundle.id,
+        features: ["REPORTS"],
+        quotas: {}
+      });
+      await catalog.publishDraft(draft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      await assert.rejects(
+        () => discardDraft(draft.id),
+        "a published version must not be discardable"
+      );
+      assert.ok(
+        await catalog.findVersionById(draft.id),
+        "and it must still be there afterwards"
+      );
+    });
+    test("publishing one draft twice claims it once, and the windows stay adjacent", async (t) => {
+      const catalog = harness.adapter.bundleRepository;
+      const publish = catalog?.publishDraft?.bind(catalog);
+      if (!catalog || !publish) {
+        missing(t, "bundleDraftPublish");
+        return;
+      }
+      const bundle = await catalog.create({
+        bundleKey: "CLAIM",
+        label: "Claim"
+      });
+      const first = await catalog.createDraft({
+        bundleId: bundle.id,
+        features: ["A"],
+        quotas: {}
+      });
+      await publish(first.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const second = await catalog.createDraft({
+        bundleId: bundle.id,
+        baseVersionId: first.id,
+        features: ["A", "B"],
+        quotas: {}
+      });
+      const publishedAt = /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z");
+      await publish(second.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: publishedAt,
+        validUntil: null
+      });
+      await assert.rejects(
+        () => publish(second.id, {
+          publishedByUserId: null,
+          publishedChanges: [],
+          nonRegressive: true,
+          validFrom: /* @__PURE__ */ new Date("2026-06-01T00:00:00.000Z"),
+          validUntil: null
+        }),
+        "a version that is already published must not be published again"
+      );
+      const successor = await catalog.findVersionById(second.id);
+      const predecessor = await catalog.findVersionById(first.id);
+      assert.equal(
+        successor?.validFrom && new Date(successor.validFrom).toISOString(),
+        publishedAt.toISOString(),
+        "the winning date must still stand"
+      );
+      assert.ok(predecessor?.supersededAt, "the predecessor must be superseded");
+      if (predecessor?.validUntil) {
+        const closesAt = new Date(predecessor.validUntil);
+        assert.equal(
+          closesAt.toISOString().slice(0, 10),
+          "2026-02-28",
+          "the predecessor must close the day before its successor opens"
+        );
+      }
+    });
+    test("a plan key names one plan for the whole installation", async (t) => {
+      const repository = harness.adapter.planRepository;
+      if (!repository) {
+        missing(t, "planRepository");
+        return;
+      }
+      await repository.create({ planKey: "DOUBLE", label: "First" });
+      await assert.rejects(
+        () => repository.create({ planKey: "DOUBLE", label: "Second" }),
+        "a plan key is taken once"
+      );
+    });
+    test("a bundle key names one bundle for the whole installation", async (t) => {
+      const catalog = harness.adapter.bundleRepository;
+      if (!catalog) {
+        missing(t, "bundleRepository");
+        return;
+      }
+      await catalog.create({ bundleKey: "DOUBLE", label: "First" });
+      await assert.rejects(
+        () => catalog.create({ bundleKey: "DOUBLE", label: "Second" }),
+        "a bundle key is taken once"
+      );
+    });
+    test("a retired plan still occupies its key", async (t) => {
+      const repository = harness.adapter.planRepository;
+      const retire = repository?.softDelete?.bind(repository);
+      const byKey = repository?.findByKey?.bind(repository);
+      if (!repository || !retire || !byKey) {
+        missing(t, "planRetirement");
+        return;
+      }
+      const plan = await repository.create({ planKey: "RETIRED_PLAN", label: "Retired" });
+      await retire(plan.id);
+      const stillThere = await byKey("RETIRED_PLAN");
+      assert.equal(stillThere?.id, plan.id, "the key is not free again");
+      assert.ok(stillThere?.deletedAt, "and the row says it is retired");
+      assert.equal(
+        (await repository.list({})).some((row) => row.id === plan.id),
+        false,
+        "a retired plan is not in the catalogue an operator browses"
+      );
+    });
+    test("a plan key no plan has finds no versions, rather than failing", async (t) => {
+      const repository = harness.adapter.planRepository;
+      if (!repository?.listVersions || !repository.findCurrentDraft || !repository.findLatestLivePlanVersion) {
+        missing(t, "planVersionReads");
+        return;
+      }
+      const entitlementVersions = harness.adapter.planVersionRepository;
+      assert.deepEqual(await repository.listVersions("NO_SUCH_PLAN"), []);
+      assert.equal(await repository.findCurrentDraft("NO_SUCH_PLAN"), null);
+      assert.equal(await repository.findLatestLivePlanVersion("NO_SUCH_PLAN"), null);
+      if (repository.findActivePlanVersion) {
+        assert.equal(
+          await repository.findActivePlanVersion("NO_SUCH_PLAN", /* @__PURE__ */ new Date()),
+          null
+        );
+      }
+      assert.equal(await entitlementVersions.findLatestLive("NO_SUCH_PLAN"), null);
+      if (entitlementVersions.findActive) {
+        assert.equal(
+          await entitlementVersions.findActive("NO_SUCH_PLAN", /* @__PURE__ */ new Date()),
+          null
+        );
+      }
+    });
+    test("retiring a plan hides none of its versions", async (t) => {
+      const repository = harness.adapter.planRepository;
+      if (!repository?.createPlanVersionDraft || !repository.publishPlanVersionDraft || !repository.listVersions || !repository.findCurrentDraft || !repository.findLatestLivePlanVersion || !repository.softDelete) {
+        missing(t, "planVersionRetirement");
+        return;
+      }
+      const listVersions = repository.listVersions.bind(repository);
+      const findCurrentDraft = repository.findCurrentDraft.bind(repository);
+      const findLatestLive = repository.findLatestLivePlanVersion.bind(repository);
+      const entitlementVersions = harness.adapter.planVersionRepository;
+      const plan = await repository.create({ planKey: "RETIRING", label: "Retiring" });
+      const firstDraft = await repository.createPlanVersionDraft({
+        planId: "RETIRING",
+        features: ["CORE"],
+        quotas: { users: 5 },
+        monthlyNet: "10.00",
+        yearlyNet: "100.00",
+        validFrom: "2026-01-01"
+      });
+      const live = await repository.publishPlanVersionDraft(firstDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const openDraft = await repository.createPlanVersionDraft({
+        planId: "RETIRING",
+        baseVersionId: live.id,
+        features: ["CORE", "PLUS"],
+        quotas: { users: 10 },
+        monthlyNet: "15.00",
+        yearlyNet: "150.00",
+        validFrom: "2026-06-01"
+      });
+      const reads = async () => ({
+        versions: (await listVersions("RETIRING")).map((row) => row.id),
+        draft: (await findCurrentDraft("RETIRING"))?.id ?? null,
+        latestLive: (await findLatestLive("RETIRING"))?.id ?? null,
+        entitlementFeatures: (await entitlementVersions.findLatestLive("RETIRING"))?.features ?? null
+      });
+      const beforeRetiring = await reads();
+      assert.deepEqual(
+        {
+          versions: beforeRetiring.versions,
+          draft: beforeRetiring.draft,
+          latestLive: beforeRetiring.latestLive
+        },
+        { versions: [live.id, openDraft.id], draft: openDraft.id, latestLive: live.id },
+        "a live plan reads its versions, so the comparison below has a subject"
+      );
+      await repository.softDelete(plan.id);
+      assert.deepEqual(await reads(), beforeRetiring, "retiring the plan hid its versions");
+    });
+    test("a retired bundle still occupies its key", async (t) => {
+      const catalog = harness.adapter.bundleRepository;
+      const retire = catalog?.softDelete?.bind(catalog);
+      const byKey = catalog?.findByKey?.bind(catalog);
+      if (!catalog || !retire || !byKey) {
+        missing(t, "bundleRetirement");
+        return;
+      }
+      const bundle = await catalog.create({
+        bundleKey: "RETIRED_KEY",
+        label: "Retired"
+      });
+      assert.equal((await byKey("RETIRED_KEY"))?.id, bundle.id);
+      await retire(bundle.id);
+      const stillThere = await byKey("RETIRED_KEY");
+      assert.equal(stillThere?.id, bundle.id, "the key is not free again");
+      assert.ok(stillThere?.deletedAt, "and the row says it is retired");
+      const listed = await catalog.list({});
+      assert.equal(
+        listed.some((row) => row.id === bundle.id),
+        false,
+        "a retired bundle is not in the catalogue an operator browses"
+      );
+    });
     test("countByPlanVersionId counts current AND pending bindings in one query", async (t) => {
       const { seed, adapter } = harness;
       if (!adapter.subscriptionRepository.countByPlanVersionId) {
-        t.skip("adapter does not implement countByPlanVersionId (fail-closed fallback)");
+        missing(t, "countByPlanVersionId");
         return;
       }
       const v1 = await seed.createPlanVersion({
@@ -377,9 +1107,7 @@ function persistenceAdapterContract(options) {
         return;
       }
       if (!adapter.promoCodeRedemptionRepository) {
-        t.skip(
-          "adapter provides no PromoCodeRedemptionRepository (needed as tx write probe)"
-        );
+        missing(t, "promoCodeRedemptions");
         return;
       }
       const redemptions = adapter.promoCodeRedemptionRepository;
@@ -462,7 +1190,7 @@ function persistenceAdapterContract(options) {
     test("concurrent claimSlot grants exactly maxRedemptions slots", async (t) => {
       const { seed, adapter } = harness;
       if (!adapter.promoCodeRepository) {
-        t.skip("adapter provides no PromoCodeRepository");
+        missing(t, "promoCodes");
         return;
       }
       const promoCodes = adapter.promoCodeRepository;
@@ -483,7 +1211,7 @@ function persistenceAdapterContract(options) {
     test("claimSlot / markExhaustedIfFull / releaseSlot lifecycle", async (t) => {
       const { seed, adapter } = harness;
       if (!adapter.promoCodeRepository) {
-        t.skip("adapter provides no PromoCodeRepository");
+        missing(t, "promoCodes");
         return;
       }
       const promoCodes = adapter.promoCodeRepository;
@@ -503,7 +1231,7 @@ function persistenceAdapterContract(options) {
     test("a subscription cannot redeem twice (unique guard)", async (t) => {
       const { seed, adapter } = harness;
       if (!adapter.promoCodeRedemptionRepository) {
-        t.skip("adapter provides no PromoCodeRedemptionRepository");
+        missing(t, "promoCodeRedemptions");
         return;
       }
       const redemptions = adapter.promoCodeRedemptionRepository;
@@ -543,7 +1271,7 @@ function persistenceAdapterContract(options) {
     test("audit write \u2192 query roundtrip with actorTag filters", async (t) => {
       const { adapter } = harness;
       if (!adapter.audit || !adapter.auditQuery) {
-        t.skip("adapter provides no AuditPort/AuditQueryPort pair");
+        missing(t, "audit");
         return;
       }
       await adapter.audit.write({
@@ -583,7 +1311,7 @@ function persistenceAdapterContract(options) {
     test("MFA secret roundtrip", async (t) => {
       const { adapter } = harness;
       if (!adapter.mfa) {
-        t.skip("adapter provides no MfaPort");
+        missing(t, "mfa");
         return;
       }
       assert.equal(await adapter.mfa.getSecret("admin-1"), null);
@@ -598,7 +1326,7 @@ function persistenceAdapterContract(options) {
     test("finds the subscription the id names, not merely a subscription", async (t) => {
       const { adapter, seed } = harness;
       if (!adapter.promoSubscriptionLookup) {
-        t.skip("adapter provides no PromoSubscriptionLookup");
+        missing(t, "promoSubscriptionLookup");
         return;
       }
       const { planVersionId } = await seed.createPlanVersion({
@@ -627,7 +1355,7 @@ function persistenceAdapterContract(options) {
     test("returns null for an id that does not exist", async (t) => {
       const { adapter, seed } = harness;
       if (!adapter.promoSubscriptionLookup) {
-        t.skip("adapter provides no PromoSubscriptionLookup");
+        missing(t, "promoSubscriptionLookup");
         return;
       }
       const { planVersionId } = await seed.createPlanVersion({
@@ -648,7 +1376,7 @@ function persistenceAdapterContract(options) {
     test("carries the fields a promo rule reads: cycle and start date", async (t) => {
       const { adapter, seed } = harness;
       if (!adapter.promoSubscriptionLookup) {
-        t.skip("adapter provides no PromoSubscriptionLookup");
+        missing(t, "promoSubscriptionLookup");
         return;
       }
       const { planVersionId } = await seed.createPlanVersion({
@@ -683,7 +1411,7 @@ function persistenceAdapterContract(options) {
     test("reads inside a transaction, so validation and redemption agree", async (t) => {
       const { adapter, seed } = harness;
       if (!adapter.promoSubscriptionLookup) {
-        t.skip("adapter provides no PromoSubscriptionLookup");
+        missing(t, "promoSubscriptionLookup");
         return;
       }
       const { planVersionId } = await seed.createPlanVersion({
@@ -704,13 +1432,1584 @@ function persistenceAdapterContract(options) {
       assert.equal(seen?.id, subscriptionId);
       assert.equal(seen?.tenantId, "tenant-a");
     });
-    test("immutable subscription contracts (append-only, terminate-only)", (t) => {
-      if (!harness.adapter.subscriptionContractRepository) {
-        t.skip("adapter provides no SubscriptionContractRepository \u2014 scenario pending");
+    test("a contract keeps what was agreed, and ending it does not rewrite it", async (t) => {
+      const contracts = harness.adapter.subscriptionContractRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!contracts || !createSubscriber) {
+        missing(t, "subscriptionContracts");
         return;
       }
-      assert.fail(
-        "SubscriptionContractRepository present but the contract kit has no scenario yet \u2014 extend the kit"
+      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",
+          billingCycle: "monthly",
+          subtotalNet: 29.9,
+          discountNet: 0,
+          totalNet: 29.9,
+          vatRate: 19,
+          totalGross: 35.58
+        },
+        entitlementSnapshot: {
+          plan: "STANDARD",
+          features: ["CORE"],
+          quotas: { users: 5 }
+        },
+        originalBundleVersionIds: ["bundle-version-1"],
+        termsSnapshot: { noticePeriodDays: 30 },
+        lineItems: [
+          {
+            kind: "plan",
+            sourceKey: "STANDARD",
+            sourceVersionId: "plan-version-1",
+            titleSnapshot: "Standard",
+            descriptionSnapshot: "The plan as it was signed",
+            quantity: 1,
+            unit: null,
+            priceNet: 19.9,
+            priceGross: 23.68,
+            billingCycle: "monthly",
+            currency: "EUR",
+            taxRate: 19,
+            taxAmount: 3.78,
+            minimumTermUntil: /* @__PURE__ */ new Date("2027-01-01T00:00:00.000Z"),
+            featuresSnapshot: ["CORE"],
+            quotaEffectsSnapshot: { users: 5 },
+            metadata: { origin: "onboarding" }
+          },
+          {
+            kind: "bundle",
+            sourceKey: "EXTRA-SEATS",
+            sourceVersionId: "bundle-version-1",
+            titleSnapshot: "Extra seats",
+            descriptionSnapshot: null,
+            quantity: 1,
+            unit: "seat",
+            priceNet: 10,
+            priceGross: 11.9,
+            billingCycle: "monthly",
+            currency: "EUR",
+            taxRate: 19,
+            taxAmount: 1.9,
+            minimumTermUntil: null,
+            featuresSnapshot: [],
+            quotaEffectsSnapshot: { users: 5 },
+            metadata: null
+          }
+        ]
+      });
+      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 });
+      const planLine = created.lineItems.find((item) => item.kind === "plan");
+      assert.ok(planLine, "plan line expected");
+      assert.equal(planLine.priceNet, 19.9, "money must survive the round trip unrounded");
+      assert.equal(planLine.priceGross, 23.68);
+      assert.equal(planLine.billingCycle, "monthly");
+      assert.deepEqual(planLine.quotaEffectsSnapshot, { users: 5 });
+      assert.equal(planLine.descriptionSnapshot, "The plan as it was signed");
+      assert.equal(
+        planLine.minimumTermUntil?.getTime(),
+        (/* @__PURE__ */ new Date("2027-01-01T00:00:00.000Z")).getTime(),
+        "the commitment is part of what was agreed"
+      );
+      assert.deepEqual(planLine.metadata, { origin: "onboarding" });
+      assert.equal(planLine.currency, "EUR", "the line says what it was booked in");
+      assert.equal(planLine.taxRate, 19, "the rate is a recorded fact, not the ratio");
+      assert.equal(planLine.taxAmount, 3.78);
+      assert.equal(
+        Math.round((planLine.priceNet + planLine.taxAmount) * 100) / 100,
+        planLine.priceGross,
+        "the tax closes the gap between net and gross"
+      );
+      const bundleLine = created.lineItems.find((item) => item.kind === "bundle");
+      assert.ok(bundleLine, "bundle line expected");
+      assert.equal(bundleLine.descriptionSnapshot, null);
+      assert.equal(bundleLine.unit, "seat");
+      assert.equal(bundleLine.minimumTermUntil, null);
+      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,
+        "lines belong to the contract, not the call"
+      );
+      assert.equal(
+        (await contracts.findActiveByTenantId(
+          tenantId,
+          /* @__PURE__ */ new Date("2026-06-01T00:00:00.000Z")
+        ))?.id,
+        created.id
+      );
+      assert.equal(
+        await contracts.findActiveByTenantId(
+          tenantId,
+          /* @__PURE__ */ new Date("2025-12-31T23:59:59.999Z")
+        ),
+        null,
+        "a contract is not active before it starts"
+      );
+      const endsAt = /* @__PURE__ */ new Date("2026-07-01T00:00:00.000Z");
+      const terminated = await contracts.terminate(created.id, {
+        effectiveUntil: endsAt,
+        status: null
+      });
+      assert.equal(
+        terminated.status,
+        "active",
+        "a null status leaves the contract in the state it had"
+      );
+      assert.equal(terminated.effectiveUntil?.getTime(), endsAt.getTime());
+      assert.equal(terminated.lineItems.length, 2, "ending a contract keeps its lines");
+      assert.equal(
+        terminated.priceSnapshot.totalNet,
+        created.priceSnapshot.totalNet,
+        "ending a contract does not restate its price"
+      );
+      const afterEnd = await contracts.findById(created.id);
+      assert.ok(afterEnd, "a terminated contract is still readable");
+      assert.equal(afterEnd.lineItems.length, 2);
+      assert.equal(
+        (await contracts.findActiveByTenantId(
+          tenantId,
+          /* @__PURE__ */ new Date("2026-06-30T00:00:00.000Z")
+        ))?.id,
+        created.id,
+        "active up to the moment it ends"
+      );
+      assert.equal(
+        await contracts.findActiveByTenantId(tenantId, endsAt),
+        null,
+        "and not at that moment"
+      );
+    });
+    test("a successor takes over without erasing the contract it replaces", async (t) => {
+      const contracts = harness.adapter.subscriptionContractRepository;
+      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",
+        sourceKey: "STANDARD",
+        sourceVersionId: null,
+        titleSnapshot: "Standard",
+        descriptionSnapshot: null,
+        quantity: 1,
+        unit: null,
+        priceNet,
+        priceGross,
+        billingCycle: "monthly",
+        currency: "EUR",
+        taxRate: 19,
+        taxAmount: Math.round((priceGross - priceNet) * 100) / 100,
+        minimumTermUntil: null,
+        featuresSnapshot: [],
+        quotaEffectsSnapshot: {},
+        metadata: null
+      });
+      const priceAt = (net, gross) => ({
+        currency: "EUR",
+        billingCycle: "monthly",
+        subtotalNet: net,
+        discountNet: 0,
+        totalNet: net,
+        vatRate: 19,
+        totalGross: gross
+      });
+      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)]
+      });
+      assert.equal(
+        (await contracts.findActiveByTenantId(
+          tenantId,
+          /* @__PURE__ */ new Date("2026-03-31T00:00:00.000Z")
+        ))?.id,
+        first.id
+      );
+      await contracts.terminate(first.id, {
+        effectiveUntil: handover,
+        status: "superseded"
+      });
+      const second = await contracts.create({
+        tenantId,
+        parties,
+        effectiveFrom: handover,
+        priceSnapshot: priceAt(24.9, 29.63),
+        lineItems: [lineAt(24.9, 29.63)]
+      });
+      assert.equal(
+        (await contracts.findActiveByTenantId(tenantId, handover))?.id,
+        second.id,
+        "the successor takes over at the moment the predecessor ends"
+      );
+      assert.equal(
+        await contracts.findActiveByTenantId(
+          tenantId,
+          /* @__PURE__ */ new Date("2026-03-31T00:00:00.000Z")
+        ),
+        null,
+        "a superseded contract is not live at any asOf"
+      );
+      const superseded = await contracts.findById(first.id);
+      assert.equal(superseded?.status, "superseded");
+      assert.equal(
+        superseded?.priceSnapshot.totalNet,
+        19.9,
+        "the replaced contract keeps the price it was signed at"
+      );
+      const history = await contracts.list({ tenantId });
+      assert.equal(history.length, 2, "both contracts remain in the history");
+      assert.deepEqual(
+        history.map((contract) => contract.lineItems.map((item) => item.priceNet)),
+        [[24.9], [19.9]]
+      );
+      assert.deepEqual(
+        history.map((contract) => contract.id),
+        [second.id, first.id],
+        "newest first"
+      );
+      assert.deepEqual(
+        (await contracts.list({ tenantId, asOf: /* @__PURE__ */ new Date("2026-03-31T00:00:00.000Z") })).map((contract) => contract.id),
+        [first.id],
+        "asOf narrows the history to what was in force then"
+      );
+      assert.deepEqual(
+        (await contracts.list({ tenantId, status: "superseded" })).map(
+          (contract) => contract.id
+        ),
+        [first.id]
+      );
+    });
+    test("a line keeps the currency and the tax it was booked with", async (t) => {
+      const contracts = harness.adapter.subscriptionContractRepository;
+      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",
+          billingCycle: "monthly",
+          subtotalNet: 100,
+          discountNet: 10,
+          totalNet: 90,
+          vatRate: 8.1,
+          totalGross: 97.29
+        },
+        lineItems: [
+          {
+            kind: "plan",
+            sourceKey: "STANDARD",
+            sourceVersionId: null,
+            titleSnapshot: "Standard",
+            descriptionSnapshot: null,
+            quantity: 1,
+            unit: null,
+            priceNet: 100,
+            priceGross: 108.1,
+            billingCycle: "monthly",
+            // Not the installation this suite's other contracts
+            // run under, and not a whole number of per cent —
+            // a rate stored as an integer, or a currency taken
+            // from a default, passes every other case here.
+            currency: "CHF",
+            taxRate: 8.1,
+            taxAmount: 8.1,
+            minimumTermUntil: null,
+            featuresSnapshot: [],
+            quotaEffectsSnapshot: {},
+            metadata: null
+          },
+          {
+            kind: "discount",
+            sourceKey: "WELCOME10",
+            sourceVersionId: null,
+            titleSnapshot: "Welcome discount",
+            descriptionSnapshot: null,
+            quantity: 1,
+            unit: null,
+            priceNet: -10,
+            priceGross: -10.81,
+            billingCycle: "monthly",
+            currency: "CHF",
+            taxRate: 8.1,
+            taxAmount: -0.81,
+            minimumTermUntil: null,
+            featuresSnapshot: [],
+            quotaEffectsSnapshot: {},
+            metadata: null
+          }
+        ]
+      });
+      const read = await contracts.findById(created.id);
+      const plan = read?.lineItems.find((item) => item.kind === "plan");
+      const discount = read?.lineItems.find((item) => item.kind === "discount");
+      assert.ok(plan && discount, "both lines expected");
+      assert.equal(plan.currency, "CHF");
+      assert.equal(plan.taxRate, 8.1, "a fractional rate survives the column");
+      assert.equal(plan.taxAmount, 8.1);
+      assert.equal(discount.currency, "CHF");
+      assert.equal(discount.taxRate, 8.1);
+      assert.equal(discount.taxAmount, -0.81);
+      for (const line of [plan, discount]) {
+        assert.equal(
+          Math.round((line.priceNet + line.taxAmount) * 100) / 100,
+          line.priceGross,
+          "net plus tax is gross, on every line"
+        );
+      }
+    });
+    test("a contract written on a transaction is undone with it, and found by its offer", async (t) => {
+      const { adapter, seed } = harness;
+      const contracts = adapter.subscriptionContractRepository;
+      if (!contracts || !seed.createSubscriber) {
+        missing(t, "subscriptionContracts");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        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", parties), tx);
+          throw new Error("the conclusion fails after the contract is written");
+        })
+      );
+      assert.equal(
+        await contracts.findByOriginalOfferId("offer-rolled-back"),
+        null,
+        "the contract outlived its transaction"
+      );
+      const kept = await adapter.transactionRunner.run(
+        (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("the contracts still running say which issuer each names", async (t) => {
+      const { adapter } = harness;
+      const contracts = adapter.subscriptionContractRepository;
+      const createSubscriber = harness.seed.createSubscriber;
+      if (!contracts || !createSubscriber) {
+        missing(t, "subscriptionContracts");
+        return;
+      }
+      const { subscriberId } = await createSubscriber({ legalName: "Meier GmbH" });
+      const parties = partiesWith(subscriberId, "Meier GmbH");
+      const written = async (offerId, overrides) => contracts.create({ ...contractFromOffer(offerId, parties), ...overrides });
+      const oldest = await written("running-oldest", {
+        effectiveFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z")
+      });
+      const scheduled = await written("running-scheduled", {
+        effectiveFrom: /* @__PURE__ */ new Date("2026-02-01T00:00:00.000Z"),
+        status: "scheduled"
+      });
+      const lapsed = await written("running-lapsed", {
+        effectiveFrom: /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z"),
+        effectiveUntil: /* @__PURE__ */ new Date("2026-04-01T00:00:00.000Z")
+      });
+      const ending = await written("running-ending", {
+        effectiveFrom: /* @__PURE__ */ new Date("2026-04-01T00:00:00.000Z"),
+        effectiveUntil: /* @__PURE__ */ new Date("2026-12-01T00:00:00.000Z")
+      });
+      const noIssuer = await written("running-no-issuer", {
+        effectiveFrom: /* @__PURE__ */ new Date("2026-05-01T00:00:00.000Z"),
+        parties: { ...parties, issuer: null }
+      });
+      await written("running-terminated", {
+        effectiveFrom: /* @__PURE__ */ new Date("2025-01-01T00:00:00.000Z"),
+        status: "terminated"
+      });
+      await written("running-superseded", {
+        effectiveFrom: /* @__PURE__ */ new Date("2025-02-01T00:00:00.000Z"),
+        status: "superseded"
+      });
+      const asOf = /* @__PURE__ */ new Date("2026-06-01T00:00:00.000Z");
+      const listed = await contracts.listRunningIssuers(10, asOf);
+      assert.equal(listed.total, 4, "a contract that ended or was ended is not running");
+      assert.deepEqual(
+        listed.contracts.map((row) => row.id),
+        [oldest.id, scheduled.id, ending.id, noIssuer.id],
+        "oldest first, and the one whose term ran out is not among them"
+      );
+      assert.ok(
+        !listed.contracts.some((row) => row.id === lapsed.id),
+        "a window that closed ends a contract, whatever its status still says"
+      );
+      const earlier = await contracts.listRunningIssuers(
+        10,
+        /* @__PURE__ */ new Date("2026-03-15T00:00:00.000Z")
+      );
+      assert.equal(earlier.total, 5);
+      assert.ok(earlier.contracts.some((row) => row.id === lapsed.id));
+      assert.equal(listed.contracts[0].tenantId, oldest.tenantId);
+      assert.equal(
+        listed.contracts[0].effectiveFrom.getTime(),
+        (/* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z")).getTime()
+      );
+      assert.equal(listed.contracts[0].issuerLegalName, "Example Software GmbH");
+      assert.equal(
+        listed.contracts[3].issuerLegalName,
+        null,
+        "a contract with no issuer copy says so rather than inventing one"
+      );
+      const capped = await contracts.listRunningIssuers(2, asOf);
+      assert.equal(capped.total, 4, "the limit caps the list, not the count");
+      assert.deepEqual(
+        capped.contracts.map((row) => row.id),
+        [oldest.id, scheduled.id]
+      );
+      const counted = await contracts.listRunningIssuers(0, asOf);
+      assert.equal(counted.total, 4);
+      assert.deepEqual(counted.contracts, []);
+    });
+    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) {
+        missing(t, "checkoutOffers");
+        return;
+      }
+      const offer = await offers.create(OFFER);
+      assert.equal(offer.status, "open");
+      const attempts = await Promise.allSettled([
+        offers.consume(offer.id),
+        offers.consume(offer.id)
+      ]);
+      assert.equal(
+        attempts.filter((attempt) => attempt.status === "fulfilled").length,
+        1,
+        "exactly one consume wins"
+      );
+      const consumed = await offers.findById(offer.id);
+      assert.equal(consumed?.status, "consumed");
+      assert.ok(consumed?.consumedAt, "and it records when");
+      await assert.rejects(() => offers.consume(offer.id), "a later consume is refused");
+      assert.equal(
+        (await offers.findById(offer.id))?.consumedAt,
+        consumed.consumedAt,
+        "and changes nothing"
+      );
+    });
+    test("a consume on a transaction that rolls back leaves the offer open", async (t) => {
+      const { adapter } = harness;
+      const offers = adapter.checkoutOfferRepository;
+      if (!offers) {
+        missing(t, "checkoutOffers");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        t.skip("adapter declares no transaction capability");
+        return;
+      }
+      const offer = await offers.create(OFFER);
+      await assert.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await offers.consume(offer.id, tx);
+          throw new Error("the contract after the consume fails");
+        })
+      );
+      const afterwards = await offers.findById(offer.id);
+      assert.equal(afterwards?.status, "open", "the consume outlived its transaction");
+      assert.equal(afterwards?.consumedAt, null);
+      assert.equal((await offers.consume(offer.id)).status, "consumed");
+    });
+    const SETTINGS = {
+      app: { name: "Demo" },
+      currency: "EUR",
+      vatRate: 19,
+      tenantBilling: {
+        cancellationNoticeDays: { monthly: 14, yearly: 90 },
+        selfServiceBlockedPlans: { asTarget: ["ENTERPRISE"], asSource: [] }
+      }
+    };
+    const SOURCE = "/srv/app/config/saas.yaml";
+    const FIRST_START = /* @__PURE__ */ new Date("2026-09-01T06:30:00.000Z");
+    const SECOND_START = /* @__PURE__ */ new Date("2026-09-02T06:30:00.000Z");
+    const applied = (fingerprint, appliedAt, settings = SETTINGS) => ({ fingerprint, settings, source: SOURCE, appliedAt });
+    const changeTo = (current, noticedAt, previous = SETTINGS) => ({ noticedAt, source: SOURCE, previous, current });
+    const TWENTY = { ...SETTINGS, vatRate: 20 };
+    const TWENTY_ONE = { ...SETTINGS, vatRate: 21 };
+    test("no record before the first boot that could write one", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      assert.equal(await port.readApplied(), null);
+      assert.deepEqual(await port.listChanges(), []);
+    });
+    test("the record comes back as it was written \u2014 values, source and moment", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      assert.equal(await port.writeApplied(applied("sha256-a", FIRST_START), null), true);
+      const read = await port.readApplied();
+      assert.ok(read, "a record expected");
+      assert.equal(read.fingerprint, "sha256-a");
+      assert.equal(read.source, SOURCE);
+      assert.equal(read.appliedAt.toISOString(), FIRST_START.toISOString());
+      assert.deepEqual(read.settings, SETTINGS);
+    });
+    test("writing again replaces the one row rather than adding a second", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      await port.writeApplied(applied("sha256-a", FIRST_START), null);
+      assert.equal(
+        await port.writeApplied(applied("sha256-b", SECOND_START, TWENTY), "sha256-a"),
+        true
+      );
+      const read = await port.readApplied();
+      assert.equal(read?.fingerprint, "sha256-b");
+      assert.equal(read?.appliedAt.toISOString(), SECOND_START.toISOString());
+      assert.equal((read?.settings).vatRate, 20);
+    });
+    test("the first record is written once: a second writer that read none is refused", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      assert.equal(await port.writeApplied(applied("sha256-a", FIRST_START), null), true);
+      assert.equal(await port.writeApplied(applied("sha256-b", SECOND_START), null), false);
+      assert.equal((await port.readApplied())?.fingerprint, "sha256-a");
+    });
+    test("a write guarded on a fingerprint the row no longer carries is refused", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      await port.writeApplied(applied("sha256-a", FIRST_START), null);
+      assert.equal(
+        await port.writeApplied(applied("sha256-b", SECOND_START), "sha256-a"),
+        true
+      );
+      assert.equal(
+        await port.writeApplied(applied("sha256-c", SECOND_START), "sha256-a"),
+        false
+      );
+      const read = await port.readApplied();
+      assert.equal(
+        read?.fingerprint,
+        "sha256-b",
+        "the row stands as the first writer left it"
+      );
+      assert.equal(read?.appliedAt.toISOString(), SECOND_START.toISOString());
+    });
+    test("a change lands with the record it supersedes, and is listed newest first", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      await port.writeApplied(applied("sha256-a", FIRST_START), null);
+      const first = await port.recordChange(
+        changeTo(TWENTY, FIRST_START),
+        applied("sha256-b", FIRST_START, TWENTY),
+        "sha256-a"
+      );
+      const second = await port.recordChange(
+        changeTo(TWENTY_ONE, SECOND_START, TWENTY),
+        applied("sha256-c", SECOND_START, TWENTY_ONE),
+        "sha256-b"
+      );
+      assert.ok(first && second, "both guards held");
+      assert.ok(first.id && second.id && first.id !== second.id, "two distinct ids");
+      assert.equal(first.acknowledgedAt, null);
+      assert.equal(first.acknowledgedBy, null);
+      assert.equal(
+        (await port.readApplied())?.fingerprint,
+        "sha256-c",
+        "the record moved with the change"
+      );
+      const listed = await port.listChanges();
+      assert.deepEqual(
+        listed.map((c) => c.id),
+        [second.id, first.id]
+      );
+      assert.deepEqual(listed[1].previous, SETTINGS);
+      assert.equal(listed[1].current.vatRate, 20);
+      assert.deepEqual(
+        (await port.listChanges({ limit: 1 })).map((c) => c.id),
+        [second.id]
+      );
+    });
+    test("a change whose record has moved on is refused whole: no change, and the record as it was", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      await port.writeApplied(applied("sha256-a", FIRST_START), null);
+      const refused = await port.recordChange(
+        changeTo(TWENTY, SECOND_START),
+        applied("sha256-b", SECOND_START, TWENTY),
+        "sha256-stale"
+      );
+      assert.equal(refused, null);
+      assert.deepEqual(await port.listChanges(), [], "no change without its record");
+      const read = await port.readApplied();
+      assert.equal(read?.fingerprint, "sha256-a");
+      assert.equal(read?.appliedAt.toISOString(), FIRST_START.toISOString());
+    });
+    test("starts noticing the same difference at once record it once", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      await port.writeApplied(applied("sha256-a", FIRST_START), null);
+      const attempts = await Promise.all(
+        [1, 2, 3].map(
+          () => port.recordChange(
+            changeTo(TWENTY, SECOND_START),
+            applied("sha256-b", SECOND_START, TWENTY),
+            "sha256-a"
+          )
+        )
+      );
+      const recorded = attempts.filter((change) => change !== null);
+      assert.equal(recorded.length, 1, "exactly one start records the change");
+      assert.deepEqual(
+        (await port.listChanges()).map((c) => c.id),
+        [recorded[0]?.id]
+      );
+      assert.equal((await port.readApplied())?.fingerprint, "sha256-b");
+    });
+    test("several first starts write the record once", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      const written = await Promise.all(
+        [1, 2, 3].map(() => port.writeApplied(applied("sha256-a", FIRST_START), null))
+      );
+      assert.equal(written.filter(Boolean).length, 1, "exactly one start writes it");
+      assert.equal((await port.readApplied())?.fingerprint, "sha256-a");
+    });
+    test("changes are listed in the order they were recorded, latest first \u2014 not by the moment they carry", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      await port.writeApplied(applied("sha256-0", FIRST_START, {}), null);
+      const earlierMove = await port.recordChange(
+        changeTo({ vatRate: 1 }, SECOND_START, {}),
+        applied("sha256-1", SECOND_START, { vatRate: 1 }),
+        "sha256-0"
+      );
+      const laterMove = await port.recordChange(
+        changeTo({ vatRate: 2 }, FIRST_START, { vatRate: 1 }),
+        applied("sha256-2", FIRST_START, { vatRate: 2 }),
+        "sha256-1"
+      );
+      assert.ok(earlierMove && laterMove, "both guards held");
+      assert.deepEqual(
+        (await port.listChanges()).map((c) => c.id),
+        [laterMove.id, earlierMove.id]
+      );
+      assert.deepEqual(
+        (await port.listChanges({ limit: 1 })).map((c) => c.id),
+        [laterMove.id]
+      );
+      assert.deepEqual(
+        (await port.listChanges()).map((c) => c.id),
+        [laterMove.id, earlierMove.id],
+        "the same order the second time it is asked"
+      );
+    });
+    test("acknowledging a change is recorded once, and filters it out of what is owed", async (t) => {
+      const port = harness.adapter.appliedSettings;
+      if (!port) {
+        missing(t, "appliedSettings");
+        return;
+      }
+      await port.writeApplied(applied("sha256-a", FIRST_START), null);
+      const change = await port.recordChange(
+        changeTo(TWENTY, FIRST_START),
+        applied("sha256-b", FIRST_START, TWENTY),
+        "sha256-a"
+      );
+      const open = await port.recordChange(
+        changeTo(TWENTY_ONE, SECOND_START, TWENTY),
+        applied("sha256-c", SECOND_START, TWENTY_ONE),
+        "sha256-b"
+      );
+      assert.ok(change && open, "both guards held");
+      const seenAt = /* @__PURE__ */ new Date("2026-09-03T08:00:00.000Z");
+      const acknowledged = await port.acknowledgeChange(
+        change.id,
+        "web:ops@example.com:s1",
+        seenAt
+      );
+      assert.equal(acknowledged?.acknowledgedAt?.toISOString(), seenAt.toISOString());
+      assert.equal(acknowledged?.acknowledgedBy, "web:ops@example.com:s1");
+      const again = await port.acknowledgeChange(
+        change.id,
+        "web:other@example.com:s2",
+        /* @__PURE__ */ new Date("2026-09-04T08:00:00.000Z")
+      );
+      assert.equal(again?.acknowledgedAt?.toISOString(), seenAt.toISOString());
+      assert.equal(again?.acknowledgedBy, "web:ops@example.com:s1");
+      assert.deepEqual(
+        (await port.listChanges({ acknowledged: false })).map((c) => c.id),
+        [open.id]
+      );
+      assert.deepEqual(
+        (await port.listChanges({ acknowledged: true })).map((c) => c.id),
+        [change.id]
+      );
+      assert.equal(
+        await port.acknowledgeChange("no-such-change", "web:ops@example.com:s1", seenAt),
+        null
       );
     });
   });