@saasicat/spec 1.0.0-rc.22 → 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.22
+    version: 1.0.0-rc.24
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -58,6 +58,7 @@ tags:
     - name: manifest
     - name: catalog
     - name: settings
+    - name: maintenance
 
 security:
     - bearerAuth: []
@@ -351,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 }
@@ -999,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
@@ -1013,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:
@@ -1406,6 +1477,146 @@ paths:
                 '404':
                     description: No recorded change has this id (`SETTINGS_CHANGE_NOT_FOUND`)
 
+    # ── Maintenance windows (MaintenanceModule, packages/nest/src/maintenance/*) ──
+    #
+    # An operator announces a window, locks the application for a deploy and
+    # unlocks it. The announced times are what tenants are told; they never
+    # start or end the lock. These routes stay reachable while the lock holds.
+    # The status a tenant's page reads is `GET /public/maintenance`, outside
+    # this document's prefix.
+
+    /maintenance:
+        get:
+            tags: [maintenance]
+            summary: The open window, if any, and the ones before it
+            responses:
+                '200':
+                    description: The overview, read fresh
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceOverview' }
+        post:
+            tags: [maintenance]
+            summary: Announce a window to the tenants
+            description: >-
+                Locks nobody out. Refused while another window is open. The application hears
+                of it through its `MaintenanceNotificationPort`, where it binds one. Audited as
+                MAINTENANCE_WINDOW_ANNOUNCE.
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/MaintenanceAnnouncement' }
+            responses:
+                '201':
+                    description: The window, announced
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                '400':
+                    description: >-
+                        A time without its zone (`MAINTENANCE_TIME_INVALID`), an end not after the
+                        start (`MAINTENANCE_WINDOW_END_NOT_AFTER_START`) or in the past
+                        (`MAINTENANCE_WINDOW_END_IN_PAST`), a message too long
+                        (`MAINTENANCE_MESSAGE_TOO_LONG`)
+                '409':
+                    description: Another window is open (`MAINTENANCE_WINDOW_ALREADY_OPEN`)
+
+    /maintenance/{id}:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        patch:
+            tags: [maintenance]
+            summary: Move the open window, or change its message
+            description: >-
+                What is left out stays; `message: null` takes the message away. A locked window
+                keeps its start and may still move its expected end. Audited as
+                MAINTENANCE_WINDOW_RESCHEDULE.
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/MaintenanceRevision' }
+            responses:
+                '200':
+                    description: The window as it now stands
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                '400':
+                    description: As for announcing
+                '404':
+                    description: No open window has this id (`MAINTENANCE_WINDOW_NOT_OPEN`)
+                '409':
+                    description: The window is locked and its start cannot move (`MAINTENANCE_WINDOW_LOCKED`)
+
+    /maintenance/{id}/cancel:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        post:
+            tags: [maintenance]
+            summary: Call off an announced window
+            description: Audited as MAINTENANCE_WINDOW_CANCEL. A locked window is ended by unlocking it.
+            responses:
+                '201':
+                    description: The window, cancelled
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                '404':
+                    description: No open window has this id (`MAINTENANCE_WINDOW_NOT_OPEN`)
+                '409':
+                    description: The window is locked (`MAINTENANCE_WINDOW_LOCKED`)
+
+    /maintenance/lock:
+        post:
+            tags: [maintenance]
+            summary: Lock every tenant out
+            description: >-
+                Locks the open window, or opens one locked at once where none is open. Locking what
+                is locked changes nothing and says so. Takes effect in every process within
+                `takesEffectWithinSeconds`. Audited as MAINTENANCE_LOCK.
+            x-mfa-required: true
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/MaintenanceLockRequest' }
+            responses:
+                '201':
+                    description: The lock
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceLockView' }
+                '400':
+                    description: An end without its zone or in the past
+                '404':
+                    description: The window named is not the open one (`MAINTENANCE_WINDOW_NOT_OPEN`)
+
+    /maintenance/unlock:
+        post:
+            tags: [maintenance]
+            summary: Let tenants back in
+            description: >-
+                Ends the locked window. Where nothing is locked it changes nothing and says so; an
+                announced window is left as it is. Audited as MAINTENANCE_UNLOCK.
+            x-mfa-required: true
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                windowId:
+                                    { type: string, description: The window the operator means }
+            responses:
+                '201':
+                    description: What the unlock did
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceUnlockView' }
+                '404':
+                    description: The window named is not the open one (`MAINTENANCE_WINDOW_NOT_OPEN`)
+
     # ── Discovery (scan/status, outside /catalog) ──
     /discovery:
         get:
@@ -1514,6 +1725,123 @@ components:
                 before: { description: 'Absent where the leaf did not exist before' }
                 after: { description: 'Absent where the leaf no longer exists' }
 
+        # ────────── Maintenance windows (packages/core/src/maintenance-window.types.ts) ──────────
+        MaintenanceWindowView:
+            type: object
+            required:
+                [
+                    id,
+                    status,
+                    startsAt,
+                    endsAt,
+                    message,
+                    createdAt,
+                    createdBy,
+                    lockedAt,
+                    lockedBy,
+                    endedAt,
+                    endedBy,
+                    overrun,
+                    lapsed,
+                ]
+            properties:
+                id: { type: string }
+                status: { type: string, enum: [announced, locked, ended, cancelled] }
+                startsAt:
+                    {
+                        type: [string, 'null'],
+                        format: date-time,
+                        description: 'The announced start; null for a window locked without being announced',
+                    }
+                endsAt:
+                    {
+                        type: [string, 'null'],
+                        format: date-time,
+                        description: 'The announced, expected end; null where nobody said',
+                    }
+                message: { type: [string, 'null'], description: 'Shown to the tenants as written' }
+                createdAt: { type: string, format: date-time }
+                createdBy: { type: string, description: 'An actor tag, as the audit log writes it' }
+                lockedAt: { type: [string, 'null'], format: date-time }
+                lockedBy: { type: [string, 'null'] }
+                endedAt: { type: [string, 'null'], format: date-time }
+                endedBy: { type: [string, 'null'] }
+                overrun: { type: boolean, description: 'Locked, and past its announced end' }
+                lapsed:
+                    {
+                        type: boolean,
+                        description: 'Announced, never locked, and past its announced end: tenants no longer see it',
+                    }
+
+        MaintenanceOverview:
+            type: object
+            required: [open, recent, takesEffectWithinSeconds]
+            properties:
+                open:
+                    oneOf:
+                        - $ref: '#/components/schemas/MaintenanceWindowView'
+                        - type: 'null'
+                recent:
+                    type: array
+                    description: 'Newest first, the open one included'
+                    items: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                takesEffectWithinSeconds:
+                    { type: integer, description: 'How long a lock takes to reach every process' }
+
+        MaintenanceAnnouncement:
+            type: object
+            required: [startsAt, endsAt]
+            properties:
+                startsAt:
+                    {
+                        type: string,
+                        description: 'Date and time with its zone, e.g. 2026-10-02T22:00+02:00',
+                    }
+                endsAt:
+                    {
+                        type: string,
+                        description: 'Date and time with its zone; after startsAt, and ahead',
+                    }
+                message: { type: [string, 'null'], maxLength: 500 }
+
+        MaintenanceRevision:
+            type: object
+            properties:
+                startsAt: { type: string, description: 'Date and time with its zone' }
+                endsAt: { type: string, description: 'Date and time with its zone' }
+                message:
+                    { type: [string, 'null'], maxLength: 500, description: 'null takes it away' }
+
+        MaintenanceLockRequest:
+            type: object
+            properties:
+                windowId:
+                    {
+                        type: string,
+                        description: 'The window the operator means; left out, the open one or a new one',
+                    }
+                endsAt: { type: string, description: 'The expected end, with its zone' }
+                message: { type: [string, 'null'], maxLength: 500 }
+
+        MaintenanceLockView:
+            type: object
+            required: [window, alreadyLocked, takesEffectWithinSeconds]
+            properties:
+                window: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                alreadyLocked:
+                    { type: boolean, description: 'The lock already held; nothing changed' }
+                takesEffectWithinSeconds: { type: integer }
+
+        MaintenanceUnlockView:
+            type: object
+            required: [window, wasLocked]
+            properties:
+                window:
+                    oneOf:
+                        - $ref: '#/components/schemas/MaintenanceWindowView'
+                        - type: 'null'
+                wasLocked: { type: boolean }
+
         # ────────── Catalog V2 (DTO = SSOT: packages/nest/src/catalog/dto/*) ──────────
         CatalogPlanCreate:
             type: object
@@ -1667,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'
@@ -1911,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:
@@ -1923,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.22",
+  "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?