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

package/README.md

@@ -1,5 +1,7 @@
 # @saasicat/persistence-testing
 
+## What this is
+
 The executable persistence contract for SaaSiCat adapters. One `node:test`
 suite that every adapter (Prisma and Drizzle ship today, TypeORM plugs into
 the same harness) must pass **against a real database** — this is what makes
@@ -14,17 +16,51 @@ Verified scenarios:
 - PlanVersion and BundleVersion validity windows with auto-succession
 - `countByPlanVersionId` counts current AND pending bindings in one query
 - transaction rollback discards writes
+- a contract written on a transaction is undone with it, and found by the offer it came from
+- a checkout offer is consumed once, whoever asks first, and a consume on a rolled-back transaction
+  leaves it open
 - `findByTenantIdLocked` serializes concurrent transactions (row lock)
 - concurrent `claimSlot` grants exactly `maxRedemptions` slots
 - claim / exhaust / release lifecycle
 - one promo redemption per subscription (unique guard)
 - audit write → query roundtrip incl. `actorTag` wildcard filters
 - MFA secret roundtrip
+- a gateway event is claimed once per account, a session is confirmed once however many events
+  report it, an event that changed nothing gives its session back while staying claimed itself, and
+  a claim rolled back with its transaction is free for the retry
+- a confirmed payment method replaces the one in use and keeps it as history, per subscriber
+- a change of payment method a tenant started is completed once, and only for the account, session
+  and subscriber it was started for
+- the applied settings: one row per installation, replaced only by a writer that
+  read its current fingerprint — so replicas starting together record one change,
+  concurrently — with the change and the record it supersedes landing together;
+  changes listed in the order they were recorded, acknowledged once
+
+Scenario groups gate on declared capabilities and provided slices. A group the
+capabilities rule out, such as the lock scenarios with `pessimisticLocking:
+false`, reports as **skipped with reason**. A group whose port or seed writer
+the harness does not provide **fails**, unless the adapter names it in `gaps` —
+then it reports as skipped. A gap named there that the harness does provide
+fails the suite, so the list stays true. A skipped scenario is easy to read
+past in a green run; a harness that forgot to wire a port would otherwise pass
+without checking it.
+
+The list describes the harness as it is built, not the adapter package. Where a
+port adds a member only under an option — `@saasicat/adapter-prisma`'s
+`validityWindows` and `atomicOnboardingSelection`, off by default for a 0.6
+schema — compute `gaps` from the same option rather than writing a constant, so
+the declaration moves when the schema does.
+
+## What this is not
 
-Scenario groups gate on declared capabilities and provided slices; a
-gated-off group reports as **skipped with reason** — coverage gaps stay
-visible, never silent. Roadmap scenarios (subscription contracts, reference
-migrations N→N+1) are registered as visible skips until the slices ship.
+Not a test framework and not a set of fixtures for your application. It is one
+executable contract: the suite an adapter must pass before it can claim to
+implement the ports.
+
+Not runnable without a database. The semantics it checks — row locks, rollback,
+atomic promo redemption, tenant isolation — are exactly the ones an in-memory
+double cannot have, so it needs a real PostgreSQL and says so when it does not
+find one.
 
 ## Usage
 
@@ -32,27 +68,46 @@ migrations N→N+1) are registered as visible skips until the slices ship.
 import { persistenceAdapterContract } from '@saasicat/persistence-testing';
 
 persistenceAdapterContract({
-    name: 'adapter-drizzle @ postgres',
-    projectKey: 'my-app',
+    name: 'my-adapter @ postgres',
     create: async () => ({
         adapter: {
             capabilities: { transactions: true, pessimisticLocking: true /* … */ },
             transactionRunner,
             subscriptionRepository,
             planVersionRepository,
-            promoCodeRepository, // optional slices activate more scenarios
+            planRepository,
+            bundleRepository,
+            subscriptionBundleRepository,
+            tenantSubscriptionWrite,
+            promoCodeRepository,
             promoCodeRedemptionRepository,
+            promoSubscriptionLookup,
             mfa,
             audit,
             auditQuery,
-            tenantSubscriptionWrite, // optional: enables atomic plan-binding scenarios
-            planRepository, // optional: enables plan lifecycle scenarios
-            bundleRepository, // optional: enables bundle validity scenarios
+            // Leave a part out and name it in `gaps` below; left out and not
+            // named, its scenarios fail.
+        },
+        seed: {
+            createPlanVersion,
+            createSubscription,
+            createBundleVersion,
+            clearBookingRequestDate,
+            createPromoCode,
         },
-        seed: { createPlanVersion, createSubscription, createPromoCode },
         reset: () => truncatePlatformTables(),
         close: () => pool.end(),
     }),
+    // The parts this adapter deliberately does not provide. A part named here
+    // that the harness does provide fails the suite as well.
+    gaps: [
+        'subscriptionContracts',
+        'subscribers',
+        'paymentEventLog',
+        'subscriberPaymentMethods',
+        'checkoutOffers',
+        'appliedSettings',
+    ],
 });
 ```
 
@@ -64,3 +119,9 @@ fixture writes are schema-specific. See
 In-memory fakes must not be used to "verify" an adapter — they cannot
 emulate lock semantics (declare `pessimisticLocking: false` and the lock
 scenarios gate off, visibly).
+
+## Next
+
+- [Ports and adapters](../../docs/explanation/adr/0007-ports-and-adapters.md) — what a port promises
+- [Test coverage](../../docs/explanation/test-coverage.md) — what this contract reaches, and what it
+  does not

package/dist/.build-stamp

@@ -1 +1 @@
-43f727faea9d157b3ac6d065838ecaa4035ae6ae630dbcc6a579fa6f2a3d5b74
+661fda5524fdc45e8824e920730ec225c532d6c4d61b964f3fccffb7bb62b15e