@saasicat/core 1.0.0-rc.22 → 1.0.0-rc.24

package/dist/index.d.cts

@@ -24,11 +24,17 @@ interface DateAtOrAfter {
 interface DateAfter {
     gt: Date;
 }
-/** `OR` block of the validity window; exactly one date field per variant. */
+/** `OR` block of the validity window; exactly one field per variant. */
 type ValidityWindowClause = {
     validFrom: DateAtOrBefore | null;
 } | {
     validUntil: DateAtOrAfter | null;
+} | {
+    supersededAt: null;
+} | {
+    validUntil: {
+        not: null;
+    };
 };
 /** Optional `OR` block for models with `endsAt` (precise admin termination). */
 type EndsAtClause = {
@@ -60,6 +66,7 @@ interface ActivePlanVersionWhereWithEndsAt {
  *   `publishedAt IS NOT NULL`
  *   `(validFrom IS NULL OR validFrom <= asOf)`
  *   `(validUntil IS NULL OR validUntil >= startOfUtcDay(asOf))`  // day-inclusive
+ *   `(supersededAt IS NULL OR validUntil IS NOT NULL)`  // superseded: only with a last day
  *   with `withEndsAt`: additionally `(endsAt IS NULL OR endsAt > asOf)`.  // precise
  *
  * `planId` stays with the caller (repo-specific type). Matching Prisma
@@ -79,6 +86,22 @@ declare function buildActivePlanVersionWhere(asOf: Date, options: {
 type ActiveVersionWhere = ActivePlanVersionWhere;
 /** Model-neutral counterpart that additionally checks an `endsAt` timestamp. */
 type ActiveVersionWhereWithEndsAt = ActivePlanVersionWhereWithEndsAt;
+/** The dates of a version that decide whether it takes bookings, as a row carries them. */
+interface VersionWindow {
+    validFrom?: string | Date | null;
+    validUntil?: string | Date | null;
+    endsAt?: string | Date | null;
+    supersededAt?: string | Date | null;
+}
+/**
+ * Whether a version that is published takes bookings at `asOf` — the same
+ * window {@link buildActivePlanVersionWhere} asks the database for, for a row
+ * already read: `validFrom` at or before `asOf`, `validUntil` not before the
+ * day of `asOf`, `endsAt` after `asOf`, and a superseded version only within
+ * a last day it carries. A date that is absent does not close the window.
+ * Whether the row is published is the caller's to know.
+ */
+declare function isVersionActiveAt(version: VersionWindow, asOf: Date): boolean;
 /**
  * Model-neutral alias for {@link buildActivePlanVersionWhere}. The original
  * export remains available for backwards compatibility.
@@ -770,9 +793,18 @@ interface SelfServiceBlockedPlans {
  * passed it in code" attached. The file is read at boot, so an edit lands on
  * the next restart.
  */
+/**
+ * Whether the operator may retire a plan version for the subscriptions already
+ * on it. It reaches contracts customers have made, so it rests on a clause in
+ * the operator's terms; `termsConfirmed` states that they carry it.
+ */
+interface OrderlyRetirementSettings {
+    termsConfirmed: boolean;
+}
 interface PlanCatalogTenantBilling {
     cancellationNoticeDays: CancellationNoticePeriods;
     selfServiceBlockedPlans: SelfServiceBlockedPlans;
+    orderlyRetirement: OrderlyRetirementSettings;
 }
 /**
  * Who is told when the settings in the file change between two starts.
@@ -975,6 +1007,48 @@ interface PromoCodeValidationLog {
     createdAt: string;
 }
 
+/**
+ * A tenant's own limits beside its plan — a negotiated contract, a pilot.
+ * `quotas[key]` replaces the plan's value for that quota, `-1` meaning
+ * unlimited; `features` adds to the plan's. Stored as JSON in
+ * `subscriptions.customLimits`.
+ */
+interface CustomLimits {
+    quotas?: Record<QuotaKey, number>;
+    features?: FeatureKey[];
+}
+/**
+ * The keys a stored `customLimits` value is read by. The normative admin API
+ * schema (`CustomLimits` in `@saasicat/spec`) is held to the same list.
+ */
+declare const CUSTOM_LIMITS_KEYS: readonly ["quotas", "features"];
+/** What a stored `customLimits` value gave, and what in it went unread. */
+interface ReadCustomLimits {
+    limits: CustomLimits | null;
+    /**
+     * The parts of the stored value the platform does not read — a key it does
+     * not know, or a `quotas`/`features` of the wrong kind. Empty when every
+     * part was read.
+     */
+    unread: string[];
+}
+/**
+ * Reads a stored `customLimits` value the way the platform applies it.
+ *
+ * A shape the platform does not read is reported rather than refused: the
+ * tenant keeps its plan's limits and goes on working, as a limit nothing can
+ * count does not block anybody (`SC-ENTL-010`), and the caller says out loud
+ * which limits were not applied. Each quota value goes through
+ * `readQuotaValue`, the one reading of a quota in JSON.
+ */
+declare function readCustomLimits(value: unknown): ReadCustomLimits;
+/**
+ * Reads stored limits for an adapter, and reports what went unread once per
+ * subscription — every entitlement read passes through here, so reporting on
+ * each would bury the one line an operator needs under thousands.
+ */
+declare function customLimitsReader(report: (line: string) => void): (subscriptionId: string, stored: unknown) => CustomLimits | null;
+
 type SubscriptionStatus = 'TRIAL' | 'ACTIVE' | 'PAST_DUE' | 'CANCELED' | 'PENDING_SALES';
 interface Subscription {
     id: string;
@@ -984,8 +1058,8 @@ interface Subscription {
     planVersionId: string;
     billingCycle: BillingCycle;
     status: SubscriptionStatus;
-    /** Override per Tenant; unset fields fall back to the PlanVersion. */
-    customLimits?: Partial<Record<QuotaKey, number>>;
+    /** Override per tenant; unset fields fall back to the PlanVersion. */
+    customLimits?: CustomLimits | null;
     /** ENTERPRISE special contract. */
     customMonthlyNet?: number | null;
     isPilot: boolean;
@@ -996,15 +1070,7 @@ interface Subscription {
     canceledAt: string | null;
     currentPeriodStart: string | null;
     currentPeriodEnd: string | null;
-    /** Plan version migration (see ROADMAP §6). */
-    pendingPlanVersionId: string | null;
-    pendingPlanVersionEffectiveAt: string | null;
-    pendingPlanVersionAccepted: boolean;
-    pendingPlanVersionAcceptedAt: string | null;
-    pendingPlanVersionAcceptedByUserId: string | null;
-    pendingPlanVersionNotifiedAt: string | null;
-    pendingPlanVersionReminderSentAt: string | null;
-    /** Plan change at period end (orthogonal to pendingPlanVersionId). */
+    /** Plan change at period end. */
     pendingPlanId: PlanId | null;
     pendingBillingCycle: BillingCycle | null;
     pendingEffectiveAt: string | null;
@@ -1067,7 +1133,7 @@ interface VersionedEntityBase {
      * has become part of the contract. Optional for backwards-compat reasons;
      * the helper defensively interprets `undefined` as `>0` (= frozen). How the
      * adapter counts depends on the version type: PlanVersion via
-     * `Subscription.planVersionId` (+ `pendingPlanVersionId`), BundleVersion
+     * `Subscription.planVersionId` (+ `pendingChangeVersionId`), BundleVersion
      * via the respective app-specific Subscription→Bundle binding.
      */
     subscriptionCount?: number;
@@ -1514,7 +1580,7 @@ interface AdminManifest {
         actions?: AuditActionDef[];
     };
 }
-type StandardPageKey = 'dashboard' | 'tenants' | 'subscriptions' | 'promoCodes' | 'plans' | 'audit' | 'users' | 'pilots' | 'discovery' | 'bundles' | 'marketingCatalog' | 'platformEmail' | 'platformEmailHistory' | 'settings';
+type StandardPageKey = 'dashboard' | 'tenants' | 'subscriptions' | 'promoCodes' | 'plans' | 'audit' | 'users' | 'pilots' | 'discovery' | 'bundles' | 'marketingCatalog' | 'platformEmail' | 'platformEmailHistory' | 'settings' | 'maintenance';
 interface StandardPageDef {
     enabled: boolean;
     requiredCapability?: CapabilityKey;
@@ -1627,7 +1693,13 @@ interface AuditQuery {
     entity?: string;
     entityId?: string;
     action?: string;
-    /** Wildcard-capable, e.g. 'cli:*'. */
+    /**
+     * A tag, matched exactly, or a pattern with `*` at its start, its end or
+     * both, matched without regard to case: `cli:*` is every entry from the
+     * command line, `*:ops@example.com:*` every entry of one person, whatever
+     * they acted through. Everything between the stars is literal. A tag reads
+     * `<source>:<email>:<context>`.
+     */
     actorTag?: string;
     from?: string;
     to?: string;
@@ -1780,6 +1852,23 @@ interface PromotionOnPrice {
  */
 declare function promotionOnPrice(promotions: PromotionRow[], targetKey: string, locale: string, cycle: 'monthly' | 'yearly', basePrice: number | null, today?: Date, targetType?: PromotionTargetType): PromotionOnPrice | null;
 
+/** An amount as written, to the cent. */
+declare function roundToCents(amount: number): number;
+/** The terms added as written, exactly, and rounded once to the cent. */
+declare function sumToCents(...terms: number[]): number;
+/** The amount in whole cents, rounded once. */
+declare function toCents(amount: number): number;
+/** `percent` % of `amount`, to the cent — the discount a percentage takes off. */
+declare function percentOf(amount: number, percent: number): number;
+/** `amount × part / whole`, to the cent — a share of a period, say. */
+declare function prorate(amount: number, part: number, whole: number): number;
+/** Gross from net at a tax rate in per cent: net × (100 + rate) / 100. */
+declare function grossFromNet(net: number, vatRate: number): number;
+/** Net from gross at a tax rate in per cent: gross × 100 / (100 + rate). */
+declare function netFromGross(gross: number, vatRate: number): number;
+/** The tax a gross amount includes at a rate in per cent: gross × rate / (100 + rate). */
+declare function computeIncludedVat(gross: number, vatRate: number): number;
+
 type CheckoutOfferLineItemKind = 'plan' | 'bundle' | 'discount';
 /** Frozen billable line item in the offer. */
 interface CheckoutOfferLineItem {
@@ -2303,6 +2392,79 @@ declare function classifyPlanDiff(oldV: PlanVersionFields, newV: PlanVersionFiel
  */
 declare function classifyBundleVersionDiff(oldV: BundleVersionFields, newV: BundleVersionFields): DiffResult;
 
+/**
+ * - `improvement` — nothing dearer in any rhythm, no feature missing, no quota
+ *   lower. Taken at once and free, the term kept.
+ * - `more-for-more` — nothing missing or lower, but dearer in at least one
+ *   rhythm. Taken like an upgrade: at once, the difference prorated. The rule
+ *   reads every rhythm, so in the subscriber's own the difference can be zero
+ *   or below — monthly 49 to 45 with yearly 490 to 500 is more for more for a
+ *   monthly subscriber too.
+ * - `takes-something-away` — a feature missing or a quota lower, whatever the
+ *   price. Taken like a downgrade: at the end of the running term, and only
+ *   when the subscriber asks for it.
+ * - `same` — the two agree on everything compared: there is nothing to offer.
+ */
+type VersionOfferClass = 'improvement' | 'more-for-more' | 'takes-something-away' | 'same';
+/**
+ * A version as the comparison reads it. A price may be absent: that is a
+ * rhythm the version is not sold in, and a rhythm that stops being sold counts
+ * against the candidate like a price that went up.
+ */
+type VersionOfferFields = BundleVersionFields;
+interface VersionOffer {
+    readonly class: VersionOfferClass;
+    /** Every difference, bound to candidate, as the catalogue's diff states it. */
+    readonly changes: readonly VersionChange[];
+}
+/** One version as a subscriber compares it. A price of null is a rhythm it is not sold in. */
+interface VersionOfferSide {
+    readonly planVersionId: string;
+    readonly version: number;
+    readonly features: readonly string[];
+    readonly quotas: Readonly<Record<string, number>>;
+    readonly monthlyNet: number | null;
+    readonly yearlyNet: number | null;
+    /** The last day it is sold on, where a successor closes its window — ISO, the whole day included. */
+    readonly validUntil: string | null;
+    /** When an operator ended it, where one did — ISO; from then it is not sold. */
+    readonly endsAt: string | null;
+}
+/**
+ * A newer version of the subscriber's plan, offered: the version bound and the
+ * one offered side by side, what kind of offer it is, and when a switch taken
+ * now would take effect — at once, or, for one that takes something away, at
+ * the end of the running term. `GET billing/version-offer` answers with it.
+ */
+interface VersionOfferView {
+    readonly plan: string;
+    readonly bound: VersionOfferSide;
+    readonly offered: VersionOfferSide;
+    readonly class: Exclude<VersionOfferClass, 'same'>;
+    readonly changes: readonly VersionChange[];
+    /** ISO instant. */
+    readonly takesEffectAt: string;
+}
+/**
+ * What taking an offer did: the version left and the one taken, and whether it
+ * applied at once or waits for `takesEffectAt`. `POST billing/version-offer/accept`
+ * answers with it.
+ */
+interface VersionSwitchResult {
+    readonly class: Exclude<VersionOfferClass, 'same'>;
+    readonly fromPlanVersionId: string;
+    readonly planVersionId: string;
+    readonly immediate: boolean;
+    /** ISO instant. */
+    readonly takesEffectAt: string;
+}
+/**
+ * Classifies `candidate` against `bound`. The comparison is the catalogue's
+ * own diff — prices with a rhythm that may be absent, as a bundle version's
+ * are — so an offer and a published version describe their changes alike.
+ */
+declare function classifyVersionOffer(bound: VersionOfferFields, candidate: VersionOfferFields): VersionOffer;
+
 interface PromoPreviewRequest {
     /** Promo code (case-insensitive, normalized to uppercase in the service). */
     code: string;
@@ -2443,6 +2605,560 @@ interface SettingsDifference {
     after: unknown;
 }
 
+/** One window, as a store reads it back. */
+interface MaintenanceWindowRecord {
+    id: string;
+    /** The announced start; null for a window locked without being announced first. */
+    startsAt: Date | null;
+    /** The announced, expected end; null where nobody said. */
+    endsAt: Date | null;
+    /** The operator's words to the tenants, shown as written; null for none. */
+    message: string | null;
+    /** When the window was recorded — announced, or locked at once. */
+    createdAt: Date;
+    /** Who recorded it, as the audit log tags an actor. */
+    createdBy: string;
+    /** When the lock began; null while the window is only announced. */
+    lockedAt: Date | null;
+    lockedBy: string | null;
+    /** When the window was over — unlocked, or cancelled before it locked. */
+    endedAt: Date | null;
+    endedBy: string | null;
+}
+/** A window to record: it is open, so it has not ended. */
+type NewMaintenanceWindow = Omit<MaintenanceWindowRecord, 'id' | 'endedAt' | 'endedBy'>;
+/**
+ * Where an open window stands. A write names the stage it expects, so that it
+ * cannot move a window that moved on in the meantime — one that another
+ * operator locked, unlocked or cancelled a moment earlier.
+ */
+type MaintenanceWindowStage = 'announced' | 'locked';
+/** What a write may change about an open window. */
+type MaintenanceWindowChanges = Partial<Pick<MaintenanceWindowRecord, 'startsAt' | 'endsAt' | 'message' | 'lockedAt' | 'lockedBy' | 'endedAt' | 'endedBy'>>;
+/**
+ * What became of a window, read off its record. `cancelled` is a window that
+ * ended without ever locking anybody out.
+ */
+type MaintenanceWindowStatus = 'announced' | 'locked' | 'ended' | 'cancelled';
+/**
+ * What SaaSiCat tells the application about a window, so that it can write to
+ * its own users — in its own words, from its own sender, in their language.
+ * The lock itself is not among them: tenants see it in the application.
+ */
+type MaintenanceWindowEvent = {
+    kind: 'announced';
+    window: MaintenanceWindowRecord;
+} | {
+    kind: 'rescheduled';
+    window: MaintenanceWindowRecord;
+    /** The window as it was announced before this change. */
+    previous: MaintenanceWindowRecord;
+} | {
+    kind: 'cancelled';
+    window: MaintenanceWindowRecord;
+};
+/** The longest message a window carries; the operator's words, not a document. */
+declare const MAINTENANCE_MESSAGE_MAX_LENGTH = 500;
+/**
+ * How long a process may go on reading a lock state it read before. Every
+ * request asks, so each process keeps the answer this long rather than asking
+ * the database per request; the command that locks waits this long before it
+ * returns, so that every process has seen the lock by then.
+ *
+ * Part of the contract between two versions of an application: the command
+ * that locks comes from the release being deployed, while the processes it
+ * waits for may still run the one before. It is safe only while the figure it
+ * waits by is at least theirs, so a later release may raise it and never lower
+ * it.
+ */
+declare const MAINTENANCE_STATE_MAX_AGE_SECONDS = 5;
+/**
+ * The manifest capability that announces the maintenance screen. The platform
+ * sets it where it keeps maintenance windows, and the administration offers the
+ * screen — and its lock banner — only where it is set.
+ */
+declare const MAINTENANCE_CAPABILITY = "maintenance.manage";
+/**
+ * What a tenant's page is told: nothing, a window ahead, or a lock. Dates are
+ * ISO strings, and `overrun` is the server's answer rather than the browser's,
+ * whose clock is not the one the window was announced by.
+ */
+type MaintenanceStatusView = {
+    state: 'none';
+} | {
+    state: 'announced';
+    startsAt: string;
+    endsAt: string;
+    message: string | null;
+} | {
+    state: 'locked';
+    lockedAt: string;
+    /** The announced end; null where nobody said. */
+    endsAt: string | null;
+    message: string | null;
+    /** The announced end has passed, and the lock still holds. */
+    overrun: boolean;
+};
+/** A window as the administration shows it. */
+interface MaintenanceWindowView {
+    id: string;
+    status: MaintenanceWindowStatus;
+    startsAt: string | null;
+    endsAt: string | null;
+    message: string | null;
+    createdAt: string;
+    createdBy: string;
+    lockedAt: string | null;
+    lockedBy: string | null;
+    endedAt: string | null;
+    endedBy: string | null;
+    /** Locked, and past its announced end. */
+    overrun: boolean;
+    /** Announced, never locked, and past its announced end: tenants no longer see it. */
+    lapsed: boolean;
+}
+/** `GET /admin/maintenance`: the open window, if any, and the ones before it. */
+interface MaintenanceOverview {
+    open: MaintenanceWindowView | null;
+    /** Newest first, the open one included. */
+    recent: MaintenanceWindowView[];
+    /** How long a lock takes to reach every process. */
+    takesEffectWithinSeconds: number;
+}
+/** `POST /admin/maintenance/lock`: the locked window, and whether it was locked before. */
+interface MaintenanceLockView {
+    window: MaintenanceWindowView;
+    /** The lock already held; nothing was changed. */
+    alreadyLocked: boolean;
+    /** How long the lock takes to reach every process. */
+    takesEffectWithinSeconds: number;
+}
+/** `POST /admin/maintenance/unlock`: the window it ended, or the open one it left alone. */
+interface MaintenanceUnlockView {
+    window: MaintenanceWindowView | null;
+    /** Whether a lock held and was ended by this call. */
+    wasLocked: boolean;
+}
+
+/** What the switch costs, per period of the subscriber's rhythm. */
+interface RetirementSwitchTerms {
+    /** The replacement's net price. */
+    readonly priceNet: number;
+    /**
+     * Where the replacement costs more: the price the subscriber goes on paying,
+     * the difference that is held, and the last day it is held — the day before
+     * the date they were told. Null where it costs the same or less: its price
+     * then applies from the subscriber's next period.
+     */
+    readonly held: {
+        readonly priceNet: number;
+        readonly amountNet: number;
+        readonly lastDay: string;
+    } | null;
+}
+/**
+ * What switching to the replacement now costs in `billingCycle`, or null where
+ * the replacement has no price in it.
+ */
+declare function retirementSwitchTerms(notice: Pick<VersionRetiredNotice, 'retired' | 'replacement' | 'lastDayToCancel'>, billingCycle: string): RetirementSwitchTerms | null;
+
+/** A version, as an announcement names it. */
+interface RetiredVersionRef {
+    readonly planVersionId: string;
+    readonly planKey: string;
+    readonly version: number;
+}
+/** An announcement as it is kept: one per retirement, whoever it reaches. */
+interface VersionRetirementRecord {
+    readonly id: string;
+    /** The version retired. */
+    readonly retired: RetiredVersionRef;
+    /** The version its subscriptions continue on, named by the operator. */
+    readonly replacement: RetiredVersionRef;
+    readonly announcedAt: Date;
+    /** Who announced it — an actor tag, as the audit log writes it. */
+    readonly announcedBy: string;
+}
+type NewVersionRetirement = Omit<VersionRetirementRecord, 'id'>;
+/**
+ * The manifest capability that announces retiring a version. The platform sets
+ * it where it serves the routes, and the admin UI offers the action only where
+ * it is set. Whether the operator's terms allow it is a blocker the preview
+ * reports, so an operator who has not confirmed them learns what is missing.
+ */
+declare const VERSION_RETIREMENT_CAPABILITY = "planVersions.retire";
+/**
+ * One of the two versions of a retirement, as the subscriber compares them:
+ * price in each rhythm, quotas and features, with the plan it belongs to — the
+ * replacement may be a version of another plan.
+ */
+interface RetirementSide extends VersionOfferSide {
+    readonly planKey: string;
+}
+/**
+ * A plan version a subscription is on is being retired, and the subscription
+ * continues on the named replacement from its effective date. Sent once per
+ * subscription and retirement, when the retirement is announced, and kept as
+ * it was sent: the record shows what the subscriber was told, prices included.
+ */
+interface VersionRetiredNotice {
+    readonly kind: 'version-retired';
+    readonly tenantId: string;
+    readonly subscriptionId: string;
+    readonly retirementId: string;
+    readonly retired: RetirementSide;
+    readonly replacement: RetirementSide;
+    /** Every difference, retired to replacement, as the catalogue's diff states it. */
+    readonly changes: readonly VersionChange[];
+    /**
+     * The rhythm the subscription is billed in when the retirement takes
+     * effect — a change of rhythm scheduled by then included — which says
+     * which of the two prices applies.
+     */
+    readonly billingCycle: string;
+    /** ISO 8601. */
+    readonly effectiveAt: string;
+    /** ISO date (`YYYY-MM-DD`), UTC. */
+    readonly lastDayToCancel: string;
+}
+/**
+ * The one reminder of a retirement, where staying put costs the subscription
+ * something (`SC-SUB-034`): sent 14 days before the retirement takes effect,
+ * once per subscription and retired version. It says again what the
+ * retirement notice said, and what a switch taken now would cost. Its
+ * `billingCycle` is still the rhythm billed at the date, read again from the
+ * subscription as it stands when the reminder is sent: a change of rhythm
+ * scheduled since the announcement is in it.
+ */
+interface VersionRetirementReminder extends Omit<VersionRetiredNotice, 'kind'> {
+    readonly kind: 'version-retirement-reminder';
+    /**
+     * What switching to the replacement now costs in the subscription's rhythm
+     * (`SC-SUB-032`), or null where it cannot switch now: in a trial, with a
+     * change scheduled, or where either plan is held for a special contract.
+     */
+    readonly switchTerms: RetirementSwitchTerms | null;
+}
+/**
+ * Why a retirement does not reach a subscription on the version:
+ *
+ * - `ended` — the subscription is over.
+ * - `cancelled-before` — its cancellation lands by the effective date.
+ * - `changes-before` — a scheduled change moves it to another plan, or to
+ *   another version of this one, by then.
+ * - `no-term` — it carries no date a term can be counted from.
+ * - `already-told` — an earlier announcement of this version reached it, and
+ *   stands.
+ */
+type RetirementSkipReason = 'ended' | 'cancelled-before' | 'changes-before' | 'no-term' | 'already-told';
+/** A refusal as the preview reports it and the announcement throws it. */
+interface RetirementBlocker {
+    readonly code: string;
+    readonly message: string;
+    readonly params: Record<string, string | number>;
+}
+/** A subscription a retirement reaches, with what it means there. */
+interface RetirementReachedRow {
+    readonly tenantId: string;
+    readonly subscriptionId: string;
+    readonly status: string;
+    /** The rhythm it is billed in when the retirement takes effect. */
+    readonly billingCycle: string;
+    /** ISO 8601. */
+    readonly effectiveAt: string;
+    /** ISO date, UTC. */
+    readonly lastDayToCancel: string;
+    /** Reached by another retirement within the last twelve months: the announcement waits. */
+    readonly reachedRecently: boolean;
+}
+/** A subscription on the version a retirement does not reach, and why. */
+interface RetirementSkippedRow {
+    readonly tenantId: string;
+    readonly subscriptionId: string;
+    readonly reason: RetirementSkipReason;
+}
+/** What announcing a retirement now would do. */
+interface RetirementPreview {
+    readonly retired: RetirementSide;
+    readonly replacement: RetirementSide;
+    /** Every difference, retired to replacement, as the subscribers will be told it. */
+    readonly changes: readonly VersionChange[];
+    /** ISO 8601: the moment it is computed for. */
+    readonly asOf: string;
+    readonly reached: readonly RetirementReachedRow[];
+    readonly skipped: readonly RetirementSkippedRow[];
+    /** Empty where it may be announced as it stands. */
+    readonly blockers: readonly RetirementBlocker[];
+}
+/** What an announcement did. */
+interface RetirementAnnounced {
+    readonly retirement: VersionRetirementRecord;
+    /** Notices sent now; the rest are sent by the next run. */
+    readonly told: number;
+    readonly failed: number;
+}
+/**
+ * How far a retirement has come, counted over the subscriptions it reached
+ * (`SC-SUB-033`).
+ */
+interface RetirementProgress {
+    /** Off the retired version: moved at their date, switched early, or changed on their own. */
+    readonly moved: number;
+    /** Still on the retired version, before their date. */
+    readonly waiting: number;
+    /** Still on the retired version after their date: the run has not moved them yet, or cannot. */
+    readonly overdue: number;
+    /** Still on the retired version, and ended by their date: there is nothing to move. */
+    readonly ended: number;
+    /**
+     * Still on the retired version, and not told yet: their notice has reached
+     * nobody, so their date is not set and nothing moves them (`SC-SUB-036`).
+     */
+    readonly notTold: number;
+    /**
+     * Reminded 14 days before their date (`SC-SUB-034`) — counted beside the
+     * four above, not instead of one: a subscription reminded moves later.
+     */
+    readonly reminded: number;
+}
+/** An announcement as the administration lists it, with how far it has come. */
+interface VersionRetirementView extends VersionRetirementRecord {
+    readonly progress: RetirementProgress;
+}
+/** What one run of the moves at the date did. */
+interface RetirementMoveRun {
+    /** Subscriptions moved onto their replacement, with the contract the move writes. */
+    readonly moved: number;
+    /** Moves that could not be made, and are tried again by the next run. */
+    readonly failed: number;
+}
+/** What switching to the replacement before the date did (`SC-SUB-032`). */
+interface RetirementSwitchResult {
+    readonly fromPlanVersionId: string;
+    readonly planVersionId: string;
+    /** ISO date of the last day the price is held, or null where none is. */
+    readonly heldUntilDay: string | null;
+}
+
+/** What a notice is about. */
+type SubscriptionNoticeKind = 'version-offered' | 'version-retired' | 'version-retirement-reminder';
+/** Which notice: there is one per subscription, kind and subject. */
+interface SubscriptionNoticeKey {
+    readonly tenantId: string;
+    readonly subscriptionId: string;
+    readonly kind: SubscriptionNoticeKind;
+    /**
+     * What it is about. For `version-offered`, the id of the version offered;
+     * for `version-retired`, the id of the version retired — so a subscription
+     * is told of a version's retirement once, whichever announcement it came
+     * with. The announcement is in the notice as `retirementId`. For
+     * `version-retirement-reminder`, the id of the version retired as well: a
+     * subscription is reminded of a version's retirement once.
+     */
+    readonly subject: string;
+}
+/** Who a notice went to and how, in the application's own terms. */
+interface SubscriptionNoticeDelivery {
+    /** The addresses, or user ids, it was sent to. Empty where nobody could be told. */
+    readonly recipients: readonly string[];
+    /** The way it went — `email`, `in-app`, whatever the application calls it. */
+    readonly channel: string;
+}
+/** A notice as it is kept. */
+interface SubscriptionNoticeRecord extends SubscriptionNoticeKey {
+    readonly id: string;
+    /** The notice as it was last handed to the application: a `SubscriptionNotice`. */
+    readonly content: unknown;
+    readonly createdAt: Date;
+    /**
+     * When a run took it on to deliver it. Null where no run holds it — before
+     * the first attempt, and again after an attempt that failed.
+     */
+    readonly claimedAt: Date | null;
+    /** When the application confirmed it sent it; null until then. */
+    readonly deliveredAt: Date | null;
+    /** Who it went to and how; set together with `deliveredAt`. */
+    readonly delivery: SubscriptionNoticeDelivery | null;
+}
+/**
+ * A newer version of the subscription's plan is now offered to it. Sent once
+ * per version, when the offer appears beside the plan — the notice and the
+ * offer say the same thing.
+ */
+interface VersionOfferedNotice {
+    readonly kind: 'version-offered';
+    readonly tenantId: string;
+    readonly subscriptionId: string;
+    /** The offer as `GET billing/version-offer` answers it at the moment the notice is due. */
+    readonly offer: VersionOfferView;
+}
+/** A notice handed to the application to send. */
+type SubscriptionNotice = VersionOfferedNotice | VersionRetiredNotice | VersionRetirementReminder;
+
+/**
+ * A `subscription_notices` row as either adapter reads it back. The two JSON
+ * columns are `unknown`: the database holds whatever was written to them.
+ */
+interface CanonicalSubscriptionNoticeRow {
+    id: string;
+    tenantId: string;
+    subscriptionId: string;
+    kind: string;
+    subject: string;
+    content: unknown;
+    createdAt: Date;
+    claimedAt: Date | null;
+    deliveredAt: Date | null;
+    recipients: unknown;
+    channel: string | null;
+}
+/**
+ * Reads a row back as a record, naming each column rather than spreading the
+ * row. The kind and the delivery are checked rather than cast: the record is
+ * what a subscriber is later shown they were told, and a value nobody can read
+ * must stop at the read and name its row.
+ */
+declare function toSubscriptionNoticeRecord(row: CanonicalSubscriptionNoticeRow): SubscriptionNoticeRecord;
+
+/** The dates of a version that decide its state, as a row carries them. */
+interface VersionSaleDates extends VersionWindow {
+    readonly publishedAt?: string | Date | null;
+}
+/**
+ * Where a version stands. A day is an ISO date (`YYYY-MM-DD`, UTC):
+ * - `scheduled` — published and not on sale yet; `from` is its first day.
+ * - `on-sale` — on sale now; `until` is its last day, where one is known.
+ * - `off-sale` — no longer on sale; `since` is its first day off sale, where
+ *   one is known — a version superseded without a last day has none.
+ */
+type VersionSale = {
+    readonly kind: 'draft';
+} | {
+    readonly kind: 'scheduled';
+    readonly from: string;
+} | {
+    readonly kind: 'on-sale';
+    readonly until: string | null;
+} | {
+    readonly kind: 'off-sale';
+    readonly since: string | null;
+};
+type VersionSaleKind = VersionSale['kind'];
+/** The state of `version` at `now`. */
+declare function versionSale(version: VersionSaleDates, now: Date): VersionSale;
+/**
+ * The version on sale at `now` among one plan's or add-on's versions, in the
+ * order the platform picks it: the latest `validFrom`, a version without one
+ * last, then the highest number.
+ */
+declare function versionOnSale<V extends VersionSaleDates & {
+    readonly version?: number;
+}>(versions: readonly V[], now: Date): V | null;
+/**
+ * What a listing shows for a plan or add-on: the version on sale, otherwise
+ * the next one scheduled. A draft is not shown by this.
+ */
+declare function versionOnSaleOrNext<V extends VersionSaleDates & {
+    readonly version?: number;
+}>(versions: readonly V[], now: Date): V | null;
+
+/** A `version_retirements` row as either adapter reads it back. */
+interface CanonicalVersionRetirementRow {
+    id: string;
+    retiredPlanVersionId: string;
+    retiredPlanKey: string;
+    retiredVersion: number;
+    replacementPlanVersionId: string;
+    replacementPlanKey: string;
+    replacementVersion: number;
+    announcedAt: Date;
+    announcedBy: string;
+}
+/** Reads a row back as a record, naming each column rather than spreading the row. */
+declare function toVersionRetirementRecord(row: CanonicalVersionRetirementRow): VersionRetirementRecord;
+
+/** A scheduled change as a subscription row holds it. */
+interface ScheduledChangeColumns {
+    readonly pendingPlan: string | null;
+    readonly pendingBillingCycle: string | null;
+    readonly pendingEffectiveAt: Date | null;
+    readonly pendingChangeVersionId: string | null;
+}
+/** No change scheduled: what a plan change writes where it does not keep one. */
+declare const NO_SCHEDULED_CHANGE: ScheduledChangeColumns;
+/**
+ * The scheduled-change columns a plan change writes onto `current`: all
+ * cleared, unless the write keeps the change. A kept change is left as it is,
+ * with one exception: a change that only moves the rhythm on the plan being
+ * left — the plan it was scheduled on, no version named — follows the
+ * subscription to its new plan. Recorded as it was, it would take the
+ * subscription back to the plan it left when it comes due.
+ */
+declare function scheduledChangeAfterWrite(current: {
+    readonly plan: string;
+} & ScheduledChangeColumns, input: {
+    readonly planId: string;
+    readonly keepsPendingChange?: boolean;
+}): Partial<ScheduledChangeColumns>;
+
+/** How many days before a retirement takes effect its reminder is due. */
+declare const RETIREMENT_REMINDER_LEAD_DAYS = 14;
+/**
+ * When the reminder of a retirement is due: 14 days before it takes effect, at
+ * the same time of day. UTC has no change of clocks, so that is the effective
+ * day less 14 calendar days.
+ */
+declare function retirementReminderDueAt(notice: Pick<VersionRetiredNotice, 'effectiveAt'>): Date;
+/**
+ * Whether the reminder is due at `now`: from its day until the retirement
+ * takes effect. A run that did not happen on the day is caught up by the next
+ * one before the date; after it there is nothing left to remind of.
+ */
+declare function retirementReminderIsDue(notice: Pick<VersionRetiredNotice, 'effectiveAt'>, now: Date): boolean;
+/**
+ * Whether staying put costs the subscription something when the retirement
+ * takes effect (D9): the replacement takes a feature or a quota away, or is
+ * dearer in `billingCycle`, the rhythm it is billed in then — or not sold in
+ * it. A price that rises only in another rhythm costs it nothing.
+ */
+declare function retirementCostsTheSubscription(notice: Pick<VersionRetiredNotice, 'retired' | 'replacement' | 'changes' | 'lastDayToCancel'>, billingCycle: string): boolean;
+
+/** A `maintenance_windows` row as either adapter reads it back. */
+type CanonicalMaintenanceWindowRow = MaintenanceWindowRecord;
+/**
+ * Reads a row back as a record, naming each column rather than spreading the
+ * row: a column a later release adds is not handed to the platform by accident,
+ * and a version reading the table a later release extended reads what it knows.
+ */
+declare function toMaintenanceWindowRecord(row: CanonicalMaintenanceWindowRow): MaintenanceWindowRecord;
+
+/** What became of a window. */
+declare function maintenanceWindowStatusOf(window: MaintenanceWindowRecord): MaintenanceWindowStatus;
+/** Whether the lock still holds after the end it announced. */
+declare function isMaintenanceOverrun(window: MaintenanceWindowRecord, now: Date): boolean;
+/**
+ * Whether an announcement has lapsed: never locked, and its announced end has
+ * passed. Tenants are no longer shown it — past information is noise — while
+ * the operator is, because it still stands in the way of the next one.
+ */
+declare function isMaintenanceAnnouncementLapsed(window: MaintenanceWindowRecord, now: Date): boolean;
+/** What a tenant's page is told, given the open window — or none. */
+declare function maintenanceStatusOf(open: MaintenanceWindowRecord | null, now: Date): MaintenanceStatusView;
+/** A window as the administration shows it. */
+declare function maintenanceWindowViewOf(window: MaintenanceWindowRecord, now: Date): MaintenanceWindowView;
+/**
+ * Seconds until the announced end, for the `Retry-After` of a refused request.
+ * Never less than one: a client told zero would retry at once, in a loop.
+ */
+declare function maintenanceRetryAfterSeconds(window: MaintenanceWindowRecord, now: Date): number;
+
+/**
+ * The moment an ISO 8601 date and time names, provided it states its zone —
+ * `2026-10-02T22:00+02:00` or `2026-10-02T20:00Z`. Null for anything else: a
+ * date without a time, a time without a zone, or text that is not a date.
+ */
+declare function parseZonedInstant(text: string): Date | null;
+
 /**
  * The top-level blocks of `config/saas.yaml` that are the catalogue rather than
  * the configuration, and the format marker.
@@ -2555,11 +3271,8 @@ interface PlanVersionRow extends VersionedEntityBase {
      * `endsAt` is user-initiated: `POST /admin/catalog/plan-versions/:id/terminate`
      * sets the field. When `endsAt < NOW()` the version is no longer live for
      * new bookings — existing subscriptions (P1) stay bound.
-     *
-     * Optional, because consumer backends add the column additively — if it
-     * is missing, there is no end date.
      */
-    endsAt?: string | null;
+    endsAt: string | null;
     /** @deprecated Read from `quotas['users']` once available. */
     maxUsers?: number;
     /** @deprecated Legacy field; read from `quotas['vehicles']`. */
@@ -2624,12 +3337,12 @@ interface PlanCatalogReadSnapshot {
     /** Plan stems (deletedAt IS NULL). */
     plans: PlanRow[];
     /**
-     * Live PlanVersions: per `planId` (= planKey) the currently published
-     * version (publishedAt IS NOT NULL AND supersededAt IS NULL).
-     * Apps with plans without a live version take over the plan, but without
-     * pricing/quotas — the importer probably emitted a warning.
+     * Per `planId` (= planKey) the version on sale at the moment the snapshot
+     * was asked for — the rule of `PlanRepository.findActivePlanVersion`, so
+     * the catalogue names the version a booking made at that moment binds.
+     * A plan with nothing on sale is taken over without pricing or quotas.
      */
-    livePlanVersions: PlanVersionRow[];
+    versionsOnSale: PlanVersionRow[];
     /** Feature catalog entries (deletedAt IS NULL). */
     featureEntries: FeatureCatalogEntryRow[];
 }
@@ -2638,7 +3351,8 @@ interface PlanCatalogReadSnapshot {
  * implement it against their Prisma tables.
  */
 interface PlanCatalogReadSink {
-    loadSnapshot(): Promise<PlanCatalogReadSnapshot>;
+    /** The catalogue as it stands at `asOf`. */
+    loadSnapshot(asOf: Date): Promise<PlanCatalogReadSnapshot>;
 }
 
 /**
@@ -2897,13 +3611,34 @@ interface EmailPort {
 }
 /** Adapter for MFA secret persistence. */
 interface MfaPort {
-    /** Returns the stored TOTP secret or null. */
+    /**
+     * Returns the stored secret or null. What is stored is the value the
+     * platform handed to `setSecret`: sealed by the installation's
+     * `SecretSealer`, and opened by the platform, not here.
+     */
     getSecret(userId: string): Promise<string | null>;
-    /** Persists or deletes (null) the TOTP secret. */
+    /** Persists or deletes (null) the sealed secret, as it is given. */
     setSecret(userId: string, secret: string | null): Promise<void>;
     /** The platform calls this during the mfa-setup command. */
     isEnabled(userId: string): Promise<boolean>;
 }
+/**
+ * Seals a secret before it is stored and opens it after it is read.
+ *
+ * The TOTP secret of a SuperAdmin is the second factor of the accounts that can
+ * change every tenant's plan, codes and contracts. Stored as it is, whoever
+ * holds a dump, a backup or a replica holds it too, and the second factor adds
+ * nothing against them. The key stays with the installation — in its
+ * configuration, not in the database the sealed value lives in.
+ *
+ * `open` refuses what it did not seal: a value from another key, a format it
+ * does not know, a secret stored before sealing. The platform then treats the
+ * code as wrong and the administrator enrols again.
+ */
+interface SecretSealer {
+    seal(plain: string): Promise<string>;
+    open(sealed: string): Promise<string>;
+}
 /**
  * Opaque transaction context. The consumer determines the concrete type
  * (e.g. `Prisma.TransactionClient`). Platform code only passes it
@@ -3034,8 +3769,18 @@ interface PromoCodeRedemptionListItem extends PromoCodeRedemptionRecord {
  */
 interface PromoCodeRepository {
     findById(id: string): Promise<PromoCodeRecord | null>;
+    /**
+     * The code with this name, deleted ones included: a deleted code keeps its
+     * name (`SC-PROMO-028`), so the platform's duplicate check has to see it.
+     * Every caller that redeems or previews checks `deletedAt` itself.
+     */
     findByCode(code: string, tx?: TransactionContext): Promise<PromoCodeRecord | null>;
     findMany(filter: PromoCodeFilter): Promise<PromoCodeRecord[]>;
+    /**
+     * Refuses a name that is taken — by a live or a deleted code — with
+     * `promoCodeTaken`: two creates can pass the platform's duplicate check
+     * together, and the second one's answer is the refusal, not a driver error.
+     */
     create(data: CreatePromoCodeData): Promise<PromoCodeRecord>;
     update(id: string, data: UpdatePromoCodeData): Promise<PromoCodeRecord>;
     softDelete(id: string): Promise<void>;
@@ -3057,7 +3802,8 @@ interface PromoCodeRepository {
     releaseSlot(id: string, tx?: TransactionContext): Promise<void>;
     /**
      * Bulk-expire cron: sets all codes with `validUntil < now` and status
-     * ACTIVE/PAUSED to EXPIRED. Returns: number of updated rows.
+     * ACTIVE/PAUSED to EXPIRED, leaving deleted codes as they were — a write
+     * to a row the operator removed. Returns: number of updated rows.
      */
     expireDueCodes(now: Date): Promise<number>;
 }
@@ -3157,7 +3903,14 @@ interface PromoCodeHoldRepository {
 interface PromoCodeRedemptionRepository {
     findBySubscription(subscriptionId: string, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord | null>;
     create(data: Omit<PromoCodeRedemptionRecord, 'id' | 'redeemedAt' | 'status' | 'reversedAt'>, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord>;
-    setReversed(id: string, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    /**
+     * Marks the redemption reversed while it is not reversed yet, in one
+     * conditional statement, and answers with it; `null` where it already was.
+     * Two reversals of one redemption at the same moment then find one winner,
+     * and only the winner gives the slot back — without the claim both would,
+     * and a limited code would gain a slot it never issued.
+     */
+    setReversed(id: string, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord | null>;
     countByPromoCode(promoCodeId: string, status?: PromoCodeRedemptionStatus): Promise<number>;
     listByPromoCode(promoCodeId: string): Promise<PromoCodeRedemptionListItem[]>;
     expireDueRedemptions(now: Date): Promise<number>;
@@ -3356,8 +4109,21 @@ interface CreateSubscriptionContractData {
 /** What a repository writes: the contract as asked for, with the parties the platform copied. */
 interface NewSubscriptionContractData extends CreateSubscriptionContractData {
     parties: SubscriptionContractParties;
+    /**
+     * The parties are a copy the migration made rather than what was agreed —
+     * set where a successor takes them over from a contract that says so, so
+     * that the copy is not passed off as agreed one contract later. Absent
+     * means `false`.
+     */
+    partiesMigrated?: boolean;
 }
 interface TerminateSubscriptionContractData {
+    /**
+     * The tenant the caller read the contract under. The write matches it as
+     * well as the id, so an id that reaches the call by mistake cannot end
+     * another tenant's contract, whether or not a row policy would stop it.
+     */
+    tenantId: string;
     effectiveUntil: Date;
     /**
      * The terminal status, or `null` to end the contract by date alone.
@@ -3374,6 +4140,25 @@ interface TerminateSubscriptionContractData {
      */
     status: Extract<SubscriptionContractStatus, 'terminated' | 'superseded'> | null;
 }
+/**
+ * Ends a contract because a successor takes its place — on the condition that
+ * it is still as the caller read it.
+ */
+interface SupersedeSubscriptionContractData {
+    /**
+     * The tenant the caller read the contract under. The write matches it as
+     * well as the id, so an id that reaches the call by mistake cannot end
+     * another tenant's contract, whether or not a row policy would stop it.
+     */
+    tenantId: string;
+    /** When the successor takes over; written as the contract's `effectiveUntil`. */
+    at: Date;
+    /**
+     * The `effectiveUntil` the caller read. A contract whose end moved since —
+     * a cancellation capped it, or ended it — is not superseded.
+     */
+    readEffectiveUntil: Date | null;
+}
 interface SubscriptionContractFilter {
     tenantId?: string;
     status?: SubscriptionContractStatus;
@@ -3663,10 +4448,7 @@ interface SubscriptionRecord {
     trialEntitlementPlan?: string | null;
     pendingPlan?: string | null;
     pendingEffectiveAt?: Date | null;
-    customLimits?: {
-        quotas?: Record<string, number>;
-        features?: string[];
-    } | null;
+    customLimits?: CustomLimits | null;
     planVersionId: string;
     planVersion: PlanVersionRecord;
     /**
@@ -3710,7 +4492,8 @@ interface SubscriptionRepository {
     findByTenantIdLocked(tenantId: string, tx: TransactionContext): Promise<SubscriptionRecord | null>;
     /**
      * Counts subscriptions that bind a specific PlanVersion — both
-     * via the active `planVersionId` and via the scheduled `pendingPlanVersionId`.
+     * via the active `planVersionId` and via the version a scheduled change will
+     * bind (`pendingChangeVersionId`).
      * Needed by the `PlanVersionsService` for the editability decision:
      * a published-but-future PlanVersion stays correctable only as long
      * as no booking references it.
@@ -3720,6 +4503,14 @@ interface SubscriptionRepository {
      * frozen (fail-closed). Implementation hint: count in a single
      * COUNT(*) over the subscription table with an OR over the two
      * FK columns — not in two separate queries, to avoid race conditions.
+     *
+     * Counts across every tenant. The platform calls it inside
+     * `RlsBypassPort`; an implementation on a tenant-scoped client has to see
+     * every tenant's rows there. Whether the frame lifts the policy for this
+     * query is up to the application's bypass and the database layer behind it
+     * — one that lifts only reads such as `find*` leaves a `count` filtered, and
+     * then the implementation lifts the policy itself. A subscriber hidden from
+     * the count counts as nobody, which opens the version for editing.
      */
     countByPlanVersionId?(planVersionId: string): Promise<number>;
     /**
@@ -3739,6 +4530,9 @@ interface SubscriptionRepository {
      *
      * Optional — if not implemented, the service defensively treats the
      * version as frozen (fail-closed).
+     *
+     * Counts across every tenant, inside `RlsBypassPort`, and has to see every
+     * tenant's rows there, as `countByPlanVersionId` does.
      */
     countByBundleVersionId?(bundleVersionId: string): Promise<number>;
     /**
@@ -3749,8 +4543,9 @@ interface SubscriptionRepository {
      * (subscriptions on superseded versions are included).
      *
      * Returns a map `planKey → count`; plans without an active subscription
-     * are missing (UI defaults to 0). Platform-wide count across all tenants →
-     * adapters must count RLS-exempt.
+     * are missing (UI defaults to 0). Platform-wide count across all tenants:
+     * the platform calls it inside `RlsBypassPort`, and an implementation has to
+     * see every tenant's rows there, as for `countByPlanVersionId`.
      *
      * Optional — if not implemented, the tenant column stays 0.
      */
@@ -3826,6 +4621,22 @@ interface SubscriptionContractRepository {
      */
     findByOriginalOfferId(offerId: string, tx?: TransactionContext): Promise<SubscriptionContractRecord | null>;
     terminate(contractId: string, data: TerminateSubscriptionContractData): Promise<SubscriptionContractRecord>;
+    /**
+     * Ends a contract at `data.at` with the status `superseded`, where it is
+     * still as the caller read it: `active` or `scheduled`, and ending when it
+     * ended then. `null`, with nothing written, where it has moved since —
+     * another successor took its place, or a cancellation capped or ended it.
+     *
+     * The condition belongs to the write rather than to a read before it. Two
+     * callers superseding one contract at once — a plan change and an
+     * operator's refresh, say — then end with one successor: the second write
+     * finds the status the first one left and changes nothing, where a read
+     * followed by a plain update would give the tenant two contracts in force.
+     *
+     * With `tx`, written on that transaction and undone with it, so that the
+     * successor written beside it lands with it or not at all.
+     */
+    supersede(contractId: string, data: SupersedeSubscriptionContractData, tx?: TransactionContext): Promise<SubscriptionContractRecord | null>;
     /**
      * The contracts concluded and not yet over, with the issuer each was
      * concluded under: how many there are, and the first `limit` of them,
@@ -3848,8 +4659,8 @@ interface SubscriptionContractRepository {
      *
      * Platform-wide: unlike every other read here it is anchored by no tenant,
      * no contract and no offer, and a start makes it before anything is served.
-     * An implementation on a tenant-scoped client must count RLS-exempt, as
-     * `countActiveByPlanKey` must — the platform wraps the call in
+     * An implementation on a tenant-scoped client counts inside the bypass
+     * frame, as `countActiveByPlanKey` does — the platform wraps the call in
      * `RlsBypassPort`, and one that answers with the caller's tenant scope
      * instead returns nothing at a boot, where there is no tenant. The
      * persistence contract runs with no policy forced, so it cannot catch that
@@ -3926,7 +4737,7 @@ interface SubscriberLedgerRepository {
  *
  * The platform controller `GET /billing/usage` maps this form 1:1 into the
  * response body. The consumer adapter loads from its own subscription
- * table (Prisma include planVersion + pendingPlanVersion).
+ * table (Prisma include planVersion).
  */
 interface SubscriptionUsageRecord {
     /**
@@ -3985,6 +4796,17 @@ interface SubscriptionUsageRecord {
     pendingPlan: string | null;
     pendingBillingCycle: string | null;
     pendingEffectiveAt: Date | null;
+    /**
+     * The version a scheduled change binds when it lands, where it names one —
+     * a newer version taken for the end of the term, or the version a change
+     * to another plan was quoted at. Read where it matters whether the
+     * subscription stays on its version: a change on the same plan in the same
+     * rhythm is otherwise indistinguishable from staying put.
+     *
+     * Optional, because an adapter written before it does not pass it through;
+     * both shipped adapters do.
+     */
+    pendingChangeVersionId?: string | null;
     planVersion: {
         id: string;
         planId: string;
@@ -3993,18 +4815,6 @@ interface SubscriptionUsageRecord {
         supersededAt: Date | null;
         changeNote: string | null;
     };
-    pendingPlanVersion: {
-        id: string;
-        planId: string;
-        version: number;
-        nonRegressive: boolean;
-        changeNote: string | null;
-        /** Catalog diff form from version-publish; free-form JSON structure. */
-        publishedChanges: unknown;
-    } | null;
-    pendingPlanVersionEffectiveAt: Date | null;
-    pendingPlanVersionAccepted: boolean;
-    pendingPlanVersionAcceptedAt: Date | null;
     /**
      * P11.4: frozen package snapshot from the
      * `CheckoutOffer` that was activated during onboarding. Read-only —
@@ -4025,8 +4835,34 @@ interface SubscriptionUsageRecord {
  * Read adapter for the UI/display form of a subscription. Used by
  * `TenantBillingController.getUsage`.
  */
+/** A subscription read across tenants, with the tenant it belongs to. */
+interface TenantSubscriptionUsage {
+    readonly tenantId: string;
+    readonly subscription: SubscriptionUsageRecord & {
+        readonly id: string;
+    };
+}
 interface SubscriptionUsagePort {
     findForTenant(tenantId: string): Promise<SubscriptionUsageRecord | null>;
+    /**
+     * Every subscription of `planKey`, in every tenant, bound to a version of
+     * that plan numbered below `version`. The platform reads it to find the
+     * subscriptions a newer version is offered to, inside the RLS bypass.
+     *
+     * Optional, so a port written before it keeps working; an application that
+     * turns version notices on over a port without it is refused at start-up.
+     */
+    listBoundToEarlierVersions?(planKey: string, version: number): Promise<TenantSubscriptionUsage[]>;
+    /**
+     * Every subscription, in every tenant, bound to the plan version
+     * `planVersionId`, whatever its status. The platform reads it to find the
+     * subscriptions a retirement reaches, inside the RLS bypass, and decides
+     * itself which of them are still running.
+     *
+     * Optional, so a port written before it keeps working; a retirement over a
+     * port without it is refused at start-up.
+     */
+    listBoundToVersion?(planVersionId: string): Promise<TenantSubscriptionUsage[]>;
 }
 /**
  * Returns the current usage for all quotaKeys of a tenant declared via
@@ -4072,14 +4908,98 @@ interface ImmediatePlanChangeInput {
      * no cancellation, and loses against one that has acquired one.
      */
     expectedCanceledAt: Date | null;
+    /**
+     * Whether a change that leaves the plan as it is keeps the plan version
+     * the subscription is bound to.
+     *
+     * A scheduled change that only moves the rhythm passes `true`: the
+     * subscriber agreed to the version they are on, and moving them to a newer
+     * one is theirs to decide, by taking it when it is offered. A sale passes
+     * `false` — a change of plan, or onboarding, where the customer chose at
+     * the version in effect — and the write binds the version of `planId` in effect at
+     * `periodStart`. Where `planId` is another plan than the one bound, the
+     * version in effect is bound either way, and so it is where the
+     * subscription is bound to no version at all: it has none to keep.
+     */
+    keepsBoundVersion: boolean;
+    /**
+     * The version of `planId` the change was quoted at: a scheduled change to
+     * another plan passes the version its preview showed when it was
+     * scheduled, recorded as `pendingChangeVersionId`. The write binds it
+     * rather than the version in effect, so a version published in between
+     * does not reach the customer by a change they already agreed to. `null`
+     * binds the version in effect — a sale, onboarding, and a change quoted
+     * where no repository reads versions. A version kept by
+     * `keepsBoundVersion` wins over it.
+     */
+    quotedPlanVersionId: string | null;
+    /**
+     * `true`: bind `quotedPlanVersionId` or nothing. Where that version no
+     * longer takes bookings by `periodStart` (or now), the write claims nothing
+     * and answers `claimed: false`, rather than binding the version in effect.
+     * A switch to a version offered passes it: the subscriber agreed to that
+     * version, and what the switch answers and records names it. Left out, a
+     * version that stopped taking bookings gives way to the one in effect.
+     */
+    quotedVersionOnly?: boolean;
+    /**
+     * The version the caller read the subscription bound to, where its
+     * decision rests on it: the write claims the row only while that binding
+     * still holds. A switch to a version offered passes it — it writes back the
+     * plan it read, and a change made in between would otherwise be undone.
+     * `null` claims a row bound to no version. Left out, the binding is not
+     * claimed — and a write that binds no version (`bindsPlanVersion: false`)
+     * has none to claim.
+     */
+    expectedPlanVersionId?: string | null;
+    /**
+     * `true`: the change the subscription has scheduled survives the write. A
+     * retirement's move passes it — the change is the subscriber's own, and the
+     * move is not. One that only moves the rhythm on the plan being left follows
+     * the subscription to `planId` (`scheduledChangeAfterWrite`). The write then
+     * claims the row only while the scheduled change is still the one it read.
+     * Left out, the write clears it: a change the subscriber makes replaces the
+     * one they scheduled before.
+     */
+    keepsPendingChange?: boolean;
+    /**
+     * `true`: the write puts back a binding the subscription held a moment
+     * before, so `quotedPlanVersionId` counts whether or not it still takes
+     * bookings — it has to be a version of `planId`, nothing more. A
+     * retirement's move or switch passes it to bind the subscription back to
+     * the version retired, where the contract that has to come with the move
+     * could not be written: that version is off sale, often by its own end, and
+     * undoing a move is not a booking (`SC-PLAN-016` asks only of one). Left
+     * out, a version that no longer takes bookings is not bound.
+     */
+    restoresQuotedVersion?: boolean;
 }
 /** Input for `schedulePlanChange` (change at period end). */
 interface ScheduledPlanChangeInput {
     pendingPlan: string;
     pendingBillingCycle: string;
     pendingEffectiveAt: Date;
+    /**
+     * The version of `pendingPlan` the preview quoted, where the change does
+     * not keep the version bound — a change to another plan, or one on a
+     * subscription bound to none; stored as `pendingChangeVersionId` and bound
+     * when the change comes due. `null` where the plan stays on a bound
+     * version — the version bound then is kept, whatever it is by that day — or
+     * where no repository reads versions.
+     */
+    pendingChangeVersionId: string | null;
     /** See `ImmediatePlanChangeInput.expectedCanceledAt`. */
     expectedCanceledAt: Date | null;
+    /** See `ImmediatePlanChangeInput.expectedPlanVersionId`. */
+    expectedPlanVersionId?: string | null;
+    /**
+     * The change the caller read as scheduled, where its decision rests on it —
+     * `null` for nothing scheduled. The write claims the row only while that
+     * still holds. A switch to a version offered passes `null`: an offer is
+     * made only while nothing is scheduled, and a change scheduled in between
+     * would otherwise be written over. Left out, it is not claimed.
+     */
+    expectedPendingPlan?: string | null;
 }
 /**
  * Input for `applyOnboardingSelection`. Plan-change fields that the
@@ -4174,24 +5094,17 @@ interface TenantSubscriptionWritePort {
     changePlanImmediate(tenantId: string, input: ImmediatePlanChangeInput): Promise<{
         plan: string;
         billingCycle: string;
-        /** False when the row's cancellation moved since the caller read it. */
+        /**
+         * False when what the caller claimed moved since it read it — the
+         * cancellation, and the binding where it passed one — or when the
+         * version it required no longer takes bookings.
+         */
         claimed: boolean;
     }>;
     /** Change at period end: set pending fields. */
     schedulePlanChange(tenantId: string, input: ScheduledPlanChangeInput): Promise<{
         claimed: boolean;
     }>;
-    /**
-     * Marks the pending PlanVersion as accepted. Idempotent — a duplicate
-     * accept is a no-op. Returns `alreadyAccepted: true` if the status was
-     * already set.
-     */
-    acceptPendingPlanVersion(tenantId: string, userId: string, now: Date): Promise<{
-        accepted: boolean;
-        acceptedAt: Date | null;
-        effectiveAt: Date | null;
-        alreadyAccepted: boolean;
-    }>;
     /**
      * Record a cancellation. The dates are decided above this port.
      *
@@ -4233,30 +5146,22 @@ interface TenantSubscriptionWritePort {
 /** Read adapter for PlanVersions. */
 interface PlanVersionRepository {
     /**
-     * Currently published (= live) PlanVersion of a plan:
-     * `publishedAt IS NOT NULL AND supersededAt IS NULL`. Optionally within a
-     * transaction.
-     *
-     * Note: ignores `validFrom`/`validUntil`. For time-aware
-     * resolution (onboarding, plan fallback for TRIAL) use `findActive`.
-     *
-     * A plan key no plan has finds `null`, not an error.
-     */
-    findLatestLive(planId: string, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
-    /**
-     * PlanVersion of a plan active at `asOf`:
+     * The version of a plan on sale at `asOf` — what a booking made then
+     * binds — by the same rule as `PlanRepository.findActivePlanVersion`:
      *   `publishedAt IS NOT NULL`
      *   `(validFrom IS NULL OR validFrom <= asOf)`
      *   `(validUntil IS NULL OR validUntil >= startOfUtcDay(asOf))`
+     *   `(endsAt IS NULL OR endsAt > asOf)`
      *
      * `validUntil` is day-inclusive. If multiple versions match, adapters
-     * return the highest `validFrom`, explicitly ordering null start dates
-     * last as a legacy fallback. Adapters without validity columns may omit
-     * the method (consumers fall back to `findLatestLive`).
+     * return the highest `validFrom`, ordering null start dates last, then the
+     * highest version. Adapters build the WHERE with
+     * `buildActivePlanVersionWhere(asOf, { withEndsAt: true })`. Optionally
+     * within a transaction.
      *
      * A plan key no plan has finds `null`, not an error.
      */
-    findActive?(planId: string, asOf?: Date, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
+    findActive(planId: string, asOf?: Date, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
 }
 
 /** Aggregate snapshot of subscriptions, orchestrated by `AdminStatsService`. */
@@ -4275,6 +5180,11 @@ interface SubscriptionStatsSnapshot {
 /**
  * Stats adapter for subscriptions. Consumers implement this based on their
  * Prisma `subscription.groupBy(...)` / `count(...)` calls.
+ *
+ * The figures span every tenant: the platform reads them, together with the
+ * promo code and audit figures, inside `RlsBypassPort`, and an implementation
+ * has to see every tenant's rows there — as for
+ * `SubscriptionRepository.countByPlanVersionId`.
  */
 interface SubscriptionStatsPort {
     getStats(): Promise<SubscriptionStatsSnapshot>;
@@ -4321,6 +5231,19 @@ interface AdminActor {
     source: 'web' | 'cli';
     context: string;
 }
+/**
+ * A platform job acting on its own schedule — no person behind it, so no user:
+ * the canonical `audit_logs.userId` is nullable for exactly this. `context`
+ * names the job, and the actor tag reads `job:platform:<job>`.
+ */
+interface PlatformJobActor {
+    userId: null;
+    email: 'platform';
+    source: 'job';
+    context: string;
+}
+/** Whoever an audit entry names: a person, from the web or the CLI, or a platform job. */
+type AuditActor = AdminActor | PlatformJobActor;
 /**
  * Audit adapter: platform services write to the audit log through this
  * interface. The consumer implementation persists the records (e.g.
@@ -4332,7 +5255,7 @@ interface AdminActor {
  */
 interface AuditPort {
     write(input: {
-        actor: AdminActor;
+        actor: AuditActor;
         entity: string;
         entityId: string;
         action: string;
@@ -4475,6 +5398,14 @@ interface ManifestAccessPort {
  * good at boot as it is in a request.
  */
 interface RlsBypassPort {
+    /**
+     * Runs `fn` with the policy lifted. Where the installation keeps more than
+     * the flag in the frame — the user, the tenant, an audit actor — the bypass
+     * frame carries it over rather than replacing it: an operator's route runs
+     * inside it, and what the request's own frame held is still read there.
+     * `store.run({ ...store.getStore(), bypassRls: true }, fn)` rather than
+     * `store.run({ bypassRls: true }, fn)`.
+     */
     runWithBypass<T>(fn: () => Promise<T>): Promise<T>;
 }
 
@@ -4535,37 +5466,41 @@ interface PlanRepository {
     findVersionById?(versionId: string): Promise<PlanVersionRow | null>;
     findCurrentDraft?(planKey: string): Promise<PlanVersionRow | null>;
     /**
-     * Currently published (= live) PlanVersion of a plan:
+     * The newest published version of a plan:
      * `publishedAt IS NOT NULL AND supersededAt IS NULL`.
      *
-     * Note: returns the *newest* published version by
-     * `version` number and ignores `validFrom`/`validUntil`. For
-     * time-aware reads (onboarding, marketing catalog, entitlement
-     * fallback) use `findActivePlanVersion(planKey, asOf)`, which returns
-     * the version *active at a point in time*.
+     * The version a publish chains to, not the version on sale: a successor
+     * published today with a start next month is the newest at once, and its
+     * predecessor goes on selling until then. What is on sale — for a booking,
+     * a price, a catalogue, an offer — is `findActivePlanVersion`.
      */
     findLatestLivePlanVersion?(planKey: string, tx?: TransactionContext): Promise<PlanVersionRow | null>;
     /**
-     * PlanVersion of a plan active at `asOf` ( extended):
+     * The version of a plan on sale at `asOf` — the one a booking made then
+     * binds:
      *   `publishedAt IS NOT NULL`
      *   `(validFrom IS NULL OR validFrom <= asOf)`
      *   `(validUntil IS NULL OR validUntil >= startOfUtcDay(asOf))`  — day-inclusive
+     *   `(endsAt IS NULL OR endsAt > asOf)`
      *
-     * `validFrom IS NULL` is treated like "valid since forever" so that legacy data
-     * without a start date (published before the §4.2 publish requirement) does not
-     * fall out of the catalog. `validUntil` is day-inclusive (calendar day): the version
-     * is valid until the end of its validUntil day, not just until midnight.
-     * Adapters build the WHERE via `buildActivePlanVersionWhere`.
+     * `validFrom IS NULL` is treated like "valid since forever" so that a
+     * version published without a start date does not fall out of the
+     * catalogue. `validUntil` is day-inclusive (calendar day): the version is
+     * valid until the end of its validUntil day, not just until midnight.
+     * Adapters build the WHERE via
+     * `buildActivePlanVersionWhere(asOf, { withEndsAt: true })`.
      *
      * If multiple match: the one with the highest `validFrom` (= the
-     * "last active"). Adapters must request `NULLS LAST` explicitly so a
-     * null start date remains a genuine fallback. Default `asOf` is the call
-     * time.
+     * "last active"), then the highest version. Adapters must request
+     * `NULLS LAST` explicitly so a null start date remains a genuine fallback.
+     * Default `asOf` is the call time.
      *
-     * Usage: everything that concerns *new* bookings/plan changes
-     * (onboarding, public marketing, entitlement fallback on TRIAL).
-     * Existing subscriptions stay on their bound `planVersionId`
-     * (P1 contract protection).
+     * Every read of what is on sale goes through this — the catalogue, the
+     * plan-change preview, checkout, the public marketing catalogue, every
+     * booking and the offer to existing subscriptions — so all of them name
+     * the same version at the same moment. Existing subscriptions stay on
+     * their bound `planVersionId`. A repository that reads versions and
+     * leaves this out is refused at start-up.
      */
     findActivePlanVersion?(planKey: string, asOf?: Date, tx?: TransactionContext): Promise<PlanVersionRow | null>;
     /**
@@ -4663,27 +5598,30 @@ interface BundleRepository {
     findVersionById(versionId: string, tx?: TransactionContext): Promise<BundleVersionRow | null>;
     findCurrentDraft(bundleId: string): Promise<BundleVersionRow | null>;
     /**
-     * Currently published (= live) BundleVersion of a bundle:
+     * The newest published BundleVersion of a bundle:
      * `publishedAt IS NOT NULL AND supersededAt IS NULL`.
      *
-     * This deliberately ignores `validFrom`/`validUntil`. For new bookings
-     * and other time-aware catalog reads use `findActiveBundleVersion`.
+     * The version a publish chains to, not the version on sale: a successor
+     * published today with a start next month is the newest at once, and its
+     * predecessor goes on selling until then. What is on sale — for a booking,
+     * a catalogue, an upsell — is `findActiveBundleVersion`.
      */
     findLatestLive(bundleId: string, tx?: TransactionContext): Promise<BundleVersionRow | null>;
     /**
-     * BundleVersion active at `asOf`:
+     * The BundleVersion on sale at `asOf` — the one a booking made then may
+     * take:
      *   `publishedAt IS NOT NULL`
      *   `(validFrom IS NULL OR validFrom <= asOf)`
      *   `(validUntil IS NULL OR validUntil >= startOfUtcDay(asOf))`
+     *   `(supersededAt IS NULL OR validUntil IS NOT NULL)`
      *
-     * Both boundaries are inclusive. If multiple versions match, adapters
-     * return the highest `validFrom`, then the highest `version`; a null
-     * `validFrom` is a legacy fallback. Default `asOf` is the call time.
-     *
-     * Optional so adapters backed by legacy schemas without validity columns
-     * can omit the capability and consumers can fall back explicitly.
+     * Both boundaries are inclusive, and a superseded version sells only
+     * within a last day it carries — the rule of `buildActiveVersionWhere`.
+     * If multiple versions match, adapters return the highest `validFrom`,
+     * then the highest `version`; a null `validFrom` sorts last. Default
+     * `asOf` is the call time.
      */
-    findActiveBundleVersion?(bundleId: string, asOf?: Date, tx?: TransactionContext): Promise<BundleVersionRow | null>;
+    findActiveBundleVersion(bundleId: string, asOf?: Date, tx?: TransactionContext): Promise<BundleVersionRow | null>;
     /**
      * Creates a new draft version (`publishedAt = null`). Throws if
      * a draft already exists (partial unique index violation).
@@ -5174,6 +6112,135 @@ interface AppliedSettingsPort {
     acknowledgeChange(id: string, acknowledgedBy: string, acknowledgedAt: Date): Promise<SettingsChangeRecord | null>;
 }
 
+/**
+ * Keeps the maintenance windows, in the application's own database.
+ *
+ * Every running version of the application reads this table while the lock
+ * holds — the one being replaced as well as the one replacing it — so its shape
+ * is part of the contract between two releases: it gains columns, and never in
+ * a deploy the lock protects.
+ *
+ * An adapter translates. It does not decide whether a window may be locked or
+ * moved; it makes each write conditional on what the caller read, so that two
+ * operators acting at once cannot both succeed.
+ */
+interface MaintenanceWindowPort {
+    /** The open window — announced or locked, not yet over — or null. There is at most one. */
+    findOpen(): Promise<MaintenanceWindowRecord | null>;
+    /** The most recently recorded windows first, open or over; at most `limit` of them. */
+    listRecent(limit: number): Promise<MaintenanceWindowRecord[]>;
+    /**
+     * Records a new open window and returns it as stored — the id is the
+     * adapter's to assign. Returns null where a window is already open: the
+     * database holds an installation to one, so of two concurrent calls exactly
+     * one lands.
+     */
+    open(window: NewMaintenanceWindow): Promise<MaintenanceWindowRecord | null>;
+    /**
+     * Applies `changes` to window `id`, provided it is still open and at
+     * `stage`. Returns the window as stored, or null where it is not: it ended,
+     * it was locked in the meantime, or no window has that id.
+     */
+    update(id: string, stage: MaintenanceWindowStage, changes: MaintenanceWindowChanges): Promise<MaintenanceWindowRecord | null>;
+}
+/**
+ * Hears when a window is announced, moved or cancelled, so the application can
+ * write to its users. Optional: without it tenants learn of a window from the
+ * banner alone.
+ *
+ * Called after the change is recorded, and never waited on by the operator: a
+ * notification that fails is logged, and the window stands as recorded.
+ */
+interface MaintenanceNotificationPort {
+    windowChanged(event: MaintenanceWindowEvent): Promise<void>;
+}
+
+/** A notice to record before anybody is told: its key and what it says. */
+interface NoticeToRecord extends SubscriptionNoticeKey {
+    readonly content: unknown;
+}
+/**
+ * Keeps the record of every notice sent to a subscriber: one per subscription,
+ * kind and subject, with when and to whom it went.
+ *
+ * Delivery takes three writes so that a notice is sent once even where several
+ * instances run the same job: a run claims the notice, the application sends
+ * it, and the run confirms it — or releases it where the sending failed, for the
+ * next run to try again. Each write is conditional on what the caller read; an
+ * adapter translates and does not decide.
+ */
+interface SubscriptionNoticeRepository {
+    /**
+     * Records the notice named by `key` where it is not recorded yet, and
+     * claims it for this run: where it is not delivered and no run holds it,
+     * or the run that holds it took it on before `staleBefore`. A claim stores
+     * `content` as what the notice says. Returns the notice as claimed, or null
+     * where it is delivered or another run holds a fresh claim — of two
+     * concurrent calls exactly one claims it.
+     */
+    claim(key: SubscriptionNoticeKey, content: unknown, now: Date, staleBefore: Date): Promise<SubscriptionNoticeRecord | null>;
+    /**
+     * Records the notice `id` as delivered, provided it is still held by the
+     * claim taken at `claimedAt` and not delivered. Returns false where it is
+     * not: the claim went stale and another run took the notice on.
+     */
+    confirm(id: string, claimedAt: Date, delivery: SubscriptionNoticeDelivery, now: Date): Promise<boolean>;
+    /**
+     * Lets go of the claim taken at `claimedAt`, so the next run tries again.
+     * Does nothing where the notice is delivered or held by another claim.
+     */
+    release(id: string, claimedAt: Date): Promise<void>;
+    /** The subscriptions a notice of `kind` about `subject` has been delivered to. */
+    listDeliveredSubscriptionIds(kind: SubscriptionNoticeKind, subject: string): Promise<string[]>;
+    /** Every notice of one subscription, the most recently recorded first. */
+    listForSubscription(subscriptionId: string): Promise<SubscriptionNoticeRecord[]>;
+    /**
+     * Records each notice where it is not recorded yet, unclaimed and not
+     * delivered — in the caller's transaction where one is given, so a notice
+     * exists exactly when what it tells of does. A notice already recorded
+     * under the same key is left as it is and not counted: the answer is how
+     * many were recorded now, so a caller can tell that another got there
+     * first — under a transaction running beside it as well.
+     */
+    record(notices: readonly NoticeToRecord[], now: Date, tx?: TransactionContext): Promise<number>;
+    /** Every notice of `kind` recorded at or after `since`, the most recent first. */
+    listOfKindSince(kind: SubscriptionNoticeKind, since: Date): Promise<SubscriptionNoticeRecord[]>;
+    /**
+     * The notices of `kind` that are not delivered and that no run holds — never
+     * claimed, released, or claimed before `staleBefore` — the oldest first.
+     */
+    listUndelivered(kind: SubscriptionNoticeKind, staleBefore: Date): Promise<SubscriptionNoticeRecord[]>;
+}
+/**
+ * Sends a notice to the administrators of the tenant it is for, in the
+ * application's words and through its channels. The platform decides when a
+ * notice is due; who the administrators are, what the message says and how it
+ * travels are the application's.
+ *
+ * Resolve with who it went to and how — the platform keeps that as the record.
+ * Throw where it could not be sent and should be tried again: the claim is
+ * released and the next run sends it. Resolving with no recipients records that
+ * nobody could be told, and the notice is not tried again — except a
+ * retirement's notice (`version-retired`), which nobody was told of: it is tried
+ * again by every run until somebody is, and its date counts from then.
+ */
+interface SubscriptionNoticePort {
+    deliver(notice: SubscriptionNotice): Promise<SubscriptionNoticeDelivery>;
+}
+
+/**
+ * Keeps every retirement announcement: which version, which replacement, when
+ * and by whom. What it means for each subscription it reaches is kept beside it
+ * as a notice of kind `version-retired`, written in the same transaction.
+ */
+interface VersionRetirementRepository {
+    /** Records an announcement, in the caller's transaction where one is given. */
+    create(data: NewVersionRetirement, tx?: TransactionContext): Promise<VersionRetirementRecord>;
+    /** Every announcement, the most recent first. */
+    list(): Promise<VersionRetirementRecord[]>;
+    findById(id: string): Promise<VersionRetirementRecord | null>;
+}
+
 /** Class reference usable as a DI token (e.g. the consumer's `PrismaService`). */
 type PersistenceClassRef = abstract new (...args: never[]) => unknown;
 /** DI token forms a persistence bundle may reference in `inject`. */
@@ -5211,9 +6278,11 @@ interface PersistenceCapabilities {
      */
     pessimisticLocking: boolean;
     /**
-     * The adapter stack integrates with Postgres row-level security (the
-     * `RlsBypassPort` frame actually lifts RLS for SuperAdmin reads).
-     * Informational — RLS policies themselves remain consumer-owned.
+     * The adapter stack integrates with Postgres row-level security: the
+     * `RlsBypassPort` frame lifts the installation's policies for what the
+     * platform does across tenants, reads and writes alike. Informational —
+     * nothing in the platform reads it, and the policies themselves remain
+     * the installation's.
      */
     rowLevelSecurity: boolean;
     /** Advisory-lock support (`pg_advisory_*`). No platform path requires it today. */
@@ -5221,7 +6290,12 @@ interface PersistenceCapabilities {
 }
 /** Always-required slice: admin surface + transactions. */
 interface SaaSiCatPersistenceCore {
-    mfa: PersistenceProvider<MfaPort>;
+    /**
+     * Absent where the schema leaves the SuperAdmin MFA table out
+     * (`notAdopted: ['SuperAdminMfa']`); the application then passes its own
+     * `MfaPort` in `adapters`, and a start without one is refused.
+     */
+    mfa?: PersistenceProvider<MfaPort>;
     audit: PersistenceProvider<AuditPort>;
     rlsBypass: PersistenceProvider<RlsBypassPort>;
     transactionRunner: PersistenceProvider<TransactionRunner>;
@@ -5237,6 +6311,13 @@ interface SaaSiCatPersistenceCore {
      * platform says once at boot that it is not recording.
      */
     appliedSettings?: PersistenceProvider<AppliedSettingsPort>;
+    /**
+     * Where maintenance windows are kept (`maintenance` in
+     * `SaaSiCatModule.forRoot`). Optional so an adapter written before it
+     * existed keeps working; an installation that turns maintenance on without
+     * one is refused at start-up.
+     */
+    maintenanceWindows?: PersistenceProvider<MaintenanceWindowPort>;
 }
 /** Repositories for the entitlement/contract loop (`EntitlementModule`). */
 interface SaaSiCatPersistenceEntitlement {
@@ -5272,6 +6353,18 @@ interface SaaSiCatPersistenceTenantBilling {
     subscriptionUsagePort: PersistenceProvider<SubscriptionUsagePort>;
     subscriptionWritePort: PersistenceProvider<TenantSubscriptionWritePort>;
     usageSnapshotPort?: PersistenceProvider<UsageSnapshotPort>;
+    /**
+     * The record of what each subscriber was told (`tenantBilling.versionNotices`).
+     * Optional so an adapter written before it keeps working; an installation
+     * that turns notices on without one is refused at start-up.
+     */
+    subscriptionNotices?: PersistenceProvider<SubscriptionNoticeRepository>;
+    /**
+     * The record of every retirement announcement. Optional so an adapter
+     * written before it keeps working; an installation that lets an operator
+     * retire versions without one is refused at start-up.
+     */
+    versionRetirements?: PersistenceProvider<VersionRetirementRepository>;
 }
 /**
  * The record of payment gateway callbacks and the payment methods they confirm
@@ -5386,10 +6479,41 @@ declare const CATALOG_ERROR_CODES: {
     readonly PLAN_TERMINATE_INVALID_DATE: "PLAN_TERMINATE_INVALID_DATE";
     readonly PLAN_TERMINATE_DATE_NOT_FUTURE: "PLAN_TERMINATE_DATE_NOT_FUTURE";
     readonly PLAN_TERMINATE_NOT_IMPLEMENTED: "PLAN_TERMINATE_NOT_IMPLEMENTED";
+    /**
+     * Subscriptions told of a retirement still move onto this version, and
+     * nothing moves onto a version that has ended. Carries the version, its
+     * plan key and the first day it may end: the day after the last move.
+     */
+    readonly PLAN_TERMINATE_BEFORE_RETIREMENT_MOVES: "PLAN_TERMINATE_BEFORE_RETIREMENT_MOVES";
+    /**
+     * Subscriptions told of a retirement are past their date and still to be
+     * moved onto this version — a move the platform could not make yet — so it
+     * cannot end until they have moved. Carries how many, the version and its
+     * plan key.
+     */
+    readonly PLAN_TERMINATE_WHILE_MOVES_OVERDUE: "PLAN_TERMINATE_WHILE_MOVES_OVERDUE";
+    /**
+     * Subscriptions on a retired version have not yet been told of their move
+     * onto this version — their notice has reached nobody, so their date is not
+     * set — and it cannot end until they have been. Carries how many, the
+     * version and its plan key.
+     */
+    readonly PLAN_TERMINATE_WHILE_NOTICES_UNDELIVERED: "PLAN_TERMINATE_WHILE_NOTICES_UNDELIVERED";
     readonly BUNDLE_VERSION_ALREADY_PUBLISHED: "BUNDLE_VERSION_ALREADY_PUBLISHED";
     readonly BUNDLE_VERSION_NOT_EDITABLE: "BUNDLE_VERSION_NOT_EDITABLE";
     readonly BUNDLE_VERSION_NOT_PUBLISHED: "BUNDLE_VERSION_NOT_PUBLISHED";
     readonly BUNDLE_VERSION_SUPERSEDED: "BUNDLE_VERSION_SUPERSEDED";
+    /**
+     * The bundle version is published, and its window has not opened: it goes
+     * on sale on `validFrom`, and until then its predecessor is the one sold.
+     */
+    readonly BUNDLE_VERSION_NOT_YET_ON_SALE: "BUNDLE_VERSION_NOT_YET_ON_SALE";
+    /**
+     * The add-on itself has been deleted from the catalogue. Deleting it leaves
+     * its versions' dates as they were, so the version asked for can still be
+     * inside its window; it is not on offer all the same.
+     */
+    readonly BUNDLE_DELETED: "BUNDLE_DELETED";
     readonly BUNDLE_VERSION_REGRESSION: "BUNDLE_VERSION_REGRESSION";
     readonly BUNDLE_VERSION_ZERO_PRICE: "BUNDLE_VERSION_ZERO_PRICE";
     readonly BUNDLE_VERSION_NO_PRICE: "BUNDLE_VERSION_NO_PRICE";
@@ -5446,6 +6570,22 @@ declare const BILLING_ERROR_CODES: {
     readonly BUNDLE_NOT_SELF_SERVICE: "BUNDLE_NOT_SELF_SERVICE";
     readonly BUNDLE_CYCLE_EXCEEDS_PLAN: "BUNDLE_CYCLE_EXCEEDS_PLAN";
     readonly BUNDLE_NOT_PRICED_FOR_THIS_PLAN: "BUNDLE_NOT_PRICED_FOR_THIS_PLAN";
+    /**
+     * The bundle cannot run on a plan the subscription is already set to move
+     * to — by a scheduled change, or by a retirement it has been told of — and
+     * the booking would still be running then: that plan does not book it, or
+     * has no price for it. Carries that plan's key, the rhythm it is billed in
+     * there, and the day the move takes effect from, which can lie in the past
+     * while the move has not run yet.
+     */
+    readonly BUNDLE_CANNOT_RUN_ON_UPCOMING_PLAN: "BUNDLE_CANNOT_RUN_ON_UPCOMING_PLAN";
+    /**
+     * As `BUNDLE_CANNOT_RUN_ON_UPCOMING_PLAN`, where only the rhythm stands in
+     * the way: a yearly bundle, and the subscription billed monthly from the
+     * day of the move — a switch of rhythm on the plan it keeps, for one, where
+     * naming the plan would point at the one it is already on. Same values.
+     */
+    readonly BUNDLE_CANNOT_RUN_ON_UPCOMING_CYCLE: "BUNDLE_CANNOT_RUN_ON_UPCOMING_CYCLE";
     readonly SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED: "SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED";
     readonly SUBSCRIPTION_BUNDLE_NOT_CANCELLED: "SUBSCRIPTION_BUNDLE_NOT_CANCELLED";
     readonly SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE: "SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE";
@@ -5464,6 +6604,12 @@ declare const BILLING_ERROR_CODES: {
      * in it: a plan without a yearly price is a monthly plan.
      */
     readonly PLAN_NOT_SOLD_IN_CYCLE: "PLAN_NOT_SOLD_IN_CYCLE";
+    /**
+     * The subscription is bound to a plan version the plan repository does not
+     * find, or finds as a version of another plan. What the subscription pays
+     * cannot be read, so no change is quoted until the binding is repaired.
+     */
+    readonly BOUND_PLAN_VERSION_UNREADABLE: "BOUND_PLAN_VERSION_UNREADABLE";
     /** Plan change refused. Carries `blockers[]` with their own codes. */
     readonly PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED";
     /**
@@ -5486,6 +6632,102 @@ declare const BILLING_ERROR_CODES: {
      * Carries the recomputed dates, so the page can re-ask instead of guessing.
      */
     readonly CANCELLATION_TERMS_CHANGED: "CANCELLATION_TERMS_CHANGED";
+    /**
+     * The version the caller asked to switch to is no longer the one offered —
+     * another is on sale, the subscription moved, or there is no offer. Nothing
+     * was switched. Carries the current `offer`, or `null`, so the page can show
+     * it instead of guessing.
+     */
+    readonly VERSION_OFFER_CHANGED: "VERSION_OFFER_CHANGED";
+    /**
+     * The version a change to another plan named is not the one on sale when
+     * the change was submitted: its preview was shown at another moment.
+     * Nothing was changed. Carries the current `preview`, so the page shows
+     * what the change binds now instead of what it would have.
+     */
+    readonly PLAN_CHANGE_QUOTE_CHANGED: "PLAN_CHANGE_QUOTE_CHANGED";
+    /**
+     * A change to another plan named no version, where its preview names one:
+     * nothing says which price and terms the customer was shown, so nothing
+     * is changed.
+     */
+    readonly PLAN_CHANGE_VERSION_NOT_NAMED: "PLAN_CHANGE_VERSION_NOT_NAMED";
+    /**
+     * A version that takes something away takes effect when the term ends, and
+     * the subscription's cancellation lands no later: the switch would never
+     * happen, so it is refused rather than recorded. Carries both dates.
+     */
+    readonly VERSION_SWITCH_AFTER_CANCELLATION: "VERSION_SWITCH_AFTER_CANCELLATION";
+    /**
+     * A version that takes something away takes effect when the term ends, and
+     * it stops being sold before then — by its window or because an operator
+     * ended it — so it could not be bound when the change comes due. Refused
+     * rather than recorded; carries the dates.
+     */
+    readonly VERSION_ENDS_BEFORE_SWITCH: "VERSION_ENDS_BEFORE_SWITCH";
+    /**
+     * The operator's terms are not confirmed to carry the clause a retirement
+     * rests on (`tenantBilling.orderlyRetirement.termsConfirmed` in
+     * `config/saas.yaml`), so none is accepted.
+     */
+    readonly RETIREMENT_TERMS_NOT_CONFIRMED: "RETIREMENT_TERMS_NOT_CONFIRMED";
+    /**
+     * The version is still on sale: a subscription booked after the
+     * announcement would be on it without having been told. Carries the plan
+     * key and the version.
+     */
+    readonly RETIREMENT_VERSION_ON_SALE: "RETIREMENT_VERSION_ON_SALE";
+    /** The replacement is not on sale, so nobody can continue on it. Carries plan key and version. */
+    readonly RETIREMENT_REPLACEMENT_NOT_ON_SALE: "RETIREMENT_REPLACEMENT_NOT_ON_SALE";
+    /**
+     * The replacement has no price in the rhythm some of the subscriptions it
+     * reaches are billed in, so they cannot continue on it. Carries how many,
+     * and the replacement's plan key and version.
+     */
+    readonly RETIREMENT_REPLACEMENT_NOT_SOLD_IN_RHYTHM: "RETIREMENT_REPLACEMENT_NOT_SOLD_IN_RHYTHM";
+    /**
+     * Some of the subscriptions the retirement reaches hold an add-on that
+     * cannot run on the replacement's plan, so they cannot continue on it.
+     * Carries how many, and the replacement's plan key and version.
+     */
+    readonly RETIREMENT_REPLACEMENT_CANNOT_CARRY_BUNDLES: "RETIREMENT_REPLACEMENT_CANNOT_CARRY_BUNDLES";
+    /** The replacement named is the version being retired. */
+    readonly RETIREMENT_REPLACEMENT_IS_RETIRED: "RETIREMENT_REPLACEMENT_IS_RETIRED";
+    /** No running subscription is on the version: there is nobody to tell. Carries plan key and version. */
+    readonly RETIREMENT_NOTHING_AFFECTED: "RETIREMENT_NOTHING_AFFECTED";
+    /**
+     * Some of the subscriptions it reaches were reached by a retirement within
+     * the last twelve months, and a subscription is reached at most once in that
+     * time. Carries how many and which.
+     */
+    readonly RETIREMENT_WITHIN_TWELVE_MONTHS: "RETIREMENT_WITHIN_TWELVE_MONTHS";
+    /**
+     * The subscriptions the retirement reaches, or their dates, changed since
+     * the preview the operator confirmed. Carries the preview as it stands.
+     */
+    readonly RETIREMENT_PREVIEW_CHANGED: "RETIREMENT_PREVIEW_CHANGED";
+    /** No retirement of the subscription's version waits for its date: there is nothing to switch to. */
+    readonly RETIREMENT_SWITCH_NOT_PENDING: "RETIREMENT_SWITCH_NOT_PENDING";
+    /** The switch opens once the trial has converted: a trial has no contract to hold the price on. */
+    readonly RETIREMENT_SWITCH_IN_TRIAL: "RETIREMENT_SWITCH_IN_TRIAL";
+    /**
+     * An add-on running today cannot run beside the replacement's plan, which
+     * the switch would move the subscription onto today. Carries the add-on,
+     * the plan and the earliest day the booking can end. Its own code rather
+     * than a plan change's: the switch has no other plan to choose and no day
+     * to pick, so the way past it is the add-on ending.
+     */
+    readonly RETIREMENT_SWITCH_BUNDLE_CANNOT_FOLLOW: "RETIREMENT_SWITCH_BUNDLE_CANNOT_FOLLOW";
+    /**
+     * The subscription takes no switch now: a change is scheduled, it has
+     * ended, or its plan is held for a special contract.
+     */
+    readonly RETIREMENT_SWITCH_NOT_OPEN: "RETIREMENT_SWITCH_NOT_OPEN";
+    /**
+     * The version named is not the replacement the retirement names. Carries
+     * the retirement as it now stands.
+     */
+    readonly RETIREMENT_SWITCH_CHANGED: "RETIREMENT_SWITCH_CHANGED";
     /** The subscription has ended; its plan can no longer be changed. */
     readonly SUBSCRIPTION_ENDED: "SUBSCRIPTION_ENDED";
     /** An active special contract blocks self-service plan changes. */
@@ -5503,14 +6745,23 @@ declare const BILLING_ERROR_CODES: {
     readonly CANCELLATION_LOCKS_THE_CYCLE: "CANCELLATION_LOCKS_THE_CYCLE";
     /**
      * A bundle the tenant already holds runs past the cycle they are moving to.
+     * Carries the bundle, the earliest day the booking can end, and the two
+     * rhythms.
      *
      * Its own code rather than `BUNDLE_CYCLE_EXCEEDS_PLAN`, which states the
      * same rule about a booking that has not been made yet. The two need
      * different sentences: this one can name the day the obstacle lifts and
-     * tell the reader to cancel the booking, and that advice is wrong for
-     * someone who is only about to book. One template cannot serve both.
+     * tell the reader how to get past it, and that advice is wrong for someone
+     * who is only about to book. One template cannot serve both.
      */
     readonly BUNDLE_BOOKING_OUTLASTS_TARGET_CYCLE: "BUNDLE_BOOKING_OUTLASTS_TARGET_CYCLE";
+    /**
+     * A bundle the tenant already holds cannot run on the plan they are moving
+     * to: that plan may not book it, or it has no price there in the rhythm
+     * the booking is billed in. Carries the bundle, the plan and the earliest
+     * day the booking can end.
+     */
+    readonly BUNDLE_BOOKING_DOES_NOT_FIT_TARGET_PLAN: "BUNDLE_BOOKING_DOES_NOT_FIT_TARGET_PLAN";
     /**
      * Features of the previewed bundle are already covered by the plan or by
      * another booked bundle. A warning rather than a blocker: paying twice is
@@ -5532,7 +6783,6 @@ declare const BILLING_ERROR_CODES: {
      * tenant reads and therefore needs a shipped text for.
      */
     readonly BUNDLE_FEATURE_DEPENDENCY_UNSATISFIED: "BUNDLE_FEATURE_DEPENDENCY_UNSATISFIED";
-    readonly NO_PENDING_PLAN_VERSION: "NO_PENDING_PLAN_VERSION";
     readonly ONBOARDING_CREATE_FAILED: "ONBOARDING_CREATE_FAILED";
     readonly BUNDLE_PREVIEW_ARGUMENT_AMBIGUOUS: "BUNDLE_PREVIEW_ARGUMENT_AMBIGUOUS";
     /**
@@ -5584,6 +6834,14 @@ declare const CONTRACT_ERROR_CODES: {
     readonly SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND";
     readonly NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT";
     readonly SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED";
+    /**
+     * A successor would run beside another contract of the tenant: the
+     * contract in force moved while it was being written — another successor
+     * took its place, or a cancellation capped it — and kept moving on a
+     * second attempt, or a contract begins after the moment the successor
+     * would take effect. Nothing was written.
+     */
+    readonly SUBSCRIPTION_CONTRACT_CHANGED: "SUBSCRIPTION_CONTRACT_CHANGED";
 };
 type ContractErrorCode = (typeof CONTRACT_ERROR_CODES)[keyof typeof CONTRACT_ERROR_CODES];
 /** The parties contracts are concluded with (`SubscriberService`), and their absence. */
@@ -5707,6 +6965,26 @@ declare const SETTINGS_ERROR_CODES: {
     readonly SETTINGS_CHANGE_NOT_FOUND: "SETTINGS_CHANGE_NOT_FOUND";
 };
 type SettingsErrorCode = (typeof SETTINGS_ERROR_CODES)[keyof typeof SETTINGS_ERROR_CODES];
+/** Codes of maintenance windows: the lock's refusal, and the operator's routes. */
+declare const MAINTENANCE_ERROR_CODES: {
+    /** The application is locked for maintenance; the body carries the window. */
+    readonly MAINTENANCE: "MAINTENANCE";
+    /** A window is already open: move or cancel it before announcing another. */
+    readonly MAINTENANCE_WINDOW_ALREADY_OPEN: "MAINTENANCE_WINDOW_ALREADY_OPEN";
+    /** No open window has this id — it ended, or it never existed. */
+    readonly MAINTENANCE_WINDOW_NOT_OPEN: "MAINTENANCE_WINDOW_NOT_OPEN";
+    /** The window is locked: its start is history, and unlocking is what ends it. */
+    readonly MAINTENANCE_WINDOW_LOCKED: "MAINTENANCE_WINDOW_LOCKED";
+    /** The announced end is not after the announced start. */
+    readonly MAINTENANCE_WINDOW_END_NOT_AFTER_START: "MAINTENANCE_WINDOW_END_NOT_AFTER_START";
+    /** The announced end has already passed. */
+    readonly MAINTENANCE_WINDOW_END_IN_PAST: "MAINTENANCE_WINDOW_END_IN_PAST";
+    /** A time without its zone, or not a date and time at all; `field` names which. */
+    readonly MAINTENANCE_TIME_INVALID: "MAINTENANCE_TIME_INVALID";
+    /** The message is longer than `MAINTENANCE_MESSAGE_MAX_LENGTH`. */
+    readonly MAINTENANCE_MESSAGE_TOO_LONG: "MAINTENANCE_MESSAGE_TOO_LONG";
+};
+type MaintenanceErrorCode = (typeof MAINTENANCE_ERROR_CODES)[keyof typeof MAINTENANCE_ERROR_CODES];
 /**
  * Every exception code the platform emits, in one object.
  *
@@ -5715,6 +6993,22 @@ type SettingsErrorCode = (typeof SETTINGS_ERROR_CODES)[keyof typeof SETTINGS_ERR
  * removing one may not.
  */
 declare const PLATFORM_ERROR_CODES: {
+    /** The application is locked for maintenance; the body carries the window. */
+    readonly MAINTENANCE: "MAINTENANCE";
+    /** A window is already open: move or cancel it before announcing another. */
+    readonly MAINTENANCE_WINDOW_ALREADY_OPEN: "MAINTENANCE_WINDOW_ALREADY_OPEN";
+    /** No open window has this id — it ended, or it never existed. */
+    readonly MAINTENANCE_WINDOW_NOT_OPEN: "MAINTENANCE_WINDOW_NOT_OPEN";
+    /** The window is locked: its start is history, and unlocking is what ends it. */
+    readonly MAINTENANCE_WINDOW_LOCKED: "MAINTENANCE_WINDOW_LOCKED";
+    /** The announced end is not after the announced start. */
+    readonly MAINTENANCE_WINDOW_END_NOT_AFTER_START: "MAINTENANCE_WINDOW_END_NOT_AFTER_START";
+    /** The announced end has already passed. */
+    readonly MAINTENANCE_WINDOW_END_IN_PAST: "MAINTENANCE_WINDOW_END_IN_PAST";
+    /** A time without its zone, or not a date and time at all; `field` names which. */
+    readonly MAINTENANCE_TIME_INVALID: "MAINTENANCE_TIME_INVALID";
+    /** The message is longer than `MAINTENANCE_MESSAGE_MAX_LENGTH`. */
+    readonly MAINTENANCE_MESSAGE_TOO_LONG: "MAINTENANCE_MESSAGE_TOO_LONG";
     /** No recorded change has this id, or the installation keeps no record at all. */
     readonly SETTINGS_CHANGE_NOT_FOUND: "SETTINGS_CHANGE_NOT_FOUND";
     /**
@@ -5812,6 +7106,14 @@ declare const PLATFORM_ERROR_CODES: {
     readonly SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND";
     readonly NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT";
     readonly SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED";
+    /**
+     * A successor would run beside another contract of the tenant: the
+     * contract in force moved while it was being written — another successor
+     * took its place, or a cancellation capped it — and kept moving on a
+     * second attempt, or a contract begins after the moment the successor
+     * would take effect. Nothing was written.
+     */
+    readonly SUBSCRIPTION_CONTRACT_CHANGED: "SUBSCRIPTION_CONTRACT_CHANGED";
     /**
      * Feature not covered by the plan. Defined in `upsell.types.ts` because the
      * upsell body type is built around it; re-exported here so an exhaustive
@@ -5823,6 +7125,22 @@ declare const PLATFORM_ERROR_CODES: {
     readonly BUNDLE_NOT_SELF_SERVICE: "BUNDLE_NOT_SELF_SERVICE";
     readonly BUNDLE_CYCLE_EXCEEDS_PLAN: "BUNDLE_CYCLE_EXCEEDS_PLAN";
     readonly BUNDLE_NOT_PRICED_FOR_THIS_PLAN: "BUNDLE_NOT_PRICED_FOR_THIS_PLAN";
+    /**
+     * The bundle cannot run on a plan the subscription is already set to move
+     * to — by a scheduled change, or by a retirement it has been told of — and
+     * the booking would still be running then: that plan does not book it, or
+     * has no price for it. Carries that plan's key, the rhythm it is billed in
+     * there, and the day the move takes effect from, which can lie in the past
+     * while the move has not run yet.
+     */
+    readonly BUNDLE_CANNOT_RUN_ON_UPCOMING_PLAN: "BUNDLE_CANNOT_RUN_ON_UPCOMING_PLAN";
+    /**
+     * As `BUNDLE_CANNOT_RUN_ON_UPCOMING_PLAN`, where only the rhythm stands in
+     * the way: a yearly bundle, and the subscription billed monthly from the
+     * day of the move — a switch of rhythm on the plan it keeps, for one, where
+     * naming the plan would point at the one it is already on. Same values.
+     */
+    readonly BUNDLE_CANNOT_RUN_ON_UPCOMING_CYCLE: "BUNDLE_CANNOT_RUN_ON_UPCOMING_CYCLE";
     readonly SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED: "SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED";
     readonly SUBSCRIPTION_BUNDLE_NOT_CANCELLED: "SUBSCRIPTION_BUNDLE_NOT_CANCELLED";
     readonly SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE: "SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE";
@@ -5841,6 +7159,12 @@ declare const PLATFORM_ERROR_CODES: {
      * in it: a plan without a yearly price is a monthly plan.
      */
     readonly PLAN_NOT_SOLD_IN_CYCLE: "PLAN_NOT_SOLD_IN_CYCLE";
+    /**
+     * The subscription is bound to a plan version the plan repository does not
+     * find, or finds as a version of another plan. What the subscription pays
+     * cannot be read, so no change is quoted until the binding is repaired.
+     */
+    readonly BOUND_PLAN_VERSION_UNREADABLE: "BOUND_PLAN_VERSION_UNREADABLE";
     /** Plan change refused. Carries `blockers[]` with their own codes. */
     readonly PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED";
     /**
@@ -5863,6 +7187,102 @@ declare const PLATFORM_ERROR_CODES: {
      * Carries the recomputed dates, so the page can re-ask instead of guessing.
      */
     readonly CANCELLATION_TERMS_CHANGED: "CANCELLATION_TERMS_CHANGED";
+    /**
+     * The version the caller asked to switch to is no longer the one offered —
+     * another is on sale, the subscription moved, or there is no offer. Nothing
+     * was switched. Carries the current `offer`, or `null`, so the page can show
+     * it instead of guessing.
+     */
+    readonly VERSION_OFFER_CHANGED: "VERSION_OFFER_CHANGED";
+    /**
+     * The version a change to another plan named is not the one on sale when
+     * the change was submitted: its preview was shown at another moment.
+     * Nothing was changed. Carries the current `preview`, so the page shows
+     * what the change binds now instead of what it would have.
+     */
+    readonly PLAN_CHANGE_QUOTE_CHANGED: "PLAN_CHANGE_QUOTE_CHANGED";
+    /**
+     * A change to another plan named no version, where its preview names one:
+     * nothing says which price and terms the customer was shown, so nothing
+     * is changed.
+     */
+    readonly PLAN_CHANGE_VERSION_NOT_NAMED: "PLAN_CHANGE_VERSION_NOT_NAMED";
+    /**
+     * A version that takes something away takes effect when the term ends, and
+     * the subscription's cancellation lands no later: the switch would never
+     * happen, so it is refused rather than recorded. Carries both dates.
+     */
+    readonly VERSION_SWITCH_AFTER_CANCELLATION: "VERSION_SWITCH_AFTER_CANCELLATION";
+    /**
+     * A version that takes something away takes effect when the term ends, and
+     * it stops being sold before then — by its window or because an operator
+     * ended it — so it could not be bound when the change comes due. Refused
+     * rather than recorded; carries the dates.
+     */
+    readonly VERSION_ENDS_BEFORE_SWITCH: "VERSION_ENDS_BEFORE_SWITCH";
+    /**
+     * The operator's terms are not confirmed to carry the clause a retirement
+     * rests on (`tenantBilling.orderlyRetirement.termsConfirmed` in
+     * `config/saas.yaml`), so none is accepted.
+     */
+    readonly RETIREMENT_TERMS_NOT_CONFIRMED: "RETIREMENT_TERMS_NOT_CONFIRMED";
+    /**
+     * The version is still on sale: a subscription booked after the
+     * announcement would be on it without having been told. Carries the plan
+     * key and the version.
+     */
+    readonly RETIREMENT_VERSION_ON_SALE: "RETIREMENT_VERSION_ON_SALE";
+    /** The replacement is not on sale, so nobody can continue on it. Carries plan key and version. */
+    readonly RETIREMENT_REPLACEMENT_NOT_ON_SALE: "RETIREMENT_REPLACEMENT_NOT_ON_SALE";
+    /**
+     * The replacement has no price in the rhythm some of the subscriptions it
+     * reaches are billed in, so they cannot continue on it. Carries how many,
+     * and the replacement's plan key and version.
+     */
+    readonly RETIREMENT_REPLACEMENT_NOT_SOLD_IN_RHYTHM: "RETIREMENT_REPLACEMENT_NOT_SOLD_IN_RHYTHM";
+    /**
+     * Some of the subscriptions the retirement reaches hold an add-on that
+     * cannot run on the replacement's plan, so they cannot continue on it.
+     * Carries how many, and the replacement's plan key and version.
+     */
+    readonly RETIREMENT_REPLACEMENT_CANNOT_CARRY_BUNDLES: "RETIREMENT_REPLACEMENT_CANNOT_CARRY_BUNDLES";
+    /** The replacement named is the version being retired. */
+    readonly RETIREMENT_REPLACEMENT_IS_RETIRED: "RETIREMENT_REPLACEMENT_IS_RETIRED";
+    /** No running subscription is on the version: there is nobody to tell. Carries plan key and version. */
+    readonly RETIREMENT_NOTHING_AFFECTED: "RETIREMENT_NOTHING_AFFECTED";
+    /**
+     * Some of the subscriptions it reaches were reached by a retirement within
+     * the last twelve months, and a subscription is reached at most once in that
+     * time. Carries how many and which.
+     */
+    readonly RETIREMENT_WITHIN_TWELVE_MONTHS: "RETIREMENT_WITHIN_TWELVE_MONTHS";
+    /**
+     * The subscriptions the retirement reaches, or their dates, changed since
+     * the preview the operator confirmed. Carries the preview as it stands.
+     */
+    readonly RETIREMENT_PREVIEW_CHANGED: "RETIREMENT_PREVIEW_CHANGED";
+    /** No retirement of the subscription's version waits for its date: there is nothing to switch to. */
+    readonly RETIREMENT_SWITCH_NOT_PENDING: "RETIREMENT_SWITCH_NOT_PENDING";
+    /** The switch opens once the trial has converted: a trial has no contract to hold the price on. */
+    readonly RETIREMENT_SWITCH_IN_TRIAL: "RETIREMENT_SWITCH_IN_TRIAL";
+    /**
+     * An add-on running today cannot run beside the replacement's plan, which
+     * the switch would move the subscription onto today. Carries the add-on,
+     * the plan and the earliest day the booking can end. Its own code rather
+     * than a plan change's: the switch has no other plan to choose and no day
+     * to pick, so the way past it is the add-on ending.
+     */
+    readonly RETIREMENT_SWITCH_BUNDLE_CANNOT_FOLLOW: "RETIREMENT_SWITCH_BUNDLE_CANNOT_FOLLOW";
+    /**
+     * The subscription takes no switch now: a change is scheduled, it has
+     * ended, or its plan is held for a special contract.
+     */
+    readonly RETIREMENT_SWITCH_NOT_OPEN: "RETIREMENT_SWITCH_NOT_OPEN";
+    /**
+     * The version named is not the replacement the retirement names. Carries
+     * the retirement as it now stands.
+     */
+    readonly RETIREMENT_SWITCH_CHANGED: "RETIREMENT_SWITCH_CHANGED";
     /** The subscription has ended; its plan can no longer be changed. */
     readonly SUBSCRIPTION_ENDED: "SUBSCRIPTION_ENDED";
     /** An active special contract blocks self-service plan changes. */
@@ -5880,14 +7300,23 @@ declare const PLATFORM_ERROR_CODES: {
     readonly CANCELLATION_LOCKS_THE_CYCLE: "CANCELLATION_LOCKS_THE_CYCLE";
     /**
      * A bundle the tenant already holds runs past the cycle they are moving to.
+     * Carries the bundle, the earliest day the booking can end, and the two
+     * rhythms.
      *
      * Its own code rather than `BUNDLE_CYCLE_EXCEEDS_PLAN`, which states the
      * same rule about a booking that has not been made yet. The two need
      * different sentences: this one can name the day the obstacle lifts and
-     * tell the reader to cancel the booking, and that advice is wrong for
-     * someone who is only about to book. One template cannot serve both.
+     * tell the reader how to get past it, and that advice is wrong for someone
+     * who is only about to book. One template cannot serve both.
      */
     readonly BUNDLE_BOOKING_OUTLASTS_TARGET_CYCLE: "BUNDLE_BOOKING_OUTLASTS_TARGET_CYCLE";
+    /**
+     * A bundle the tenant already holds cannot run on the plan they are moving
+     * to: that plan may not book it, or it has no price there in the rhythm
+     * the booking is billed in. Carries the bundle, the plan and the earliest
+     * day the booking can end.
+     */
+    readonly BUNDLE_BOOKING_DOES_NOT_FIT_TARGET_PLAN: "BUNDLE_BOOKING_DOES_NOT_FIT_TARGET_PLAN";
     /**
      * Features of the previewed bundle are already covered by the plan or by
      * another booked bundle. A warning rather than a blocker: paying twice is
@@ -5909,7 +7338,6 @@ declare const PLATFORM_ERROR_CODES: {
      * tenant reads and therefore needs a shipped text for.
      */
     readonly BUNDLE_FEATURE_DEPENDENCY_UNSATISFIED: "BUNDLE_FEATURE_DEPENDENCY_UNSATISFIED";
-    readonly NO_PENDING_PLAN_VERSION: "NO_PENDING_PLAN_VERSION";
     readonly ONBOARDING_CREATE_FAILED: "ONBOARDING_CREATE_FAILED";
     readonly BUNDLE_PREVIEW_ARGUMENT_AMBIGUOUS: "BUNDLE_PREVIEW_ARGUMENT_AMBIGUOUS";
     /**
@@ -5941,10 +7369,41 @@ declare const PLATFORM_ERROR_CODES: {
     readonly PLAN_TERMINATE_INVALID_DATE: "PLAN_TERMINATE_INVALID_DATE";
     readonly PLAN_TERMINATE_DATE_NOT_FUTURE: "PLAN_TERMINATE_DATE_NOT_FUTURE";
     readonly PLAN_TERMINATE_NOT_IMPLEMENTED: "PLAN_TERMINATE_NOT_IMPLEMENTED";
+    /**
+     * Subscriptions told of a retirement still move onto this version, and
+     * nothing moves onto a version that has ended. Carries the version, its
+     * plan key and the first day it may end: the day after the last move.
+     */
+    readonly PLAN_TERMINATE_BEFORE_RETIREMENT_MOVES: "PLAN_TERMINATE_BEFORE_RETIREMENT_MOVES";
+    /**
+     * Subscriptions told of a retirement are past their date and still to be
+     * moved onto this version — a move the platform could not make yet — so it
+     * cannot end until they have moved. Carries how many, the version and its
+     * plan key.
+     */
+    readonly PLAN_TERMINATE_WHILE_MOVES_OVERDUE: "PLAN_TERMINATE_WHILE_MOVES_OVERDUE";
+    /**
+     * Subscriptions on a retired version have not yet been told of their move
+     * onto this version — their notice has reached nobody, so their date is not
+     * set — and it cannot end until they have been. Carries how many, the
+     * version and its plan key.
+     */
+    readonly PLAN_TERMINATE_WHILE_NOTICES_UNDELIVERED: "PLAN_TERMINATE_WHILE_NOTICES_UNDELIVERED";
     readonly BUNDLE_VERSION_ALREADY_PUBLISHED: "BUNDLE_VERSION_ALREADY_PUBLISHED";
     readonly BUNDLE_VERSION_NOT_EDITABLE: "BUNDLE_VERSION_NOT_EDITABLE";
     readonly BUNDLE_VERSION_NOT_PUBLISHED: "BUNDLE_VERSION_NOT_PUBLISHED";
     readonly BUNDLE_VERSION_SUPERSEDED: "BUNDLE_VERSION_SUPERSEDED";
+    /**
+     * The bundle version is published, and its window has not opened: it goes
+     * on sale on `validFrom`, and until then its predecessor is the one sold.
+     */
+    readonly BUNDLE_VERSION_NOT_YET_ON_SALE: "BUNDLE_VERSION_NOT_YET_ON_SALE";
+    /**
+     * The add-on itself has been deleted from the catalogue. Deleting it leaves
+     * its versions' dates as they were, so the version asked for can still be
+     * inside its window; it is not on offer all the same.
+     */
+    readonly BUNDLE_DELETED: "BUNDLE_DELETED";
     readonly BUNDLE_VERSION_REGRESSION: "BUNDLE_VERSION_REGRESSION";
     readonly BUNDLE_VERSION_ZERO_PRICE: "BUNDLE_VERSION_ZERO_PRICE";
     readonly BUNDLE_VERSION_NO_PRICE: "BUNDLE_VERSION_NO_PRICE";
@@ -6034,7 +7493,7 @@ declare const PLATFORM_ERROR_CODES: {
     /** Email already taken (mapped from `PlatformUserExistsError`). */
     readonly EMAIL_EXISTS: "EMAIL_EXISTS";
 };
-type PlatformErrorCode = SetupErrorCode | AuthErrorCode | PromoErrorCode | CatalogErrorCode | BillingErrorCode | ContractErrorCode | SubscriberErrorCode | RegistrationErrorCode | PaymentErrorCode | SettingsErrorCode;
+type PlatformErrorCode = SetupErrorCode | AuthErrorCode | PromoErrorCode | CatalogErrorCode | BillingErrorCode | ContractErrorCode | SubscriberErrorCode | RegistrationErrorCode | PaymentErrorCode | SettingsErrorCode | MaintenanceErrorCode;
 /**
  * Shape of a coded error response.
  *
@@ -6072,6 +7531,160 @@ declare class PlatformUserExistsError extends Error {
  * when thrower and catcher see the class from different module instances.
  */
 declare function isPlatformUserExistsError(err: unknown): err is PlatformUserExistsError;
+/**
+ * What a refused write found instead of the state its caller had read:
+ * `gone` — the row no longer exists; `moved` — it exists, but no longer in the
+ * state the write required, because a concurrent request changed it first.
+ */
+type PersistenceRefusalReason = 'gone' | 'moved';
+/**
+ * A write an adapter refused because the row was no longer what the caller
+ * read, carrying the platform's error code for that case.
+ *
+ * The platform checks these conditions before it writes and answers with the
+ * same code. The adapter's own guard is what holds when two requests pass
+ * that check together — a double click, two operators — and throwing this
+ * rather than a plain `Error` gives the loser of that race the answer the
+ * check would have given, instead of a 500 that reads like a crash in the log.
+ * The adapter says what it found; the platform decides what that is on the
+ * wire.
+ */
+declare class PersistenceRefusal extends Error {
+    readonly code: string;
+    readonly reason: PersistenceRefusalReason;
+    readonly params: Readonly<Record<string, unknown>>;
+    constructor(code: string, reason: PersistenceRefusalReason, message: string, params?: Readonly<Record<string, unknown>>);
+}
+/** Realm-safe type guard, like `isPlatformUserExistsError`. */
+declare function isPersistenceRefusal(err: unknown): err is PersistenceRefusal;
+
+/**
+ * The canonical models a schema may leave out, each with the persistence
+ * bundle members that need it.
+ *
+ * `saasicat schema check` lists every canonical model it does not find as not
+ * adopted. Naming one of these in a bundle's `notAdopted` leaves its members
+ * out of the bundle, so the platform decides at start what it can do without
+ * them — and says so where it cannot — instead of the first request failing
+ * against a table that is not there. Any other model the bundle needs: an
+ * application that leaves it out brings its own adapter for it.
+ */
+declare const OPTIONAL_CANONICAL_MODELS: {
+    readonly SuperAdminUser: readonly ["core.superAdminProvisioning"];
+    readonly SuperAdminMfa: readonly ["core.mfa"];
+    readonly AppliedSettings: readonly ["core.appliedSettings"];
+    readonly SettingsChange: readonly ["core.appliedSettings"];
+    readonly MaintenanceWindow: readonly ["core.maintenanceWindows"];
+    readonly SubscriptionNotice: readonly ["tenantBilling.subscriptionNotices"];
+    readonly VersionRetirement: readonly ["tenantBilling.versionRetirements"];
+    readonly SubscriberLedgerEntry: readonly ["entitlement.subscriberLedgerRepository"];
+    readonly PromoCodeHold: readonly ["promo.holdRepository"];
+};
+type OptionalCanonicalModel = keyof typeof OPTIONAL_CANONICAL_MODELS;
+/** A bundle member one of the optional models is needed by. */
+type OptionalBundleMember = (typeof OPTIONAL_CANONICAL_MODELS)[OptionalCanonicalModel][number];
+/**
+ * The bundle members a `notAdopted` list leaves out.
+ *
+ * A name that is not one of the optional models is refused rather than
+ * ignored: a typo would otherwise leave a member in that fails at its first
+ * request, and a model the bundle cannot run without needs the application's
+ * own adapter, which only the application can supply.
+ */
+declare function membersLeftOut(notAdopted?: readonly string[]): ReadonlySet<OptionalBundleMember>;
+
+/** Admits a piece of work when a place is free; see `concurrencyGate`. */
+type ConcurrencyGate = <T>(work: () => Promise<T>) => Promise<T>;
+/**
+ * Admits at most `limit` pieces of work at once and queues the rest in the
+ * order they arrived.
+ *
+ * Meant for transactions. Each holds a pooled connection for its whole life,
+ * and the platform's transactions take row locks and then read further. Run
+ * as many at once as there are requests, and every connection can end up held
+ * by a transaction waiting for a lock — or for a connection a sibling needs —
+ * while the statements that would let them finish wait for the pool: the
+ * service stalls until transactions time out. A limit below the pool size
+ * keeps connections free for the work outside a transaction.
+ *
+ * A place is handed to the next in line when work ends, however it ends, so
+ * the count never rises above the limit and nobody waiting is overtaken.
+ */
+declare function concurrencyGate(limit: number): ConcurrencyGate;
+/**
+ * The one gate of a pool: every caller naming the same `pool` — the client or
+ * database handle the transactions run on — gets the same queue.
+ *
+ * A bound is a property of the pool, not of whoever builds a runner. Where
+ * the client is an injection token, Nest builds a runner once for every module
+ * that asks for one, all on the same client; a gate per runner would admit the
+ * limit once per module, and a gate per configuration object would join two
+ * pools that happen to share one. A second, different limit for a pool already
+ * bounded is refused rather than split.
+ */
+declare function concurrencyGateOf(pool: object, limit: number): ConcurrencyGate;
+
+/** The two versioned catalogue entities, by the name their rows go by. */
+type CatalogVersionKind = 'PlanVersion' | 'BundleVersion';
+/** A publish of a version that is not there, refused with the platform's code. */
+declare function catalogVersionGone(kind: CatalogVersionKind, versionId: string): PersistenceRefusal;
+/**
+ * A publish or discard of a version somebody published first. A published
+ * version is what tenants may have booked, so it is neither published a second
+ * time — which would rewrite when and by whom — nor discarded.
+ */
+declare function catalogVersionAlreadyPublished(kind: CatalogVersionKind, versionId: string): PersistenceRefusal;
+/**
+ * A draft asked for where the plan or bundle already has one: there is one
+ * draft at a time, so that publishing it is never a choice between two.
+ */
+declare function catalogDraftExists(kind: CatalogVersionKind, key: string, draftVersion: number): PersistenceRefusal;
+
+/** A plan key a plan already carries. */
+declare function planKeyTaken(planKey: string): PersistenceRefusal;
+/** A bundle key a bundle already carries. */
+declare function bundleKeyTaken(bundleKey: string): PersistenceRefusal;
+/** A marketing projection for a version and locale that already has one. */
+declare function marketingProjectionTaken(target: {
+    targetType: string;
+    targetVersionId: string;
+    locale: string;
+}): PersistenceRefusal;
+
+/**
+ * The decimal a number was written as, for a `numeric` column.
+ *
+ * `toFixed` rounds the binary double rather than the decimal somebody typed:
+ * `(1.005).toFixed(2)` is `'1.00'` and `(2.675).toFixed(2)` is `'2.67'`, while
+ * `(10.005).toFixed(2)` is `'10.01'` — which way a value goes depends on its
+ * binary representation, not on a rule anyone chose. The shortest decimal that
+ * reads back as the same number is what was written; handed to the column, the
+ * database applies its one rounding rule, half away from zero. Where the
+ * platform validates an amount to the column's places at its boundary, nothing
+ * is rounded at all.
+ */
+declare function toDecimalString(value: number): string;
+
+/**
+ * A code whose name is taken — by a live code, or by a deleted one, since a
+ * deleted code keeps its name (`SC-PROMO-028`). The platform checks before it
+ * creates; this is what the unique index answers when two creates race past
+ * that check.
+ */
+declare function promoCodeTaken(code: string): PersistenceRefusal;
+
+/** The tenant has no subscription to write to. */
+declare function subscriptionGone(tenantId: string): PersistenceRefusal;
+/** The plan to bind has no version in effect at `asOf`. */
+declare function noActivePlanVersion(planId: string, asOf: Date): PersistenceRefusal;
+/** The plan to bind is not in the catalogue, or was retired in the meantime. */
+declare function planNotInCatalog(planKey: string): PersistenceRefusal;
+/** The booking to cancel does not exist. */
+declare function subscriptionBundleGone(subscriptionBundleId: string): PersistenceRefusal;
+/** The booking to cancel was cancelled first, by another request. */
+declare function subscriptionBundleAlreadyCancelled(subscriptionBundleId: string): PersistenceRefusal;
+/** No contract of the tenant named carries the id. */
+declare function subscriptionContractGone(contractId: string): PersistenceRefusal;
 
 /** Feature key → its `requires` keys (from Discovery/FeatureCatalogEntry). */
 type FeatureRequiresIndex = ReadonlyMap<string, readonly string[]>;
@@ -6807,13 +8420,6 @@ interface SetupConfirmMfaResponse {
     ok: boolean;
 }
 
-/** What the adapter's schema can actually answer about a version's dates. */
-interface PlanVersionMappingFields {
-    /** `validFrom`/`validUntil` are maintained; otherwise both read as null. */
-    validityWindows: boolean;
-    /** `endsAt` exists; otherwise the field is left off the record entirely. */
-    endsAt: boolean;
-}
 /** A `plans` row as either adapter reads it back. */
 interface CanonicalPlanRow {
     id: string;
@@ -6841,9 +8447,9 @@ interface CanonicalPlanVersionRow {
     publishedChanges: unknown;
     changeNote: string;
     nonRegressive: boolean;
-    validFrom?: Date | null;
-    validUntil?: Date | null;
-    endsAt?: Date | null;
+    validFrom: Date | null;
+    validUntil: Date | null;
+    endsAt: Date | null;
     createdByUserId: string | null;
     publishedByUserId: string | null;
     createdAt: Date;
@@ -6856,7 +8462,7 @@ declare function toPlanRow(row: CanonicalPlanRow): PlanRow;
  * real foreign key has to resolve it first, and only the adapter knows which
  * shape it is looking at.
  */
-declare function toPlanVersionRow(row: CanonicalPlanVersionRow, planKey: string, fields: PlanVersionMappingFields): PlanVersionRow;
+declare function toPlanVersionRow(row: CanonicalPlanVersionRow, planKey: string): PlanVersionRow;
 
 /**
  * The legal identity of the issuer a catalogue names, or none where it names no
@@ -7298,4 +8904,4 @@ declare function resolveErrorMessage(body: ResolvableErrorBody, overrides?: Part
 
 declare const ERROR_MESSAGES_DE: Record<PlatformErrorCode, string>;
 
-export { ACTIVE_SUBSCRIPTION_CONTRACT_STATUSES, AUTH_ERROR_CODES, type ActionKey, type ActivationOrchestrator, type ActivePlanVersionWhere, type ActivePlanVersionWhereWithEndsAt, type ActiveVersionWhere, type ActiveVersionWhereWithEndsAt, type ActorTag, type AdminAccountEntry, type AdminAccountHolder, type AdminActor, type AdminAuditListFilter, type AdminManifest, type AdminResourcesPort, type AdminSubscriberAccount, type AdminSubscriptionListRow, type AdminTenantDetail, type AdminTenantListFilter, type AdminTenantListRow, type AdminTenantStateResult, type AdminUserListFilter, type AdminUserListRow, type AppliedSettingsPort, type AppliedSettingsRecord, type AppliedSettingsValues, type ApplyOnboardingSelectionInput, type ApplyOnboardingSelectionResult, type ApprovedCatalogKeys, type AuditActionDef, type AuditEntry, type AuditPort, type AuditQuery, type AuditQueryPort, type AuditStatsPort, type AuditStatsSnapshot, type AuthErrorCode, BILLING_ERROR_CODES, BUNDLE_PRICE_LOOKUP_LIMIT, type BillingCycle, type BillingErrorCode, type BundleAvailabilityState, type BundleCompatibility, type BundleFeatureShape, type BundleListFilter, type BundlePricingOverride, type BundleRepository, type BundleRow, type BundleVersionFields, type BundleVersionMutationResult, type BundleVersionRow, CATALOGUE_KEYS, CATALOG_ERROR_CODES, CONTRACT_ERROR_CODES, type CancelSubscriptionBundleData, type CancelSubscriptionInput, type CancelSubscriptionResult, type CancellationNoticePeriods, type CanonicalContractLineItemRow, type CanonicalContractRow, type CanonicalPlanRow, type CanonicalPlanVersionRow, type CanonicalRunningContractRow, type CanonicalSubscriberChargeRow, type CanonicalSubscriberCorrectionRow, type CanonicalSubscriberPaymentMethodRow, type CanonicalSubscriberRow, type CanonicalSubscriptionBundleRow, type CapabilityCatalogEntryRow, type CapabilityCodeStatus, type CapabilityKey, type CapabilityKind, type CatalogEntryFilter, type CatalogEntryI18n, type CatalogEntryI18nFields, type CatalogEntryRepository, type CatalogErrorCode, type ChangeDirection, type CheckoutOfferFilter, type CheckoutOfferLineItem, type CheckoutOfferLineItemKind, type CheckoutOfferPriceBreakdown, type CheckoutOfferPromoCodeSnapshot, type CheckoutOfferPromotionSnapshot, type CheckoutOfferRepository, type CheckoutOfferRow, type CheckoutOfferSelection, type CheckoutOfferSelectionUpdate, type CheckoutOfferStatus, type CleanupResult, type CliUserRow, type ComponentKey, type ConfiguratorCatalog, type ConfiguratorMarketingProvider, type ConfiguratorModel, type ConfiguratorPlanMarketing, type ConfiguratorPlanVersionRow, type ConfiguratorPriceBreakdown, type ConfiguratorSourcesLookup, type ConfirmedPaymentMethod, type ContractErrorCode, type ContractIssuerParty, type ContractLineItemKind, type ContractLineItemRecord, type ContractSubscriberParty, type CreateBundleData, type CreateBundleVersionDraftData, type CreateCheckoutOfferData, type CreateMarketingProjectionData, type CreatePlanData, type CreatePlanVersionDraftData, type CreatePromoCodeData, type CreatePromoCodeRequest, type CreatePromotionData, type CreateSubscriberData, type CreateSubscriptionBundleData, type CreateSubscriptionContractData, type CreateSuperAdminCliInput, type CreateTenantInput, type DiffResult, type DiscoveredCapability, type DiscoveredFeature, type DiscoveredQuota, type DiscoveredQuotaPolicy, type DiscoveryCodeStatus, type DiscoverySnapshot, type DiscoveryStatus, ERROR_MESSAGES_DE, ERROR_MESSAGES_EN, type EffectiveLimitsSnapshot, type EmailPort, type ErrorMessageParams, FEATURE_NOT_LICENSED, type FeatureCatalogEntryRow, type FeatureDef, type FeatureKey, type FeatureNotLicensedBody, type FeatureRequiresIndex, type FeatureTier, type FeatureUiMeta, type FeatureUiRegistry, type FinalActivationResult, type FirstTimeCustomerCheck, ForeignPaymentMethodReferenceError, type ImmediatePlanChangeInput, type InvoiceLineItemSnapshot, type IssuerCorrectionFault, type IssuerIdentityChange, type KpiCardDef, type KpiDisplayHint, LEGAL_IDENTITY_FIELDS, type LegalIdentity, type LegalIdentityField, MARKETING_PRIORITY_MAX, MARKETING_PRIORITY_MIN, type ManifestAccessPort, type ManifestContribution, type MarketingProjectionFilter, type MarketingProjectionRepository, type MarketingProjectionRow, type MarketingSettingsRepository, type MarketingSettingsRow, type MarketingTargetType, type MarketingTopFeature, type MaskedPaymentMethod, type MfaPort, type NewContractLineItemData, type NewSettingsChange, type NewSubscriberCharge, type NewSubscriberDetails, type NewSubscriptionContractData, OTP_RATE_LIMIT_MAX_SENDS, OTP_RATE_LIMIT_WINDOW_MINUTES, OTP_TTL_MINUTES, OTP_VERIFY_MAX_ATTEMPTS, type OnboardingPromoRedemption, type OnboardingSelectionRequest, type OnboardingSelectionResponse, PASSWORD_RESET_TTL_MINUTES, PAYMENT_ERROR_CODES, PAYMENT_METHOD_TYPES, PENDING_CHECKOUT_TTL_DAYS, PENDING_EMAIL_TTL_HOURS, PENDING_ONBOARDING_TTL_DAYS, PLATFORM_ERROR_CODES, PROMO_ERROR_CODES, type Paginated, type PartyAddress, type PasswordHasher, type PasswordResetCliResult, PaymentCallbackRejectedError, type PaymentErrorCode, type PaymentEventClaim, type PaymentEventLog, type PaymentGateway, type PaymentGatewayCallback, type PaymentGatewayEvent, type PaymentMethodHolder, type PaymentMethodSetupSession, type PaymentMethodSetupSubject, type PaymentMethodType, type PendingRegistration, type PendingRegistrationCreateInput, type PendingRegistrationRepository, type PendingRegistrationSnapshot, type PendingRegistrationUpdateInput, type PersistenceCapabilities, PersistenceCapabilityError, type PersistenceClassRef, type PersistenceInjectionToken, type PersistenceProvider, type PlanCatalog, type PlanCatalogApp, type PlanCatalogImportReport, type PlanCatalogImportSink, type PlanCatalogIssuer, type PlanCatalogIssuerCorrection, type PlanCatalogLookup, type PlanCatalogMarketing, type PlanCatalogNotifications, type PlanCatalogPaymentAccount, type PlanCatalogPayments, type PlanCatalogReadSink, type PlanCatalogReadSnapshot, type PlanCatalogSettings, type PlanCatalogSubscribers, type PlanCatalogTenantBilling, type PlanDef, type PlanId, type PlanListFilter, type PlanRepository, type PlanRow, type PlanVersion, type PlanVersionFields, type PlanVersionMappingFields, type PlanVersionMutationResult, type PlanVersionRecord, type PlanVersionRepository, type PlanVersionRow, type PlatformErrorBody, type PlatformErrorCode, type PlatformRole, type PlatformUserDto, PlatformUserExistsError, type ProjectPageDef, type PromoCode, type PromoCodeDurationType, type PromoCodeFilter, type PromoCodeHoldRecord, type PromoCodeHoldRepository, type PromoCodeHoldTaken, type PromoCodeRecord, type PromoCodeRedemption, type PromoCodeRedemptionListItem, type PromoCodeRedemptionRecord, type PromoCodeRedemptionRepository, type PromoCodeRedemptionStatus, type PromoCodeRepository, type PromoCodeStatsPort, type PromoCodeStatsSnapshot, type PromoCodeStatus, type PromoCodeValidationLog, type PromoCodeValidationLogRepository, type PromoCodeValidationResult, type PromoCodeValueType, type PromoErrorCode, type PromoPreviewInvalidReason, type PromoPreviewRequest, type PromoPreviewResponse, type PromoPreviewValidResponse, type PromoRevenueDeductionAggregator, type PromoSubscriptionLookup, type PromotionBillingCycle, type PromotionI18n, type PromotionI18nFields, type PromotionOnPrice, type PromotionRepository, type PromotionResult, type PromotionRow, type PromotionStatus, type PromotionTargetType, type PromotionType, type PromotionValue, type PublicBootResponse, type PublicComparisonRow, type PublicMarketingBundle, type PublicMarketingCatalogResponse, type PublicMarketingPlan, type PublicMarketingPromo, type PublicNewPaymentMethods, type PublicSignupPlan, type PublishBundleVersionData, type PublishBundleVersionMeta, type PublishPlanVersionData, type QuotaCatalogEntryRow, type QuotaEnforcementMode, type QuotaKey, type QuotaProvider, REGISTRATION_ERROR_CODES, REGISTRATION_RESUME_TTL_MINUTES, REGISTRATION_STEP_BY_STATUS, type ReassignTenantAdminCliResult, type RecommendablePlan, type RecordSubscriberPaymentMethodData, type RecordSubscriberPaymentMethodOutcome, type RecordSubscriberPaymentMethodResult, type RedeemPromoInTransactionCallback, type RegistrationActivation, type RegistrationAuditContext, type RegistrationAuditEvent, type RegistrationAuditEventType, type RegistrationAuditLogger, type RegistrationBillingDetails, type RegistrationConfigSelection, type RegistrationConfiguratorLookup, type RegistrationErrorCode, type RegistrationOtpDelivery, type RegistrationPromoPreview, type RegistrationResumeDelivery, type RegistrationResumeTokenSigner, type RegistrationStatus, type RegistrationStep, type RequiredCapabilities, type ResolvableErrorBody, type ResumeRegistrationInput, type ResumeRegistrationResult, type ReviewCatalogEntryData, type RlsBypassPort, type RunningContractIssuer, type RunningContractIssuers, SETTINGS_ERROR_CODES, SETUP_ERROR_CODES, SUBSCRIBER_ACCOUNT_CAPABILITY, SUBSCRIBER_ERROR_CODES, type SaaSiCatPersistenceAdapter, type SaaSiCatPersistenceAdminResources, type SaaSiCatPersistenceCatalog, type SaaSiCatPersistenceCore, type SaaSiCatPersistenceEntitlement, type SaaSiCatPersistencePayments, type SaaSiCatPersistencePromo, type SaaSiCatPersistenceTenantBilling, type SaveRegistrationConfigInput, type SaveRegistrationConfigResult, type ScheduledPlanChangeInput, type SelectPlanInput, type SelectPlanResult, type SelectableBundleShape, type SelfServiceBlockedPlans, type SetCatalogEntryReviewData, type SettingsChangeFilter, type SettingsChangeRecord, type SettingsDifference, type SettingsErrorCode, type SetupConfirmMfaRequest, type SetupConfirmMfaResponse, type SetupErrorCode, type SetupRequest, type SetupResult, type SetupStatusResponse, type SlugAvailabilityCheck, type StandardPageDef, type StandardPageKey, type StartCheckoutInput, type StartCheckoutResult, type StartPaymentMethodSetupInput, type StartRegistrationInput, type StartRegistrationResult, type StoredBundleStem, type StrictModeWarning, type StrictModeWarningCode, type SubscriberCharge, type SubscriberChargeOrigin, type SubscriberChargeRecord, type SubscriberChargeSource, type SubscriberContact, type SubscriberContactChange, type SubscriberCorrectionData, type SubscriberCorrectionRecord, type SubscriberCorrectionResult, type SubscriberDetails, type SubscriberErrorCode, type SubscriberIdentityCorrection, type SubscriberIdentityDelta, type SubscriberIdentityValues, type SubscriberLedgerRepository, type SubscriberPaymentMethodRecord, type SubscriberPaymentMethodReference, type SubscriberPaymentMethodRepository, type SubscriberPaymentMethodSetupData, type SubscriberPaymentMethodSetupMatch, type SubscriberPaymentMethodStatus, type SubscriberRecord, type SubscriberRepository, type Subscription, type SubscriptionBundleRecord, type SubscriptionBundleRepository, type SubscriptionBundleView, type SubscriptionContractFilter, type SubscriptionContractInvoiceSnapshot, type SubscriptionContractParties, type SubscriptionContractPriceSnapshot, type SubscriptionContractRecord, type SubscriptionContractRepository, type SubscriptionContractStatus, type SubscriptionRecord, type SubscriptionRepository, type SubscriptionStatsPort, type SubscriptionStatsSnapshot, type SubscriptionStatus, type SubscriptionUsagePort, type SubscriptionUsageRecord, type SuperAdminProvisioningPort, type SyncDiscoveryResult, type TenantActionDef, type TenantColumnDef, type TenantDto, type TenantListFilter, type TenantPort, type TenantSubscriptionWritePort, type TerminateSubscriptionContractData, type TopPromoCode, type TransactionContext, type TransactionRunner, type UpdateBundleData, type UpdateBundleVersionDraftData, type UpdateCatalogEntryBaseData, type UpdateCatalogEntryI18nData, type UpdateCheckoutOfferData, type UpdateMarketingProjectionData, type UpdateMarketingSettingsData, type UpdatePlanData, type UpdatePlanVersionDraftData, type UpdatePromoCodeData, type UpdatePromoCodeRequest, type UpdatePromotionData, type UpsellOffer, type UpsellOfferResolver, type UpsertCapabilityEntryData, type UpsertFeatureCatalogEntryInput, type UpsertFeatureEntryData, type UpsertPlanInput, type UpsertPlanVersionInput, type UpsertQuotaEntryData, type UpsertResult, type UsageSnapshotPort, type UserAccountLookup, type UserListFilter, type UserManagementPort, type UserPort, type VerifyRegistrationOtpResult, type VersionChange, type VersionChangeDirection, type VersionEditability, type VersionEditableReason, type VersionedEntityBase, applyPromo, assertPersistenceCapabilities, buildActivePlanVersionWhere, buildActiveVersionWhere, buildFeatureRequiresIndex, bundleDraftDefaults, bundleStemDefaults, canonicalJson, classifyBundleVersionDiff, classifyIssuerChange, classifyPlanDiff, collectUnsatisfiedRequires, contractPartiesOf, coverageExcludingSelf, definedFields, diffSettings, formatCustomerNumber, formatErrorMessage, identityCorrectionDelta, isBundleRedundant, isForeignPaymentMethodReferenceError, isPaymentCallbackRejectedError, isPlatformUserExistsError, isVersionEditable, issuerIdentityOf, keepOneRecommended, missingRequiresFor, movedIdentityFields, pickActivePromo, planCatalogSettingsOf, previousUtcDay, promoStatus, promotionOnPrice, readQuotaRecord, readQuotaValue, recordedIssuerIdentity, refuseForeignPaymentMethodReference, resolveBundleAvailability, resolveErrorMessage, sameLegalIdentity, selectChargeableBundles, settingsSubtreeOf, startOfUtcDay, subscriberChargeColumns, subscriberFromRegistration, subscriberPaymentMethodColumns, toBundleStemRow, toContractLineItemRecord, toPlanRow, toPlanVersionRow, toRunningContractIssuer, toSubscriberChargeRecord, toSubscriberCorrectionRecord, toSubscriberPaymentMethodRecord, toSubscriberRecord, toSubscriptionBundleRecord, toSubscriptionContractRecord };
+export { ACTIVE_SUBSCRIPTION_CONTRACT_STATUSES, AUTH_ERROR_CODES, type ActionKey, type ActivationOrchestrator, type ActivePlanVersionWhere, type ActivePlanVersionWhereWithEndsAt, type ActiveVersionWhere, type ActiveVersionWhereWithEndsAt, type ActorTag, type AdminAccountEntry, type AdminAccountHolder, type AdminActor, type AdminAuditListFilter, type AdminManifest, type AdminResourcesPort, type AdminSubscriberAccount, type AdminSubscriptionListRow, type AdminTenantDetail, type AdminTenantListFilter, type AdminTenantListRow, type AdminTenantStateResult, type AdminUserListFilter, type AdminUserListRow, type AppliedSettingsPort, type AppliedSettingsRecord, type AppliedSettingsValues, type ApplyOnboardingSelectionInput, type ApplyOnboardingSelectionResult, type ApprovedCatalogKeys, type AuditActionDef, type AuditActor, type AuditEntry, type AuditPort, type AuditQuery, type AuditQueryPort, type AuditStatsPort, type AuditStatsSnapshot, type AuthErrorCode, BILLING_ERROR_CODES, BUNDLE_PRICE_LOOKUP_LIMIT, type BillingCycle, type BillingErrorCode, type BundleAvailabilityState, type BundleCompatibility, type BundleFeatureShape, type BundleListFilter, type BundlePricingOverride, type BundleRepository, type BundleRow, type BundleVersionFields, type BundleVersionMutationResult, type BundleVersionRow, CATALOGUE_KEYS, CATALOG_ERROR_CODES, CONTRACT_ERROR_CODES, CUSTOM_LIMITS_KEYS, type CancelSubscriptionBundleData, type CancelSubscriptionInput, type CancelSubscriptionResult, type CancellationNoticePeriods, type CanonicalContractLineItemRow, type CanonicalContractRow, type CanonicalMaintenanceWindowRow, type CanonicalPlanRow, type CanonicalPlanVersionRow, type CanonicalRunningContractRow, type CanonicalSubscriberChargeRow, type CanonicalSubscriberCorrectionRow, type CanonicalSubscriberPaymentMethodRow, type CanonicalSubscriberRow, type CanonicalSubscriptionBundleRow, type CanonicalSubscriptionNoticeRow, type CanonicalVersionRetirementRow, type CapabilityCatalogEntryRow, type CapabilityCodeStatus, type CapabilityKey, type CapabilityKind, type CatalogEntryFilter, type CatalogEntryI18n, type CatalogEntryI18nFields, type CatalogEntryRepository, type CatalogErrorCode, type CatalogVersionKind, type ChangeDirection, type CheckoutOfferFilter, type CheckoutOfferLineItem, type CheckoutOfferLineItemKind, type CheckoutOfferPriceBreakdown, type CheckoutOfferPromoCodeSnapshot, type CheckoutOfferPromotionSnapshot, type CheckoutOfferRepository, type CheckoutOfferRow, type CheckoutOfferSelection, type CheckoutOfferSelectionUpdate, type CheckoutOfferStatus, type CleanupResult, type CliUserRow, type ComponentKey, type ConcurrencyGate, type ConfiguratorCatalog, type ConfiguratorMarketingProvider, type ConfiguratorModel, type ConfiguratorPlanMarketing, type ConfiguratorPlanVersionRow, type ConfiguratorPriceBreakdown, type ConfiguratorSourcesLookup, type ConfirmedPaymentMethod, type ContractErrorCode, type ContractIssuerParty, type ContractLineItemKind, type ContractLineItemRecord, type ContractSubscriberParty, type CreateBundleData, type CreateBundleVersionDraftData, type CreateCheckoutOfferData, type CreateMarketingProjectionData, type CreatePlanData, type CreatePlanVersionDraftData, type CreatePromoCodeData, type CreatePromoCodeRequest, type CreatePromotionData, type CreateSubscriberData, type CreateSubscriptionBundleData, type CreateSubscriptionContractData, type CreateSuperAdminCliInput, type CreateTenantInput, type CustomLimits, type DiffResult, type DiscoveredCapability, type DiscoveredFeature, type DiscoveredQuota, type DiscoveredQuotaPolicy, type DiscoveryCodeStatus, type DiscoverySnapshot, type DiscoveryStatus, ERROR_MESSAGES_DE, ERROR_MESSAGES_EN, type EffectiveLimitsSnapshot, type EmailPort, type ErrorMessageParams, FEATURE_NOT_LICENSED, type FeatureCatalogEntryRow, type FeatureDef, type FeatureKey, type FeatureNotLicensedBody, type FeatureRequiresIndex, type FeatureTier, type FeatureUiMeta, type FeatureUiRegistry, type FinalActivationResult, type FirstTimeCustomerCheck, ForeignPaymentMethodReferenceError, type ImmediatePlanChangeInput, type InvoiceLineItemSnapshot, type IssuerCorrectionFault, type IssuerIdentityChange, type KpiCardDef, type KpiDisplayHint, LEGAL_IDENTITY_FIELDS, type LegalIdentity, type LegalIdentityField, MAINTENANCE_CAPABILITY, MAINTENANCE_ERROR_CODES, MAINTENANCE_MESSAGE_MAX_LENGTH, MAINTENANCE_STATE_MAX_AGE_SECONDS, MARKETING_PRIORITY_MAX, MARKETING_PRIORITY_MIN, type MaintenanceErrorCode, type MaintenanceLockView, type MaintenanceNotificationPort, type MaintenanceOverview, type MaintenanceStatusView, type MaintenanceUnlockView, type MaintenanceWindowChanges, type MaintenanceWindowEvent, type MaintenanceWindowPort, type MaintenanceWindowRecord, type MaintenanceWindowStage, type MaintenanceWindowStatus, type MaintenanceWindowView, type ManifestAccessPort, type ManifestContribution, type MarketingProjectionFilter, type MarketingProjectionRepository, type MarketingProjectionRow, type MarketingSettingsRepository, type MarketingSettingsRow, type MarketingTargetType, type MarketingTopFeature, type MaskedPaymentMethod, type MfaPort, NO_SCHEDULED_CHANGE, type NewContractLineItemData, type NewMaintenanceWindow, type NewSettingsChange, type NewSubscriberCharge, type NewSubscriberDetails, type NewSubscriptionContractData, type NewVersionRetirement, type NoticeToRecord, OPTIONAL_CANONICAL_MODELS, OTP_RATE_LIMIT_MAX_SENDS, OTP_RATE_LIMIT_WINDOW_MINUTES, OTP_TTL_MINUTES, OTP_VERIFY_MAX_ATTEMPTS, type OnboardingPromoRedemption, type OnboardingSelectionRequest, type OnboardingSelectionResponse, type OptionalBundleMember, type OptionalCanonicalModel, type OrderlyRetirementSettings, PASSWORD_RESET_TTL_MINUTES, PAYMENT_ERROR_CODES, PAYMENT_METHOD_TYPES, PENDING_CHECKOUT_TTL_DAYS, PENDING_EMAIL_TTL_HOURS, PENDING_ONBOARDING_TTL_DAYS, PLATFORM_ERROR_CODES, PROMO_ERROR_CODES, type Paginated, type PartyAddress, type PasswordHasher, type PasswordResetCliResult, PaymentCallbackRejectedError, type PaymentErrorCode, type PaymentEventClaim, type PaymentEventLog, type PaymentGateway, type PaymentGatewayCallback, type PaymentGatewayEvent, type PaymentMethodHolder, type PaymentMethodSetupSession, type PaymentMethodSetupSubject, type PaymentMethodType, type PendingRegistration, type PendingRegistrationCreateInput, type PendingRegistrationRepository, type PendingRegistrationSnapshot, type PendingRegistrationUpdateInput, type PersistenceCapabilities, PersistenceCapabilityError, type PersistenceClassRef, type PersistenceInjectionToken, type PersistenceProvider, PersistenceRefusal, type PersistenceRefusalReason, type PlanCatalog, type PlanCatalogApp, type PlanCatalogImportReport, type PlanCatalogImportSink, type PlanCatalogIssuer, type PlanCatalogIssuerCorrection, type PlanCatalogLookup, type PlanCatalogMarketing, type PlanCatalogNotifications, type PlanCatalogPaymentAccount, type PlanCatalogPayments, type PlanCatalogReadSink, type PlanCatalogReadSnapshot, type PlanCatalogSettings, type PlanCatalogSubscribers, type PlanCatalogTenantBilling, type PlanDef, type PlanId, type PlanListFilter, type PlanRepository, type PlanRow, type PlanVersion, type PlanVersionFields, type PlanVersionMutationResult, type PlanVersionRecord, type PlanVersionRepository, type PlanVersionRow, type PlatformErrorBody, type PlatformErrorCode, type PlatformJobActor, type PlatformRole, type PlatformUserDto, PlatformUserExistsError, type ProjectPageDef, type PromoCode, type PromoCodeDurationType, type PromoCodeFilter, type PromoCodeHoldRecord, type PromoCodeHoldRepository, type PromoCodeHoldTaken, type PromoCodeRecord, type PromoCodeRedemption, type PromoCodeRedemptionListItem, type PromoCodeRedemptionRecord, type PromoCodeRedemptionRepository, type PromoCodeRedemptionStatus, type PromoCodeRepository, type PromoCodeStatsPort, type PromoCodeStatsSnapshot, type PromoCodeStatus, type PromoCodeValidationLog, type PromoCodeValidationLogRepository, type PromoCodeValidationResult, type PromoCodeValueType, type PromoErrorCode, type PromoPreviewInvalidReason, type PromoPreviewRequest, type PromoPreviewResponse, type PromoPreviewValidResponse, type PromoRevenueDeductionAggregator, type PromoSubscriptionLookup, type PromotionBillingCycle, type PromotionI18n, type PromotionI18nFields, type PromotionOnPrice, type PromotionRepository, type PromotionResult, type PromotionRow, type PromotionStatus, type PromotionTargetType, type PromotionType, type PromotionValue, type PublicBootResponse, type PublicComparisonRow, type PublicMarketingBundle, type PublicMarketingCatalogResponse, type PublicMarketingPlan, type PublicMarketingPromo, type PublicNewPaymentMethods, type PublicSignupPlan, type PublishBundleVersionData, type PublishBundleVersionMeta, type PublishPlanVersionData, type QuotaCatalogEntryRow, type QuotaEnforcementMode, type QuotaKey, type QuotaProvider, REGISTRATION_ERROR_CODES, REGISTRATION_RESUME_TTL_MINUTES, REGISTRATION_STEP_BY_STATUS, RETIREMENT_REMINDER_LEAD_DAYS, type ReadCustomLimits, type ReassignTenantAdminCliResult, type RecommendablePlan, type RecordSubscriberPaymentMethodData, type RecordSubscriberPaymentMethodOutcome, type RecordSubscriberPaymentMethodResult, type RedeemPromoInTransactionCallback, type RegistrationActivation, type RegistrationAuditContext, type RegistrationAuditEvent, type RegistrationAuditEventType, type RegistrationAuditLogger, type RegistrationBillingDetails, type RegistrationConfigSelection, type RegistrationConfiguratorLookup, type RegistrationErrorCode, type RegistrationOtpDelivery, type RegistrationPromoPreview, type RegistrationResumeDelivery, type RegistrationResumeTokenSigner, type RegistrationStatus, type RegistrationStep, type RequiredCapabilities, type ResolvableErrorBody, type ResumeRegistrationInput, type ResumeRegistrationResult, type RetiredVersionRef, type RetirementAnnounced, type RetirementBlocker, type RetirementMoveRun, type RetirementPreview, type RetirementProgress, type RetirementReachedRow, type RetirementSide, type RetirementSkipReason, type RetirementSkippedRow, type RetirementSwitchResult, type RetirementSwitchTerms, type ReviewCatalogEntryData, type RlsBypassPort, type RunningContractIssuer, type RunningContractIssuers, SETTINGS_ERROR_CODES, SETUP_ERROR_CODES, SUBSCRIBER_ACCOUNT_CAPABILITY, SUBSCRIBER_ERROR_CODES, type SaaSiCatPersistenceAdapter, type SaaSiCatPersistenceAdminResources, type SaaSiCatPersistenceCatalog, type SaaSiCatPersistenceCore, type SaaSiCatPersistenceEntitlement, type SaaSiCatPersistencePayments, type SaaSiCatPersistencePromo, type SaaSiCatPersistenceTenantBilling, type SaveRegistrationConfigInput, type SaveRegistrationConfigResult, type ScheduledChangeColumns, type ScheduledPlanChangeInput, type SecretSealer, type SelectPlanInput, type SelectPlanResult, type SelectableBundleShape, type SelfServiceBlockedPlans, type SetCatalogEntryReviewData, type SettingsChangeFilter, type SettingsChangeRecord, type SettingsDifference, type SettingsErrorCode, type SetupConfirmMfaRequest, type SetupConfirmMfaResponse, type SetupErrorCode, type SetupRequest, type SetupResult, type SetupStatusResponse, type SlugAvailabilityCheck, type StandardPageDef, type StandardPageKey, type StartCheckoutInput, type StartCheckoutResult, type StartPaymentMethodSetupInput, type StartRegistrationInput, type StartRegistrationResult, type StoredBundleStem, type StrictModeWarning, type StrictModeWarningCode, type SubscriberCharge, type SubscriberChargeOrigin, type SubscriberChargeRecord, type SubscriberChargeSource, type SubscriberContact, type SubscriberContactChange, type SubscriberCorrectionData, type SubscriberCorrectionRecord, type SubscriberCorrectionResult, type SubscriberDetails, type SubscriberErrorCode, type SubscriberIdentityCorrection, type SubscriberIdentityDelta, type SubscriberIdentityValues, type SubscriberLedgerRepository, type SubscriberPaymentMethodRecord, type SubscriberPaymentMethodReference, type SubscriberPaymentMethodRepository, type SubscriberPaymentMethodSetupData, type SubscriberPaymentMethodSetupMatch, type SubscriberPaymentMethodStatus, type SubscriberRecord, type SubscriberRepository, type Subscription, type SubscriptionBundleRecord, type SubscriptionBundleRepository, type SubscriptionBundleView, type SubscriptionContractFilter, type SubscriptionContractInvoiceSnapshot, type SubscriptionContractParties, type SubscriptionContractPriceSnapshot, type SubscriptionContractRecord, type SubscriptionContractRepository, type SubscriptionContractStatus, type SubscriptionNotice, type SubscriptionNoticeDelivery, type SubscriptionNoticeKey, type SubscriptionNoticeKind, type SubscriptionNoticePort, type SubscriptionNoticeRecord, type SubscriptionNoticeRepository, type SubscriptionRecord, type SubscriptionRepository, type SubscriptionStatsPort, type SubscriptionStatsSnapshot, type SubscriptionStatus, type SubscriptionUsagePort, type SubscriptionUsageRecord, type SuperAdminProvisioningPort, type SupersedeSubscriptionContractData, type SyncDiscoveryResult, type TenantActionDef, type TenantColumnDef, type TenantDto, type TenantListFilter, type TenantPort, type TenantSubscriptionUsage, type TenantSubscriptionWritePort, type TerminateSubscriptionContractData, type TopPromoCode, type TransactionContext, type TransactionRunner, type UpdateBundleData, type UpdateBundleVersionDraftData, type UpdateCatalogEntryBaseData, type UpdateCatalogEntryI18nData, type UpdateCheckoutOfferData, type UpdateMarketingProjectionData, type UpdateMarketingSettingsData, type UpdatePlanData, type UpdatePlanVersionDraftData, type UpdatePromoCodeData, type UpdatePromoCodeRequest, type UpdatePromotionData, type UpsellOffer, type UpsellOfferResolver, type UpsertCapabilityEntryData, type UpsertFeatureCatalogEntryInput, type UpsertFeatureEntryData, type UpsertPlanInput, type UpsertPlanVersionInput, type UpsertQuotaEntryData, type UpsertResult, type UsageSnapshotPort, type UserAccountLookup, type UserListFilter, type UserManagementPort, type UserPort, VERSION_RETIREMENT_CAPABILITY, type VerifyRegistrationOtpResult, type VersionChange, type VersionChangeDirection, type VersionEditability, type VersionEditableReason, type VersionOffer, type VersionOfferClass, type VersionOfferFields, type VersionOfferSide, type VersionOfferView, type VersionOfferedNotice, type VersionRetiredNotice, type VersionRetirementRecord, type VersionRetirementReminder, type VersionRetirementRepository, type VersionRetirementView, type VersionSale, type VersionSaleDates, type VersionSaleKind, type VersionSwitchResult, type VersionWindow, type VersionedEntityBase, applyPromo, assertPersistenceCapabilities, buildActivePlanVersionWhere, buildActiveVersionWhere, buildFeatureRequiresIndex, bundleDraftDefaults, bundleKeyTaken, bundleStemDefaults, canonicalJson, catalogDraftExists, catalogVersionAlreadyPublished, catalogVersionGone, classifyBundleVersionDiff, classifyIssuerChange, classifyPlanDiff, classifyVersionOffer, collectUnsatisfiedRequires, computeIncludedVat, concurrencyGate, concurrencyGateOf, contractPartiesOf, coverageExcludingSelf, customLimitsReader, definedFields, diffSettings, formatCustomerNumber, formatErrorMessage, grossFromNet, identityCorrectionDelta, isBundleRedundant, isForeignPaymentMethodReferenceError, isMaintenanceAnnouncementLapsed, isMaintenanceOverrun, isPaymentCallbackRejectedError, isPersistenceRefusal, isPlatformUserExistsError, isVersionActiveAt, isVersionEditable, issuerIdentityOf, keepOneRecommended, maintenanceRetryAfterSeconds, maintenanceStatusOf, maintenanceWindowStatusOf, maintenanceWindowViewOf, marketingProjectionTaken, membersLeftOut, missingRequiresFor, movedIdentityFields, netFromGross, noActivePlanVersion, parseZonedInstant, percentOf, pickActivePromo, planCatalogSettingsOf, planKeyTaken, planNotInCatalog, previousUtcDay, promoCodeTaken, promoStatus, promotionOnPrice, prorate, readCustomLimits, readQuotaRecord, readQuotaValue, recordedIssuerIdentity, refuseForeignPaymentMethodReference, resolveBundleAvailability, resolveErrorMessage, retirementCostsTheSubscription, retirementReminderDueAt, retirementReminderIsDue, retirementSwitchTerms, roundToCents, sameLegalIdentity, scheduledChangeAfterWrite, selectChargeableBundles, settingsSubtreeOf, startOfUtcDay, subscriberChargeColumns, subscriberFromRegistration, subscriberPaymentMethodColumns, subscriptionBundleAlreadyCancelled, subscriptionBundleGone, subscriptionContractGone, subscriptionGone, sumToCents, toBundleStemRow, toCents, toContractLineItemRecord, toDecimalString, toMaintenanceWindowRecord, toPlanRow, toPlanVersionRow, toRunningContractIssuer, toSubscriberChargeRecord, toSubscriberCorrectionRecord, toSubscriberPaymentMethodRecord, toSubscriberRecord, toSubscriptionBundleRecord, toSubscriptionContractRecord, toSubscriptionNoticeRecord, toVersionRetirementRecord, versionOnSale, versionOnSaleOrNext, versionSale };