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

package/README.md

@@ -33,7 +33,7 @@ from there.
 | `schemas/plan-catalog.schema.json`      | App identity config format (`config/saas.yaml`)   |
 | `schemas/promo-code.schema.json`        | Promo code format incl. redemption lifecycle      |
 | `schemas/audit-event.schema.json`       | Audit log entry format                            |
-| `schemas/tenant-ledger.schema.json`     | A tenant's account: charges, payments, balance    |
+| `schemas/subscriber-ledger.schema.json` | One charge in a subscriber's account              |
 | `admin-api.openapi.yaml`                | NORMATIVE REST contract of the SuperAdmin backend |
 | `acceptance/`                           | HTTP test scenarios (stubs; runner planned)       |
 | `index.js` / `index.cjs` / `index.d.ts` | Re-exports for JS/TS consumers                    |

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.21
+    version: 1.0.0-rc.23
     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: []
@@ -125,7 +126,7 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: 'admin-manifest.schema.json'
+                                $ref: 'schemas/admin-manifest.schema.json'
                 '304':
                     description: Unchanged since ETag
                 '403':
@@ -368,6 +369,28 @@ paths:
                         application/json:
                             schema: { $ref: '#/components/schemas/SubscriptionDetail' }
 
+    /tenants/{slug}/charges:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        get:
+            tags: [subscriptions]
+            summary: The charges of the tenant's subscriber, newest first
+            description: >-
+                Served where the platform keeps a charge journal
+                (`tenantBilling.chargeJournal`) and shows tenants
+                (`adminResources`); the manifest announces it as `charges.read`.
+                Read only, and net: a charge's tax is decided when it is
+                invoiced. No total — without invoices and payments, a sum would
+                be read as what is owed.
+            responses:
+                '200':
+                    description: The account
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminSubscriberAccount' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+
     # ────────────────────────────────────────────────────────
     # Users
     # ────────────────────────────────────────────────────────
@@ -1384,6 +1407,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:
@@ -1492,6 +1655,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
@@ -1915,6 +2195,38 @@ components:
                 promoRedemption:
                     $ref: '#/components/schemas/PromoRedemptionDto'
 
+        AdminSubscriberAccount:
+            type: object
+            required: [holder, entries]
+            properties:
+                holder:
+                    type: object
+                    nullable: true
+                    description: Whose account it is; null for a tenant that has no subscriber.
+                    required: [id, customerNumber, legalName]
+                    properties:
+                        id: { type: string }
+                        customerNumber: { type: string }
+                        legalName: { type: string }
+                entries:
+                    type: array
+                    description: >-
+                        Newest first — by when each charge became due, then by
+                        its period, then the plan before its add-ons before its
+                        discounts.
+                    items:
+                        type: object
+                        required: [charge, title]
+                        properties:
+                            charge: { $ref: 'schemas/subscriber-ledger.schema.json' }
+                            title:
+                                type: string
+                                nullable: true
+                                description: >-
+                                    The contract line's title as it was when the
+                                    contract was concluded; null where that line
+                                    cannot be read.
+
         # ────────── User ──────────
         AdminUserRow:
             type: object

package/index.cjs

@@ -3,19 +3,19 @@ const adminManifestSchema = require('./schemas/admin-manifest.schema.json');
 const planCatalogSchema = require('./schemas/plan-catalog.schema.json');
 const promoCodeSchema = require('./schemas/promo-code.schema.json');
 const auditEventSchema = require('./schemas/audit-event.schema.json');
-const tenantLedgerSchema = require('./schemas/tenant-ledger.schema.json');
+const subscriberLedgerSchema = require('./schemas/subscriber-ledger.schema.json');
 
 module.exports = {
     adminManifestSchema,
     planCatalogSchema,
     promoCodeSchema,
     auditEventSchema,
-    tenantLedgerSchema,
+    subscriberLedgerSchema,
     SCHEMAS: {
         adminManifest: adminManifestSchema,
         planCatalog: planCatalogSchema,
         promoCode: promoCodeSchema,
         auditEvent: auditEventSchema,
-        tenantLedger: tenantLedgerSchema,
+        subscriberLedger: subscriberLedgerSchema,
     },
 };

package/index.d.cts

@@ -4,12 +4,12 @@ export declare const adminManifestSchema: Record<string, unknown>;
 export declare const planCatalogSchema: Record<string, unknown>;
 export declare const promoCodeSchema: Record<string, unknown>;
 export declare const auditEventSchema: Record<string, unknown>;
-export declare const tenantLedgerSchema: Record<string, unknown>;
+export declare const subscriberLedgerSchema: Record<string, unknown>;
 
 export declare const SCHEMAS: {
     readonly adminManifest: Record<string, unknown>;
     readonly planCatalog: Record<string, unknown>;
     readonly promoCode: Record<string, unknown>;
     readonly auditEvent: Record<string, unknown>;
-    readonly tenantLedger: Record<string, unknown>;
+    readonly subscriberLedger: Record<string, unknown>;
 };

package/index.d.ts

@@ -5,12 +5,12 @@ export declare const adminManifestSchema: Record<string, unknown>;
 export declare const planCatalogSchema: Record<string, unknown>;
 export declare const promoCodeSchema: Record<string, unknown>;
 export declare const auditEventSchema: Record<string, unknown>;
-export declare const tenantLedgerSchema: Record<string, unknown>;
+export declare const subscriberLedgerSchema: Record<string, unknown>;
 
 export declare const SCHEMAS: {
     readonly adminManifest: Record<string, unknown>;
     readonly planCatalog: Record<string, unknown>;
     readonly promoCode: Record<string, unknown>;
     readonly auditEvent: Record<string, unknown>;
-    readonly tenantLedger: Record<string, unknown>;
+    readonly subscriberLedger: Record<string, unknown>;
 };

package/index.js

@@ -6,14 +6,14 @@ import adminManifestSchema from './schemas/admin-manifest.schema.json' with { ty
 import planCatalogSchema from './schemas/plan-catalog.schema.json' with { type: 'json' };
 import promoCodeSchema from './schemas/promo-code.schema.json' with { type: 'json' };
 import auditEventSchema from './schemas/audit-event.schema.json' with { type: 'json' };
-import tenantLedgerSchema from './schemas/tenant-ledger.schema.json' with { type: 'json' };
+import subscriberLedgerSchema from './schemas/subscriber-ledger.schema.json' with { type: 'json' };
 
 export {
     adminManifestSchema,
     planCatalogSchema,
     promoCodeSchema,
     auditEventSchema,
-    tenantLedgerSchema,
+    subscriberLedgerSchema,
 };
 
 export const SCHEMAS = {
@@ -21,5 +21,5 @@ export const SCHEMAS = {
     planCatalog: planCatalogSchema,
     promoCode: promoCodeSchema,
     auditEvent: auditEventSchema,
-    tenantLedger: tenantLedgerSchema,
+    subscriberLedger: subscriberLedgerSchema,
 };

package/package.json

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

package/prisma-fragments/08-subscription-contract.prisma

@@ -64,7 +64,8 @@ model SubscriptionContract {
     promoCodeSnapshots  Json @default("[]")
     termsSnapshot       Json?
 
-    lineItems ContractLineItem[]
+    lineItems     ContractLineItem[]
+    ledgerEntries SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
 
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
@@ -121,7 +122,8 @@ model ContractLineItem {
 
     createdAt DateTime @default(now())
 
-    contract SubscriptionContract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+    contract      SubscriptionContract    @relation(fields: [contractId], references: [id], onDelete: Cascade)
+    ledgerEntries SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
 
     @@index([contractId, kind])
     @@index([sourceVersionId])

package/prisma-fragments/13-subscriber.prisma

@@ -52,6 +52,7 @@ model Subscriber {
     contracts      SubscriptionContract[]
     paymentMethods      SubscriberPaymentMethod[] // see 14-payments.prisma
     paymentMethodSetups SubscriberPaymentMethodSetup[]
+    ledgerEntries       SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
 
     @@map("subscribers")
 }

package/prisma-fragments/15-subscriber-ledger.prisma

@@ -0,0 +1,65 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriberLedgerEntry
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// The subscriber's account: one row per charge that became due, one per
+// contract line and period. The platform derives each charge from the contract
+// in force, the billing windows and the bookings, and writes it once — the
+// unique index below is what makes a second derivation of the same charge a
+// no-op, however many run at the same time. A row is never updated or deleted:
+// a mistake is answered with a counter-entry.
+//
+// A charge is net. The tax is the invoice's, decided by the tax adapter when
+// the charge is invoiced (ADR 0013), so this table records the amount, its
+// currency and the period, and nothing that a later invoice would have to
+// agree with to the cent.
+//
+// The account belongs to the subscriber, not to the tenant, and outlives it
+// (ADR 0012): `tenantId` and `subscriptionId` are kept as values, and the keys
+// that point anywhere point at the subscriber and the contract line, which are
+// kept as long as the documents that need them.
+//
+// `origin` and `source` are text holding a closed set, checked when a row is
+// read (`toSubscriberChargeRecord` in @saasicat/core):
+//   origin: activation | renewal | planChange | bundleBooking | credit | correction
+//   source: plan | bundle | discount
+//
+// Optional: adopt it where `tenantBilling.chargeJournal` is configured, which
+// needs frozen contracts (`contractFreeze`).
+//
+// Contract: @saasicat/core (SubscriberLedgerRepository).
+
+model SubscriberLedgerEntry {
+    id                 String @id @default(uuid())
+    subscriberId       String
+    tenantId           String
+    subscriptionId     String
+    contractId         String
+    contractLineItemId String
+
+    origin String
+    source String
+    // The subscription id for the plan, the booking id for an add-on, the
+    // discount's key — stable across the contracts that replace one another.
+    sourceRef String
+
+    periodStart DateTime
+    periodEnd   DateTime
+
+    currency  String
+    amountNet Decimal @db.Decimal(10, 2)
+
+    bookedAt  DateTime
+    createdAt DateTime @default(now())
+
+    subscriber       Subscriber           @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+    contract         SubscriptionContract @relation(fields: [contractId], references: [id], onDelete: Restrict)
+    contractLineItem ContractLineItem     @relation(fields: [contractLineItemId], references: [id], onDelete: Restrict)
+
+    @@unique([subscriptionId, source, sourceRef, periodStart, origin])
+    @@index([subscriberId, bookedAt])
+    @@index([contractLineItemId])
+    @@map("subscriber_ledger_entries")
+}

package/prisma-fragments/16-maintenance-window.prisma

@@ -0,0 +1,47 @@
+// =============================================================================
+// SaaS platform Prisma fragment: MaintenanceWindow
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per maintenance window: announced to the tenants ahead of time,
+// locked while a deploy runs a migration that must not race with requests, and
+// ended when the operator says so. A window can also be locked at once without
+// having been announced, which leaves `startsAt` null.
+//
+// While a window is locked, every running version of the application reads this
+// table on its requests — the one being replaced as well as the one replacing
+// it. Its shape is therefore part of the contract between two releases: it
+// gains columns, and never in a deploy the lock protects.
+//
+// At most ONE window is open (not yet ended) at a time. Prisma cannot express a
+// partial unique index; the one that holds it is in
+// sql/constraints.postgres.sql, and it is what makes two operators locking at
+// the same moment land one window rather than two.
+//
+// Optional: adopt it where `maintenance` is turned on in
+// `SaaSiCatModule.forRoot`, which refuses to start without a place to keep
+// windows.
+
+model MaintenanceWindow {
+    id        String    @id @default(uuid())
+    // What the tenants were told: the announced start and the expected end.
+    // Neither starts or ends the lock — that is the operator's command.
+    startsAt  DateTime?
+    endsAt    DateTime?
+    // The operator's words to the tenants, shown as written.
+    message   String?
+    // When the window was recorded — announced, or locked at once — and by whom
+    // (an actor tag, as the audit log writes it).
+    createdAt DateTime  @default(now())
+    createdBy String
+    // Null while the window is only announced.
+    lockedAt  DateTime?
+    lockedBy  String?
+    // Set when the window is over: unlocked, or cancelled before it locked.
+    endedAt   DateTime?
+    endedBy   String?
+
+    @@index([createdAt])
+    @@map("maintenance_windows")
+}

package/prisma-fragments/README.md

@@ -44,6 +44,8 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 | [`12-applied-settings.prisma`](12-applied-settings.prisma)           | `AppliedSettings`, `SettingsChange`                                                   |
 | [`13-subscriber.prisma`](13-subscriber.prisma)                       | `Subscriber`, `SubscriberTenant`, `SubscriberCorrection`                              |
 | [`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`                                                                   |
 
 ## How the consumer uses the fragments
 

package/schemas/admin-manifest.schema.json

@@ -141,7 +141,8 @@
                         "marketingCatalog": { "$ref": "#/$defs/StandardPageDef" },
                         "platformEmail": { "$ref": "#/$defs/StandardPageDef" },
                         "platformEmailHistory": { "$ref": "#/$defs/StandardPageDef" },
-                        "settings": { "$ref": "#/$defs/StandardPageDef" }
+                        "settings": { "$ref": "#/$defs/StandardPageDef" },
+                        "maintenance": { "$ref": "#/$defs/StandardPageDef" }
                     }
                 },
                 "projectPages": {

package/schemas/subscriber-ledger.schema.json

@@ -0,0 +1,100 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://saasicat.dev/schemas/subscriber-ledger.schema.json",
+    "title": "SubscriberCharge",
+    "description": "One charge in a subscriber's account: an amount that became due for a period, derived from a line of the contract in force. The journal is append-only — a charge is never updated, and a mistake is answered with a counter-entry rather than an edit, so the account says what happened rather than what somebody thinks today. A charge is net: the tax is decided by the tax adapter when the charge is invoiced, from the subscriber's origin on that day, and computed once per rate on the invoice.",
+    "type": "object",
+    "required": [
+        "id",
+        "subscriberId",
+        "tenantId",
+        "subscriptionId",
+        "contractId",
+        "contractLineItemId",
+        "origin",
+        "source",
+        "sourceRef",
+        "periodStart",
+        "periodEnd",
+        "currency",
+        "amountNet",
+        "bookedAt",
+        "createdAt"
+    ],
+    "additionalProperties": false,
+    "properties": {
+        "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The charge's own identifier. Never shown to a customer as an invoice number: invoice numbering is sequential, gapless and legally constrained per country, and an identifier somebody has already seen on a screen cannot become one later without confusion."
+        },
+        "subscriberId": {
+            "type": "string",
+            "description": "The party the contract is concluded with, whose account this is. It outlives the tenant."
+        },
+        "tenantId": {
+            "type": "string",
+            "description": "The tenant the subscription belonged to when the charge arose."
+        },
+        "subscriptionId": {
+            "type": "string",
+            "description": "The subscription the charge arose on. Part of the natural key."
+        },
+        "contractId": {
+            "type": "string",
+            "description": "The contract whose line the charge realises."
+        },
+        "contractLineItemId": {
+            "type": "string",
+            "description": "The contract line the charge came from, so that every invoice line can be traced back to what was agreed."
+        },
+        "origin": { "$ref": "#/$defs/SubscriberChargeOrigin" },
+        "source": { "$ref": "#/$defs/SubscriberChargeSource" },
+        "sourceRef": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Which thing of its source the charge is for, stable across contracts: the subscription id for the plan, the booking id for an add-on, the discount's key for a discount. Part of the natural key (subscriptionId, source, sourceRef, periodStart, origin), which is unique — a charge derived twice is written once."
+        },
+        "periodStart": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The start of the period the charge belongs to — the grouping key for an invoice."
+        },
+        "periodEnd": { "type": "string", "format": "date-time" },
+        "currency": {
+            "type": "string",
+            "pattern": "^[A-Z]{3}$",
+            "description": "ISO 4217, as the contract line records it — recorded per charge so that a charge written in 2026 still means what it meant after the configured currency changes."
+        },
+        "amountNet": {
+            "type": "number",
+            "description": "Net, rounded to the currency's decimal places once, when the charge is written; the written figure is the truth from then on. Negative for a discount."
+        },
+        "bookedAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the amount became due. The account is ordered by this, not by when the row was written."
+        },
+        "createdAt": { "type": "string", "format": "date-time" }
+    },
+
+    "$defs": {
+        "SubscriberChargeOrigin": {
+            "type": "string",
+            "enum": [
+                "activation",
+                "renewal",
+                "planChange",
+                "bundleBooking",
+                "credit",
+                "correction"
+            ],
+            "description": "What made the charge arise. activation: the first period of a subscription. renewal: a later period. planChange: what an immediate plan change adds. bundleBooking: the first, short period of an add-on. credit: a decision that reduces what is owed. correction: a counter-entry reversing an earlier charge, which is how the append-only journal answers a mistake."
+        },
+        "SubscriberChargeSource": {
+            "type": "string",
+            "enum": ["plan", "bundle", "discount"],
+            "description": "Which kind of contract line the charge realises."
+        }
+    }
+}

package/sql/1.0-a-subscriber-account-records-its-charges.postgres.sql

@@ -0,0 +1,101 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a subscriber's account records the charges its contracts give.
+-- =============================================================================
+--
+-- The journal of charges: one row per contract line and period, derived from
+-- the contract in force, the billing windows and the bookings, and written
+-- once (ADR 0012, #276 step 4). Needed where `tenantBilling.chargeJournal` is
+-- configured. Run it BEFORE `db push`, and after
+-- `1.0-a-contract-names-its-subscriber.postgres.sql`, whose `subscribers`
+-- table it points at:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-subscriber-account-records-its-charges.postgres.sql
+--
+-- What it touches, in one transaction:
+--
+--   `subscriber_ledger_entries` — created with its indexes, among them the
+--   unique index on (subscriptionId, source, sourceRef, periodStart, origin)
+--   that makes a charge derived twice a charge written once, and its foreign
+--   keys to `subscribers`, `subscription_contracts` and `contract_line_items`.
+--   Skipped, with a notice, where one of those three tables is missing.
+--
+-- Nothing is backfilled: the first time the platform brings an account up to
+-- date it charges the period each subscription is in, and nothing before it.
+--
+-- Safe to run again: the table and every index are created only where they are
+-- missing, and each foreign key only where its name is not taken. On a
+-- database created from `reference-schema.postgres.sql` the whole file does
+-- nothing at all.
+
+BEGIN;
+
+DO $$
+BEGIN
+    IF to_regclass('subscribers') IS NULL
+        OR to_regclass('subscription_contracts') IS NULL
+        OR to_regclass('contract_line_items') IS NULL THEN
+        RAISE NOTICE 'subscribers, subscription_contracts or contract_line_items is not present — subscriber_ledger_entries is not created; the journal needs contracts and the subscribers they are concluded with.';
+        RETURN;
+    END IF;
+
+    CREATE TABLE IF NOT EXISTS "subscriber_ledger_entries" (
+        "id" TEXT NOT NULL,
+        "subscriberId" TEXT NOT NULL,
+        "tenantId" TEXT NOT NULL,
+        "subscriptionId" TEXT NOT NULL,
+        "contractId" TEXT NOT NULL,
+        "contractLineItemId" TEXT NOT NULL,
+        "origin" TEXT NOT NULL,
+        "source" TEXT NOT NULL,
+        "sourceRef" TEXT NOT NULL,
+        "periodStart" TIMESTAMP(3) NOT NULL,
+        "periodEnd" TIMESTAMP(3) NOT NULL,
+        "currency" TEXT NOT NULL,
+        "amountNet" DECIMAL(10,2) NOT NULL,
+        "bookedAt" TIMESTAMP(3) NOT NULL,
+        "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        CONSTRAINT "subscriber_ledger_entries_pkey" PRIMARY KEY ("id")
+    );
+    CREATE INDEX IF NOT EXISTS "subscriber_ledger_entries_subscriberId_bookedAt_idx"
+        ON "subscriber_ledger_entries"("subscriberId", "bookedAt");
+    CREATE INDEX IF NOT EXISTS "subscriber_ledger_entries_contractLineItemId_idx"
+        ON "subscriber_ledger_entries"("contractLineItemId");
+    -- The name is the one Prisma derives and cuts at 63 characters, so that a
+    -- later `db push` finds it rather than creating a second index.
+    CREATE UNIQUE INDEX IF NOT EXISTS "subscriber_ledger_entries_subscriptionId_source_sourceRef_p_key"
+        ON "subscriber_ledger_entries"("subscriptionId", "source", "sourceRef", "periodStart", "origin");
+
+    -- `ADD CONSTRAINT` has no `IF NOT EXISTS`.
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscriber_ledger_entries')
+           AND conname = 'subscriber_ledger_entries_subscriberId_fkey'
+    ) THEN
+        ALTER TABLE "subscriber_ledger_entries"
+            ADD CONSTRAINT "subscriber_ledger_entries_subscriberId_fkey"
+            FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscriber_ledger_entries')
+           AND conname = 'subscriber_ledger_entries_contractId_fkey'
+    ) THEN
+        ALTER TABLE "subscriber_ledger_entries"
+            ADD CONSTRAINT "subscriber_ledger_entries_contractId_fkey"
+            FOREIGN KEY ("contractId") REFERENCES "subscription_contracts"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscriber_ledger_entries')
+           AND conname = 'subscriber_ledger_entries_contractLineItemId_fkey'
+    ) THEN
+        ALTER TABLE "subscriber_ledger_entries"
+            ADD CONSTRAINT "subscriber_ledger_entries_contractLineItemId_fkey"
+            FOREIGN KEY ("contractLineItemId") REFERENCES "contract_line_items"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+END $$;
+
+COMMIT;

package/sql/1.0-maintenance-windows-are-kept.postgres.sql

@@ -0,0 +1,51 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — maintenance windows are kept.
+-- =============================================================================
+--
+-- One table, additive: `maintenance_windows` holds one row per maintenance
+-- window — announced to the tenants, locked while a deploy runs, ended when the
+-- operator unlocks. The platform reads it on every request while it is turned
+-- on (`maintenance` in `SaaSiCatModule.forRoot`), through a cache of a few
+-- seconds.
+--
+-- 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-maintenance-windows-are-kept.postgres.sql
+--
+-- Apply it in an ordinary deploy, BEFORE the first deploy you lock: the lock
+-- protects a deploy only when the version already running reads it, so the
+-- table has to be there, and that version with it, before it is needed.
+--
+-- The index on a constant is what holds an installation to one open window:
+-- every open row carries the same key, so a second one collides, and a window
+-- that ended leaves the index.
+--
+-- 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 "maintenance_windows" (
+    "id" TEXT NOT NULL,
+    "startsAt" TIMESTAMP(3),
+    "endsAt" TIMESTAMP(3),
+    "message" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "createdBy" TEXT NOT NULL,
+    "lockedAt" TIMESTAMP(3),
+    "lockedBy" TEXT,
+    "endedAt" TIMESTAMP(3),
+    "endedBy" TEXT,
+
+    CONSTRAINT "maintenance_windows_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "maintenance_windows_createdAt_idx"
+    ON "maintenance_windows"("createdAt");
+
+CREATE UNIQUE INDEX IF NOT EXISTS maintenance_windows_one_open
+    ON maintenance_windows ((true)) WHERE "endedAt" IS NULL;
+
+COMMIT;

package/sql/constraints.postgres.sql

@@ -47,6 +47,15 @@ ALTER TABLE applied_settings
 ALTER TABLE applied_settings
     ADD CONSTRAINT applied_settings_is_a_singleton CHECK ("id" = 'installation');
 
+-- At most ONE maintenance window is open — announced or locked, not yet ended.
+--
+-- The index is on a constant, so every open row carries the same key and a
+-- second one collides. A window that ended leaves the index and makes room for
+-- the next. Two operators locking at the same moment therefore land one window,
+-- because the second insert meets the first and is told a window is open.
+CREATE UNIQUE INDEX IF NOT EXISTS maintenance_windows_one_open
+    ON maintenance_windows ((true)) WHERE "endedAt" IS NULL;
+
 -- A subscriber is live for at most ONE tenant, and a tenant has at most ONE
 -- live subscriber. A link that ended keeps its row with `unlinkedAt` set, so the
 -- tenants a subscriber had before stay in its history. Two partial unique

package/sql/reference-schema.postgres.sql

@@ -17,6 +17,8 @@
 --   prisma-fragments/12-applied-settings.prisma
 --   prisma-fragments/13-subscriber.prisma
 --   prisma-fragments/14-payments.prisma
+--   prisma-fragments/15-subscriber-ledger.prisma
+--   prisma-fragments/16-maintenance-window.prisma
 -- plus the normative constraints from sql/constraints.postgres.sql.
 -- Do not edit by hand — change the fragments/constraints and regenerate.
 
@@ -684,6 +686,43 @@ CREATE TABLE "PaymentEventLog" (
     CONSTRAINT "PaymentEventLog_pkey" PRIMARY KEY ("id")
 );
 
+-- CreateTable
+CREATE TABLE "subscriber_ledger_entries" (
+    "id" TEXT NOT NULL,
+    "subscriberId" TEXT NOT NULL,
+    "tenantId" TEXT NOT NULL,
+    "subscriptionId" TEXT NOT NULL,
+    "contractId" TEXT NOT NULL,
+    "contractLineItemId" TEXT NOT NULL,
+    "origin" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "sourceRef" TEXT NOT NULL,
+    "periodStart" TIMESTAMP(3) NOT NULL,
+    "periodEnd" TIMESTAMP(3) NOT NULL,
+    "currency" TEXT NOT NULL,
+    "amountNet" DECIMAL(10,2) NOT NULL,
+    "bookedAt" TIMESTAMP(3) NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "subscriber_ledger_entries_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "maintenance_windows" (
+    "id" TEXT NOT NULL,
+    "startsAt" TIMESTAMP(3),
+    "endsAt" TIMESTAMP(3),
+    "message" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "createdBy" TEXT NOT NULL,
+    "lockedAt" TIMESTAMP(3),
+    "lockedBy" TEXT,
+    "endedAt" TIMESTAMP(3),
+    "endedBy" TEXT,
+
+    CONSTRAINT "maintenance_windows_pkey" PRIMARY KEY ("id")
+);
+
 -- CreateIndex
 CREATE UNIQUE INDEX "subscriptions_tenantId_key" ON "subscriptions"("tenantId");
 
@@ -909,6 +948,18 @@ CREATE INDEX "PaymentEventLog_status_processedAt_idx" ON "PaymentEventLog"("stat
 -- CreateIndex
 CREATE UNIQUE INDEX "PaymentEventLog_gatewayAccount_eventId_key" ON "PaymentEventLog"("gatewayAccount", "eventId");
 
+-- CreateIndex
+CREATE INDEX "subscriber_ledger_entries_subscriberId_bookedAt_idx" ON "subscriber_ledger_entries"("subscriberId", "bookedAt");
+
+-- CreateIndex
+CREATE INDEX "subscriber_ledger_entries_contractLineItemId_idx" ON "subscriber_ledger_entries"("contractLineItemId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "subscriber_ledger_entries_subscriptionId_source_sourceRef_p_key" ON "subscriber_ledger_entries"("subscriptionId", "source", "sourceRef", "periodStart", "origin");
+
+-- CreateIndex
+CREATE INDEX "maintenance_windows_createdAt_idx" ON "maintenance_windows"("createdAt");
+
 -- AddForeignKey
 ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_planVersionId_fkey" FOREIGN KEY ("planVersionId") REFERENCES "plan_versions"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
@@ -960,6 +1011,15 @@ ALTER TABLE "subscriber_payment_methods" ADD CONSTRAINT "subscriber_payment_meth
 -- AddForeignKey
 ALTER TABLE "subscriber_payment_method_setups" ADD CONSTRAINT "subscriber_payment_method_setups_subscriberId_fkey" FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
+-- AddForeignKey
+ALTER TABLE "subscriber_ledger_entries" ADD CONSTRAINT "subscriber_ledger_entries_subscriberId_fkey" FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "subscriber_ledger_entries" ADD CONSTRAINT "subscriber_ledger_entries_contractId_fkey" FOREIGN KEY ("contractId") REFERENCES "subscription_contracts"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "subscriber_ledger_entries" ADD CONSTRAINT "subscriber_ledger_entries_contractLineItemId_fkey" FOREIGN KEY ("contractLineItemId") REFERENCES "contract_line_items"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
 -- =============================================================================
 -- SaaSiCat — normative PostgreSQL constraints the Prisma DSL cannot express.
 -- =============================================================================
@@ -1009,6 +1069,15 @@ ALTER TABLE applied_settings
 ALTER TABLE applied_settings
     ADD CONSTRAINT applied_settings_is_a_singleton CHECK ("id" = 'installation');
 
+-- At most ONE maintenance window is open — announced or locked, not yet ended.
+--
+-- The index is on a constant, so every open row carries the same key and a
+-- second one collides. A window that ended leaves the index and makes room for
+-- the next. Two operators locking at the same moment therefore land one window,
+-- because the second insert meets the first and is told a window is open.
+CREATE UNIQUE INDEX IF NOT EXISTS maintenance_windows_one_open
+    ON maintenance_windows ((true)) WHERE "endedAt" IS NULL;
+
 -- A subscriber is live for at most ONE tenant, and a tenant has at most ONE
 -- live subscriber. A link that ended keeps its row with `unlinkedAt` set, so the
 -- tenants a subscriber had before stay in its history. Two partial unique

package/schemas/tenant-ledger.schema.json

@@ -1,236 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://saasicat.dev/schemas/tenant-ledger.schema.json",
-    "title": "TenantLedgerEntry",
-    "description": "One entry in a tenant's account. Two kinds share one journal: a charge is what became due, a payment is what settled part of it. The journal is append-only — an entry is never updated, and a mistake is answered with a counter-entry rather than an edit, so the account says what happened rather than what somebody thinks today.",
-    "oneOf": [{ "$ref": "#/$defs/LedgerCharge" }, { "$ref": "#/$defs/LedgerPayment" }],
-
-    "$defs": {
-        "LedgerEntryKind": {
-            "type": "string",
-            "enum": ["charge", "payment"],
-            "description": "charge: an amount became due. payment: an amount settled."
-        },
-
-        "ChargeOrigin": {
-            "type": "string",
-            "enum": [
-                "activation",
-                "renewal",
-                "planChange",
-                "bundleBooking",
-                "credit",
-                "correction"
-            ],
-            "description": "What made the charge arise. activation: the first period of a subscription. renewal: a period renewing. planChange: the prorated difference of an immediate plan change. bundleBooking: an add-on booked. credit: a decision that reduces what is owed. correction: a counter-entry reversing an earlier one, which is how the append-only journal answers a mistake."
-        },
-
-        "Currency": {
-            "type": "string",
-            "pattern": "^[A-Z]{3}$",
-            "description": "ISO 4217. Recorded per entry even though an installation configures one at a time, so that a row written in 2026 still means what it meant after the configured currency changes."
-        },
-
-        "LedgerCharge": {
-            "type": "object",
-            "title": "LedgerCharge",
-            "description": "An amount that became due. It names the period it belongs to, so the charges that make up one invoice can be found later, and it names the agreement it came from, so it can be walked back to what the tenant agreed to.",
-            "required": [
-                "id",
-                "tenantId",
-                "kind",
-                "subscriptionId",
-                "origin",
-                "originRef",
-                "periodStart",
-                "periodEnd",
-                "currency",
-                "amountNet",
-                "taxRate",
-                "taxAmount",
-                "amountGross",
-                "bookedAt",
-                "createdAt"
-            ],
-            "additionalProperties": false,
-            "properties": {
-                "id": {
-                    "type": "string",
-                    "format": "uuid",
-                    "description": "The entry's own identifier. Never shown to a customer as an invoice number: invoice numbering is sequential, gapless and legally constrained per country, and an identifier somebody has already seen on a screen cannot become one later without confusion."
-                },
-                "tenantId": { "type": "string" },
-                "kind": { "const": "charge" },
-                "subscriptionId": {
-                    "type": "string",
-                    "description": "The subscription the charge arose on. Part of the natural key below."
-                },
-                "origin": { "$ref": "#/$defs/ChargeOrigin" },
-                "originRef": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "Which thing within the origin the charge is for, so that two charges of the same origin in the same period stay apart. activation and renewal: the subscription id. planChange: the id of the contract the change concluded, which differs for every change. bundleBooking: the booking id. credit and correction: the entry they answer. Never empty — the natural key (subscriptionId, origin, originRef, periodStart) is unique, and a NULL would not collide with itself, which is the one thing the key exists to prevent."
-                },
-                "periodStart": {
-                    "type": "string",
-                    "format": "date-time",
-                    "description": "The billing period the charge belongs to. It is the grouping key for a later invoice: a set of individually booked amounts with nothing tying them to a period leaves 'which charges go on one invoice' to guesswork."
-                },
-                "periodEnd": { "type": "string", "format": "date-time" },
-                "contractId": {
-                    "type": ["string", "null"],
-                    "description": "The frozen agreement the charge realises. Null where none was frozen — a subscription older than the contract model, or a credit that answers no line."
-                },
-                "contractLineItemId": {
-                    "type": ["string", "null"],
-                    "description": "The contract line the charge came from. Null under the same conditions as contractId."
-                },
-                "currency": { "$ref": "#/$defs/Currency" },
-                "amountNet": {
-                    "type": "number",
-                    "description": "Held to the currency's decimal places. Negative on a credit or a correction."
-                },
-                "taxRate": {
-                    "type": "number",
-                    "minimum": 0,
-                    "maximum": 100,
-                    "description": "The rate in percent, recorded rather than left to live in the ratio between net and gross. A ratio cannot be reproduced for a rounded gross, cannot express an exempt or reverse-charge line, and does not survive a rate change."
-                },
-                "taxAmount": {
-                    "type": "number",
-                    "description": "The tax contained in the charge. It closes the gap between amountNet and amountGross exactly, so the entry cannot disagree with itself."
-                },
-                "amountGross": { "type": "number" },
-                "bookedAt": {
-                    "type": "string",
-                    "format": "date-time",
-                    "description": "When the amount became due. The account is ordered by this, not by when the row was written."
-                },
-                "createdAt": { "type": "string", "format": "date-time" }
-            }
-        },
-
-        "LedgerPayment": {
-            "type": "object",
-            "title": "LedgerPayment",
-            "description": "An amount that settled. What talks to a bank, a card processor or an invoice run is a consumer's adapter behind a port; this records only that the money arrived and which external reference it arrived under. It carries no tax split: a payment is a movement of money, and the net, the rate and the tax belong to the charges it settles — asking a payment for them would make an integrator write a number nobody knows, which the account would then read as a fact.",
-            "required": [
-                "id",
-                "tenantId",
-                "kind",
-                "externalReference",
-                "currency",
-                "amountGross",
-                "bookedAt",
-                "createdAt"
-            ],
-            "additionalProperties": false,
-            "properties": {
-                "id": { "type": "string", "format": "uuid" },
-                "tenantId": { "type": "string" },
-                "kind": { "const": "payment" },
-                "externalReference": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "The payment provider's own identifier for the settlement. It is what makes a payment reconcilable against the provider, and what a second delivery of the same provider event is recognised by."
-                },
-                "settlesEntryId": {
-                    "type": ["string", "null"],
-                    "description": "The charge this payment settles, where the provider says which. Null for a payment on account, which reduces the balance without naming a charge."
-                },
-                "currency": { "$ref": "#/$defs/Currency" },
-                "amountGross": {
-                    "type": "number",
-                    "description": "What arrived. Negative on a reversal, which is a movement the other way rather than an edit of the payment it answers."
-                },
-                "bookedAt": {
-                    "type": "string",
-                    "format": "date-time",
-                    "description": "The value date — when the money settled, which is not when the row was written."
-                },
-                "createdAt": { "type": "string", "format": "date-time" }
-            }
-        },
-
-        "TenantAccountOpenItem": {
-            "type": "object",
-            "title": "TenantAccountOpenItem",
-            "description": "A charge that is not yet settled in full.",
-            "required": [
-                "entryId",
-                "origin",
-                "periodStart",
-                "periodEnd",
-                "currency",
-                "amountGross",
-                "settledGross",
-                "openGross",
-                "dueAt"
-            ],
-            "additionalProperties": false,
-            "properties": {
-                "entryId": { "type": "string", "format": "uuid" },
-                "origin": { "$ref": "#/$defs/ChargeOrigin" },
-                "periodStart": { "type": "string", "format": "date-time" },
-                "periodEnd": { "type": "string", "format": "date-time" },
-                "currency": { "$ref": "#/$defs/Currency" },
-                "amountGross": { "type": "number" },
-                "settledGross": {
-                    "type": "number",
-                    "description": "What payments naming this charge have settled so far."
-                },
-                "openGross": {
-                    "type": "number",
-                    "description": "amountGross minus settledGross."
-                },
-                "dueAt": { "type": "string", "format": "date-time" }
-            }
-        },
-
-        "TenantAccount": {
-            "type": "object",
-            "title": "TenantAccount",
-            "description": "What a tenant and an administrator both read: the balance, what is open, and the history. One shape for both, because a balance a tenant is shown and a balance an administrator is shown must not be two answers.",
-            "required": [
-                "tenantId",
-                "currency",
-                "asOf",
-                "chargedGross",
-                "paidGross",
-                "balanceGross",
-                "openItems",
-                "entries"
-            ],
-            "additionalProperties": false,
-            "properties": {
-                "tenantId": { "type": "string" },
-                "currency": { "$ref": "#/$defs/Currency" },
-                "asOf": {
-                    "type": "string",
-                    "format": "date-time",
-                    "description": "A balance is only ever true at a moment, and this is the moment."
-                },
-                "chargedGross": { "type": "number" },
-                "paidGross": { "type": "number" },
-                "balanceGross": {
-                    "type": "number",
-                    "description": "chargedGross minus paidGross. Positive means the tenant owes; negative means they have paid ahead."
-                },
-                "openItems": {
-                    "type": "array",
-                    "items": { "$ref": "#/$defs/TenantAccountOpenItem" }
-                },
-                "entries": {
-                    "type": "array",
-                    "description": "The history the read was asked for, newest first. The window is the caller's decision, not a property of the account.",
-                    "items": {
-                        "oneOf": [
-                            { "$ref": "#/$defs/LedgerCharge" },
-                            { "$ref": "#/$defs/LedgerPayment" }
-                        ]
-                    }
-                }
-            }
-        }
-    }
-}