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

package/dist/index.js

@@ -2,12 +2,133 @@
 import assert from "node:assert/strict";
 import { after, before, beforeEach, describe, test } from "node:test";
 var LOCK_HOLD_MS = 150;
+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)
+  },
+  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 +138,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 +226,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 +271,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 +355,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 +419,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 +478,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 +533,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 +587,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 +632,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 +663,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 +684,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 +716,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 +779,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 +791,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 +805,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 +819,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 +924,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 +964,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 +1047,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 +1068,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 +1088,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 +1128,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 +1168,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 +1183,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 +1212,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 +1233,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 +1268,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 +1292,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 +1448,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 +1550,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";
@@ -1437,7 +1648,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 +1657,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 +1671,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 +1687,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 +1697,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 +1720,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 +1758,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 +1776,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 +1800,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 +1812,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 +1844,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);

package/package.json

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