@saasicat/spec 1.0.0-rc.20 → 1.0.0-rc.22

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.20
+    version: 1.0.0-rc.22
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -125,7 +125,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 +368,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
     # ────────────────────────────────────────────────────────
@@ -1915,6 +1937,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
@@ -1979,6 +2033,9 @@ components:
                 validUntil: { type: string, format: date-time, nullable: true }
                 maxRedemptions: { type: integer, nullable: true }
                 redemptionsCount: { type: integer }
+                heldCount:
+                    type: integer
+                    description: Slots held for checkouts that started and have not concluded.
                 appliesToPlans:
                     type: array
                     items: { type: string }

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.20",
+  "version": "1.0.0-rc.22",
   "description": "Language-neutral spec of the SaaS platform: JSON Schemas, OpenAPI contract, Prisma fragments, acceptance scenarios.",
   "type": "module",
   "main": "./index.cjs",

package/prisma-fragments/02-promo-code.prisma

@@ -56,6 +56,10 @@ model PromoCode {
     // Availability-relevant — counts only redemptions with status=ACTIVE.
     // Incremented atomically in the redeem() path, decremented on trial cancellation.
     redemptionsCount Int @default(0)
+    // Slots kept for checkouts that have started and not concluded (see
+    // PromoCodeHold). A code has a free slot while redemptionsCount + heldCount
+    // stays below maxRedemptions; the status says nothing about holds.
+    heldCount        Int @default(0)
 
     // Plan whitelist as String[] — values are plan IDs from plans.yaml.
     // Consumers using a Postgres enum can cast the field locally.
@@ -86,6 +90,7 @@ model PromoCode {
 
     redemptions    PromoCodeRedemption[]
     validationLogs PromoCodeValidationLog[]
+    holds          PromoCodeHold[]
 
     @@index([status, validFrom, validUntil])
     @@index([campaignTag])
@@ -126,6 +131,39 @@ model PromoCodeRedemption {
     @@map("promo_code_redemptions")
 }
 
+// -----------------------------------------------------------------------------
+// PromoCodeHold — a slot of a code kept for a checkout from its start, so that
+// a customer who reaches the payment form keeps the code they started with.
+// For a sign-up, `expiresAt` is the last moment a confirmation of its payment
+// form can arrive, not the checkout's lifetime. It counts in
+// PromoCode.heldCount, and it ends in one of three ways, each deleting the row
+// and giving the count back: the conclusion turns it into the redemption, the
+// checkout offer's code changes, or `expiresAt` passes. It is a reservation
+// rather than a record — what a customer was granted is the
+// PromoCodeRedemption.
+// -----------------------------------------------------------------------------
+
+model PromoCodeHold {
+    id          String @id @default(uuid())
+    promoCodeId String
+    // Not a foreign key: an offer deleted while it holds a slot leaves the hold
+    // to expire, which gives the slot back. A cascade would delete the row and
+    // leave heldCount counting it.
+    checkoutOfferId String    @unique
+    expiresAt       DateTime
+    // The id of the transaction a conclusion runs on (`txid_current()`), set on
+    // that transaction and gone before it commits: the redemption running on
+    // the same transaction finds its slot by it, and no other one can.
+    handedOverTx    BigInt?
+    createdAt       DateTime  @default(now())
+
+    promoCode PromoCode @relation(fields: [promoCodeId], references: [id])
+
+    @@index([promoCodeId, expiresAt])
+    @@index([expiresAt])
+    @@map("promo_code_holds")
+}
+
 // -----------------------------------------------------------------------------
 // PromoCodeValidationLog — audit trail of all validation attempts
 // (including failed NOT_FOUND/EXPIRED), for anti-abuse analysis.

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/14-payments.prisma

@@ -15,6 +15,14 @@
 // payment method, a partial unique index in sql/constraints.postgres.sql;
 // the one a newer payment method replaced stays as `REPLACED`.
 //
+// Within an account a reference belongs to exactly one subscriber, which is
+// what `@@unique([gatewayAccount, paymentMethodRef])` below holds. The port
+// draws the same boundary for reading: a confirmation carrying a reference
+// another subscriber holds is refused rather than recorded, and a read by
+// reference names the subscriber it asks about. Both are reached on the
+// gateway's callback, which arrives without a session — an installation that
+// keeps its tenants apart with a policy on this table lifts it there.
+//
 // Contract: @saasicat/core (SubscriberPaymentMethodRepository, PaymentEventLog).
 // Both are needed wherever payment methods are taken — self-registration or
 // not — because every gateway callback is claimed in `PaymentEventLog`.

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/README.md

@@ -28,22 +28,23 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 
 ## Files
 
-| File                                                                 | Models                                                                       |
-| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `CheckoutOffer` + Enums                                      |
-| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeValidationLog` + Enums         |
-| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                        |
-| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                                   |
-| [`05-bundle.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                                    |
-| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models                      |
-| [`07-promotion.prisma`](07-promotion.prisma)                         | `Promotion`                                                                  |
-| [`08-subscription-contract.prisma`](08-subscription-contract.prisma) | `SubscriptionContract`, `ContractLineItem`                                   |
-| [`09-pending-registration.prisma`](09-pending-registration.prisma)   | `PendingRegistration` + `RegistrationStatus`                                 |
-| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                            |
-| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                         |
-| [`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` |
+| File                                                                 | Models                                                                                |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `CheckoutOffer` + Enums                                               |
+| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeHold`, `PromoCodeValidationLog` + Enums |
+| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                                 |
+| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                                            |
+| [`05-bundle.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                                             |
+| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models                               |
+| [`07-promotion.prisma`](07-promotion.prisma)                         | `Promotion`                                                                           |
+| [`08-subscription-contract.prisma`](08-subscription-contract.prisma) | `SubscriptionContract`, `ContractLineItem`                                            |
+| [`09-pending-registration.prisma`](09-pending-registration.prisma)   | `PendingRegistration` + `RegistrationStatus`                                          |
+| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                                     |
+| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                                  |
+| [`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`                                                               |
 
 ## How the consumer uses the fragments
 
@@ -94,7 +95,7 @@ from ever being deleted.
 ### 3. Table names (`@@map`) are canonical
 
 `subscriptions`, `checkout_offers`, `plans`, `plan_versions`, `promo_codes`,
-`promo_code_redemptions`, `promo_code_validation_logs`, `audit_logs`, `bundles`,
+`promo_code_redemptions`, `promo_code_holds`, `promo_code_validation_logs`, `audit_logs`, `bundles`,
 `bundle_versions`, `capability_catalog_entries`, `feature_catalog_entries`,
 `quota_catalog_entries`, `marketing_projections`, `marketing_settings`,
 `promotions`, `subscription_contracts`, `contract_line_items`,

package/schemas/admin-manifest.schema.json

@@ -76,7 +76,7 @@
             "properties": {
                 "source": {
                     "type": "string",
-                    "description": "Path to the source, e.g. 'config/saas.yaml'"
+                    "description": "Where the plans and features were read from: 'database' for the ones an operator publishes, 'given' for a catalogue passed in at start"
                 },
                 "hash": { "type": "string", "pattern": "^sha256-[A-Za-z0-9+/=_-]{32,}$" },
                 "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },

package/schemas/promo-code.schema.json

@@ -129,7 +129,8 @@
                 "value",
                 "durationType",
                 "status",
-                "redemptionsCount"
+                "redemptionsCount",
+                "heldCount"
             ],
             "additionalProperties": false,
             "properties": {
@@ -143,6 +144,11 @@
                 "validUntil": { "type": ["string", "null"], "format": "date-time" },
                 "maxRedemptions": { "type": ["integer", "null"], "minimum": 1 },
                 "redemptionsCount": { "type": "integer", "minimum": 0 },
+                "heldCount": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Slots held for checkouts that started and have not concluded. A code has a free slot while redemptionsCount + heldCount is below maxRedemptions."
+                },
                 "appliesToPlans": {
                     "type": "array",
                     "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" }

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-promo-slot-is-held-through-checkout.postgres.sql

@@ -0,0 +1,69 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a promo code's slot is held from the start of a checkout.
+-- =============================================================================
+--
+-- A sign-up that starts its checkout with a promo code keeps a slot of that
+-- code until the checkout concludes, or until a confirmation of its payment
+-- form can no longer arrive, so that a customer who reaches the payment form is
+-- not refused afterwards because somebody else took the code's last redemption
+-- in between. Run it the same way as the other files in
+-- this directory, before `db push` where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-promo-slot-is-held-through-checkout.postgres.sql
+--
+-- What it touches, in one transaction, and only where `promo_codes` is there:
+--
+--   1. `promo_codes` — gains `heldCount`, the slots held for checkouts, next to
+--      `redemptionsCount`. Every existing code starts at 0: no checkout held a
+--      slot before this file.
+--   2. `promo_code_holds` — created with its indexes and its foreign key to
+--      `promo_codes`. One row per checkout offer holding a slot; the row is
+--      deleted when the hold ends, so the table stays small.
+--
+-- Safe to run again: the column, the table and the indexes are created only
+-- where they are missing, and the 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('promo_codes') IS NULL THEN
+        RAISE NOTICE 'promo_codes is not present — nothing to do; this installation takes no promo codes.';
+        RETURN;
+    END IF;
+
+    ALTER TABLE "promo_codes" ADD COLUMN IF NOT EXISTS "heldCount" INTEGER NOT NULL DEFAULT 0;
+
+    CREATE TABLE IF NOT EXISTS "promo_code_holds" (
+        "id" TEXT NOT NULL,
+        "promoCodeId" TEXT NOT NULL,
+        "checkoutOfferId" TEXT NOT NULL,
+        "expiresAt" TIMESTAMP(3) NOT NULL,
+        "handedOverTx" BIGINT,
+        "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+        CONSTRAINT "promo_code_holds_pkey" PRIMARY KEY ("id")
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS "promo_code_holds_checkoutOfferId_key"
+        ON "promo_code_holds"("checkoutOfferId");
+    CREATE INDEX IF NOT EXISTS "promo_code_holds_promoCodeId_expiresAt_idx"
+        ON "promo_code_holds"("promoCodeId", "expiresAt");
+    CREATE INDEX IF NOT EXISTS "promo_code_holds_expiresAt_idx"
+        ON "promo_code_holds"("expiresAt");
+
+    -- `ADD CONSTRAINT` has no `IF NOT EXISTS`.
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('promo_code_holds')
+           AND conname = 'promo_code_holds_promoCodeId_fkey'
+    ) THEN
+        ALTER TABLE "promo_code_holds"
+            ADD CONSTRAINT "promo_code_holds_promoCodeId_fkey"
+            FOREIGN KEY ("promoCodeId") REFERENCES "promo_codes"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+END $$;
+
+COMMIT;

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/reference-schema.postgres.sql

@@ -17,6 +17,7 @@
 --   prisma-fragments/12-applied-settings.prisma
 --   prisma-fragments/13-subscriber.prisma
 --   prisma-fragments/14-payments.prisma
+--   prisma-fragments/15-subscriber-ledger.prisma
 -- plus the normative constraints from sql/constraints.postgres.sql.
 -- Do not edit by hand — change the fragments/constraints and regenerate.
 
@@ -128,6 +129,7 @@ CREATE TABLE "promo_codes" (
     "validUntil" TIMESTAMP(3),
     "maxRedemptions" INTEGER,
     "redemptionsCount" INTEGER NOT NULL DEFAULT 0,
+    "heldCount" INTEGER NOT NULL DEFAULT 0,
     "appliesToPlans" TEXT[],
     "appliesToBilling" "BillingCycle",
     "firstTimeCustomersOnly" BOOLEAN NOT NULL DEFAULT true,
@@ -164,6 +166,18 @@ CREATE TABLE "promo_code_redemptions" (
     CONSTRAINT "promo_code_redemptions_pkey" PRIMARY KEY ("id")
 );
 
+-- CreateTable
+CREATE TABLE "promo_code_holds" (
+    "id" TEXT NOT NULL,
+    "promoCodeId" TEXT NOT NULL,
+    "checkoutOfferId" TEXT NOT NULL,
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    "handedOverTx" BIGINT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "promo_code_holds_pkey" PRIMARY KEY ("id")
+);
+
 -- CreateTable
 CREATE TABLE "promo_code_validation_logs" (
     "id" TEXT NOT NULL,
@@ -671,6 +685,27 @@ 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")
+);
+
 -- CreateIndex
 CREATE UNIQUE INDEX "subscriptions_tenantId_key" ON "subscriptions"("tenantId");
 
@@ -710,6 +745,15 @@ CREATE INDEX "promo_code_redemptions_promoCodeId_status_idx" ON "promo_code_rede
 -- CreateIndex
 CREATE INDEX "promo_code_redemptions_startsAt_endsAt_idx" ON "promo_code_redemptions"("startsAt", "endsAt");
 
+-- CreateIndex
+CREATE UNIQUE INDEX "promo_code_holds_checkoutOfferId_key" ON "promo_code_holds"("checkoutOfferId");
+
+-- CreateIndex
+CREATE INDEX "promo_code_holds_promoCodeId_expiresAt_idx" ON "promo_code_holds"("promoCodeId", "expiresAt");
+
+-- CreateIndex
+CREATE INDEX "promo_code_holds_expiresAt_idx" ON "promo_code_holds"("expiresAt");
+
 -- CreateIndex
 CREATE INDEX "promo_code_validation_logs_codeAttempt_createdAt_idx" ON "promo_code_validation_logs"("codeAttempt", "createdAt");
 
@@ -887,6 +931,15 @@ 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");
+
 -- AddForeignKey
 ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_planVersionId_fkey" FOREIGN KEY ("planVersionId") REFERENCES "plan_versions"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
@@ -899,6 +952,9 @@ ALTER TABLE "promo_code_redemptions" ADD CONSTRAINT "promo_code_redemptions_prom
 -- AddForeignKey
 ALTER TABLE "promo_code_redemptions" ADD CONSTRAINT "promo_code_redemptions_subscriptionId_fkey" FOREIGN KEY ("subscriptionId") REFERENCES "subscriptions"("id") ON DELETE CASCADE ON UPDATE CASCADE;
 
+-- AddForeignKey
+ALTER TABLE "promo_code_holds" ADD CONSTRAINT "promo_code_holds_promoCodeId_fkey" FOREIGN KEY ("promoCodeId") REFERENCES "promo_codes"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
 -- AddForeignKey
 ALTER TABLE "promo_code_validation_logs" ADD CONSTRAINT "promo_code_validation_logs_promoCodeId_fkey" FOREIGN KEY ("promoCodeId") REFERENCES "promo_codes"("id") ON DELETE SET NULL ON UPDATE CASCADE;
 
@@ -935,6 +991,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.
 -- =============================================================================

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" }
-                        ]
-                    }
-                }
-            }
-        }
-    }
-}