@saasicat/spec 1.0.0-rc.23 → 1.0.0-rc.24

package/acceptance/README.md

@@ -45,8 +45,7 @@ server, and verifies `setup` → `when` → `then` sequentially.
 | `promo/`        | Allow-zero-invoice false blocks a 100% discount                                                     | 🔴      |
 | `promo/`        | Code with `valueType=PERCENT, value>100` is rejected                                                | 🔴      |
 | `plan-version/` | Publish does not touch `Subscription.planVersionId` of existing tenants (P1 guarantee from SPEC §6) | 🟡 stub |
-| `plan-version/` | Regressive version requires tenant opt-in                                                           | 🔴      |
-| `plan-version/` | 6-week notification cron sends mail to affected subscriptions                                       | 🔴      |
+| `plan-version/` | A newer version reaches an existing subscription only as an offer it takes                          | 🔴      |
 | `tenant/`       | Suspend → 403 for tenant login + audit entry with reason                                            | 🟡 stub |
 | `tenant/`       | Suspend without MFA header → 401 MFA_REQUIRED                                                       | 🔴      |
 | `mfa/`          | TOTP verify with a good code → 200, with a bad one → 401                                            | 🟡 stub |

package/acceptance/plan-version/publish-does-not-touch-existing-contracts.yaml

@@ -3,8 +3,8 @@ description: |
     P1 guarantee from SPEC §6: When a new plan version is published,
     `Subscription.planVersionId` of the existing tenants is NOT touched.
     Only publishedAt of the new version + supersededAt of the old version
-    are written. Migration runs exclusively through the
-    notification + renewal cron with a 6-week lead time.
+    are written. A subscription moves to the new version only when the
+    subscriber takes it as an offer (SC-SUB-021); no renewal moves it.
 
     This is the core guarantee for grandfathering protection. If this
     test goes red, the implementation violates that contract protection.
@@ -43,13 +43,6 @@ then:
     - assertSubscriptionPriceMonthlyNet:
           tenantSlug: 'test-existing-contracts'
           value: 24.90
-    # pendingPlanVersion fields are not yet set (the notification cron
-    # has not run yet).
-    - assertSubscription:
-          tenantSlug: 'test-existing-contracts'
-          pendingPlanVersionId: null
-          pendingPlanVersionEffectiveAt: null
-
     # Catalog: the old version has supersededAt, the new one has publishedAt.
     - assertPlanVersion:
           planId: 'STANDARD'

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.23
+    version: 1.0.0-rc.24
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -352,11 +352,7 @@ paths:
                             properties:
                                 planId: { type: string }
                                 billingCycle: { type: string, enum: [MONTHLY, YEARLY] }
-                                customLimits:
-                                    type: object
-                                    additionalProperties:
-                                        type: integer
-                                        description: 'quotaKey → maxValue (-1 = unlimited)'
+                                customLimits: { $ref: '#/components/schemas/CustomLimits' }
                                 customMonthlyNet: { type: number, format: decimal }
                                 isPilot: { type: boolean }
                                 pilotEndsAt: { type: string, format: date-time }
@@ -1000,7 +996,7 @@ paths:
         parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
         post:
             tags: [catalog]
-            summary: Retire a plan version (endsAt; without a successor version)
+            summary: End a plan version's sale (endsAt; without a successor version)
             x-mfa-required: true
             requestBody:
                 required: true
@@ -1014,6 +1010,80 @@ paths:
                     }
             responses: { '200': { description: Terminated } }
 
+    # ── Retiring a version for running subscriptions (packages/nest/src/billing/version-retirement*) ──
+    #
+    # Served where the manifest carries the capability `planVersions.retire`. The
+    # subscriptions on a version no longer on sale move to a replacement on sale, each at
+    # the first end of a term at least three calendar months after the announcement, and
+    # may cancel without notice until then. Where the operator's terms are not confirmed to
+    # allow it, both routes refuse with `RETIREMENT_TERMS_NOT_CONFIRMED` before reading anything.
+
+    /catalog/plan-versions/{id}/retirement:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        get:
+            tags: [catalog]
+            summary: What retiring the version for its running subscriptions would do now
+            parameters:
+                - name: replacement
+                  in: query
+                  required: true
+                  description: The plan version the subscriptions continue on
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: >-
+                        Whom it reaches and when, whom it does not and why, and every blocker the
+                        announcement would refuse with
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/RetirementPreview' }
+                '404':
+                    description: Either version does not exist (`PLAN_VERSION_NOT_FOUND`)
+                '422':
+                    description: >-
+                        The terms are not confirmed (`RETIREMENT_TERMS_NOT_CONFIRMED`), or the
+                        replacement is the version itself (`RETIREMENT_REPLACEMENT_IS_RETIRED`)
+        post:
+            tags: [catalog]
+            summary: Announce the retirement to every subscription it reaches
+            description: >-
+                The announcement and one notice per subscription are recorded in one
+                transaction, then handed to the application's `SubscriptionNoticePort`; a notice
+                that cannot be sent now is sent by the next run. Audited as PLAN_VERSION_RETIRE.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/RetirementAnnouncement' }
+            responses:
+                '201':
+                    description: Announced
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/RetirementAnnounced' }
+                '409':
+                    description: >-
+                        The subscriptions it reaches are no longer the ones named
+                        (`RETIREMENT_PREVIEW_CHANGED`); the body carries the preview as it stands
+                '422':
+                    description: >-
+                        The first blocker the preview reports (`RETIREMENT_*`), with every blocker
+                        beside it
+
+    /catalog/version-retirements:
+        get:
+            tags: [catalog]
+            summary: Every retirement announced, the most recent first
+            responses:
+                '200':
+                    description: List
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items: { $ref: '#/components/schemas/VersionRetirement' }
+
     # ── Bundles ──
     /catalog/bundles:
         get:
@@ -1925,6 +1995,125 @@ components:
             properties:
                 endsAt: { type: string, description: 'ISO-8601; must lie in the future' }
 
+        RetiredVersionRef:
+            type: object
+            required: [planVersionId, planKey, version]
+            properties:
+                planVersionId: { type: string }
+                planKey: { type: string }
+                version: { type: integer }
+
+        RetirementSide:
+            description: 'A version as the subscribers compare it; a price of null is a rhythm it is not sold in'
+            allOf:
+                - $ref: '#/components/schemas/RetiredVersionRef'
+                - type: object
+                  required: [features, quotas, monthlyNet, yearlyNet, validUntil, endsAt]
+                  properties:
+                      features: { type: array, items: { type: string } }
+                      quotas: { type: object, additionalProperties: { type: number } }
+                      monthlyNet: { type: [number, 'null'] }
+                      yearlyNet: { type: [number, 'null'] }
+                      validUntil: { type: [string, 'null'] }
+                      endsAt: { type: [string, 'null'] }
+
+        RetirementPreview:
+            type: object
+            required: [retired, replacement, changes, asOf, reached, skipped, blockers]
+            properties:
+                retired: { $ref: '#/components/schemas/RetirementSide' }
+                replacement: { $ref: '#/components/schemas/RetirementSide' }
+                changes:
+                    type: array
+                    description: 'Every difference, retired to replacement, as the catalogue diff states it'
+                    items: { type: object }
+                asOf: { type: string, description: 'ISO-8601: the moment it is computed for' }
+                reached:
+                    type: array
+                    items:
+                        type: object
+                        required:
+                            [
+                                tenantId,
+                                subscriptionId,
+                                status,
+                                billingCycle,
+                                effectiveAt,
+                                lastDayToCancel,
+                                reachedRecently,
+                            ]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            status: { type: string }
+                            billingCycle: { type: string }
+                            effectiveAt: { type: string, description: 'ISO-8601: a term end' }
+                            lastDayToCancel:
+                                { type: string, description: 'ISO date, UTC: the day before' }
+                            reachedRecently:
+                                {
+                                    type: boolean,
+                                    description: 'Reached by a retirement within twelve months',
+                                }
+                skipped:
+                    type: array
+                    items:
+                        type: object
+                        required: [tenantId, subscriptionId, reason]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            reason:
+                                {
+                                    type: string,
+                                    enum:
+                                        [
+                                            ended,
+                                            cancelled-before,
+                                            changes-before,
+                                            no-term,
+                                            already-told,
+                                        ],
+                                }
+                blockers:
+                    type: array
+                    description: 'Empty where it may be announced as it stands'
+                    items:
+                        type: object
+                        required: [code, message, params]
+                        properties:
+                            code: { type: string, description: 'RETIREMENT_*' }
+                            message: { type: string }
+                            params: { type: object }
+
+        RetirementAnnouncement:
+            type: object
+            required: [replacementPlanVersionId, subscriptionIds]
+            properties:
+                replacementPlanVersionId: { type: string, format: uuid }
+                subscriptionIds:
+                    type: array
+                    description: 'The subscriptions the operator was shown in the preview'
+                    items: { type: string }
+
+        VersionRetirement:
+            type: object
+            required: [id, retired, replacement, announcedAt, announcedBy]
+            properties:
+                id: { type: string }
+                retired: { $ref: '#/components/schemas/RetiredVersionRef' }
+                replacement: { $ref: '#/components/schemas/RetiredVersionRef' }
+                announcedAt: { type: string }
+                announcedBy: { type: string }
+
+        RetirementAnnounced:
+            type: object
+            required: [retirement, told, failed]
+            properties:
+                retirement: { $ref: '#/components/schemas/VersionRetirement' }
+                told: { type: integer, description: 'Notices sent at once' }
+                failed: { type: integer, description: 'Notices the next run sends' }
+
         CatalogMarketingProjectionUpdate:
             type: object
             description: 'Partial update of a marketing projection'
@@ -2169,6 +2358,24 @@ components:
                 sendWelcomeMail: { type: boolean, default: true }
 
         # ────────── Subscription ──────────
+        CustomLimits:
+            type: object
+            description: >-
+                A tenant's own limits beside its plan — a negotiated contract, a pilot
+                (`CustomLimits` in @saasicat/core). A quota replaces the plan's value for that
+                quota; a feature is added to the plan's. Stored as JSON in
+                `subscriptions.customLimits`; a stored value in any other shape is not applied.
+            additionalProperties: false
+            properties:
+                quotas:
+                    type: object
+                    additionalProperties:
+                        type: integer
+                        minimum: -1
+                        description: 'quotaKey → maxValue (-1 = unlimited)'
+                features:
+                    type: array
+                    items: { type: string }
         SubscriptionDetail:
             type: object
             properties:
@@ -2181,9 +2388,7 @@ components:
                 canceledAt: { type: string, format: date-time }
                 isPilot: { type: boolean }
                 pilotEndsAt: { type: string, format: date-time }
-                customLimits:
-                    type: object
-                    additionalProperties: { type: integer }
+                customLimits: { $ref: '#/components/schemas/CustomLimits' }
                 customMonthlyNet: { type: number, format: decimal, nullable: true }
                 effectiveLimits:
                     type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/spec",
-  "version": "1.0.0-rc.23",
+  "version": "1.0.0-rc.24",
   "description": "Language-neutral spec of the SaaS platform: JSON Schemas, OpenAPI contract, Prisma fragments, acceptance scenarios.",
   "type": "module",
   "main": "./index.cjs",

package/prisma-fragments/01-subscription.prisma

@@ -89,20 +89,10 @@ model Subscription {
     // which is the old behaviour for one step and correct for that step.
     billingAnchorDay Int?
 
-    // Plan versioning — binds to a published PlanVersion.
-    // `pendingPlanVersion*` concern a version change within the
-    // same plan; `pendingPlan` the change to a different plan. Both
-    // can coexist.
-    //
-    // Every subscription binds a concrete published PlanVersion.
-    planVersionId                      String
-    pendingPlanVersionId               String?
-    pendingPlanVersionEffectiveAt      DateTime?
-    pendingPlanVersionAccepted         Boolean   @default(false)
-    pendingPlanVersionAcceptedAt       DateTime?
-    pendingPlanVersionAcceptedByUserId String?
-    pendingPlanVersionNotifiedAt       DateTime?
-    pendingPlanVersionReminderSentAt   DateTime?
+    // Plan versioning — binds to a published PlanVersion, and keeps it across
+    // renewals: a newer version reaches the subscription as an offer, and a
+    // switch to it is a change like any other (`pendingPlan` below).
+    planVersionId String
 
     // Trial / scheduled plan changes
     trialEntitlementPlan String? // Default entitlement during TRIAL
@@ -110,10 +100,13 @@ model Subscription {
     pendingPlan          String? // Downgrade/change at period end
     pendingBillingCycle  BillingCycle?
     pendingEffectiveAt   DateTime?
+    // The version of `pendingPlan` the change was quoted at, bound when it
+    // comes due; null where the plan stays or nothing reads versions.
+    pendingChangeVersionId String?
 
     // Special contract / pilot — audit (who/when) lives in the AuditLog.
     customMonthlyNet Decimal?  @db.Decimal(10, 2)
-    customLimits     Json? // { maxUsers?, maxVehicles?, maxStorageGb?, features?: string[] }
+    customLimits     Json? // CustomLimits (@saasicat/core): { quotas?: { <quotaKey>: number }, features?: string[] }
     customNote       String?
     isPilot          Boolean   @default(false)
     pilotEndsAt      DateTime?
@@ -134,13 +127,13 @@ model Subscription {
     // tenant             Tenant                    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
     promoRedemption     PromoCodeRedemption? // see 02-promo-code.prisma
     planVersion         PlanVersion                 @relation("SubscriptionPlanVersion", fields: [planVersionId], references: [id])
-    pendingPlanVersion  PlanVersion?                @relation("SubscriptionPendingPlanVersion", fields: [pendingPlanVersionId], references: [id])
+    pendingChangeVersion PlanVersion?               @relation("SubscriptionPendingChangeVersion", fields: [pendingChangeVersionId], references: [id], onDelete: Restrict)
     // Standalone add-on bookings (see 11-subscription-bundle.prisma).
     bundles             SubscriptionBundle[]
 
     @@index([tenantId])
     @@index([planVersionId])
-    @@index([pendingPlanVersionId])
+    @@index([pendingChangeVersionId])
     @@index([currentPeriodEnd])
     @@map("subscriptions")
 }

package/prisma-fragments/03-plan-versions.prisma

@@ -90,7 +90,7 @@ model PlanVersion {
     baseVersion          PlanVersion?   @relation("PlanVersionLineage", fields: [baseVersionId], references: [id])
     derivedVersions      PlanVersion[]  @relation("PlanVersionLineage")
     subscriptionsCurrent Subscription[] @relation("SubscriptionPlanVersion")
-    subscriptionsPending Subscription[] @relation("SubscriptionPendingPlanVersion")
+    subscriptionsPendingChange Subscription[] @relation("SubscriptionPendingChangeVersion")
 
     @@unique([planId, version])
     @@index([planId, supersededAt])

package/prisma-fragments/04-audit-log.prisma

@@ -21,7 +21,8 @@ model AuditLog {
     entityId  String
     action    String // SCREAMING_SNAKE_CASE; e.g. "PROMO_CODE_REDEEM"
     changes   Json? // { field: { old: …, new: … } }
-    // Origin marker 'web:<email>:<sessionId>' | 'cli:<email>:<host>' — see
+    // Origin marker 'web:<email>:<sessionId>' | 'cli:<email>:<host>' |
+    // 'job:platform:<job>' — see
     // audit-event.schema.json `actorTag`. Queryable with a trailing wildcard
     // ('cli:*') via AuditQueryPort.
     actorTag  String?

package/prisma-fragments/10-super-admin.prisma

@@ -42,7 +42,7 @@ model SuperAdminMfa {
     // admins live exclusively in `super_admin_users` may add the relation:
     // user SuperAdminUser @relation(fields: [userId], references: [id], onDelete: Cascade)
     userId    String    @id
-    secret    String? // TOTP secret; null after reset
+    secret    String? // TOTP secret, sealed by the installation's SecretSealer; null after reset
     enabledAt DateTime? // set when a secret is stored, null after reset
 
     updatedAt DateTime @updatedAt

package/prisma-fragments/17-subscription-notice.prisma

@@ -0,0 +1,55 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriptionNotice
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per notice a subscriber is due: that a newer version of their plan is
+// offered to them, or that the version they are on is being retired — each told
+// once. The platform records a notice before it has the
+// application send it and confirms it after, so the unique key below is what
+// makes a notice once — however many instances run the job — and the row is
+// what shows later when it went out, to whom and how.
+//
+// A run takes a notice on by setting `claimedAt`, and lets it go again where the
+// sending failed; a claim older than a quarter of an hour counts as abandoned.
+// `deliveredAt`, `recipients` and `channel` are set together, when the
+// application confirms it sent the notice.
+//
+// The record is evidence of what a subscriber was told, and outlives the
+// subscription like the subscriber's account does (ADR 0012): `tenantId` and
+// `subscriptionId` are kept as values, not as keys.
+//
+// `kind` is text holding a closed set: version-offered, version-retired,
+// version-retirement-reminder.
+//
+// Optional: adopt it where `tenantBilling.versionNotices` is configured, which
+// refuses to start without a place to keep notices; a retirement needs it too.
+//
+// Contract: @saasicat/core (SubscriptionNoticeRepository).
+
+model SubscriptionNotice {
+    id             String @id @default(uuid())
+    tenantId       String
+    subscriptionId String
+
+    kind    String
+    // What the notice is about — for version-offered, the id of the version
+    // offered; for version-retired and version-retirement-reminder, the id of
+    // the version retired, so a subscription is told of a version's retirement
+    // once and reminded of it once.
+    subject String
+    // The notice as it was last handed to the application.
+    content Json
+
+    createdAt   DateTime  @default(now())
+    claimedAt   DateTime?
+    deliveredAt DateTime?
+    // Who it went to and how, in the application's own terms.
+    recipients  Json?
+    channel     String?
+
+    @@unique([subscriptionId, kind, subject])
+    @@index([kind, subject])
+    @@map("subscription_notices")
+}

package/prisma-fragments/18-version-retirement.prisma

@@ -0,0 +1,44 @@
+// =============================================================================
+// SaaS platform Prisma fragment: VersionRetirement
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per retirement an operator announces: a plan version ended for the
+// subscriptions already on it, with the version they continue on. It is the one
+// exception to a subscription keeping its version, so it is kept as evidence of
+// what was announced, when and by whom.
+//
+// What it means for each subscription it reaches — the date it takes effect,
+// the last day to cancel without notice, and to whom and how that was told — is
+// a `subscription_notices` row of kind version-retired, written in the same
+// transaction: its subject is the retired version, its content names this
+// row's id as `retirementId`.
+//
+// The versions are kept as values, not as keys: the record outlives the
+// catalogue entries it names, as the notices do (ADR 0012).
+//
+// Optional: adopt it where an operator may retire versions
+// (`tenantBilling.orderlyRetirement` in config/saas.yaml), which refuses to
+// start without a place to keep announcements.
+//
+// Contract: @saasicat/core (VersionRetirementRepository).
+
+model VersionRetirement {
+    id String @id @default(uuid())
+
+    retiredPlanVersionId String
+    retiredPlanKey       String
+    retiredVersion       Int
+
+    replacementPlanVersionId String
+    replacementPlanKey       String
+    replacementVersion       Int
+
+    announcedAt DateTime @default(now())
+    // Who announced it — an actor tag, as the audit log writes it.
+    announcedBy String
+
+    @@index([retiredPlanVersionId])
+    @@map("version_retirements")
+}

package/prisma-fragments/README.md

@@ -46,6 +46,7 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 | [`14-payments.prisma`](14-payments.prisma)                           | `SubscriberPaymentMethod`, `SubscriberPaymentMethodSetup`, `PaymentEventLog`          |
 | [`15-subscriber-ledger.prisma`](15-subscriber-ledger.prisma)         | `SubscriberLedgerEntry`                                                               |
 | [`16-maintenance-window.prisma`](16-maintenance-window.prisma)       | `MaintenanceWindow`                                                                   |
+| [`17-subscription-notice.prisma`](17-subscription-notice.prisma)     | `SubscriptionNotice`                                                                  |
 
 ## How the consumer uses the fragments
 

package/schemas/audit-event.schema.json

@@ -38,7 +38,7 @@
         },
         "actorTag": {
             "type": ["string", "null"],
-            "description": "Origin marker. Format: 'web:<email>:<sessionId>' or 'cli:<email>:<host>'."
+            "description": "Origin marker. Format: 'web:<email>:<sessionId>', 'cli:<email>:<host>', or 'job:platform:<job>' for a platform job acting on its own schedule."
         },
         "ipAddress": { "type": ["string", "null"] },
         "userAgent": { "type": ["string", "null"] },
@@ -48,7 +48,7 @@
     "$defs": {
         "ActorTagPattern": {
             "type": "string",
-            "pattern": "^(web|cli):[^:]+:[^:]+$",
+            "pattern": "^(web|cli|job):[^:]+:[^:]+$",
             "description": "Mandatory format for actorTag."
         },
 

package/schemas/plan-catalog.schema.json

@@ -59,7 +59,7 @@
             "type": "object",
             "additionalProperties": false,
             "description": "Commercial settings for the tenant-facing self-service routes. Required, and required member by member: every one of these has a money or a legal consequence, and a value left out is still a decision — just an invisible one. The file is read at boot, so a change lands on the next restart.",
-            "required": ["cancellationNoticeDays", "selfServiceBlockedPlans"],
+            "required": ["cancellationNoticeDays", "selfServiceBlockedPlans", "orderlyRetirement"],
             "properties": {
                 "cancellationNoticeDays": {
                     "type": "object",
@@ -100,6 +100,18 @@
                             "description": "Plan IDs that may not be left via self-service — typically an active special contract, whose change goes through sales."
                         }
                     }
+                },
+                "orderlyRetirement": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "description": "Whether the operator may retire a plan version for the subscriptions already on it — end it, or raise its price, with three calendar months of notice and a named replacement. It reaches contracts customers have already made, so it rests on a clause in the operator's terms, legally reviewed; without one only the rule that a subscription keeps its version applies.",
+                    "required": ["termsConfirmed"],
+                    "properties": {
+                        "termsConfirmed": {
+                            "type": "boolean",
+                            "description": "true states that the operator's terms carry that clause. Only then does the admin offer a retirement and the server accept one; false refuses it."
+                        }
+                    }
                 }
             }
         },

package/sql/1.0-a-newer-version-is-only-offered.postgres.sql

@@ -0,0 +1,33 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a newer version is only offered.
+-- =============================================================================
+--
+-- A subscription keeps the plan version it is bound to, and a newer one reaches
+-- it as an offer beside the plan (`SC-SUB-020`); taking it is a change like any
+-- other. The pending version — announced, reminded about, accepted and rolled
+-- forward at the end of the term — is gone, and so are the seven columns that
+-- carried it. Dropping them discards every pending version still recorded,
+-- accepted ones included: a newer version then reaches the subscription as an
+-- offer.
+--
+-- Run it the same way as the other files in this directory, before `db push`
+-- where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-newer-version-is-only-offered.postgres.sql
+--
+-- Run it once nothing reads the columns any more: no running version of the
+-- application, and no job of your own — a notice or renewal job that set or
+-- rolled forward a pending version — still uses them. A column's index and its
+-- foreign key go with it.
+--
+-- Safe to run again, and on a database without a subscriptions table: every
+-- column is dropped only where it exists.
+
+ALTER TABLE IF EXISTS "subscriptions"
+    DROP COLUMN IF EXISTS "pendingPlanVersionId",
+    DROP COLUMN IF EXISTS "pendingPlanVersionEffectiveAt",
+    DROP COLUMN IF EXISTS "pendingPlanVersionAccepted",
+    DROP COLUMN IF EXISTS "pendingPlanVersionAcceptedAt",
+    DROP COLUMN IF EXISTS "pendingPlanVersionAcceptedByUserId",
+    DROP COLUMN IF EXISTS "pendingPlanVersionNotifiedAt",
+    DROP COLUMN IF EXISTS "pendingPlanVersionReminderSentAt";

package/sql/1.0-a-retirement-is-announced.postgres.sql

@@ -0,0 +1,43 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a retirement is announced.
+-- =============================================================================
+--
+-- One table, additive: `version_retirements` keeps every retirement an operator
+-- announces — a plan version ended for the subscriptions already on it, the
+-- version they continue on, when and by whom. What it means for each
+-- subscription is a `subscription_notices` row of kind `version-retired`, which
+-- `1.0-a-subscriber-is-told-once.postgres.sql` creates.
+--
+-- Run it the same way as the other files in this directory, before `db push`
+-- where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-retirement-is-announced.postgres.sql
+--
+-- The record outlives the catalogue entries it names, so the versions are kept
+-- as values and the table has no foreign key: nothing else has to exist for it
+-- to be created.
+--
+-- Safe to run again: the table and its index are created only where they are
+-- missing. On a database created from `reference-schema.postgres.sql` the whole
+-- file does nothing at all.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS "version_retirements" (
+    "id" TEXT NOT NULL,
+    "retiredPlanVersionId" TEXT NOT NULL,
+    "retiredPlanKey" TEXT NOT NULL,
+    "retiredVersion" INTEGER NOT NULL,
+    "replacementPlanVersionId" TEXT NOT NULL,
+    "replacementPlanKey" TEXT NOT NULL,
+    "replacementVersion" INTEGER NOT NULL,
+    "announcedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "announcedBy" TEXT NOT NULL,
+
+    CONSTRAINT "version_retirements_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "version_retirements_retiredPlanVersionId_idx"
+    ON "version_retirements"("retiredPlanVersionId");
+
+COMMIT;

package/sql/1.0-a-scheduled-change-keeps-its-quoted-version.postgres.sql

@@ -0,0 +1,129 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a scheduled change to another plan binds the version it was
+-- quoted at.
+-- =============================================================================
+--
+-- `subscriptions` gains "pendingChangeVersionId": the version of "pendingPlan"
+-- the plan-change preview showed when the change was scheduled. When the change
+-- comes due, the platform binds that version rather than whichever is in effect
+-- that day, so a version published in between does not reach the customer by a
+-- change they already agreed to. Run it BEFORE `db push`, the same way as the
+-- other files in this directory:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-scheduled-change-keeps-its-quoted-version.postgres.sql
+--
+-- What happens to a change scheduled before this file. The version it was
+-- shown was never recorded, so the one live and in effect now stands for it:
+-- the newest published, not superseded, not ended, and — on a schema with
+-- validity windows — already begun. A version published ahead of its date is
+-- left out; the change then binds the version in effect when it comes due, as
+-- it did before this file. A change that stays on its plan is left empty: it keeps the
+-- version bound, whatever that is by the day it comes due. A plan with no live
+-- version is left empty too, and binds the version in effect when it comes due.
+--
+-- The plan is found the way the Prisma adapter's `planBinding` stores it: by
+-- its key in "plan_versions"."planId" (`legacy-plan-key`), or — where the
+-- column holds the plan's row id (`normalized-plan-id`) — through the row of
+-- "plans" that carries the key. The fragment generates that row id as a UUID,
+-- so it does not coincide with a key and at most one of the two matches. The
+-- second is left out where "plans" has no "planKey", which includes a schema
+-- with no "plans" at all.
+--
+-- Safe to run again: the column, its index and its foreign key are added only
+-- where they are missing, and the backfill runs only in the run that adds the
+-- column. A second run therefore finds the column and changes nothing — it
+-- does not pin a version published since the first run to a change scheduled
+-- before it. On a database created from `reference-schema.postgres.sql` the
+-- whole file does nothing: the column is already there.
+
+BEGIN;
+
+DO $$
+BEGIN
+    IF to_regclass('subscriptions') IS NULL OR to_regclass('plan_versions') IS NULL THEN
+        RAISE NOTICE 'subscriptions or plan_versions is not present — nothing to migrate.';
+        RETURN;  -- an installation that never adopted these fragments
+    END IF;
+
+    IF NOT EXISTS (
+        SELECT 1
+        FROM information_schema.columns
+        WHERE table_schema = current_schema()
+          AND table_name = 'subscriptions'
+          AND column_name = 'pendingChangeVersionId'
+    ) THEN
+        ALTER TABLE "subscriptions" ADD COLUMN "pendingChangeVersionId" TEXT;
+
+        -- Live and in effect: published, not superseded, and — where the
+        -- schema has the columns — not ended and already begun. An ended
+        -- version takes no new bookings, and one published ahead of its date
+        -- is not the one in effect. Each clause is added only where its column
+        -- exists; a schema from before it ends and delays nothing.
+        EXECUTE format(
+            $backfill$
+            UPDATE "subscriptions" AS s
+            SET "pendingChangeVersionId" = (
+                SELECT v."id"
+                FROM "plan_versions" AS v
+                WHERE (v."planId" = s."pendingPlan" %s)
+                  AND v."publishedAt" IS NOT NULL
+                  AND v."supersededAt" IS NULL
+                  %s
+                  %s
+                ORDER BY v."version" DESC
+                LIMIT 1
+            )
+            WHERE s."pendingPlan" IS NOT NULL
+              AND s."pendingPlan" <> s."plan"
+            $backfill$,
+            CASE
+                WHEN EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_schema = current_schema()
+                      AND table_name = 'plans'
+                      AND column_name = 'planKey'
+                )
+                THEN 'OR v."planId" IN (SELECT p."id" FROM "plans" AS p WHERE p."planKey" = s."pendingPlan")'
+                ELSE ''
+            END,
+            CASE
+                WHEN EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_schema = current_schema()
+                      AND table_name = 'plan_versions'
+                      AND column_name = 'endsAt'
+                )
+                THEN 'AND (v."endsAt" IS NULL OR v."endsAt" > NOW())'
+                ELSE ''
+            END,
+            CASE
+                WHEN EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_schema = current_schema()
+                      AND table_name = 'plan_versions'
+                      AND column_name = 'validFrom'
+                )
+                THEN 'AND (v."validFrom" IS NULL OR v."validFrom" <= NOW())'
+                ELSE ''
+            END
+        );
+    END IF;
+
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'subscriptions_pendingChangeVersionId_fkey'
+    ) THEN
+        ALTER TABLE "subscriptions"
+            ADD CONSTRAINT "subscriptions_pendingChangeVersionId_fkey"
+            FOREIGN KEY ("pendingChangeVersionId") REFERENCES "plan_versions"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+
+    CREATE INDEX IF NOT EXISTS "subscriptions_pendingChangeVersionId_idx"
+        ON "subscriptions"("pendingChangeVersionId");
+END
+$$;
+
+COMMIT;

package/sql/1.0-a-subscriber-is-told-once.postgres.sql

@@ -0,0 +1,48 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a subscriber is told once.
+-- =============================================================================
+--
+-- One table, additive: `subscription_notices` keeps the record of every notice
+-- a subscriber is due — that a newer version of their plan is offered to them —
+-- with when it went out, to whom and how. The platform writes it where
+-- `tenantBilling.versionNotices` is turned on, and the unique key is what makes
+-- each notice once rather than once per run.
+--
+-- Run it the same way as the other files in this directory, before `db push`
+-- where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-subscriber-is-told-once.postgres.sql
+--
+-- The record outlives the subscription, as the subscriber's account does, so
+-- the table keeps the tenant and the subscription as values and has no foreign
+-- key: nothing else has to exist for it to be created.
+--
+-- Safe to run again: the table and both indexes are created only where they are
+-- missing. On a database created from `reference-schema.postgres.sql` the whole
+-- file does nothing at all.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS "subscription_notices" (
+    "id" TEXT NOT NULL,
+    "tenantId" TEXT NOT NULL,
+    "subscriptionId" TEXT NOT NULL,
+    "kind" TEXT NOT NULL,
+    "subject" TEXT NOT NULL,
+    "content" JSONB NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "claimedAt" TIMESTAMP(3),
+    "deliveredAt" TIMESTAMP(3),
+    "recipients" JSONB,
+    "channel" TEXT,
+
+    CONSTRAINT "subscription_notices_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "subscription_notices_kind_subject_idx"
+    ON "subscription_notices"("kind", "subject");
+
+CREATE UNIQUE INDEX IF NOT EXISTS "subscription_notices_subscriptionId_kind_subject_key"
+    ON "subscription_notices"("subscriptionId", "kind", "subject");
+
+COMMIT;

package/sql/reference-schema.postgres.sql

@@ -19,6 +19,8 @@
 --   prisma-fragments/14-payments.prisma
 --   prisma-fragments/15-subscriber-ledger.prisma
 --   prisma-fragments/16-maintenance-window.prisma
+--   prisma-fragments/17-subscription-notice.prisma
+--   prisma-fragments/18-version-retirement.prisma
 -- plus the normative constraints from sql/constraints.postgres.sql.
 -- Do not edit by hand — change the fragments/constraints and regenerate.
 
@@ -68,18 +70,12 @@ CREATE TABLE "subscriptions" (
     "minimumTermUntil" TIMESTAMP(3),
     "billingAnchorDay" INTEGER,
     "planVersionId" TEXT NOT NULL,
-    "pendingPlanVersionId" TEXT,
-    "pendingPlanVersionEffectiveAt" TIMESTAMP(3),
-    "pendingPlanVersionAccepted" BOOLEAN NOT NULL DEFAULT false,
-    "pendingPlanVersionAcceptedAt" TIMESTAMP(3),
-    "pendingPlanVersionAcceptedByUserId" TEXT,
-    "pendingPlanVersionNotifiedAt" TIMESTAMP(3),
-    "pendingPlanVersionReminderSentAt" TIMESTAMP(3),
     "trialEntitlementPlan" TEXT,
     "postTrialPlan" TEXT,
     "pendingPlan" TEXT,
     "pendingBillingCycle" "BillingCycle",
     "pendingEffectiveAt" TIMESTAMP(3),
+    "pendingChangeVersionId" TEXT,
     "customMonthlyNet" DECIMAL(10,2),
     "customLimits" JSONB,
     "customNote" TEXT,
@@ -723,6 +719,38 @@ CREATE TABLE "maintenance_windows" (
     CONSTRAINT "maintenance_windows_pkey" PRIMARY KEY ("id")
 );
 
+-- CreateTable
+CREATE TABLE "subscription_notices" (
+    "id" TEXT NOT NULL,
+    "tenantId" TEXT NOT NULL,
+    "subscriptionId" TEXT NOT NULL,
+    "kind" TEXT NOT NULL,
+    "subject" TEXT NOT NULL,
+    "content" JSONB NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "claimedAt" TIMESTAMP(3),
+    "deliveredAt" TIMESTAMP(3),
+    "recipients" JSONB,
+    "channel" TEXT,
+
+    CONSTRAINT "subscription_notices_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "version_retirements" (
+    "id" TEXT NOT NULL,
+    "retiredPlanVersionId" TEXT NOT NULL,
+    "retiredPlanKey" TEXT NOT NULL,
+    "retiredVersion" INTEGER NOT NULL,
+    "replacementPlanVersionId" TEXT NOT NULL,
+    "replacementPlanKey" TEXT NOT NULL,
+    "replacementVersion" INTEGER NOT NULL,
+    "announcedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "announcedBy" TEXT NOT NULL,
+
+    CONSTRAINT "version_retirements_pkey" PRIMARY KEY ("id")
+);
+
 -- CreateIndex
 CREATE UNIQUE INDEX "subscriptions_tenantId_key" ON "subscriptions"("tenantId");
 
@@ -733,7 +761,7 @@ CREATE INDEX "subscriptions_tenantId_idx" ON "subscriptions"("tenantId");
 CREATE INDEX "subscriptions_planVersionId_idx" ON "subscriptions"("planVersionId");
 
 -- CreateIndex
-CREATE INDEX "subscriptions_pendingPlanVersionId_idx" ON "subscriptions"("pendingPlanVersionId");
+CREATE INDEX "subscriptions_pendingChangeVersionId_idx" ON "subscriptions"("pendingChangeVersionId");
 
 -- CreateIndex
 CREATE INDEX "subscriptions_currentPeriodEnd_idx" ON "subscriptions"("currentPeriodEnd");
@@ -960,11 +988,20 @@ CREATE UNIQUE INDEX "subscriber_ledger_entries_subscriptionId_source_sourceRef_p
 -- CreateIndex
 CREATE INDEX "maintenance_windows_createdAt_idx" ON "maintenance_windows"("createdAt");
 
+-- CreateIndex
+CREATE INDEX "subscription_notices_kind_subject_idx" ON "subscription_notices"("kind", "subject");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "subscription_notices_subscriptionId_kind_subject_key" ON "subscription_notices"("subscriptionId", "kind", "subject");
+
+-- CreateIndex
+CREATE INDEX "version_retirements_retiredPlanVersionId_idx" ON "version_retirements"("retiredPlanVersionId");
+
 -- AddForeignKey
 ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_planVersionId_fkey" FOREIGN KEY ("planVersionId") REFERENCES "plan_versions"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
 -- AddForeignKey
-ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_pendingPlanVersionId_fkey" FOREIGN KEY ("pendingPlanVersionId") REFERENCES "plan_versions"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_pendingChangeVersionId_fkey" FOREIGN KEY ("pendingChangeVersionId") REFERENCES "plan_versions"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
 -- AddForeignKey
 ALTER TABLE "promo_code_redemptions" ADD CONSTRAINT "promo_code_redemptions_promoCodeId_fkey" FOREIGN KEY ("promoCodeId") REFERENCES "promo_codes"("id") ON DELETE RESTRICT ON UPDATE CASCADE;