@saasicat/persistence-testing 0.5.0 → 0.7.0

package/README.md

@@ -9,6 +9,9 @@ Verified scenarios:
 
 - tenant subscription lookup + tenant isolation
 - plan-version resolution (live vs. superseded vs. draft)
+- semantic plan-key mapping at the port boundary
+- atomic plan + `planVersionId` changes and tx-bound onboarding promo rollback
+- PlanVersion and BundleVersion validity windows with auto-succession
 - `countByPlanVersionId` counts current AND pending bindings in one query
 - transaction rollback discards writes
 - `findByTenantIdLocked` serializes concurrent transactions (row lock)
@@ -30,17 +33,21 @@ import { persistenceAdapterContract } from '@saasicat/persistence-testing';
 
 persistenceAdapterContract({
     name: 'adapter-drizzle @ postgres',
+    projectKey: 'my-app',
     create: async () => ({
         adapter: {
-            capabilities: { transactions: true, pessimisticLocking: true, /* … */ },
+            capabilities: { transactions: true, pessimisticLocking: true /* … */ },
             transactionRunner,
             subscriptionRepository,
             planVersionRepository,
-            promoCodeRepository,          // optional slices activate more scenarios
+            promoCodeRepository, // optional slices activate more scenarios
             promoCodeRedemptionRepository,
             mfa,
             audit,
             auditQuery,
+            tenantSubscriptionWrite, // optional: enables atomic plan-binding scenarios
+            planRepository, // optional: enables plan lifecycle scenarios
+            bundleRepository, // optional: enables bundle validity scenarios
         },
         seed: { createPlanVersion, createSubscription, createPromoCode },
         reset: () => truncatePlatformTables(),

package/dist/index.cjs

@@ -117,8 +117,259 @@ function persistenceAdapterContract(options) {
       });
       const live = await adapter.planVersionRepository.findLatestLive("PRO");
       import_strict.default.ok(live, "live version expected");
+      import_strict.default.equal(
+        live.planId,
+        "PRO",
+        "port-facing plan identity must remain the semantic plan key"
+      );
       import_strict.default.deepEqual(live.quotas, { users: 2 });
     });
+    (0, import_node_test.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");
+        return;
+      }
+      const oldVersion = await seed.createPlanVersion({
+        planKey: "STARTER",
+        version: 1,
+        quotas: { users: 2 },
+        features: [],
+        published: true
+      });
+      const targetVersion = await seed.createPlanVersion({
+        planKey: "PRO",
+        version: 1,
+        quotas: { users: 20 },
+        features: ["PRO"],
+        published: true
+      });
+      await seed.createSubscription({
+        tenantId: "tenant-plan-change",
+        plan: "STARTER",
+        planVersionId: oldVersion.planVersionId
+      });
+      await adapter.tenantSubscriptionWrite.changePlanImmediate("tenant-plan-change", {
+        planId: "PRO",
+        cycle: "YEARLY",
+        periodStart: null,
+        periodEnd: null,
+        nextStatus: null
+      });
+      const changed = await adapter.subscriptionRepository.findByTenantId("tenant-plan-change");
+      import_strict.default.ok(changed, "changed subscription expected");
+      import_strict.default.equal(changed.plan, "PRO");
+      import_strict.default.equal(changed.planVersionId, targetVersion.planVersionId);
+      import_strict.default.equal(changed.planVersion.planId, "PRO");
+    });
+    (0, import_node_test.test)("onboarding selection rolls plan binding and promo write back together", async (t) => {
+      const { seed, adapter } = harness;
+      const writer = adapter.tenantSubscriptionWrite;
+      if (!writer?.applyOnboardingSelection) {
+        t.skip("adapter does not expose atomic onboarding writes");
+        return;
+      }
+      const redemptions = adapter.promoCodeRedemptionRepository;
+      if (!redemptions) {
+        t.skip("adapter provides no PromoCodeRedemptionRepository");
+        return;
+      }
+      const oldVersion = await seed.createPlanVersion({
+        planKey: "STARTER",
+        version: 1,
+        quotas: {},
+        features: [],
+        published: true
+      });
+      await seed.createPlanVersion({
+        planKey: "PRO",
+        version: 1,
+        quotas: {},
+        features: [],
+        published: true
+      });
+      const { subscriptionId } = await seed.createSubscription({
+        tenantId: "tenant-onboarding-rollback",
+        plan: "STARTER",
+        planVersionId: oldVersion.planVersionId
+      });
+      const { promoCodeId } = await seed.createPromoCode({
+        code: "ONBOARDING-ROLLBACK",
+        maxRedemptions: null
+      });
+      const startsAt = /* @__PURE__ */ new Date("2026-07-24T00:00:00.000Z");
+      await import_strict.default.rejects(
+        writer.applyOnboardingSelection(
+          "tenant-onboarding-rollback",
+          {
+            planId: "PRO",
+            cycle: "MONTHLY",
+            periodStart: null,
+            periodEnd: null,
+            nextStatus: null
+          },
+          async (tx, callbackSubscriptionId) => {
+            import_strict.default.equal(callbackSubscriptionId, subscriptionId);
+            await redemptions.create(
+              {
+                promoCodeId,
+                subscriptionId: callbackSubscriptionId,
+                tenantId: "tenant-onboarding-rollback",
+                appliedValueType: "PERCENT",
+                appliedValue: "10.00",
+                appliedDurationType: "ONCE",
+                appliedDurationValue: null,
+                startsAt,
+                endsAt: null
+              },
+              tx
+            );
+            import_strict.default.ok(
+              await redemptions.findBySubscription(callbackSubscriptionId, tx),
+              "promo write must be visible inside the onboarding transaction"
+            );
+            throw new Error("promo redemption failed");
+          }
+        ),
+        /promo redemption failed/
+      );
+      const unchanged = await adapter.subscriptionRepository.findByTenantId(
+        "tenant-onboarding-rollback"
+      );
+      import_strict.default.ok(unchanged, "subscription expected after rollback");
+      import_strict.default.equal(unchanged.plan, "STARTER");
+      import_strict.default.equal(unchanged.planVersionId, oldVersion.planVersionId);
+      import_strict.default.equal(unchanged.planVersion.planId, "STARTER");
+      import_strict.default.equal(
+        await redemptions.findBySubscription(subscriptionId),
+        null,
+        "promo callback write must be rolled back"
+      );
+    });
+    (0, import_node_test.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");
+        return;
+      }
+      const plan = await repository.create({
+        projectKey: options.projectKey,
+        planKey: "STANDARD",
+        label: "Standard"
+      });
+      import_strict.default.equal(plan.projectKey, options.projectKey);
+      const firstDraft = await repository.createPlanVersionDraft({
+        planId: "STANDARD",
+        features: ["CORE"],
+        quotas: { users: 5 },
+        monthlyNet: "10.00",
+        yearlyNet: "100.00",
+        validFrom: "2026-01-01"
+      });
+      import_strict.default.equal(firstDraft.planId, "STANDARD");
+      const first = await repository.publishPlanVersionDraft(firstDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const secondDraft = await repository.createPlanVersionDraft({
+        planId: "STANDARD",
+        baseVersionId: first.id,
+        features: ["CORE", "PLUS"],
+        quotas: { users: 10 },
+        monthlyNet: "15.00",
+        yearlyNet: "150.00",
+        validFrom: "2026-03-01"
+      });
+      const second = await repository.publishPlanVersionDraft(secondDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const succeeded = await repository.findVersionById(first.id);
+      import_strict.default.ok(succeeded, "predecessor expected");
+      import_strict.default.ok(succeeded.supersededAt, "predecessor must be superseded");
+      import_strict.default.equal(succeeded.validUntil, "2026-02-28T00:00:00.000Z");
+      import_strict.default.equal(succeeded.planId, "STANDARD");
+      import_strict.default.equal(
+        (await repository.findActivePlanVersion(
+          "STANDARD",
+          /* @__PURE__ */ new Date("2026-02-28T23:59:59.999Z")
+        ))?.id,
+        first.id,
+        "validUntil is day-inclusive"
+      );
+      import_strict.default.equal(
+        (await repository.findActivePlanVersion(
+          "STANDARD",
+          /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z")
+        ))?.id,
+        second.id
+      );
+    });
+    (0, import_node_test.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");
+        return;
+      }
+      const bundle = await repository.create({
+        projectKey: options.projectKey,
+        bundleKey: "REPORTING",
+        label: "Reporting"
+      });
+      import_strict.default.equal(bundle.projectKey, options.projectKey);
+      const firstDraft = await repository.createDraft({
+        bundleId: bundle.id,
+        features: ["REPORTS"],
+        quotas: {},
+        validFrom: "2026-01-01"
+      });
+      const first = await repository.publishDraft(firstDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const secondDraft = await repository.createDraft({
+        bundleId: bundle.id,
+        baseVersionId: first.id,
+        features: ["REPORTS", "EXPORTS"],
+        quotas: {},
+        validFrom: "2026-03-01"
+      });
+      const second = await repository.publishDraft(secondDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const succeeded = await repository.findVersionById(first.id);
+      import_strict.default.ok(succeeded, "predecessor expected");
+      import_strict.default.ok(succeeded.supersededAt, "predecessor must be superseded");
+      import_strict.default.equal(succeeded.validUntil, "2026-02-28T00:00:00.000Z");
+      import_strict.default.equal(
+        (await repository.findActiveBundleVersion(
+          bundle.id,
+          /* @__PURE__ */ new Date("2026-02-28T23:59:59.999Z")
+        ))?.id,
+        first.id,
+        "validUntil is day-inclusive"
+      );
+      import_strict.default.equal(
+        (await repository.findActiveBundleVersion(
+          bundle.id,
+          /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z")
+        ))?.id,
+        second.id
+      );
+    });
     (0, import_node_test.test)("countByPlanVersionId counts current AND pending bindings in one query", async (t) => {
       const { seed, adapter } = harness;
       if (!adapter.subscriptionRepository.countByPlanVersionId) {
@@ -162,7 +413,9 @@ function persistenceAdapterContract(options) {
         return;
       }
       if (!adapter.promoCodeRedemptionRepository) {
-        t.skip("adapter provides no PromoCodeRedemptionRepository (needed as tx write probe)");
+        t.skip(
+          "adapter provides no PromoCodeRedemptionRepository (needed as tx write probe)"
+        );
         return;
       }
       const redemptions = adapter.promoCodeRedemptionRepository;
@@ -330,14 +583,24 @@ function persistenceAdapterContract(options) {
         return;
       }
       await adapter.audit.write({
-        actor: { userId: "admin-1", email: "ops@example.com", source: "cli", context: "host1" },
+        actor: {
+          userId: "admin-1",
+          email: "ops@example.com",
+          source: "cli",
+          context: "host1"
+        },
         entity: "Tenant",
         entityId: "tenant-a",
         action: "TENANT_SUSPEND",
         changes: { reason: "test" }
       });
       await adapter.audit.write({
-        actor: { userId: "admin-2", email: "web@example.com", source: "web", context: "sess9" },
+        actor: {
+          userId: "admin-2",
+          email: "web@example.com",
+          source: "web",
+          context: "sess9"
+        },
         entity: "PromoCode",
         entityId: "promo-1",
         action: "PROMO_CODE_CREATE"

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository } from '@saasicat/types';
+import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, TenantSubscriptionWritePort, BundleRepository, PlanRepository } from '@saasicat/types';
 
 /**
  * Port instances under test. Required members define the minimum an adapter
@@ -17,6 +17,16 @@ interface ContractAdapterInstances {
     audit?: AuditPort;
     auditQuery?: AuditQueryPort;
     subscriptionContractRepository?: SubscriptionContractRepository;
+    /**
+     * Enables the atomic plan-binding scenarios. Adapters should expose this
+     * member only for a mode that promises to keep `plan`,
+     * `planVersionId` and pending-version state consistent.
+     */
+    tenantSubscriptionWrite?: TenantSubscriptionWritePort;
+    /** Enables BundleVersion validity-window and auto-succession scenarios. */
+    bundleRepository?: BundleRepository;
+    /** Enables PlanVersion lifecycle, identity and validity-window scenarios. */
+    planRepository?: PlanRepository;
 }
 /** Fixture writers — implemented per adapter against its own schema. */
 interface ContractSeed {
@@ -58,6 +68,8 @@ interface PersistenceContractHarness {
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;
+    /** Project identity used by catalog lifecycle scenarios. */
+    projectKey: string;
     /** Builds the harness once for the whole suite. */
     create(): Promise<PersistenceContractHarness>;
 }
@@ -68,6 +80,7 @@ interface PersistenceAdapterContractOptions {
  * ```ts
  * persistenceAdapterContract({
  *     name: 'adapter-prisma @ postgres',
+ *     projectKey: 'my-app',
  *     create: () => createPrismaHarness(),
  * });
  * ```

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository } from '@saasicat/types';
+import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, TenantSubscriptionWritePort, BundleRepository, PlanRepository } from '@saasicat/types';
 
 /**
  * Port instances under test. Required members define the minimum an adapter
@@ -17,6 +17,16 @@ interface ContractAdapterInstances {
     audit?: AuditPort;
     auditQuery?: AuditQueryPort;
     subscriptionContractRepository?: SubscriptionContractRepository;
+    /**
+     * Enables the atomic plan-binding scenarios. Adapters should expose this
+     * member only for a mode that promises to keep `plan`,
+     * `planVersionId` and pending-version state consistent.
+     */
+    tenantSubscriptionWrite?: TenantSubscriptionWritePort;
+    /** Enables BundleVersion validity-window and auto-succession scenarios. */
+    bundleRepository?: BundleRepository;
+    /** Enables PlanVersion lifecycle, identity and validity-window scenarios. */
+    planRepository?: PlanRepository;
 }
 /** Fixture writers — implemented per adapter against its own schema. */
 interface ContractSeed {
@@ -58,6 +68,8 @@ interface PersistenceContractHarness {
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;
+    /** Project identity used by catalog lifecycle scenarios. */
+    projectKey: string;
     /** Builds the harness once for the whole suite. */
     create(): Promise<PersistenceContractHarness>;
 }
@@ -68,6 +80,7 @@ interface PersistenceAdapterContractOptions {
  * ```ts
  * persistenceAdapterContract({
  *     name: 'adapter-prisma @ postgres',
+ *     projectKey: 'my-app',
  *     create: () => createPrismaHarness(),
  * });
  * ```

package/dist/index.js

@@ -81,8 +81,259 @@ function persistenceAdapterContract(options) {
       });
       const live = await adapter.planVersionRepository.findLatestLive("PRO");
       assert.ok(live, "live version expected");
+      assert.equal(
+        live.planId,
+        "PRO",
+        "port-facing plan identity must remain the semantic plan key"
+      );
       assert.deepEqual(live.quotas, { users: 2 });
     });
+    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");
+        return;
+      }
+      const oldVersion = await seed.createPlanVersion({
+        planKey: "STARTER",
+        version: 1,
+        quotas: { users: 2 },
+        features: [],
+        published: true
+      });
+      const targetVersion = await seed.createPlanVersion({
+        planKey: "PRO",
+        version: 1,
+        quotas: { users: 20 },
+        features: ["PRO"],
+        published: true
+      });
+      await seed.createSubscription({
+        tenantId: "tenant-plan-change",
+        plan: "STARTER",
+        planVersionId: oldVersion.planVersionId
+      });
+      await adapter.tenantSubscriptionWrite.changePlanImmediate("tenant-plan-change", {
+        planId: "PRO",
+        cycle: "YEARLY",
+        periodStart: null,
+        periodEnd: null,
+        nextStatus: null
+      });
+      const changed = await adapter.subscriptionRepository.findByTenantId("tenant-plan-change");
+      assert.ok(changed, "changed subscription expected");
+      assert.equal(changed.plan, "PRO");
+      assert.equal(changed.planVersionId, targetVersion.planVersionId);
+      assert.equal(changed.planVersion.planId, "PRO");
+    });
+    test("onboarding selection rolls plan binding and promo write back together", async (t) => {
+      const { seed, adapter } = harness;
+      const writer = adapter.tenantSubscriptionWrite;
+      if (!writer?.applyOnboardingSelection) {
+        t.skip("adapter does not expose atomic onboarding writes");
+        return;
+      }
+      const redemptions = adapter.promoCodeRedemptionRepository;
+      if (!redemptions) {
+        t.skip("adapter provides no PromoCodeRedemptionRepository");
+        return;
+      }
+      const oldVersion = await seed.createPlanVersion({
+        planKey: "STARTER",
+        version: 1,
+        quotas: {},
+        features: [],
+        published: true
+      });
+      await seed.createPlanVersion({
+        planKey: "PRO",
+        version: 1,
+        quotas: {},
+        features: [],
+        published: true
+      });
+      const { subscriptionId } = await seed.createSubscription({
+        tenantId: "tenant-onboarding-rollback",
+        plan: "STARTER",
+        planVersionId: oldVersion.planVersionId
+      });
+      const { promoCodeId } = await seed.createPromoCode({
+        code: "ONBOARDING-ROLLBACK",
+        maxRedemptions: null
+      });
+      const startsAt = /* @__PURE__ */ new Date("2026-07-24T00:00:00.000Z");
+      await assert.rejects(
+        writer.applyOnboardingSelection(
+          "tenant-onboarding-rollback",
+          {
+            planId: "PRO",
+            cycle: "MONTHLY",
+            periodStart: null,
+            periodEnd: null,
+            nextStatus: null
+          },
+          async (tx, callbackSubscriptionId) => {
+            assert.equal(callbackSubscriptionId, subscriptionId);
+            await redemptions.create(
+              {
+                promoCodeId,
+                subscriptionId: callbackSubscriptionId,
+                tenantId: "tenant-onboarding-rollback",
+                appliedValueType: "PERCENT",
+                appliedValue: "10.00",
+                appliedDurationType: "ONCE",
+                appliedDurationValue: null,
+                startsAt,
+                endsAt: null
+              },
+              tx
+            );
+            assert.ok(
+              await redemptions.findBySubscription(callbackSubscriptionId, tx),
+              "promo write must be visible inside the onboarding transaction"
+            );
+            throw new Error("promo redemption failed");
+          }
+        ),
+        /promo redemption failed/
+      );
+      const unchanged = await adapter.subscriptionRepository.findByTenantId(
+        "tenant-onboarding-rollback"
+      );
+      assert.ok(unchanged, "subscription expected after rollback");
+      assert.equal(unchanged.plan, "STARTER");
+      assert.equal(unchanged.planVersionId, oldVersion.planVersionId);
+      assert.equal(unchanged.planVersion.planId, "STARTER");
+      assert.equal(
+        await redemptions.findBySubscription(subscriptionId),
+        null,
+        "promo callback write must be rolled back"
+      );
+    });
+    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");
+        return;
+      }
+      const plan = await repository.create({
+        projectKey: options.projectKey,
+        planKey: "STANDARD",
+        label: "Standard"
+      });
+      assert.equal(plan.projectKey, options.projectKey);
+      const firstDraft = await repository.createPlanVersionDraft({
+        planId: "STANDARD",
+        features: ["CORE"],
+        quotas: { users: 5 },
+        monthlyNet: "10.00",
+        yearlyNet: "100.00",
+        validFrom: "2026-01-01"
+      });
+      assert.equal(firstDraft.planId, "STANDARD");
+      const first = await repository.publishPlanVersionDraft(firstDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const secondDraft = await repository.createPlanVersionDraft({
+        planId: "STANDARD",
+        baseVersionId: first.id,
+        features: ["CORE", "PLUS"],
+        quotas: { users: 10 },
+        monthlyNet: "15.00",
+        yearlyNet: "150.00",
+        validFrom: "2026-03-01"
+      });
+      const second = await repository.publishPlanVersionDraft(secondDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const succeeded = await repository.findVersionById(first.id);
+      assert.ok(succeeded, "predecessor expected");
+      assert.ok(succeeded.supersededAt, "predecessor must be superseded");
+      assert.equal(succeeded.validUntil, "2026-02-28T00:00:00.000Z");
+      assert.equal(succeeded.planId, "STANDARD");
+      assert.equal(
+        (await repository.findActivePlanVersion(
+          "STANDARD",
+          /* @__PURE__ */ new Date("2026-02-28T23:59:59.999Z")
+        ))?.id,
+        first.id,
+        "validUntil is day-inclusive"
+      );
+      assert.equal(
+        (await repository.findActivePlanVersion(
+          "STANDARD",
+          /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z")
+        ))?.id,
+        second.id
+      );
+    });
+    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");
+        return;
+      }
+      const bundle = await repository.create({
+        projectKey: options.projectKey,
+        bundleKey: "REPORTING",
+        label: "Reporting"
+      });
+      assert.equal(bundle.projectKey, options.projectKey);
+      const firstDraft = await repository.createDraft({
+        bundleId: bundle.id,
+        features: ["REPORTS"],
+        quotas: {},
+        validFrom: "2026-01-01"
+      });
+      const first = await repository.publishDraft(firstDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const secondDraft = await repository.createDraft({
+        bundleId: bundle.id,
+        baseVersionId: first.id,
+        features: ["REPORTS", "EXPORTS"],
+        quotas: {},
+        validFrom: "2026-03-01"
+      });
+      const second = await repository.publishDraft(secondDraft.id, {
+        publishedByUserId: null,
+        publishedChanges: [],
+        nonRegressive: true,
+        validFrom: /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z"),
+        validUntil: null
+      });
+      const succeeded = await repository.findVersionById(first.id);
+      assert.ok(succeeded, "predecessor expected");
+      assert.ok(succeeded.supersededAt, "predecessor must be superseded");
+      assert.equal(succeeded.validUntil, "2026-02-28T00:00:00.000Z");
+      assert.equal(
+        (await repository.findActiveBundleVersion(
+          bundle.id,
+          /* @__PURE__ */ new Date("2026-02-28T23:59:59.999Z")
+        ))?.id,
+        first.id,
+        "validUntil is day-inclusive"
+      );
+      assert.equal(
+        (await repository.findActiveBundleVersion(
+          bundle.id,
+          /* @__PURE__ */ new Date("2026-03-01T00:00:00.000Z")
+        ))?.id,
+        second.id
+      );
+    });
     test("countByPlanVersionId counts current AND pending bindings in one query", async (t) => {
       const { seed, adapter } = harness;
       if (!adapter.subscriptionRepository.countByPlanVersionId) {
@@ -126,7 +377,9 @@ function persistenceAdapterContract(options) {
         return;
       }
       if (!adapter.promoCodeRedemptionRepository) {
-        t.skip("adapter provides no PromoCodeRedemptionRepository (needed as tx write probe)");
+        t.skip(
+          "adapter provides no PromoCodeRedemptionRepository (needed as tx write probe)"
+        );
         return;
       }
       const redemptions = adapter.promoCodeRedemptionRepository;
@@ -294,14 +547,24 @@ function persistenceAdapterContract(options) {
         return;
       }
       await adapter.audit.write({
-        actor: { userId: "admin-1", email: "ops@example.com", source: "cli", context: "host1" },
+        actor: {
+          userId: "admin-1",
+          email: "ops@example.com",
+          source: "cli",
+          context: "host1"
+        },
         entity: "Tenant",
         entityId: "tenant-a",
         action: "TENANT_SUSPEND",
         changes: { reason: "test" }
       });
       await adapter.audit.write({
-        actor: { userId: "admin-2", email: "web@example.com", source: "web", context: "sess9" },
+        actor: {
+          userId: "admin-2",
+          email: "web@example.com",
+          source: "web",
+          context: "sess9"
+        },
         entity: "PromoCode",
         entityId: "promo-1",
         action: "PROMO_CODE_CREATE"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/persistence-testing",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "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",
@@ -22,7 +22,7 @@
     "dist"
   ],
   "dependencies": {
-    "@saasicat/types": "^0.5.0"
+    "@saasicat/types": "^0.7.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",