@saasicat/spec 1.0.0-rc.25 → 1.0.0-rc.26

package/prisma-fragments/README.md

@@ -28,27 +28,30 @@ 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`, `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`, `SubscriberTaxOriginChange`, `SubscriberVatIdCheck` |
-| [`14-payments.prisma`](14-payments.prisma)                                   | `SubscriberPaymentMethod`, `SubscriberPaymentMethodSetup`, `PaymentEventLog`                                  |
-| [`15-subscriber-ledger.prisma`](15-subscriber-ledger.prisma)                 | `SubscriberLedgerEntry`                                                                                       |
-| [`16-maintenance-window.prisma`](16-maintenance-window.prisma)               | `MaintenanceWindow`                                                                                           |
-| [`17-subscription-notice.prisma`](17-subscription-notice.prisma)             | `SubscriptionNotice`                                                                                          |
-| [`18-version-retirement.prisma`](18-version-retirement.prisma)               | `VersionRetirement`                                                                                           |
-| [`19-bundle-version-retirement.prisma`](19-bundle-version-retirement.prisma) | `BundleVersionRetirement`                                                                                     |
+| 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`, `SubscriberTaxOriginChange`, `SubscriberVatIdCheck` |
+| [`14-payments.prisma`](14-payments.prisma)                                         | `SubscriberPaymentMethod`, `SubscriberPaymentMethodSetup`, `PaymentEventLog`                                  |
+| [`15-subscriber-ledger.prisma`](15-subscriber-ledger.prisma)                       | `SubscriberLedgerEntry`                                                                                       |
+| [`16-maintenance-window.prisma`](16-maintenance-window.prisma)                     | `MaintenanceWindow`                                                                                           |
+| [`17-subscription-notice.prisma`](17-subscription-notice.prisma)                   | `SubscriptionNotice`                                                                                          |
+| [`18-version-retirement.prisma`](18-version-retirement.prisma)                     | `VersionRetirement`                                                                                           |
+| [`19-bundle-version-retirement.prisma`](19-bundle-version-retirement.prisma)       | `BundleVersionRetirement`                                                                                     |
+| [`20-subscription-invoice.prisma`](20-subscription-invoice.prisma)                 | `SubscriptionInvoice`, `SubscriptionInvoiceLine`, `SubscriptionInvoiceNumber`, `SubscriptionInvoiceDocument`  |
+| [`21-feature-withdrawal.prisma`](21-feature-withdrawal.prisma)                     | `FeatureWithdrawal`                                                                                           |
+| [`22-subscription-invoice-archive.prisma`](22-subscription-invoice-archive.prisma) | `SubscriptionInvoiceArchive`                                                                                  |
 
 ## How the consumer uses the fragments
 

package/schemas/admin-manifest.schema.json

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

package/schemas/plan-catalog.schema.json

@@ -258,6 +258,34 @@
                 }
             }
         },
+        "invoicing": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["numberPrefix", "paymentTermDays"],
+            "description": "Invoices issued from the charge journal (SC-PRIC-022). Named exactly where the application wires `tenantBilling.chargeJournal.invoices`; the start refuses the one without the other. Needs `tax`, whose adapter decides an invoice's treatment, checks its content and computes its tax, and `issuer`, the party every invoice names.",
+            "properties": {
+                "numberPrefix": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9]{1,16}$",
+                    "description": "Put in front of every invoice number: `AHP` gives AHP-2026-000123. The installation is one range of its issuer, numbered from 1 again each year as `timeZone` counts it (SC-PRIC-072). Once an invoice exists, the start refuses another prefix (SC-PRIC-024)."
+                },
+                "paymentTermDays": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Days from an invoice's issue date to the day it is due (SC-PRIC-046): 14 makes an invoice issued on 1 March due on 15 March; 0 makes it due on the day it is issued. Required, because a term is part of what the subscriber is asked to pay and none is assumed."
+                },
+                "footer": {
+                    "type": "array",
+                    "maxItems": 6,
+                    "items": {
+                        "type": "string",
+                        "pattern": "\\S",
+                        "maxLength": 120
+                    },
+                    "description": "Lines a business letter of the issuer has to state beyond the invoice's own content, printed at the foot of every page of its document: the register court and number and the managing directors of a GmbH (§ 35a GmbHG), a bank account to pay into, and the like — e.g. [\"Amtsgericht München HRB 123456 · Geschäftsführer: Erika Muster\", \"IBAN DE02 1203 0000 0000 2020 51 · BIC BYLADEM1001\"]. An invoice copies them on its issue date, so a later change leaves the invoices issued before as they were (SC-PRIC-077). At most six lines of 120 characters, which is what fits the foot of a page."
+                }
+            }
+        },
         "payments": {
             "type": "object",
             "additionalProperties": false,
@@ -419,5 +447,8 @@
             }
         }
     },
-    "dependentRequired": { "tax": ["timeZone"] }
+    "dependentRequired": {
+        "tax": ["timeZone"],
+        "invoicing": ["tax", "issuer"]
+    }
 }

package/schemas/subscriber-ledger.schema.json

@@ -88,9 +88,10 @@
                 "bundleBooking",
                 "bundleChange",
                 "credit",
-                "correction"
+                "correction",
+                "reductionTakenBack"
             ],
-            "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. bundleChange: what an add-on's switch to a dearer version adds for the rest of its period. 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."
+            "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. bundleChange: what an add-on's switch to a dearer version adds for the rest of its period. 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. reductionTakenBack: a reduction granted in advance, taken back for the days it no longer covers — the feature it was granted for came back, or what it reduced ended at once."
         },
         "SubscriberChargeSource": {
             "type": "string",

package/sql/1.0-a-correction-carries-its-order.postgres.sql

@@ -25,10 +25,19 @@
 -- index over `correctedAt` gives way to one over `seq`, the order the list is
 -- read in. On a database created from `reference-schema.postgres.sql` the file
 -- does nothing at all.
+--
+-- Row-level security. The numbering reaches only the rows this role may read
+-- and update. Where `subscriber_corrections` is under a policy that keeps some
+-- of them from it, the file stops before anything changes: run it as a role
+-- that reaches every row — one that bypasses row-level security, or with
+-- whatever lifts your policy.
 
 BEGIN;
 
 DO $$
+DECLARE
+    renumbered bigint;
+    numbered   bigint;
 BEGIN
     IF to_regclass('subscriber_corrections') IS NULL THEN
         RAISE NOTICE 'subscriber_corrections is not present — nothing to migrate.';
@@ -56,11 +65,25 @@ BEGIN
     FROM ordered
     WHERE c."id" = ordered."id";
 
-    PERFORM setval(
-        pg_get_serial_sequence('subscriber_corrections', 'seq'),
-        (SELECT COALESCE(MAX("seq"), 0) + 1 FROM "subscriber_corrections"),
-        false
+    -- Adding the column numbered every row, whatever this role may reach, so
+    -- the sequence already stands after the last of them. The renumbering
+    -- reaches only the rows row-level security lets this role read and update:
+    -- a row it misses keeps the number the table's storage order gave it, out
+    -- of the order the operator saw, and may share it with a row renumbered.
+    -- So the rows renumbered are counted against the numbers handed out.
+    GET DIAGNOSTICS renumbered = ROW_COUNT;
+    numbered := COALESCE(
+        pg_sequence_last_value(pg_get_serial_sequence('subscriber_corrections', 'seq')::regclass),
+        0
     );
+    IF renumbered < numbered THEN
+        RAISE EXCEPTION
+            'Cannot reach every row of subscriber_corrections under row-level security as role %: '
+            '% of % corrections were renumbered, and the others would keep the order the table '
+            'stores them in. Run this file as a role that may read and update every row. Nothing '
+            'was changed.',
+            current_user, renumbered, numbered;
+    END IF;
 END $$;
 
 DO $$

package/sql/1.0-a-feature-is-withdrawn.postgres.sql

@@ -0,0 +1,49 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a feature is withdrawn for a reason outside the platform.
+-- =============================================================================
+--
+-- One table, additive: `feature_withdrawals` keeps every feature an operator
+-- withdraws because an external service stopped or a law changed — which
+-- feature, why, from when, the reductions named, when it was lifted, and when
+-- the subscriptions it reaches were told. What it means for each subscription
+-- is a `subscription_notices` row of kind `feature-withdrawn`, which
+-- `1.0-a-subscriber-is-told-once.postgres.sql` creates.
+--
+-- Run it the same way as the other files in this directory, before `db push`
+-- where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-feature-is-withdrawn.postgres.sql
+--
+-- The partial unique index is what holds a feature to one withdrawal not yet
+-- lifted: every open row of a feature carries the same key, so a second one
+-- collides, and a withdrawal that is lifted leaves the index.
+--
+-- Safe to run again: the table and both indexes are created only where they are
+-- missing. On a database created from `reference-schema.postgres.sql` with
+-- `constraints.postgres.sql` applied, the whole file does nothing at all.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS "feature_withdrawals" (
+    "id" TEXT NOT NULL,
+    "featureKey" TEXT NOT NULL,
+    "reason" TEXT NOT NULL,
+    "effectiveFrom" TIMESTAMP(3) NOT NULL,
+    "liftedFrom" TIMESTAMP(3),
+    "reductions" JSONB NOT NULL DEFAULT '[]',
+    "announcedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "announcedBy" TEXT NOT NULL,
+    "liftedAt" TIMESTAMP(3),
+    "liftedBy" TEXT,
+    "toldAt" TIMESTAMP(3),
+
+    CONSTRAINT "feature_withdrawals_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "feature_withdrawals_featureKey_idx"
+    ON "feature_withdrawals"("featureKey");
+
+CREATE UNIQUE INDEX IF NOT EXISTS feature_withdrawals_one_open_per_feature
+    ON feature_withdrawals ("featureKey") WHERE "liftedFrom" IS NULL;
+
+COMMIT;

package/sql/1.0-an-invoice-document-is-archived.postgres.sql

@@ -0,0 +1,123 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — an invoice's document is archived and checked.
+-- =============================================================================
+--
+-- Where each invoice's document stands, and the database archive that keeps
+-- the documents (#276 step 6). Needed where `tenantBilling.chargeJournal.invoices`
+-- is configured. Run it AFTER `db push`, and after
+-- `1.0-an-invoice-is-issued.postgres.sql`, whose `subscription_invoices` table
+-- both point at:
+--
+--   psql "$DATABASE_URL" -f 1.0-an-invoice-document-is-archived.postgres.sql
+--
+-- After, because `db push` cannot create triggers, and on a database whose
+-- invoices it has only just created, a run before it finds nothing to protect.
+-- A run before it as well, as an entrypoint applying every shipped file makes,
+-- does no harm; the start refuses invoices until the triggers are in place.
+--
+-- What it touches, in one transaction:
+--
+--   `subscription_invoice_documents` — created with its index and its foreign
+--   key to `subscription_invoices`: the checksum recorded when an invoice's
+--   document was rendered, when the archive confirmed it, which run holds its
+--   mail, and when the mail took it.
+--
+--   `subscription_invoice_archive` — created with its foreign key to
+--   `subscription_invoices`: one file per invoice. And two triggers that refuse
+--   every UPDATE and DELETE of a row and every TRUNCATE of the table, whoever
+--   asks — a TRUNCATE fires no row trigger, and one cascading from
+--   `subscribers` would otherwise empty the archive: an archived invoice is
+--   kept as it was issued. The triggers are the one part of this file a
+--   database created from `reference-schema.postgres.sql` does not have yet,
+--   because that file holds plain statements only.
+--
+-- Skipped, with a notice, where `subscription_invoices` is missing. Nothing is
+-- backfilled: an invoice issued before this ran has no document recorded and
+-- is rendered by the next run.
+--
+-- Safe to run again: every table and index is created only where it is
+-- missing, each foreign key only where its name is not taken, and the trigger
+-- function is replaced and the triggers created again in the same transaction.
+
+BEGIN;
+
+DO $$
+BEGIN
+    IF to_regclass('subscription_invoices') IS NULL THEN
+        RAISE NOTICE 'subscription_invoices is not present — the invoice document tables are not created; run 1.0-an-invoice-is-issued.postgres.sql first.';
+        RETURN;
+    END IF;
+
+    CREATE TABLE IF NOT EXISTS "subscription_invoice_documents" (
+        "invoiceId" TEXT NOT NULL,
+        "checksum" TEXT NOT NULL,
+        "mediaType" TEXT NOT NULL,
+        "fileName" TEXT NOT NULL,
+        "size" INTEGER NOT NULL,
+        "renderedAt" TIMESTAMP(3) NOT NULL,
+        "archivedAt" TIMESTAMP(3),
+        "deliveryClaimedAt" TIMESTAMP(3),
+        "deliveredAt" TIMESTAMP(3),
+        "deliveredTo" TEXT,
+        CONSTRAINT "subscription_invoice_documents_pkey" PRIMARY KEY ("invoiceId")
+    );
+    CREATE INDEX IF NOT EXISTS "subscription_invoice_documents_archivedAt_idx"
+        ON "subscription_invoice_documents"("archivedAt");
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'subscription_invoice_documents_invoiceId_fkey'
+    ) THEN
+        ALTER TABLE "subscription_invoice_documents"
+            ADD CONSTRAINT "subscription_invoice_documents_invoiceId_fkey"
+            FOREIGN KEY ("invoiceId") REFERENCES "subscription_invoices"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+
+    CREATE TABLE IF NOT EXISTS "subscription_invoice_archive" (
+        "invoiceId" TEXT NOT NULL,
+        "checksum" TEXT NOT NULL,
+        "mediaType" TEXT NOT NULL,
+        "fileName" TEXT NOT NULL,
+        "content" BYTEA NOT NULL,
+        "archivedAt" TIMESTAMP(3) NOT NULL,
+        CONSTRAINT "subscription_invoice_archive_pkey" PRIMARY KEY ("invoiceId")
+    );
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'subscription_invoice_archive_invoiceId_fkey'
+    ) THEN
+        ALTER TABLE "subscription_invoice_archive"
+            ADD CONSTRAINT "subscription_invoice_archive_invoiceId_fkey"
+            FOREIGN KEY ("invoiceId") REFERENCES "subscription_invoices"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+END
+$$;
+
+-- Outside the block above, because a function body cannot be created inside
+-- one; guarded the same way, so the file still does nothing without the table.
+CREATE OR REPLACE FUNCTION saasicat_subscription_invoice_archive_is_kept()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    RAISE EXCEPTION 'An archived invoice document is kept as it was issued: % on subscription_invoice_archive is refused.', TG_OP
+        USING ERRCODE = 'restrict_violation';
+END
+$$;
+
+DO $$
+BEGIN
+    IF to_regclass('subscription_invoice_archive') IS NULL THEN
+        RETURN;
+    END IF;
+    DROP TRIGGER IF EXISTS "subscription_invoice_archive_is_kept" ON "subscription_invoice_archive";
+    CREATE TRIGGER "subscription_invoice_archive_is_kept"
+        BEFORE UPDATE OR DELETE ON "subscription_invoice_archive"
+        FOR EACH ROW EXECUTE FUNCTION saasicat_subscription_invoice_archive_is_kept();
+    DROP TRIGGER IF EXISTS "subscription_invoice_archive_is_not_emptied" ON "subscription_invoice_archive";
+    CREATE TRIGGER "subscription_invoice_archive_is_not_emptied"
+        BEFORE TRUNCATE ON "subscription_invoice_archive"
+        FOR EACH STATEMENT EXECUTE FUNCTION saasicat_subscription_invoice_archive_is_kept();
+END
+$$;
+
+COMMIT;

package/sql/1.0-an-invoice-is-issued.postgres.sql

@@ -0,0 +1,171 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — an invoice is issued from the charge journal.
+-- =============================================================================
+--
+-- The invoices the platform issues from a subscriber's charges, their lines,
+-- and the one number range they are numbered in (#276 step 6). Needed where
+-- `tenantBilling.chargeJournal.invoices` is configured. Run it BEFORE `db push`,
+-- and after `1.0-a-subscriber-account-records-its-charges.postgres.sql`, whose
+-- `subscriber_ledger_entries` table every line points at:
+--
+--   psql "$DATABASE_URL" -f 1.0-an-invoice-is-issued.postgres.sql
+--
+-- What it touches, in one transaction:
+--
+--   `subscription_invoices` — created with its indexes, among them the unique
+--   number and the unique (numberYear, numberSequence), and its foreign keys to
+--   `subscribers` and `subscription_contracts`; or, where an earlier run of
+--   this file created it, given the `footer` column, empty for the invoices it
+--   already holds.
+--
+--   `subscription_invoice_lines` — created with its indexes, among them the
+--   unique `chargeId` that puts a charge on one invoice only, and its foreign
+--   keys to `subscription_invoices`, `subscriber_ledger_entries` and
+--   `contract_line_items`.
+--
+--   `subscription_invoice_numbers` — created: one row per year, holding the last
+--   number drawn.
+--
+-- Skipped, with a notice, where one of the tables the invoices point at is
+-- missing. Nothing is backfilled: no invoice is issued for a charge before
+-- invoicing is switched on, and the range starts at 1.
+--
+-- Safe to run again: every table, column and index is created only where it
+-- is 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
+        OR to_regclass('subscriber_ledger_entries') IS NULL THEN
+        RAISE NOTICE 'subscribers, subscription_contracts, contract_line_items or subscriber_ledger_entries is not present — the invoice tables are not created; an invoice is issued from the charge journal.';
+        RETURN;
+    END IF;
+
+    CREATE TABLE IF NOT EXISTS "subscription_invoices" (
+        "id" TEXT NOT NULL,
+        "number" TEXT NOT NULL,
+        "numberPrefix" TEXT NOT NULL,
+        "numberYear" INTEGER NOT NULL,
+        "numberSequence" INTEGER NOT NULL,
+        "tenantId" TEXT NOT NULL,
+        "subscriberId" TEXT NOT NULL,
+        "subscriptionId" TEXT NOT NULL,
+        "contractId" TEXT NOT NULL,
+        "issuedAt" TIMESTAMP(3) NOT NULL,
+        "issueDate" DATE NOT NULL,
+        "dueDate" DATE NOT NULL,
+        "servicePeriodFrom" DATE NOT NULL,
+        "servicePeriodUntil" DATE NOT NULL,
+        "currency" TEXT NOT NULL,
+        "issuerParty" JSONB NOT NULL,
+        "subscriberParty" JSONB NOT NULL,
+        "footer" JSONB NOT NULL DEFAULT '[]',
+        "taxTreatment" JSONB NOT NULL,
+        "taxes" JSONB NOT NULL,
+        "totalNet" DECIMAL(12,2) NOT NULL,
+        "totalTax" DECIMAL(12,2) NOT NULL,
+        "totalGross" DECIMAL(12,2) NOT NULL,
+        "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        CONSTRAINT "subscription_invoices_pkey" PRIMARY KEY ("id")
+    );
+    -- A table an earlier run of this file created before invoices carried
+    -- their footer gains it here, empty for the invoices it holds.
+    ALTER TABLE "subscription_invoices"
+        ADD COLUMN IF NOT EXISTS "footer" JSONB NOT NULL DEFAULT '[]';
+    CREATE UNIQUE INDEX IF NOT EXISTS "subscription_invoices_number_key"
+        ON "subscription_invoices"("number");
+    CREATE UNIQUE INDEX IF NOT EXISTS "subscription_invoices_numberYear_numberSequence_key"
+        ON "subscription_invoices"("numberYear", "numberSequence");
+    CREATE INDEX IF NOT EXISTS "subscription_invoices_subscriberId_issuedAt_idx"
+        ON "subscription_invoices"("subscriberId", "issuedAt");
+    CREATE INDEX IF NOT EXISTS "subscription_invoices_subscriptionId_idx"
+        ON "subscription_invoices"("subscriptionId");
+
+    CREATE TABLE IF NOT EXISTS "subscription_invoice_lines" (
+        "id" TEXT NOT NULL,
+        "invoiceId" TEXT NOT NULL,
+        "position" INTEGER NOT NULL,
+        "chargeId" TEXT NOT NULL,
+        "contractLineItemId" TEXT NOT NULL,
+        "title" TEXT NOT NULL,
+        "origin" TEXT NOT NULL,
+        "source" TEXT NOT NULL,
+        "periodFrom" DATE NOT NULL,
+        "periodUntil" DATE NOT NULL,
+        "amountNet" DECIMAL(10,2) NOT NULL,
+        "taxRate" DECIMAL(5,2) NOT NULL,
+        CONSTRAINT "subscription_invoice_lines_pkey" PRIMARY KEY ("id")
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS "subscription_invoice_lines_chargeId_key"
+        ON "subscription_invoice_lines"("chargeId");
+    CREATE UNIQUE INDEX IF NOT EXISTS "subscription_invoice_lines_invoiceId_position_key"
+        ON "subscription_invoice_lines"("invoiceId", "position");
+    CREATE INDEX IF NOT EXISTS "subscription_invoice_lines_contractLineItemId_idx"
+        ON "subscription_invoice_lines"("contractLineItemId");
+
+    CREATE TABLE IF NOT EXISTS "subscription_invoice_numbers" (
+        "year" INTEGER NOT NULL,
+        "last" INTEGER NOT NULL,
+        CONSTRAINT "subscription_invoice_numbers_pkey" PRIMARY KEY ("year")
+    );
+
+    -- `ADD CONSTRAINT` has no `IF NOT EXISTS`.
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscription_invoices')
+           AND conname = 'subscription_invoices_subscriberId_fkey'
+    ) THEN
+        ALTER TABLE "subscription_invoices"
+            ADD CONSTRAINT "subscription_invoices_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_invoices')
+           AND conname = 'subscription_invoices_contractId_fkey'
+    ) THEN
+        ALTER TABLE "subscription_invoices"
+            ADD CONSTRAINT "subscription_invoices_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('subscription_invoice_lines')
+           AND conname = 'subscription_invoice_lines_invoiceId_fkey'
+    ) THEN
+        ALTER TABLE "subscription_invoice_lines"
+            ADD CONSTRAINT "subscription_invoice_lines_invoiceId_fkey"
+            FOREIGN KEY ("invoiceId") REFERENCES "subscription_invoices"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscription_invoice_lines')
+           AND conname = 'subscription_invoice_lines_chargeId_fkey'
+    ) THEN
+        ALTER TABLE "subscription_invoice_lines"
+            ADD CONSTRAINT "subscription_invoice_lines_chargeId_fkey"
+            FOREIGN KEY ("chargeId") REFERENCES "subscriber_ledger_entries"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscription_invoice_lines')
+           AND conname = 'subscription_invoice_lines_contractLineItemId_fkey'
+    ) THEN
+        ALTER TABLE "subscription_invoice_lines"
+            ADD CONSTRAINT "subscription_invoice_lines_contractLineItemId_fkey"
+            FOREIGN KEY ("contractLineItemId") REFERENCES "contract_line_items"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+END $$;
+
+COMMIT;

package/sql/constraints.postgres.sql

@@ -66,6 +66,13 @@ ALTER TABLE subscription_bundles
 CREATE UNIQUE INDEX IF NOT EXISTS maintenance_windows_one_open
     ON maintenance_windows ((true)) WHERE "endedAt" IS NULL;
 
+-- At most ONE withdrawal of a feature is not lifted. A lifted one keeps its row
+-- with `liftedFrom` set and leaves the index, so the feature can be withdrawn
+-- again from that date. Two operators announcing at the same moment therefore
+-- land one withdrawal, because the second insert meets the first.
+CREATE UNIQUE INDEX IF NOT EXISTS feature_withdrawals_one_open_per_feature
+    ON feature_withdrawals ("featureKey") WHERE "liftedFrom" IS NULL;
+
 -- A subscriber is live for at most ONE tenant, and a tenant has at most ONE
 -- live subscriber. A link that ended keeps its row with `unlinkedAt` set, so the
 -- tenants a subscriber had before stay in its history. Two partial unique