@saasicat/spec 1.0.0-rc.14 → 1.0.0-rc.16

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.14
+    version: 1.0.0-rc.16
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/spec",
-  "version": "1.0.0-rc.14",
+  "version": "1.0.0-rc.16",
   "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

@@ -8,6 +8,12 @@
 // V3 rule: billing and entitlement must not depend on live-mutable catalog
 // tables. `SubscriptionContract` and `ContractLineItem` therefore store full
 // snapshots. Catalog FKs are optional and only audit/trace references.
+//
+// A contract belongs to its subscriber (13-subscriber.prisma), not to the
+// tenant, and outlives the tenant (ADR 0012). `tenantId` is kept as a trace of
+// the tenant it was concluded for, and deliberately has no relation to the
+// application's `Tenant` model: a cascade there deletes the tax record with the
+// tenant, and a restriction keeps a tenant from ever being deleted.
 
 enum SubscriptionContractStatus {
     active
@@ -28,6 +34,19 @@ model SubscriptionContract {
     id       String @id @default(uuid())
     tenantId String
 
+    // Who the contract is between, copied on the day it is concluded: the
+    // subscriber as its record stood, and the issuer as `config/saas.yaml`
+    // named it — null where it named none. Neither copy follows a later change
+    // to the subscriber or the configuration. The invoice email is not copied:
+    // it says how the party is reached, not who it is.
+    subscriberId       String
+    subscriberSnapshot Json
+    issuerSnapshot     Json?
+    // The copies were made by the migration that attached contracts concluded
+    // before subscribers existed, not at conclusion, and are never presented as
+    // what was agreed.
+    partiesMigrated    Boolean @default(false)
+
     status         SubscriptionContractStatus @default(active)
     effectiveFrom  DateTime
     effectiveUntil DateTime?
@@ -50,9 +69,10 @@ model SubscriptionContract {
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
 
-    // tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
 
     @@index([tenantId, status, effectiveFrom])
+    @@index([subscriberId])
     @@index([status])
     @@index([originalOfferId])
     @@map("subscription_contracts")

package/prisma-fragments/13-subscriber.prisma

@@ -0,0 +1,92 @@
+// =============================================================================
+// SaaS platform Prisma fragment: Subscriber, its tenants, its corrections
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// A tenant is where the application keeps a customer's data. The subscriber is
+// the party the contract is with: a customer number and the master data a
+// contract names. A tenant can be deleted; its subscriber stays for as long as
+// a document that has to be kept belongs to it (ADR 0012). That is why nothing
+// here points at the application's `Tenant` model with a cascade — the link
+// below names the tenant as a value and stays after the tenant row is gone.
+//
+// Every model carries `Subscriber` in its name, so it cannot collide with a
+// `Customer` an application already keeps for the people it sells to.
+
+model Subscriber {
+    id String @id @default(uuid())
+
+    // The customer number, counted per installation. The number orders; the
+    // prefix is the one `config/saas.yaml` named when the subscriber was
+    // created, kept beside it so a later prefix renames nobody. Counting starts
+    // at 10001 (sql/constraints.postgres.sql), so numbers have five digits long
+    // before they need a sixth.
+    customerSequence     Int    @unique @default(autoincrement())
+    customerNumberPrefix String @default("")
+
+    // The legal identity. Only the name is required until invoicing requires
+    // the rest; under a running contract these change only as a correction,
+    // recorded in `SubscriberCorrection`.
+    legalName String
+    vatId     String?
+    taxNumber String?
+
+    // Contact details, which change at any time.
+    addressLine1 String?
+    addressLine2 String?
+    postalCode   String?
+    city         String?
+    country      String? // ISO 3166-1 alpha-2
+    invoiceEmail String?
+
+    // Created by the migration that gave every existing tenant its subscriber,
+    // from the application's own tenant record.
+    migrated Boolean @default(false)
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    tenants     SubscriberTenant[]
+    corrections SubscriberCorrection[]
+    contracts   SubscriptionContract[]
+
+    @@map("subscribers")
+}
+
+// Which tenant a subscriber is live for, and which it was before. A subscriber
+// has at most one live tenant and a tenant at most one live subscriber — two
+// partial unique indexes in sql/constraints.postgres.sql, which Prisma cannot
+// express. `unlinkedAt` stays null while the link is live.
+model SubscriberTenant {
+    id           String    @id @default(uuid())
+    subscriberId String
+    tenantId     String
+    linkedAt     DateTime  @default(now())
+    unlinkedAt   DateTime?
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@index([tenantId])
+    @@index([subscriberId])
+    @@map("subscriber_tenants")
+}
+
+// A correction of a subscriber's legal identity: the values it replaced, the
+// values it wrote, why, and who made it. Only the fields that moved are in the
+// two JSON objects. Written in the same transaction as the change, and never
+// rewritten.
+model SubscriberCorrection {
+    id           String   @id @default(uuid())
+    subscriberId String
+    previous     Json
+    corrected    Json
+    reason       String
+    correctedBy  String
+    correctedAt  DateTime
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@index([subscriberId, correctedAt])
+    @@map("subscriber_corrections")
+}

package/prisma-fragments/README.md

@@ -42,6 +42,7 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 | [`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`             |
 
 ## How the consumer uses the fragments
 
@@ -83,6 +84,12 @@ Fields such as `tenantId String` and `userId String?` remain as plain
 string columns in the fragments; the corresponding `@relation` is left as a
 comment. The consumer enables them using their own `Tenant`/`User` model names.
 
+Two models deliberately carry no such pointer: `SubscriptionContract` and
+`SubscriberTenant`. A contract belongs to its subscriber and outlives the tenant
+it was concluded for, so its `tenantId` is a trace — a cascade from the tenant
+would delete the tax record with it, and a restriction would keep the tenant
+from ever being deleted.
+
 ### 3. Table names (`@@map`) are canonical
 
 `subscriptions`, `subscription_payment_methods`, `checkout_offers`, `plans`,
@@ -92,7 +99,8 @@ comment. The consumer enables them using their own `Tenant`/`User` model names.
 `quota_catalog_entries`, `marketing_projections`, `marketing_settings`,
 `promotions`, `subscription_contracts`, `contract_line_items`,
 `pending_registrations`, `payment_event_logs`, `super_admin_users`,
-`super_admin_mfa`, `subscription_bundles`.
+`super_admin_mfa`, `subscription_bundles`, `subscribers`, `subscriber_tenants`,
+`subscriber_corrections`.
 Please do **not change** them — otherwise platform migration scripts and the
 `@saasicat/cli` commands that rely on these names will break.
 
@@ -125,5 +133,12 @@ CREATE UNIQUE INDEX plan_versions_draft_per_plan
 - **No add-on tables (#49)** — `subscription_addons`,
   `unit_addon_versions`, `feature_addon_versions` are not a
   sales surface; only plan versions + bundles are sold.
-- **App-specific tables** (e.g. invoice or bank master data)
-  belong in the schema of the consuming app, not in the platform.
+- **The application's own invoicing** — invoices to the people it sells to, fees
+  it collects from its members, their bank details — belongs in the schema of the
+  consuming app. The subscription business is the platform's: subscribers, their
+  invoices and their payments are decided in
+  [ADR 0012](../../../docs/explanation/adr/0012-the-subscriber-owns-the-commercial-record.md),
+  and every model added for them carries `Subscription` or `Subscriber` in its name,
+  which keeps it clear of the names applications use for their own invoicing. A
+  prefix cannot rule out a name nobody has seen, so `saasicat schema check` reports
+  an application model that carries a platform model's name with a different shape.

package/schemas/plan-catalog.schema.json

@@ -137,6 +137,64 @@
                 }
             }
         },
+        "issuer": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["legalName"],
+            "description": "The legal entity on the operator's side of every contract this installation concludes, and later of every invoice it issues. A contract copies it on the day it is concluded, so the contract keeps naming its counterparty after this block changes. Optional for now: a contract concluded while it is absent records that no issuer was named.",
+            "properties": {
+                "legalName": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The registered name, legal form included, as a contract names the party (e.g. \"Example Software GmbH\")."
+                },
+                "addressLine1": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Street and number."
+                },
+                "addressLine2": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "A second address line, such as a building or a c/o."
+                },
+                "postalCode": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "city": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "country": {
+                    "type": "string",
+                    "pattern": "^[A-Z]{2}$",
+                    "description": "ISO 3166-1 alpha-2 country code, e.g. DE."
+                },
+                "vatId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "VAT identification number, e.g. DE123456789."
+                },
+                "taxNumber": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The tax number the issuer's tax office assigned, where it is stated beside or instead of the VAT identification number."
+                }
+            }
+        },
+        "subscribers": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "How the parties this installation concludes contracts with are numbered.",
+            "properties": {
+                "customerNumberPrefix": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9._/-]{1,16}$",
+                    "description": "Put in front of every customer number assigned from the next start on: `K-` gives K-10001. A customer number keeps the prefix it was assigned with, so changing this renumbers nobody. Omitted, a customer number is the number alone."
+                }
+            }
+        },
         "features": {
             "type": "array",
             "items": {

package/sql/1.0-a-contract-names-its-subscriber.postgres.sql

@@ -0,0 +1,383 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — every contract names the subscriber it is concluded with.
+-- =============================================================================
+--
+-- A tenant is where the application keeps a customer's data; the subscriber is
+-- the party the contract is with (ADR 0012). This file brings an installation
+-- that has contracts to that model. Run it BEFORE `db push`, like the other
+-- files in this directory:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-contract-names-its-subscriber.postgres.sql
+--
+-- What it does, in two transactions:
+--
+--   1. Creates `subscribers`, `subscriber_tenants` and `subscriber_corrections`
+--      and adds `subscriberId`, `subscriberSnapshot`, `issuerSnapshot` and
+--      `partiesMigrated` to `subscription_contracts`, nullable, exactly as the
+--      shipped fragments declare them otherwise. Nothing depends on these yet,
+--      so they stay when the second transaction stops.
+--
+--   The second transaction does the rest, or nothing:
+--
+--   2. Gives every tenant that has a subscription or a contract and no live
+--      subscriber one of its own, marked `migrated`, numbered from 10001 in the
+--      order the tenants first appear.
+--   3. Attaches every contract to its tenant's subscriber and copies the
+--      subscriber onto it, with `partiesMigrated` set: the copy is made now,
+--      not when the contract was concluded, and is never presented as what was
+--      agreed. No issuer is copied — this file cannot read `config/saas.yaml`.
+--   4. Makes `subscriberId` and `subscriberSnapshot` required.
+--
+-- Where the legal name comes from. SaaSiCat keeps no master data of its own
+-- about a tenant; the application does, in its own table. This file finds that
+-- table through the foreign key the application declared on
+-- `subscriptions."tenantId"` — or, where there is none, on
+-- `subscription_contracts."tenantId"` — and takes the tenant's `name` column as
+-- the subscriber's legal name. It stops, naming what it found, when there is no
+-- such foreign key, when that table has no `name` column, or when a tenant has
+-- no row there or an empty name: a subscriber named after an identifier is
+-- worse than a migration that did not run. The tables from step 1 are in place
+-- by then, and `docs/guides/upgrade-to-1.0.md` shows the statement that creates
+-- those subscribers by hand before this file runs again.
+--
+-- The prefix. A customer number keeps the prefix it was assigned with, and this
+-- file cannot read `subscribers.customerNumberPrefix` from `config/saas.yaml`
+-- either. Set it for the session to number the migrated subscribers the way the
+-- installation numbers new ones:
+--
+--   psql "$DATABASE_URL" -c "SET saasicat.customer_number_prefix = 'K-'" \
+--        -f 1.0-a-contract-names-its-subscriber.postgres.sql
+--
+-- Without it they carry the number alone. A value the configuration would
+-- refuse stops the migration.
+--
+-- Row-level security. Where `subscription_contracts`, `subscriptions` or the
+-- tenant table has it and this role would see only some of their rows, the file
+-- stops before it creates a subscriber: run it as a role that bypasses
+-- row-level security.
+--
+-- Safe to run again: every object is created only where it is missing, and once
+-- the link is required the second transaction returns before it reads a row, so
+-- a later run creates nothing and row-level security cannot stop it. The first
+-- transaction still needs a role that owns the tables, as `db push` does. A
+-- tenant an application creates after that without a subscriber is the
+-- application's to give one; this file does not paper over it. The numbering is moved only while it has never handed
+-- out a number. On a database created from `reference-schema.postgres.sql` the
+-- whole file does nothing at all.
+
+BEGIN;
+
+-- 1. The tables and columns, as the fragments declare them ----------------------
+
+DO $$
+BEGIN
+    IF to_regclass('subscription_contracts') IS NULL THEN
+        RAISE NOTICE 'subscription_contracts is not present — nothing to migrate.';
+        RETURN;  -- an installation that never adopted the contract fragment
+    END IF;
+
+    CREATE TABLE IF NOT EXISTS "subscribers" (
+        "id" TEXT NOT NULL,
+        "customerSequence" SERIAL NOT NULL,
+        "customerNumberPrefix" TEXT NOT NULL DEFAULT '',
+        "legalName" TEXT NOT NULL,
+        "vatId" TEXT,
+        "taxNumber" TEXT,
+        "addressLine1" TEXT,
+        "addressLine2" TEXT,
+        "postalCode" TEXT,
+        "city" TEXT,
+        "country" TEXT,
+        "invoiceEmail" TEXT,
+        "migrated" BOOLEAN NOT NULL DEFAULT false,
+        "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        "updatedAt" TIMESTAMP(3) NOT NULL,
+        CONSTRAINT "subscribers_pkey" PRIMARY KEY ("id")
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS "subscribers_customerSequence_key"
+        ON "subscribers"("customerSequence");
+
+    CREATE TABLE IF NOT EXISTS "subscriber_tenants" (
+        "id" TEXT NOT NULL,
+        "subscriberId" TEXT NOT NULL,
+        "tenantId" TEXT NOT NULL,
+        "linkedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        "unlinkedAt" TIMESTAMP(3),
+        CONSTRAINT "subscriber_tenants_pkey" PRIMARY KEY ("id")
+    );
+    CREATE INDEX IF NOT EXISTS "subscriber_tenants_tenantId_idx"
+        ON "subscriber_tenants"("tenantId");
+    CREATE INDEX IF NOT EXISTS "subscriber_tenants_subscriberId_idx"
+        ON "subscriber_tenants"("subscriberId");
+    CREATE UNIQUE INDEX IF NOT EXISTS subscriber_tenants_live_per_tenant
+        ON subscriber_tenants ("tenantId") WHERE "unlinkedAt" IS NULL;
+    CREATE UNIQUE INDEX IF NOT EXISTS subscriber_tenants_live_per_subscriber
+        ON subscriber_tenants ("subscriberId") WHERE "unlinkedAt" IS NULL;
+
+    CREATE TABLE IF NOT EXISTS "subscriber_corrections" (
+        "id" TEXT NOT NULL,
+        "subscriberId" TEXT NOT NULL,
+        "previous" JSONB NOT NULL,
+        "corrected" JSONB NOT NULL,
+        "reason" TEXT NOT NULL,
+        "correctedBy" TEXT NOT NULL,
+        "correctedAt" TIMESTAMP(3) NOT NULL,
+        CONSTRAINT "subscriber_corrections_pkey" PRIMARY KEY ("id")
+    );
+    CREATE INDEX IF NOT EXISTS "subscriber_corrections_subscriberId_correctedAt_idx"
+        ON "subscriber_corrections"("subscriberId", "correctedAt");
+
+    ALTER TABLE "subscription_contracts" ADD COLUMN IF NOT EXISTS "subscriberId" TEXT;
+    ALTER TABLE "subscription_contracts" ADD COLUMN IF NOT EXISTS "subscriberSnapshot" JSONB;
+    ALTER TABLE "subscription_contracts" ADD COLUMN IF NOT EXISTS "issuerSnapshot" JSONB;
+    ALTER TABLE "subscription_contracts"
+        ADD COLUMN IF NOT EXISTS "partiesMigrated" BOOLEAN NOT NULL DEFAULT false;
+    CREATE INDEX IF NOT EXISTS "subscription_contracts_subscriberId_idx"
+        ON "subscription_contracts"("subscriberId");
+
+    -- `ADD CONSTRAINT` has no `IF NOT EXISTS`, so each foreign key is added only
+    -- where its name is not taken yet.
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscriber_tenants')
+           AND conname = 'subscriber_tenants_subscriberId_fkey'
+    ) THEN
+        ALTER TABLE "subscriber_tenants"
+            ADD CONSTRAINT "subscriber_tenants_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_corrections')
+           AND conname = 'subscriber_corrections_subscriberId_fkey'
+    ) THEN
+        ALTER TABLE "subscriber_corrections"
+            ADD CONSTRAINT "subscriber_corrections_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('subscription_contracts')
+           AND conname = 'subscription_contracts_subscriberId_fkey'
+    ) THEN
+        ALTER TABLE "subscription_contracts"
+            ADD CONSTRAINT "subscription_contracts_subscriberId_fkey"
+            FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+
+    -- The numbering starts at 10001, as `constraints.postgres.sql` has it, and
+    -- is moved only while it has never handed out a number.
+    ALTER SEQUENCE IF EXISTS "subscribers_customerSequence_seq" START WITH 10001;
+    PERFORM setval(format('%I.%I', schemaname, sequencename)::regclass, 10001, false)
+       FROM pg_sequences
+      WHERE schemaname = current_schema()
+        AND sequencename = 'subscribers_customerSequence_seq'
+        AND last_value IS NULL;
+END $$;
+
+COMMIT;
+
+BEGIN;
+
+DO $$
+DECLARE
+    prefix text := coalesce(current_setting('saasicat.customer_number_prefix', true), '');
+    hidden text[];
+    tenant_table regclass;
+    tenant_key text;
+    unnamed text[];
+    tenant record;
+    new_subscriber text;
+BEGIN
+    IF to_regclass('subscription_contracts') IS NULL THEN
+        RETURN;  -- said once already, by the first transaction
+    END IF;
+
+    -- Run through already: the link is required, and nothing below is left to
+    -- do. Asked of the catalogue rather than of the rows, so row-level security
+    -- cannot change the answer, and an entrypoint that applies this file again
+    -- as the application's own role is not stopped by the guard below. From
+    -- here on, a tenant without a subscriber is the application's to give one.
+    IF (SELECT attnotnull FROM pg_attribute
+         WHERE attrelid = to_regclass('subscription_contracts')
+           AND attname = 'subscriberId'
+           AND attnum > 0
+           AND NOT attisdropped) THEN
+        RETURN;
+    END IF;
+
+    -- The application's tenant table: the one a single-column foreign key on
+    -- "tenantId" points at, from the subscriptions first. Read off the
+    -- catalogue, before any row is.
+    SELECT c.confrelid::regclass, referenced.attname
+      INTO tenant_table, tenant_key
+      FROM pg_constraint c
+      JOIN pg_attribute referencing
+        ON referencing.attrelid = c.conrelid AND referencing.attnum = c.conkey[1]
+      JOIN pg_attribute referenced
+        ON referenced.attrelid = c.confrelid AND referenced.attnum = c.confkey[1]
+     WHERE c.contype = 'f'
+       AND cardinality(c.conkey) = 1
+       AND referencing.attname = 'tenantId'
+       AND c.conrelid IN (to_regclass('subscriptions'), to_regclass('subscription_contracts'))
+     ORDER BY c.conrelid = to_regclass('subscriptions') DESC, c.conname
+     LIMIT 1;
+
+    -- A table under row-level security shows this role only the rows its
+    -- policies allow. Hidden contracts or subscriptions would leave tenants
+    -- without a subscriber and fail the required link with a message about
+    -- null values; hidden rows of the tenant table would be reported as tenants
+    -- without a name. Either way the message would name the wrong cause.
+    SELECT array_agg(c.relname::text ORDER BY c.relname)
+      INTO hidden
+      FROM pg_class c
+     WHERE c.oid IN (
+               to_regclass('subscription_contracts'), to_regclass('subscriptions'), tenant_table
+           )
+       AND c.relrowsecurity
+       AND (c.relforcerowsecurity OR NOT pg_has_role(current_user, c.relowner, 'MEMBER'))
+       AND NOT EXISTS (
+           SELECT 1 FROM pg_roles r
+            WHERE r.rolname = current_user AND (r.rolsuper OR r.rolbypassrls)
+       );
+    IF hidden IS NOT NULL THEN
+        RAISE EXCEPTION
+            'Cannot see every row of % under row-level security as role %, so subscribers would '
+            'be missing or unnamed for the tenants it hides. Run this file as a role that '
+            'bypasses row-level security. No subscriber was created.',
+            array_to_string(hidden, ', '),
+            current_user;
+    END IF;
+
+    IF prefix <> '' AND prefix !~ '^[A-Za-z0-9._/-]{1,16}$' THEN
+        RAISE EXCEPTION
+            'saasicat.customer_number_prefix is %, which config/saas.yaml would refuse: a prefix '
+            'is 1 to 16 letters, digits, dots, slashes, hyphens or underscores. No subscriber '
+            'was created.',
+            quote_literal(prefix);
+    END IF;
+
+    -- 2. A subscriber for every tenant that has none ---------------------------
+
+    -- The tenants in question, each with the moment it first appears, so the
+    -- numbers follow the order the customers came in. Worked out once, because
+    -- the refusal and the creation below have to agree about who is meant.
+    CREATE TEMP TABLE _saasicat_tenants ON COMMIT DROP AS
+    SELECT seen."tenantId" AS tenant_id, min(seen.at) AS first_seen, NULL::text AS legal_name
+      FROM (
+          SELECT "tenantId", "createdAt" AS at FROM "subscription_contracts"
+      ) seen
+     GROUP BY seen."tenantId";
+    IF to_regclass('subscriptions') IS NOT NULL THEN
+        INSERT INTO _saasicat_tenants (tenant_id, first_seen)
+        SELECT s."tenantId", s."createdAt"
+          FROM "subscriptions" s
+         WHERE NOT EXISTS (SELECT 1 FROM _saasicat_tenants t WHERE t.tenant_id = s."tenantId");
+        UPDATE _saasicat_tenants t
+           SET first_seen = least(t.first_seen, s."createdAt")
+          FROM "subscriptions" s
+         WHERE s."tenantId" = t.tenant_id;
+    END IF;
+    DELETE FROM _saasicat_tenants t
+     WHERE EXISTS (
+         SELECT 1 FROM "subscriber_tenants" l
+          WHERE l."tenantId" = t.tenant_id AND l."unlinkedAt" IS NULL
+     );
+
+    IF EXISTS (SELECT 1 FROM _saasicat_tenants) THEN
+        IF tenant_table IS NULL THEN
+            RAISE EXCEPTION
+                'Cannot create the subscribers of % tenant(s) (%): no foreign key on '
+                'subscriptions."tenantId" or subscription_contracts."tenantId" names the '
+                'application''s tenant table, so there is nowhere to read a legal name from. '
+                'The tables are in place: create their subscribers as docs/guides/upgrade-to-1.0.md '
+                'shows and run this file again. No subscriber was created.',
+                (SELECT count(*) FROM _saasicat_tenants),
+                (SELECT array_to_string((array_agg(tenant_id ORDER BY tenant_id))[1:10], ', ')
+                   FROM _saasicat_tenants);
+        END IF;
+
+        IF NOT EXISTS (
+            SELECT 1 FROM pg_attribute
+             WHERE attrelid = tenant_table
+               AND attname = 'name'
+               AND attnum > 0
+               AND NOT attisdropped
+        ) THEN
+            RAISE EXCEPTION
+                'Cannot create the subscribers of % tenant(s): their table % has no "name" column '
+                'to take a legal name from. The tables are in place: create their subscribers as '
+                'docs/guides/upgrade-to-1.0.md shows and run this file again. No subscriber was '
+                'created.',
+                (SELECT count(*) FROM _saasicat_tenants),
+                tenant_table;
+        END IF;
+
+        EXECUTE format(
+            'UPDATE _saasicat_tenants t SET legal_name = nullif(btrim(a."name"::text), '''') '
+            'FROM %s a WHERE a.%I::text = t.tenant_id',
+            tenant_table, tenant_key
+        );
+
+        SELECT array_agg(tenant_id ORDER BY tenant_id)
+          INTO unnamed
+          FROM _saasicat_tenants
+         WHERE legal_name IS NULL;
+        IF unnamed IS NOT NULL THEN
+            RAISE EXCEPTION
+                'Cannot create the subscribers of % tenant(s) (%): % has no row for them, or an '
+                'empty name, and a subscriber is not named after an identifier. The tables are in '
+                'place: create their subscribers as docs/guides/upgrade-to-1.0.md shows and run '
+                'this file again. No subscriber was created.',
+                array_length(unnamed, 1),
+                array_to_string(unnamed[1:10], ', ')
+                    || CASE WHEN array_length(unnamed, 1) > 10 THEN ', …' ELSE '' END,
+                tenant_table;
+        END IF;
+
+        -- One at a time, in the order the tenants came in: the numbers are drawn
+        -- in exactly that order, which a set-based insert does not promise.
+        FOR tenant IN
+            SELECT tenant_id, legal_name FROM _saasicat_tenants ORDER BY first_seen, tenant_id
+        LOOP
+            new_subscriber := gen_random_uuid()::text;
+            INSERT INTO "subscribers"
+                ("id", "customerNumberPrefix", "legalName", "migrated", "updatedAt")
+            VALUES (new_subscriber, prefix, tenant.legal_name, true, CURRENT_TIMESTAMP);
+            INSERT INTO "subscriber_tenants" ("id", "subscriberId", "tenantId")
+            VALUES (gen_random_uuid()::text, new_subscriber, tenant.tenant_id);
+        END LOOP;
+    END IF;
+
+    -- 3. Every contract names its tenant's subscriber -------------------------
+
+    UPDATE "subscription_contracts" c
+       SET "subscriberId" = s."id",
+           "subscriberSnapshot" = jsonb_build_object(
+               'customerNumber', s."customerNumberPrefix" || s."customerSequence",
+               'legalName', s."legalName",
+               'vatId', s."vatId",
+               'taxNumber', s."taxNumber",
+               'addressLine1', s."addressLine1",
+               'addressLine2', s."addressLine2",
+               'postalCode', s."postalCode",
+               'city', s."city",
+               'country', s."country"
+           ),
+           "partiesMigrated" = true
+      FROM "subscriber_tenants" l
+      JOIN "subscribers" s ON s."id" = l."subscriberId"
+     WHERE l."tenantId" = c."tenantId"
+       AND l."unlinkedAt" IS NULL
+       AND c."subscriberId" IS NULL;
+
+    -- 4. Required from here on -------------------------------------------------
+
+    ALTER TABLE "subscription_contracts" ALTER COLUMN "subscriberId" SET NOT NULL;
+    ALTER TABLE "subscription_contracts" ALTER COLUMN "subscriberSnapshot" SET NOT NULL;
+END $$;
+
+COMMIT;

package/sql/constraints.postgres.sql

@@ -46,3 +46,27 @@ ALTER TABLE applied_settings
     DROP CONSTRAINT IF EXISTS applied_settings_is_a_singleton;
 ALTER TABLE applied_settings
     ADD CONSTRAINT applied_settings_is_a_singleton CHECK ("id" = 'installation');
+
+-- 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
+-- indexes, because a link that is over must not count against the next one.
+CREATE UNIQUE INDEX IF NOT EXISTS subscriber_tenants_live_per_tenant
+    ON subscriber_tenants ("tenantId") WHERE "unlinkedAt" IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS subscriber_tenants_live_per_subscriber
+    ON subscriber_tenants ("subscriberId") WHERE "unlinkedAt" IS NULL;
+
+-- Customer numbers count from 10001, so a number has five digits up to 99999
+-- and none reads as a count of subscribers. Two statements: the first makes
+-- 10001 where the sequence starts over, which a restart of its identity reads,
+-- and the second moves a sequence that has never handed out a number there. A
+-- second run finds the start already set and the sequence used, and an
+-- installation without the subscriber tables has no such sequence.
+ALTER SEQUENCE IF EXISTS "subscribers_customerSequence_seq" START WITH 10001;
+
+SELECT setval(format('%I.%I', schemaname, sequencename)::regclass, 10001, false)
+  FROM pg_sequences
+ WHERE schemaname = current_schema()
+   AND sequencename = 'subscribers_customerSequence_seq'
+   AND last_value IS NULL;

package/sql/reference-schema.postgres.sql

@@ -15,6 +15,7 @@
 --   prisma-fragments/10-super-admin.prisma
 --   prisma-fragments/11-subscription-bundle.prisma
 --   prisma-fragments/12-applied-settings.prisma
+--   prisma-fragments/13-subscriber.prisma
 -- plus the normative constraints from sql/constraints.postgres.sql.
 -- Do not edit by hand — change the fragments/constraints and regenerate.
 
@@ -437,6 +438,10 @@ CREATE TABLE "promotions" (
 CREATE TABLE "subscription_contracts" (
     "id" TEXT NOT NULL,
     "tenantId" TEXT NOT NULL,
+    "subscriberId" TEXT NOT NULL,
+    "subscriberSnapshot" JSONB NOT NULL,
+    "issuerSnapshot" JSONB,
+    "partiesMigrated" BOOLEAN NOT NULL DEFAULT false,
     "status" "SubscriptionContractStatus" NOT NULL DEFAULT 'active',
     "effectiveFrom" TIMESTAMP(3) NOT NULL,
     "effectiveUntil" TIMESTAMP(3),
@@ -595,6 +600,51 @@ CREATE TABLE "settings_changes" (
     CONSTRAINT "settings_changes_pkey" PRIMARY KEY ("id")
 );
 
+-- CreateTable
+CREATE TABLE "subscribers" (
+    "id" TEXT NOT NULL,
+    "customerSequence" SERIAL NOT NULL,
+    "customerNumberPrefix" TEXT NOT NULL DEFAULT '',
+    "legalName" TEXT NOT NULL,
+    "vatId" TEXT,
+    "taxNumber" TEXT,
+    "addressLine1" TEXT,
+    "addressLine2" TEXT,
+    "postalCode" TEXT,
+    "city" TEXT,
+    "country" TEXT,
+    "invoiceEmail" TEXT,
+    "migrated" BOOLEAN NOT NULL DEFAULT false,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "subscribers_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "subscriber_tenants" (
+    "id" TEXT NOT NULL,
+    "subscriberId" TEXT NOT NULL,
+    "tenantId" TEXT NOT NULL,
+    "linkedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "unlinkedAt" TIMESTAMP(3),
+
+    CONSTRAINT "subscriber_tenants_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "subscriber_corrections" (
+    "id" TEXT NOT NULL,
+    "subscriberId" TEXT NOT NULL,
+    "previous" JSONB NOT NULL,
+    "corrected" JSONB NOT NULL,
+    "reason" TEXT NOT NULL,
+    "correctedBy" TEXT NOT NULL,
+    "correctedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "subscriber_corrections_pkey" PRIMARY KEY ("id")
+);
+
 -- CreateIndex
 CREATE UNIQUE INDEX "subscriptions_tenantId_key" ON "subscriptions"("tenantId");
 
@@ -730,6 +780,9 @@ CREATE INDEX "promotions_targetType_validFrom_validTo_idx" ON "promotions"("targ
 -- CreateIndex
 CREATE INDEX "subscription_contracts_tenantId_status_effectiveFrom_idx" ON "subscription_contracts"("tenantId", "status", "effectiveFrom");
 
+-- CreateIndex
+CREATE INDEX "subscription_contracts_subscriberId_idx" ON "subscription_contracts"("subscriberId");
+
 -- CreateIndex
 CREATE INDEX "subscription_contracts_status_idx" ON "subscription_contracts"("status");
 
@@ -781,6 +834,18 @@ CREATE UNIQUE INDEX "settings_changes_seq_key" ON "settings_changes"("seq");
 -- CreateIndex
 CREATE INDEX "settings_changes_acknowledgedAt_noticedAt_idx" ON "settings_changes"("acknowledgedAt", "noticedAt");
 
+-- CreateIndex
+CREATE UNIQUE INDEX "subscribers_customerSequence_key" ON "subscribers"("customerSequence");
+
+-- CreateIndex
+CREATE INDEX "subscriber_tenants_tenantId_idx" ON "subscriber_tenants"("tenantId");
+
+-- CreateIndex
+CREATE INDEX "subscriber_tenants_subscriberId_idx" ON "subscriber_tenants"("subscriberId");
+
+-- CreateIndex
+CREATE INDEX "subscriber_corrections_subscriberId_correctedAt_idx" ON "subscriber_corrections"("subscriberId", "correctedAt");
+
 -- AddForeignKey
 ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_planVersionId_fkey" FOREIGN KEY ("planVersionId") REFERENCES "plan_versions"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
@@ -808,6 +873,9 @@ ALTER TABLE "bundle_versions" ADD CONSTRAINT "bundle_versions_bundleId_fkey" FOR
 -- AddForeignKey
 ALTER TABLE "bundle_versions" ADD CONSTRAINT "bundle_versions_baseVersionId_fkey" FOREIGN KEY ("baseVersionId") REFERENCES "bundle_versions"("id") ON DELETE SET NULL ON UPDATE CASCADE;
 
+-- AddForeignKey
+ALTER TABLE "subscription_contracts" ADD CONSTRAINT "subscription_contracts_subscriberId_fkey" FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
 -- AddForeignKey
 ALTER TABLE "contract_line_items" ADD CONSTRAINT "contract_line_items_contractId_fkey" FOREIGN KEY ("contractId") REFERENCES "subscription_contracts"("id") ON DELETE CASCADE ON UPDATE CASCADE;
 
@@ -817,6 +885,12 @@ ALTER TABLE "subscription_bundles" ADD CONSTRAINT "subscription_bundles_subscrip
 -- AddForeignKey
 ALTER TABLE "subscription_bundles" ADD CONSTRAINT "subscription_bundles_bundleVersionId_fkey" FOREIGN KEY ("bundleVersionId") REFERENCES "bundle_versions"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
+-- AddForeignKey
+ALTER TABLE "subscriber_tenants" ADD CONSTRAINT "subscriber_tenants_subscriberId_fkey" FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "subscriber_corrections" ADD CONSTRAINT "subscriber_corrections_subscriberId_fkey" FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
 -- =============================================================================
 -- SaaSiCat — normative PostgreSQL constraints the Prisma DSL cannot express.
 -- =============================================================================
@@ -865,3 +939,27 @@ ALTER TABLE applied_settings
     DROP CONSTRAINT IF EXISTS applied_settings_is_a_singleton;
 ALTER TABLE applied_settings
     ADD CONSTRAINT applied_settings_is_a_singleton CHECK ("id" = 'installation');
+
+-- 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
+-- indexes, because a link that is over must not count against the next one.
+CREATE UNIQUE INDEX IF NOT EXISTS subscriber_tenants_live_per_tenant
+    ON subscriber_tenants ("tenantId") WHERE "unlinkedAt" IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS subscriber_tenants_live_per_subscriber
+    ON subscriber_tenants ("subscriberId") WHERE "unlinkedAt" IS NULL;
+
+-- Customer numbers count from 10001, so a number has five digits up to 99999
+-- and none reads as a count of subscribers. Two statements: the first makes
+-- 10001 where the sequence starts over, which a restart of its identity reads,
+-- and the second moves a sequence that has never handed out a number there. A
+-- second run finds the start already set and the sequence used, and an
+-- installation without the subscriber tables has no such sequence.
+ALTER SEQUENCE IF EXISTS "subscribers_customerSequence_seq" START WITH 10001;
+
+SELECT setval(format('%I.%I', schemaname, sequencename)::regclass, 10001, false)
+  FROM pg_sequences
+ WHERE schemaname = current_schema()
+   AND sequencename = 'subscribers_customerSequence_seq'
+   AND last_value IS NULL;