@saasicat/persistence-testing 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/index.js

@@ -113,13 +113,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");
@@ -170,7 +176,8 @@ function persistenceAdapterContract(options) {
             cycle: "MONTHLY",
             periodStart: null,
             periodEnd: null,
-            nextStatus: null
+            nextStatus: null,
+            expectedCanceledAt: null
           },
           async (tx, callbackSubscriptionId) => {
             assert.equal(callbackSubscriptionId, subscriptionId);
@@ -217,11 +224,10 @@ function persistenceAdapterContract(options) {
         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"],
@@ -282,11 +288,10 @@ function persistenceAdapterContract(options) {
         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,6 +339,375 @@ 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) {
+        t.skip("adapter provides no SubscriptionBundleRepository or bundle catalog");
+        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) {
+        t.skip("adapter provides no SubscriptionBundleRepository or bundle catalog");
+        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) {
+        t.skip("adapter provides no SubscriptionBundleRepository or bundle catalog");
+        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) {
+        t.skip("adapter provides no SubscriptionBundleRepository or bundle catalog");
+        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) {
+        t.skip("adapter harness cannot write the half-cancelled shape");
+        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) {
+        t.skip("adapter provides no BundleRepository");
+        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) {
+        t.skip("adapter provides no BundleRepository");
+        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) {
+        t.skip("adapter provides no 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) {
+        t.skip("adapter provides no 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) {
+        t.skip("adapter provides no PlanRepository");
+        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 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) {
+        t.skip("adapter provides no BundleRepository");
+        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) {
@@ -704,13 +1078,602 @@ 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;
+      if (!contracts) {
+        t.skip("adapter provides no SubscriptionContractRepository");
+        return;
+      }
+      const tenantId = "tenant-contract-lifecycle";
+      const signedAt = /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z");
+      const created = await contracts.create({
+        tenantId,
+        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.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.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;
+      if (!contracts) {
+        t.skip("adapter provides no SubscriptionContractRepository");
+        return;
+      }
+      const tenantId = "tenant-contract-succession";
+      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,
+        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,
+        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;
+      if (!contracts) {
+        t.skip("adapter provides no SubscriptionContractRepository");
         return;
       }
-      assert.fail(
-        "SubscriptionContractRepository present but the contract kit has no scenario yet \u2014 extend the kit"
+      const tenantId = "tenant-contract-money-facts";
+      const created = await contracts.create({
+        tenantId,
+        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"
+        );
+      }
+    });
+    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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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) {
+        t.skip("adapter provides no AppliedSettingsPort");
+        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
       );
     });
   });