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

package/dist/index.js

@@ -2,12 +2,189 @@
 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 contractFromOffer(offerId) {
+  return {
+    tenantId: `tenant-${offerId}`,
+    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",
+    present: ({ adapter }) => Boolean(adapter.subscriptionContractRepository)
+  },
+  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 +194,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 +282,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({
@@ -136,12 +327,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({
@@ -220,7 +411,7 @@ 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({
@@ -284,7 +475,7 @@ 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({
@@ -343,7 +534,7 @@ function persistenceAdapterContract(options) {
       const repository = harness.adapter.subscriptionBundleRepository;
       const { seed } = harness;
       if (!repository || !seed.createBundleVersion) {
-        t.skip("adapter provides no SubscriptionBundleRepository or bundle catalog");
+        missing(t, "bundleBookings");
         return;
       }
       const { planVersionId } = await seed.createPlanVersion({
@@ -398,7 +589,7 @@ function persistenceAdapterContract(options) {
       const repository = harness.adapter.subscriptionBundleRepository;
       const { seed } = harness;
       if (!repository || !seed.createBundleVersion) {
-        t.skip("adapter provides no SubscriptionBundleRepository or bundle catalog");
+        missing(t, "bundleBookings");
         return;
       }
       const { planVersionId } = await seed.createPlanVersion({
@@ -452,7 +643,7 @@ function persistenceAdapterContract(options) {
       const repository = harness.adapter.subscriptionBundleRepository;
       const { seed } = harness;
       if (!repository || !seed.createBundleVersion) {
-        t.skip("adapter provides no SubscriptionBundleRepository or bundle catalog");
+        missing(t, "bundleBookings");
         return;
       }
       const { planVersionId } = await seed.createPlanVersion({
@@ -497,7 +688,7 @@ function persistenceAdapterContract(options) {
       const repository = harness.adapter.subscriptionBundleRepository;
       const { seed } = harness;
       if (!repository || !seed.createBundleVersion) {
-        t.skip("adapter provides no SubscriptionBundleRepository or bundle catalog");
+        missing(t, "bundleBookings");
         return;
       }
       const { planVersionId } = await seed.createPlanVersion({
@@ -528,7 +719,7 @@ function persistenceAdapterContract(options) {
       });
       const clearRequestDate = harness.seed.clearBookingRequestDate;
       if (!clearRequestDate) {
-        t.skip("adapter harness cannot write the half-cancelled shape");
+        missing(t, "halfCancelledBookingSeed");
         return;
       }
       await clearRequestDate(booking.id);
@@ -549,7 +740,7 @@ function persistenceAdapterContract(options) {
       const catalog = harness.adapter.bundleRepository;
       const discardDraft = catalog?.deleteDraft?.bind(catalog);
       if (!catalog || !discardDraft) {
-        t.skip("adapter provides no BundleRepository");
+        missing(t, "bundleDraftDiscard");
         return;
       }
       const bundle = await catalog.create({
@@ -581,7 +772,7 @@ function persistenceAdapterContract(options) {
       const catalog = harness.adapter.bundleRepository;
       const publish = catalog?.publishDraft?.bind(catalog);
       if (!catalog || !publish) {
-        t.skip("adapter provides no BundleRepository");
+        missing(t, "bundleDraftPublish");
         return;
       }
       const bundle = await catalog.create({
@@ -644,7 +835,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "planRepository");
         return;
       }
       await repository.create({ planKey: "DOUBLE", label: "First" });
@@ -656,7 +847,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "bundleRepository");
         return;
       }
       await catalog.create({ bundleKey: "DOUBLE", label: "First" });
@@ -670,7 +861,7 @@ function persistenceAdapterContract(options) {
       const retire = repository?.softDelete?.bind(repository);
       const byKey = repository?.findByKey?.bind(repository);
       if (!repository || !retire || !byKey) {
-        t.skip("adapter provides no PlanRepository");
+        missing(t, "planRetirement");
         return;
       }
       const plan = await repository.create({ planKey: "RETIRED_PLAN", label: "Retired" });
@@ -684,12 +875,90 @@ function persistenceAdapterContract(options) {
         "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) {
-        t.skip("adapter provides no BundleRepository");
+        missing(t, "bundleRetirement");
         return;
       }
       const bundle = await catalog.create({
@@ -711,7 +980,7 @@ function persistenceAdapterContract(options) {
     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({
@@ -751,9 +1020,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;
@@ -836,7 +1103,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;
@@ -857,7 +1124,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;
@@ -877,7 +1144,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;
@@ -917,7 +1184,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({
@@ -957,7 +1224,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);
@@ -972,7 +1239,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({
@@ -1001,7 +1268,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({
@@ -1022,7 +1289,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({
@@ -1057,7 +1324,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({
@@ -1081,7 +1348,7 @@ function persistenceAdapterContract(options) {
     test("a contract keeps what was agreed, and ending it does not rewrite it", async (t) => {
       const contracts = harness.adapter.subscriptionContractRepository;
       if (!contracts) {
-        t.skip("adapter provides no SubscriptionContractRepository");
+        missing(t, "subscriptionContracts");
         return;
       }
       const tenantId = "tenant-contract-lifecycle";
@@ -1237,7 +1504,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "subscriptionContracts");
         return;
       }
       const tenantId = "tenant-contract-succession";
@@ -1339,7 +1606,7 @@ function persistenceAdapterContract(options) {
     test("a line keeps the currency and the tax it was booked with", async (t) => {
       const contracts = harness.adapter.subscriptionContractRepository;
       if (!contracts) {
-        t.skip("adapter provides no SubscriptionContractRepository");
+        missing(t, "subscriptionContracts");
         return;
       }
       const tenantId = "tenant-contract-money-facts";
@@ -1418,6 +1685,86 @@ function persistenceAdapterContract(options) {
         );
       }
     });
+    test("a contract written on a transaction is undone with it, and found by its offer", async (t) => {
+      const { adapter } = harness;
+      const contracts = adapter.subscriptionContractRepository;
+      if (!contracts) {
+        missing(t, "subscriptionContracts");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        t.skip("adapter declares no transaction capability");
+        return;
+      }
+      await assert.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await contracts.create(contractFromOffer("offer-rolled-back"), 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"), 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("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",
@@ -1437,7 +1784,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       assert.equal(await port.readApplied(), null);
@@ -1446,7 +1793,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       assert.equal(await port.writeApplied(applied("sha256-a", FIRST_START), null), true);
@@ -1460,7 +1807,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       await port.writeApplied(applied("sha256-a", FIRST_START), null);
@@ -1476,7 +1823,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       assert.equal(await port.writeApplied(applied("sha256-a", FIRST_START), null), true);
@@ -1486,7 +1833,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       await port.writeApplied(applied("sha256-a", FIRST_START), null);
@@ -1509,7 +1856,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       await port.writeApplied(applied("sha256-a", FIRST_START), null);
@@ -1547,7 +1894,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       await port.writeApplied(applied("sha256-a", FIRST_START), null);
@@ -1565,7 +1912,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       await port.writeApplied(applied("sha256-a", FIRST_START), null);
@@ -1589,7 +1936,7 @@ function persistenceAdapterContract(options) {
     test("several first starts write the record once", async (t) => {
       const port = harness.adapter.appliedSettings;
       if (!port) {
-        t.skip("adapter provides no AppliedSettingsPort");
+        missing(t, "appliedSettings");
         return;
       }
       const written = await Promise.all(
@@ -1601,7 +1948,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       await port.writeApplied(applied("sha256-0", FIRST_START, {}), null);
@@ -1633,7 +1980,7 @@ function persistenceAdapterContract(options) {
     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");
+        missing(t, "appliedSettings");
         return;
       }
       await port.writeApplied(applied("sha256-a", FIRST_START), null);