@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/billing/services/back-office/billing-reconciliation.backend.service.js

@@ -0,0 +1,475 @@
+/**
+ * Billing Reconciliation — asks the provider what it actually holds, and repairs what drifted.
+ *
+ * ## What this service is for
+ *
+ * Every local billing fact arrives by WEBHOOK. `StandardBilling_Interface.retrieveSubscription`
+ * exists, its own doc comment says "on-demand retrieval for reconciliation (if webhook missed)",
+ * and until 2026-09-09 the only two callers were inside the webhook router itself — i.e. the
+ * recovery read only ever ran when a webhook DID arrive. A delivery that is lost, or that arrives
+ * while the application is down and exhausts the provider's retries, left a stale subscription and
+ * a missing invoice with nothing anywhere that could notice. That is the whole finding.
+ *
+ * ## The conflict rule, because a scheduled write to billing state can CORRUPT rather than merely
+ * lag
+ *
+ * Five rules, and each one is a refusal rather than a capability:
+ *
+ * 1. **Only what the provider is authoritative FOR.** `status`, `currentPeriodStart`,
+ *    `currentPeriodEnd`, `cancelAtPeriodEnd` and `discount` — exactly the set the webhook path
+ *    already syncs in `syncSubscriptionFromProvider`, no more. Two writers of one field must agree
+ *    on which fields they own, or a sweep and a webhook take turns undoing each other.
+ *
+ * 2. **`items` is NEVER reconciled.** REJECTED ALTERNATIVE: sync items too, since the provider
+ *    knows them. It races `CHANGE_PLAN` / `ADD_ADDON` / `REMOVE_ADDON`, every one of which calls
+ *    the provider FIRST and writes local items afterwards — so a sweep reading the provider inside
+ *    that window and writing items would revert a plan change the customer has already been
+ *    charged for. The webhook router refuses items for the same reason and says so; a sweep, which
+ *    runs unprompted and concurrently, has strictly more exposure than it does.
+ *
+ * 3. **A row a local mutation currently owns is SKIPPED.** Any subscription whose `updatedAt` is
+ *    inside {@link RECENT_MUTATION_QUIET_PERIOD_MS} is left alone and counted, not written.
+ *    REJECTED ALTERNATIVE: a compare-and-swap on `updatedAt` at write time. It does not close the
+ *    window that matters — the read-modify-write starts at the PROVIDER READ, not at the local
+ *    read, so a snapshot taken before a webhook that has since landed would still satisfy a CAS
+ *    taken after it. The quiet period addresses the real window, needs no schema change, and costs
+ *    one skipped row that the next tick picks up.
+ *
+ * 4. **Nothing is ever DELETED, CANCELLED or CREATED here.** A provider read that fails — including
+ *    a provider saying the subscription does not exist — is REPORTED and acted on by nobody.
+ *    REJECTED ALTERNATIVE: mark a subscription `CANCELLED` when the provider cannot find it. A
+ *    rotated key pointed at the wrong account, a test-vs-live key mix-up, or a provider outage
+ *    would then cancel every subscription in the application, revoking every entitlement, from a
+ *    read that told us nothing. Stale entitlements are recoverable by the next successful tick;
+ *    revoked ones are not.
+ *
+ * 5. **A row that AGREES is not written.** Comparison happens before any update, because a
+ *    subscription UPDATE fires the post-operation feature-sync hook — an unconditional write would
+ *    recompute entitlements for every account on every tick, bump every `updatedAt`, and file an
+ *    audit row per subscription per tick for a change that did not happen.
+ *
+ * ## Invoices are INSERT-mostly, which is why they are safe
+ *
+ * Wildo never authors an invoice: every `invoiceRefs` row exists because a webhook arrived. So the
+ * missing-invoice repair is a pure insert, and the only field the sweep will UPDATE on an existing
+ * row is `status`, which has exactly one writer and one authority. It never touches `total` — see
+ * `listInvoices` in the Stripe adapter for why one writer owns that field.
+ *
+ * assurance-control: WILDO.BILLING.PROVIDER_RECONCILIATION — local billing state is compared
+ * against the provider on a schedule, and every divergence is either repaired within the
+ * provider-authoritative field set or reported.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'inversify';
+import { CoreResourceOperation, SubscriptionStatus, deriveTrustedSystemWritePreservedFields, } from '@wildo-ai/saas-models';
+import { currencyMinorUnitDecimals } from '@wildo-ai/zod-decorators';
+import { AbstractBillingBackendService } from '../../../billing/services/back-office/abstract-billing.backend.service.js';
+import { TERMINAL_SUBSCRIPTION_STATUSES } from '../../../billing/services/back-office/billing-subject-erasure-effect.backend.js';
+import { BILLING_SCOPE_TO_VARIANTS, } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+// =====================================================
+// Policy constants
+// =====================================================
+/**
+ * How recently a local write must have happened for the sweep to leave a row alone.
+ *
+ * Ten minutes, and the number is chosen to dominate the widest window a local mutation can hold:
+ * a plan change is one provider round-trip plus one local write, so seconds in the ordinary case
+ * and at most a request timeout in the worst. Ten minutes buys a wide margin at the cost of one
+ * postponed repair — the next tick reconciles the row, and a subscription that has just been
+ * written is the least likely one in the application to be stale.
+ */
+export const RECENT_MUTATION_QUIET_PERIOD_MS = 10 * 60 * 1000;
+/**
+ * The provider-AUTHORITATIVE field set — the only fields a sweep may write on a subscription.
+ *
+ * Named, exported and iterated rather than spelled out at the comparison site, so the set that
+ * gets compared and the set that gets written cannot drift apart. It mirrors
+ * `syncSubscriptionFromProvider` in the webhook router exactly; if that grows a field, this list
+ * is the other end of the pair and the pin below is what fails.
+ */
+export const PROVIDER_AUTHORITATIVE_SUBSCRIPTION_FIELDS = [
+    'status',
+    'currentPeriodStart',
+    'currentPeriodEnd',
+    'cancelAtPeriodEnd',
+    'discount',
+];
+/** How many subscriptions or billing accounts one page reads. */
+const RECONCILIATION_PAGE_SIZE = 200;
+/**
+ * Page ceiling per scope. Unlike the usage flush's runaway guard, hitting this is NOT a refusal:
+ * reconciliation is idempotent and order-independent, so stopping after N pages reconciles a
+ * prefix and leaves the rest for the next tick. It exists to bound one tick's provider calls, not
+ * to protect a correctness invariant.
+ */
+const MAX_RECONCILIATION_PAGES = 50;
+/** Invoices per customer one tick looks back over. */
+const INVOICE_LOOKBACK_PAGE_SIZE = 20;
+// =====================================================
+// Service
+// =====================================================
+let BillingReconciliationBackendService = class BillingReconciliationBackendService extends AbstractBillingBackendService {
+    constructor(logger, servicesRegistry, executionContextCreator, resourcesRegistry, errorBuilder) {
+        super(logger, servicesRegistry, executionContextCreator, resourcesRegistry, errorBuilder);
+    }
+    async initialize(provider) {
+        if (this.isInitialized)
+            return;
+        this.initializeProvider(provider);
+        this.logDebug('Billing reconciliation initialized');
+    }
+    // ════════════════════════════════════════════════════════════
+    // Public entry point
+    // ════════════════════════════════════════════════════════════
+    /**
+     * Reconcile every billing scope against the provider.
+     *
+     * Returns rather than throws on a provider fault, for the same reason the usage flush does: one
+     * account's unreachable subscription must not stop every other account's drift from being
+     * repaired, and every row left unreconciled is selectable by the next tick at no cost.
+     */
+    async reconcile() {
+        const result = {
+            subscriptionsExamined: 0,
+            subscriptionsSkippedRecentlyMutated: 0,
+            subscriptionsDrifted: 0,
+            subscriptionsRepaired: 0,
+            subscriptionsUnreadable: 0,
+            billingAccountsExamined: 0,
+            invoicesExamined: 0,
+            invoicesRecovered: 0,
+            invoiceStatusesRepaired: 0,
+            errors: [],
+        };
+        if (!this.billingProvider) {
+            result.errors.push('Provider not initialized');
+            return result;
+        }
+        for (const [scopeKey, scopeData] of Object.entries(BILLING_SCOPE_TO_VARIANTS)) {
+            const variants = { scopeKey, ...scopeData };
+            try {
+                await this.reconcileSubscriptionsForScope(variants, result);
+            }
+            catch (error) {
+                result.errors.push(`Subscription reconciliation failed for scope ${variants.scopeType}: ${error.message}`);
+            }
+            try {
+                await this.reconcileInvoicesForScope(variants, result);
+            }
+            catch (error) {
+                result.errors.push(`Invoice reconciliation failed for scope ${variants.scopeType}: ${error.message}`);
+            }
+        }
+        this.logDebug('Billing reconciliation complete', { ...result, errors: result.errors.length });
+        return result;
+    }
+    // ════════════════════════════════════════════════════════════
+    // Subscriptions
+    // ════════════════════════════════════════════════════════════
+    async reconcileSubscriptionsForScope(variants, result) {
+        // Context construction stays OUTSIDE the loop's try for the reason `AbstractBillingBackendService`
+        // gives: failing to resolve the INTERNAL_CALL path is a wiring fault, never "no subscriptions".
+        const listCtx = await this.internalCtx(variants.subscription, CoreResourceOperation.LIST);
+        const quietPeriodCutoff = Date.now() - RECENT_MUTATION_QUIET_PERIOD_MS;
+        for (let page = 1; page <= MAX_RECONCILIATION_PAGES; page += 1) {
+            const subscriptions = await this.servicesRegistry.list(variants.subscription, listCtx, 
+            // Terminal subscriptions are excluded on purpose: `CANCELLED` and `INCOMPLETE_EXPIRED` can
+            // never become anything else, so re-reading them from the provider forever buys nothing and
+            // costs one API call per dead subscription per tick, for the life of the application.
+            { status: { $nin: TERMINAL_SUBSCRIPTION_STATUSES } }, { page, limit: RECONCILIATION_PAGE_SIZE });
+            for (const subscription of subscriptions) {
+                await this.reconcileOneSubscription(variants, subscription, quietPeriodCutoff, result);
+            }
+            if (subscriptions.length < RECONCILIATION_PAGE_SIZE)
+                return;
+        }
+        result.errors.push(`Subscription reconciliation stopped after ${MAX_RECONCILIATION_PAGES} pages for scope ${variants.scopeType}. ` +
+            `The remaining rows were not examined this tick and will be picked up by the next one.`);
+    }
+    async reconcileOneSubscription(variants, subscription, quietPeriodCutoff, result) {
+        const providerSubscriptionId = subscription.providerSubscriptionId;
+        if (!providerSubscriptionId) {
+            // A subscription with no provider link is not drift — it is a local row the provider has
+            // never heard of, and there is no authority to compare it against.
+            return;
+        }
+        result.subscriptionsExamined += 1;
+        // RULE 3 — a row a local mutation currently owns.
+        const updatedAt = subscription.updatedAt ? new Date(subscription.updatedAt).getTime() : 0;
+        if (updatedAt > quietPeriodCutoff) {
+            result.subscriptionsSkippedRecentlyMutated += 1;
+            return;
+        }
+        let providerData;
+        try {
+            providerData = await this.billingProvider.retrieveSubscription(providerSubscriptionId);
+        }
+        catch (error) {
+            // RULE 4 — reported, never acted on. Note in particular that a provider answering "no such
+            // subscription" lands here and changes nothing.
+            result.subscriptionsUnreadable += 1;
+            result.errors.push(`Subscription ${subscription._id} (provider ${providerSubscriptionId}) could not be read from the provider: ` +
+                `${error.message}. Local state is UNCHANGED — a failed read is not evidence the subscription ended.`);
+            return;
+        }
+        const drift = this.computeSubscriptionDrift(subscription, providerData);
+        if (Object.keys(drift.updateData).length === 0)
+            return;
+        result.subscriptionsDrifted += 1;
+        result.errors.push(`DRIFT REPAIRED — subscription ${subscription._id} (provider ${providerSubscriptionId}) disagreed with the ` +
+            `provider on: ${drift.fields.join(', ')}. A webhook for this subscription was very likely never delivered.`);
+        try {
+            const updateCtx = await this.internalCtx(variants.subscription, CoreResourceOperation.UPDATE);
+            await this.servicesRegistry.update(variants.subscription, updateCtx, subscription._id, drift.updateData, this.trustedWriteOptions(variants.subscription, drift.updateData));
+            result.subscriptionsRepaired += 1;
+            // Feature sync is NOT called here: the subscription UPDATE post-operation hook fires it, which
+            // is the same seam the webhook router relies on. Calling it directly would recompute twice.
+        }
+        catch (error) {
+            result.errors.push(`Failed to write the reconciled state of subscription ${subscription._id}: ${error.message}`);
+        }
+    }
+    /**
+     * The comparison, over {@link PROVIDER_AUTHORITATIVE_SUBSCRIPTION_FIELDS} and nothing else.
+     *
+     * Returns only the fields that actually differ, so the update payload is minimal and the
+     * `preserveServerInjectedFields` allowlist derived from it stays minimal with it.
+     */
+    computeSubscriptionDrift(local, provider) {
+        const providerView = {
+            status: provider.status,
+            currentPeriodStart: provider.currentPeriodStart,
+            currentPeriodEnd: provider.currentPeriodEnd,
+            cancelAtPeriodEnd: provider.cancelAtPeriodEnd,
+            // `null` and not `undefined`: a discount that has ENDED must clear the local one, and an
+            // omitted key would leave the stale discount in place. Same choice `syncSubscriptionFromProvider`
+            // makes, for the same reason.
+            discount: provider.discount
+                ? {
+                    providerCouponId: provider.discount.providerCouponId,
+                    percentOff: provider.discount.percentOff,
+                    amountOff: provider.discount.amountOff,
+                    currency: provider.discount.currency,
+                    duration: provider.discount.duration,
+                    durationInMonths: provider.discount.durationInMonths,
+                    end: provider.discount.end,
+                }
+                : null,
+        };
+        const updateData = {};
+        const fields = [];
+        for (const field of PROVIDER_AUTHORITATIVE_SUBSCRIPTION_FIELDS) {
+            const localValue = local[field];
+            const providerValue = providerView[field];
+            if (this.valuesAgree(localValue, providerValue))
+                continue;
+            updateData[field] = providerValue;
+            fields.push(field);
+        }
+        return { updateData, fields };
+    }
+    /**
+     * Equality that survives the three shapes these fields actually take.
+     *
+     * A naive `===` reports drift on EVERY row, forever: `currentPeriodEnd` comes back from the
+     * repository as a `Date` instance (or, depending on the adapter and whether the row came through
+     * a JSON column or a cache, as an ISO STRING) while the provider hands back a fresh `Date`, and
+     * `discount` is an object. A sweep that always sees drift is worse than no sweep — it writes every
+     * subscription every tick, recomputes every account's entitlements, and buries a real divergence
+     * in a report where every row is listed.
+     *
+     * Absent and `null` are treated as agreeing: a local row that has never carried a discount and a
+     * provider with no discount are the same state, and distinguishing them would write `null` over
+     * `undefined` on every discount-free subscription in the application.
+     */
+    valuesAgree(local, provider) {
+        if (local === provider)
+            return true;
+        if (local == null && provider == null)
+            return true;
+        if (local == null || provider == null)
+            return false;
+        // A Date on ONE side and a string on the other. This is the branch that earns its place:
+        // two Date INSTANCES are already handled structurally below, but a repository that hands back
+        // an ISO string — a JSON column, a serialising adapter, a cached document — against a provider
+        // `Date` would otherwise compare unequal on every row, forever, and the sweep would rewrite
+        // every subscription on every tick while reporting the whole application as drifted.
+        if (local instanceof Date || provider instanceof Date) {
+            const localTime = new Date(local).getTime();
+            const providerTime = new Date(provider).getTime();
+            return Number.isFinite(localTime) && Number.isFinite(providerTime) && localTime === providerTime;
+        }
+        if (typeof local === 'object' && typeof provider === 'object') {
+            return this.stableStringify(local) === this.stableStringify(provider);
+        }
+        return false;
+    }
+    /**
+     * Key-order-independent structural comparison for the `discount` object.
+     *
+     * Key order is not a difference: the local row comes back from a document store or a JSONB column
+     * and the provider view is built by an object literal here, so a plain `JSON.stringify` compare
+     * would report drift on ordering alone. `undefined` members are dropped so an absent optional and
+     * an explicitly-undefined one compare equal, which is the same reading `valuesAgree` takes above.
+     */
+    stableStringify(value) {
+        if (value === null || typeof value !== 'object')
+            return JSON.stringify(value) ?? 'undefined';
+        if (value instanceof Date)
+            return `D${value.getTime()}`;
+        if (Array.isArray(value))
+            return `[${value.map(entry => this.stableStringify(entry)).join(',')}]`;
+        const entries = Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, entryValue]) => `${key}:${this.stableStringify(entryValue)}`);
+        return `{${entries.join(',')}}`;
+    }
+    // ════════════════════════════════════════════════════════════
+    // Invoices
+    // ════════════════════════════════════════════════════════════
+    async reconcileInvoicesForScope(variants, result) {
+        const accountsCtx = await this.internalCtx(variants.billingAccount, CoreResourceOperation.LIST);
+        for (let page = 1; page <= MAX_RECONCILIATION_PAGES; page += 1) {
+            const accounts = await this.servicesRegistry.list(variants.billingAccount, accountsCtx, {}, { page, limit: RECONCILIATION_PAGE_SIZE });
+            for (const account of accounts) {
+                const providerCustomerId = account.providerCustomerId;
+                if (!providerCustomerId)
+                    continue;
+                result.billingAccountsExamined += 1;
+                try {
+                    await this.reconcileInvoicesForAccount(variants, account._id, providerCustomerId, result);
+                }
+                catch (error) {
+                    result.errors.push(`Invoice reconciliation failed for billing account ${account._id}: ${error.message}`);
+                }
+            }
+            if (accounts.length < RECONCILIATION_PAGE_SIZE)
+                return;
+        }
+        result.errors.push(`Invoice reconciliation stopped after ${MAX_RECONCILIATION_PAGES} pages of billing accounts for scope ` +
+            `${variants.scopeType}. The remaining accounts will be examined by the next tick.`);
+    }
+    async reconcileInvoicesForAccount(variants, billingAccountId, providerCustomerId, result) {
+        const providerInvoices = await this.billingProvider.listInvoices(providerCustomerId, {
+            limit: INVOICE_LOOKBACK_PAGE_SIZE,
+        });
+        if (providerInvoices.length === 0)
+            return;
+        const listCtx = await this.internalCtx(variants.invoiceRef, CoreResourceOperation.LIST);
+        for (const providerInvoice of providerInvoices) {
+            result.invoicesExamined += 1;
+            const existing = await this.servicesRegistry.list(variants.invoiceRef, listCtx, { providerInvoiceId: providerInvoice.providerInvoiceId }, { limit: 1 });
+            if (existing.length === 0) {
+                await this.recoverMissingInvoice(variants, billingAccountId, providerInvoice, result);
+                continue;
+            }
+            const localInvoice = existing[0];
+            if (localInvoice.status === providerInvoice.status)
+                continue;
+            // The ONLY field a sweep updates on an existing invoice. `total` is deliberately excluded, and
+            // stays excluded now that the webhook router reads the same provider `total` this sweep does:
+            // agreement is not a reason for two writers to both write. Re-deriving it here would bump
+            // `updatedAt` and file an audit row for money that did not change, on every tick.
+            const statusUpdate = { status: providerInvoice.status };
+            try {
+                const updateCtx = await this.internalCtx(variants.invoiceRef, CoreResourceOperation.UPDATE);
+                await this.servicesRegistry.update(variants.invoiceRef, updateCtx, localInvoice._id, statusUpdate, this.trustedWriteOptions(variants.invoiceRef, statusUpdate));
+                result.invoiceStatusesRepaired += 1;
+                result.errors.push(`DRIFT REPAIRED — invoice ${localInvoice._id} (provider ${providerInvoice.providerInvoiceId}) was recorded ` +
+                    `as "${localInvoice.status}" and the provider holds "${providerInvoice.status}".`);
+            }
+            catch (error) {
+                result.errors.push(`Failed to correct the status of invoice ${localInvoice._id}: ${error.message}`);
+            }
+        }
+    }
+    async recoverMissingInvoice(variants, billingAccountId, providerInvoice, result) {
+        /*
+         * The scale is the CURRENCY's, exactly as the webhook path resolves it (#515). A zero-decimal
+         * currency recorded at scale 2 stores a hundredth of the real amount; an unresolvable currency
+         * falls back to 2 with a loud line rather than dropping the invoice, because losing the record
+         * of an invoice that exists is worse than recording it at a scale somebody can correct.
+         */
+        const resolvedDecimals = currencyMinorUnitDecimals(providerInvoice.currency.toUpperCase());
+        if (resolvedDecimals === undefined) {
+            result.errors.push(`Recovered invoice ${providerInvoice.providerInvoiceId} at an ASSUMED scale of 2: currency ` +
+                `"${providerInvoice.currency}" has no resolvable minor unit.`);
+        }
+        const invoiceData = {
+            [variants.billingAccountFkField]: billingAccountId,
+            providerInvoiceId: providerInvoice.providerInvoiceId,
+            status: providerInvoice.status,
+            total: {
+                amount: BigInt(Math.trunc(providerInvoice.total)),
+                currency: providerInvoice.currency,
+                decimals: resolvedDecimals ?? 2,
+            },
+            hostedInvoiceUrl: providerInvoice.hostedInvoiceUrl,
+            invoicePdfUrl: providerInvoice.invoicePdfUrl,
+        };
+        try {
+            const createCtx = await this.internalCtx(variants.invoiceRef, CoreResourceOperation.CREATE);
+            await this.servicesRegistry.create(variants.invoiceRef, createCtx, invoiceData, this.trustedWriteOptions(variants.invoiceRef, invoiceData, CoreResourceOperation.CREATE));
+            result.invoicesRecovered += 1;
+            result.errors.push(`INVOICE RECOVERED — provider invoice ${providerInvoice.providerInvoiceId} for billing account ` +
+                `${billingAccountId} existed at the provider and nowhere locally. Its webhook was never delivered.`);
+        }
+        catch (error) {
+            result.errors.push(`Failed to record recovered invoice ${providerInvoice.providerInvoiceId}: ${error.message}`);
+        }
+    }
+    // ════════════════════════════════════════════════════════════
+    // Private — trusted-system write
+    // ════════════════════════════════════════════════════════════
+    /**
+     * `ServiceOptions` that re-attach the fields a client-shaped request DTO would strip.
+     *
+     * The same seam the webhook router and the catalog sync use, and it is not optional here: every
+     * period field on a subscription is `.isNotEditable()` and `providerInvoiceId` is
+     * `.isBackendOnly()`, so without the allowlist the write "succeeds" and persists nothing — a
+     * repair that silently repairs nothing, which is the worst possible outcome for a sweep whose
+     * whole job is to make local state true.
+     */
+    trustedWriteOptions(resourceType, payload, verb = CoreResourceOperation.UPDATE) {
+        const { mainSchema } = this.resourcesRegistry.getResourceConfiguration(resourceType);
+        return {
+            preserveServerInjectedFields: deriveTrustedSystemWritePreservedFields(mainSchema, Object.keys(payload), verb),
+        };
+    }
+};
+BillingReconciliationBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __metadata("design:paramtypes", [Function, Function, Function, Function, Function])
+], BillingReconciliationBackendService);
+export { BillingReconciliationBackendService };
+/**
+ * Statuses a reconciliation sweep considers LIVE — everything `TERMINAL_SUBSCRIPTION_STATUSES` does
+ * not claim.
+ *
+ * DERIVED, so the partition is exhaustive by construction and no pin could ever prove it: a member
+ * added to the enum lands in the swept half automatically. That default is the right one (a new
+ * status is presumed live until someone says otherwise), but it is a default rather than a decision,
+ * so the pin beside this asserts the RESULTING MEMBERSHIP literally. Adding an enum member, or
+ * moving one across the boundary, reddens it and puts the decision in front of a person — which is
+ * the only thing a test can actually contribute here.
+ */
+export const RECONCILED_SUBSCRIPTION_STATUSES = Object.values(SubscriptionStatus).filter(status => !TERMINAL_SUBSCRIPTION_STATUSES.includes(status));
+//# sourceMappingURL=billing-reconciliation.backend.service.js.map

package/dist/esm/billing/services/back-office/billing-reconciliation.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-reconciliation.backend.service.js","sourceRoot":"","sources":["../../../../../src/billing/services/back-office/billing-reconciliation.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;;;;;;;;;;;;;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAKL,qBAAqB,EACrB,kBAAkB,EAClB,uCAAuC,GACxC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAOrE,OAAO,EAAE,6BAA6B,EAAE,MAAM,kFAAkF,CAAC;AACjI,OAAO,EAAE,8BAA8B,EAAE,MAAM,wFAAwF,CAAC;AACxI,OAAO,EACL,yBAAyB,GAE1B,MAAM,mFAAmF,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAOpF,wDAAwD;AACxD,mBAAmB;AACnB,wDAAwD;AAExD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0CAA0C,GAAG;IACxD,QAAQ;IACR,oBAAoB;IACpB,kBAAkB;IAClB,mBAAmB;IACnB,UAAU;CACF,CAAC;AAEX,iEAAiE;AACjE,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC;;;;;GAKG;AACH,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAEpC,sDAAsD;AACtD,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAkCtC,wDAAwD;AACxD,UAAU;AACV,wDAAwD;AAGjD,IAAM,mCAAmC,GAAzC,MAAM,mCAAoC,SAAQ,6BAA6B;IACpF,YACqC,MAAqB,EACG,gBAAuD,EAChD,uBAA8D,EAC5E,iBAAkD,EACtD,YAAwC;QAExF,KAAK,CAAC,MAAM,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,YAAY,CAAC,CAAC;IAC5F,CAAC;IAEM,KAAK,CAAC,UAAU,CAAC,QAAmC;QACzD,IAAI,IAAI,CAAC,aAAa;YAAE,OAAO;QAC/B,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,oCAAoC,CAAC,CAAC;IACtD,CAAC;IAED,+DAA+D;IAC/D,qBAAqB;IACrB,+DAA+D;IAE/D;;;;;;OAMG;IACI,KAAK,CAAC,SAAS;QACpB,MAAM,MAAM,GAAgC;YAC1C,qBAAqB,EAAE,CAAC;YACxB,mCAAmC,EAAE,CAAC;YACtC,oBAAoB,EAAE,CAAC;YACvB,qBAAqB,EAAE,CAAC;YACxB,uBAAuB,EAAE,CAAC;YAC1B,uBAAuB,EAAE,CAAC;YAC1B,gBAAgB,EAAE,CAAC;YACnB,iBAAiB,EAAE,CAAC;YACpB,uBAAuB,EAAE,CAAC;YAC1B,MAAM,EAAE,EAAE;SACX,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;YAC/C,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,KAAK,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,yBAAyB,CAAC,EAAE,CAAC;YAC9E,MAAM,QAAQ,GAA4B,EAAE,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC;YACrE,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,8BAA8B,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC9D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,gDAAgD,QAAQ,CAAC,SAAS,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YACxH,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,yBAAyB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACzD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,2CAA2C,QAAQ,CAAC,SAAS,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YACnH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,iCAAiC,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9F,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+DAA+D;IAC/D,gBAAgB;IAChB,+DAA+D;IAEvD,KAAK,CAAC,8BAA8B,CAC1C,QAAiC,EACjC,MAAmC;QAEnC,mGAAmG;QACnG,gGAAgG;QAChG,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAgC,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAC9G,MAAM,iBAAiB,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,+BAA+B,CAAC;QAEvE,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,wBAAwB,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;YAC/D,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,CACpD,QAAQ,CAAC,YAAgC,EACzC,OAAO;YACP,2FAA2F;YAC3F,4FAA4F;YAC5F,sFAAsF;YACtF,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,8BAA8B,EAAE,EAAE,EACpD,EAAE,IAAI,EAAE,KAAK,EAAE,wBAAwB,EAAE,CACb,CAAC;YAE/B,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;gBACzC,MAAM,IAAI,CAAC,wBAAwB,CAAC,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC;YACzF,CAAC;YAED,IAAI,aAAa,CAAC,MAAM,GAAG,wBAAwB;gBAAE,OAAO;QAC9D,CAAC;QAED,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,6CAA6C,wBAAwB,oBAAoB,QAAQ,CAAC,SAAS,IAAI;YAC/G,uFAAuF,CACxF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,wBAAwB,CACpC,QAAiC,EACjC,YAAqC,EACrC,iBAAyB,EACzB,MAAmC;QAEnC,MAAM,sBAAsB,GAAG,YAAY,CAAC,sBAAsB,CAAC;QACnE,IAAI,CAAC,sBAAsB,EAAE,CAAC;YAC5B,yFAAyF;YACzF,mEAAmE;YACnE,OAAO;QACT,CAAC;QAED,MAAM,CAAC,qBAAqB,IAAI,CAAC,CAAC;QAElC,kDAAkD;QAClD,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1F,IAAI,SAAS,GAAG,iBAAiB,EAAE,CAAC;YAClC,MAAM,CAAC,mCAAmC,IAAI,CAAC,CAAC;YAChD,OAAO;QACT,CAAC;QAED,IAAI,YAA8C,CAAC;QACnD,IAAI,CAAC;YACH,YAAY,GAAG,MAAM,IAAI,CAAC,eAAgB,CAAC,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;QAC1F,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,2FAA2F;YAC3F,gDAAgD;YAChD,MAAM,CAAC,uBAAuB,IAAI,CAAC,CAAC;YACpC,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,gBAAgB,YAAY,CAAC,GAAG,cAAc,sBAAsB,yCAAyC;gBAC7G,GAAI,KAAe,CAAC,OAAO,oFAAoF,CAChH,CAAC;YACF,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,wBAAwB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QACxE,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEvD,MAAM,CAAC,oBAAoB,IAAI,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,iCAAiC,YAAY,CAAC,GAAG,cAAc,sBAAsB,uBAAuB;YAC5G,gBAAgB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,oEAAoE,CAC5G,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAgC,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;YAClH,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAChC,QAAQ,CAAC,YAAgC,EACzC,SAAS,EACT,YAAY,CAAC,GAAG,EAChB,KAAK,CAAC,UAAU,EAChB,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,YAA4B,EAAE,KAAK,CAAC,UAAU,CAAC,CAClF,CAAC;YACF,MAAM,CAAC,qBAAqB,IAAI,CAAC,CAAC;YAClC,+FAA+F;YAC/F,4FAA4F;QAC9F,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,wDAAwD,YAAY,CAAC,GAAG,KAAM,KAAe,CAAC,OAAO,EAAE,CACxG,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,wBAAwB,CAC9B,KAA8B,EAC9B,QAA0C;QAE1C,MAAM,YAAY,GAA4B;YAC5C,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB;YAC/C,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;YAC3C,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;YAC7C,yFAAyF;YACzF,kGAAkG;YAClG,8BAA8B;YAC9B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBACzB,CAAC,CAAC;oBACA,gBAAgB,EAAE,QAAQ,CAAC,QAAQ,CAAC,gBAAgB;oBACpD,UAAU,EAAE,QAAQ,CAAC,QAAQ,CAAC,UAAU;oBACxC,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,SAAS;oBACtC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,QAAQ;oBACpC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,QAAQ;oBACpC,gBAAgB,EAAE,QAAQ,CAAC,QAAQ,CAAC,gBAAgB;oBACpD,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG;iBAC3B;gBACD,CAAC,CAAC,IAAI;SACT,CAAC;QAEF,MAAM,UAAU,GAA4B,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,KAAK,MAAM,KAAK,IAAI,0CAA0C,EAAE,CAAC;YAC/D,MAAM,UAAU,GAAI,KAA4C,CAAC,KAAK,CAAC,CAAC;YACxE,MAAM,aAAa,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YAC1C,IAAI,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,aAAa,CAAC;gBAAE,SAAS;YAC1D,UAAU,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;QAED,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAChC,CAAC;IAED;;;;;;;;;;;;;OAaG;IACK,WAAW,CAAC,KAAc,EAAE,QAAiB;QACnD,IAAI,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpC,IAAI,KAAK,IAAI,IAAI,IAAI,QAAQ,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QACnD,IAAI,KAAK,IAAI,IAAI,IAAI,QAAQ,IAAI,IAAI;YAAE,OAAO,KAAK,CAAC;QACpD,yFAAyF;QACzF,8FAA8F;QAC9F,+FAA+F;QAC/F,4FAA4F;QAC5F,qFAAqF;QACrF,IAAI,KAAK,YAAY,IAAI,IAAI,QAAQ,YAAY,IAAI,EAAE,CAAC;YACtD,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,KAA+B,CAAC,CAAC,OAAO,EAAE,CAAC;YACtE,MAAM,YAAY,GAAG,IAAI,IAAI,CAAC,QAAkC,CAAC,CAAC,OAAO,EAAE,CAAC;YAC5E,OAAO,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,SAAS,KAAK,YAAY,CAAC;QACnG,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC9D,OAAO,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACK,eAAe,CAAC,KAAc;QACpC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC;QAC7F,IAAI,KAAK,YAAY,IAAI;YAAE,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAClG,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC;aACpD,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC5E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClC,CAAC;IAED,+DAA+D;IAC/D,WAAW;IACX,+DAA+D;IAEvD,KAAK,CAAC,yBAAyB,CACrC,QAAiC,EACjC,MAAmC;QAEnC,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,cAAkC,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAEpH,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,wBAAwB,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;YAC/D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAC/C,QAAQ,CAAC,cAAkC,EAC3C,WAAW,EACX,EAAE,EACF,EAAE,IAAI,EAAE,KAAK,EAAE,wBAAwB,EAAE,CACtB,CAAC;YAEtB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,MAAM,kBAAkB,GAAI,OAA8C,CAAC,kBAAwC,CAAC;gBACpH,IAAI,CAAC,kBAAkB;oBAAE,SAAS;gBAClC,MAAM,CAAC,uBAAuB,IAAI,CAAC,CAAC;gBACpC,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,2BAA2B,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE,kBAAkB,EAAE,MAAM,CAAC,CAAC;gBAC5F,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,qDAAqD,OAAO,CAAC,GAAG,KAAM,KAAe,CAAC,OAAO,EAAE,CAChG,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,IAAI,QAAQ,CAAC,MAAM,GAAG,wBAAwB;gBAAE,OAAO;QACzD,CAAC;QAED,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,wCAAwC,wBAAwB,uCAAuC;YACvG,GAAG,QAAQ,CAAC,SAAS,6DAA6D,CACnF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,2BAA2B,CACvC,QAAiC,EACjC,gBAAwB,EACxB,kBAA0B,EAC1B,MAAmC;QAEnC,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,eAAgB,CAAC,YAAY,CAAC,kBAAkB,EAAE;YACpF,KAAK,EAAE,0BAA0B;SAClC,CAAC,CAAC;QACH,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAE1C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAA8B,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAE5G,KAAK,MAAM,eAAe,IAAI,gBAAgB,EAAE,CAAC;YAC/C,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAC;YAE7B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAC/C,QAAQ,CAAC,UAA8B,EACvC,OAAO,EACP,EAAE,iBAAiB,EAAE,eAAe,CAAC,iBAAiB,EAAE,EACxD,EAAE,KAAK,EAAE,CAAC,EAAE,CACG,CAAC;YAElB,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1B,MAAM,IAAI,CAAC,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC,CAAC;gBACtF,SAAS;YACX,CAAC;YAED,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACjC,IAAI,YAAY,CAAC,MAAM,KAAK,eAAe,CAAC,MAAM;gBAAE,SAAS;YAE7D,+FAA+F;YAC/F,8FAA8F;YAC9F,0FAA0F;YAC1F,kFAAkF;YAClF,MAAM,YAAY,GAAG,EAAE,MAAM,EAAE,eAAe,CAAC,MAAM,EAAE,CAAC;YACxD,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAA8B,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;gBAChH,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAChC,QAAQ,CAAC,UAA8B,EACvC,SAAS,EACT,YAAY,CAAC,GAAG,EAChB,YAAY,EACZ,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,UAA0B,EAAE,YAAY,CAAC,CAC5E,CAAC;gBACF,MAAM,CAAC,uBAAuB,IAAI,CAAC,CAAC;gBACpC,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,4BAA4B,YAAY,CAAC,GAAG,cAAc,eAAe,CAAC,iBAAiB,iBAAiB;oBAC5G,OAAO,YAAY,CAAC,MAAM,6BAA6B,eAAe,CAAC,MAAM,IAAI,CAClF,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,2CAA2C,YAAY,CAAC,GAAG,KAAM,KAAe,CAAC,OAAO,EAAE,CAC3F,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,qBAAqB,CACjC,QAAiC,EACjC,gBAAwB,EACxB,eAA4C,EAC5C,MAAmC;QAEnC;;;;;WAKG;QACH,MAAM,gBAAgB,GAAG,yBAAyB,CAAC,eAAe,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3F,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,qBAAqB,eAAe,CAAC,iBAAiB,sCAAsC;gBAC5F,IAAI,eAAe,CAAC,QAAQ,iCAAiC,CAC9D,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAA4B;YAC3C,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,gBAAgB;YAClD,iBAAiB,EAAE,eAAe,CAAC,iBAAiB;YACpD,MAAM,EAAE,eAAe,CAAC,MAAM;YAC9B,KAAK,EAAE;gBACL,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;gBACjD,QAAQ,EAAE,eAAe,CAAC,QAAQ;gBAClC,QAAQ,EAAE,gBAAgB,IAAI,CAAC;aAChC;YACD,gBAAgB,EAAE,eAAe,CAAC,gBAAgB;YAClD,aAAa,EAAE,eAAe,CAAC,aAAa;SAC7C,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAA8B,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;YAChH,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAChC,QAAQ,CAAC,UAA8B,EACvC,SAAS,EACT,WAAW,EACX,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,UAA0B,EAAE,WAAW,EAAE,qBAAqB,CAAC,MAAM,CAAC,CACzG,CAAC;YACF,MAAM,CAAC,iBAAiB,IAAI,CAAC,CAAC;YAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,wCAAwC,eAAe,CAAC,iBAAiB,uBAAuB;gBAChG,GAAG,gBAAgB,gFAAgF,CACpG,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAChB,sCAAsC,eAAe,CAAC,iBAAiB,KAAM,KAAe,CAAC,OAAO,EAAE,CACvG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,iCAAiC;IACjC,+DAA+D;IAE/D;;;;;;;;OAQG;IACK,mBAAmB,CACzB,YAA0B,EAC1B,OAAgC,EAChC,OAAoE,qBAAqB,CAAC,MAAM;QAEhG,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,iBAAiB,CAAC,wBAAwB,CAAC,YAAY,CAAC,CAAC;QACrF,OAAO;YACL,4BAA4B,EAAE,uCAAuC,CACnE,UAAU,EACV,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EACpB,IAAI,CACL;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AA1bY,mCAAmC;IAD/C,UAAU,EAAE;IAGR,WAAA,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;IACjC,WAAA,MAAM,CAAC,kBAAkB,CAAC,8BAA8B,CAAC,CAAA;IACzD,WAAA,MAAM,CAAC,kBAAkB,CAAC,qCAAqC,CAAC,CAAA;IAChE,WAAA,MAAM,CAAC,kBAAkB,CAAC,uBAAuB,CAAC,CAAA;IAClD,WAAA,MAAM,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,CAAA;;GANtC,mCAAmC,CA0b/C;;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAC3C,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,8BAA8B,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC","sourcesContent":["/**\n * Billing Reconciliation — asks the provider what it actually holds, and repairs what drifted.\n *\n * ## What this service is for\n *\n * Every local billing fact arrives by WEBHOOK. `StandardBilling_Interface.retrieveSubscription`\n * exists, its own doc comment says \"on-demand retrieval for reconciliation (if webhook missed)\",\n * and until 2026-09-09 the only two callers were inside the webhook router itself — i.e. the\n * recovery read only ever ran when a webhook DID arrive. A delivery that is lost, or that arrives\n * while the application is down and exhausts the provider's retries, left a stale subscription and\n * a missing invoice with nothing anywhere that could notice. That is the whole finding.\n *\n * ## The conflict rule, because a scheduled write to billing state can CORRUPT rather than merely\n * lag\n *\n * Five rules, and each one is a refusal rather than a capability:\n *\n * 1. **Only what the provider is authoritative FOR.** `status`, `currentPeriodStart`,\n *    `currentPeriodEnd`, `cancelAtPeriodEnd` and `discount` — exactly the set the webhook path\n *    already syncs in `syncSubscriptionFromProvider`, no more. Two writers of one field must agree\n *    on which fields they own, or a sweep and a webhook take turns undoing each other.\n *\n * 2. **`items` is NEVER reconciled.** REJECTED ALTERNATIVE: sync items too, since the provider\n *    knows them. It races `CHANGE_PLAN` / `ADD_ADDON` / `REMOVE_ADDON`, every one of which calls\n *    the provider FIRST and writes local items afterwards — so a sweep reading the provider inside\n *    that window and writing items would revert a plan change the customer has already been\n *    charged for. The webhook router refuses items for the same reason and says so; a sweep, which\n *    runs unprompted and concurrently, has strictly more exposure than it does.\n *\n * 3. **A row a local mutation currently owns is SKIPPED.** Any subscription whose `updatedAt` is\n *    inside {@link RECENT_MUTATION_QUIET_PERIOD_MS} is left alone and counted, not written.\n *    REJECTED ALTERNATIVE: a compare-and-swap on `updatedAt` at write time. It does not close the\n *    window that matters — the read-modify-write starts at the PROVIDER READ, not at the local\n *    read, so a snapshot taken before a webhook that has since landed would still satisfy a CAS\n *    taken after it. The quiet period addresses the real window, needs no schema change, and costs\n *    one skipped row that the next tick picks up.\n *\n * 4. **Nothing is ever DELETED, CANCELLED or CREATED here.** A provider read that fails — including\n *    a provider saying the subscription does not exist — is REPORTED and acted on by nobody.\n *    REJECTED ALTERNATIVE: mark a subscription `CANCELLED` when the provider cannot find it. A\n *    rotated key pointed at the wrong account, a test-vs-live key mix-up, or a provider outage\n *    would then cancel every subscription in the application, revoking every entitlement, from a\n *    read that told us nothing. Stale entitlements are recoverable by the next successful tick;\n *    revoked ones are not.\n *\n * 5. **A row that AGREES is not written.** Comparison happens before any update, because a\n *    subscription UPDATE fires the post-operation feature-sync hook — an unconditional write would\n *    recompute entitlements for every account on every tick, bump every `updatedAt`, and file an\n *    audit row per subscription per tick for a change that did not happen.\n *\n * ## Invoices are INSERT-mostly, which is why they are safe\n *\n * Wildo never authors an invoice: every `invoiceRefs` row exists because a webhook arrived. So the\n * missing-invoice repair is a pure insert, and the only field the sweep will UPDATE on an existing\n * row is `status`, which has exactly one writer and one authority. It never touches `total` — see\n * `listInvoices` in the Stripe adapter for why one writer owns that field.\n *\n * assurance-control: WILDO.BILLING.PROVIDER_RECONCILIATION — local billing state is compared\n * against the provider on a schedule, and every divergence is either repaired within the\n * provider-authoritative field set or reported.\n */\n\nimport { injectable, inject } from 'inversify';\nimport {\n  type BillingAccount,\n  type BillingSubscriptionBase,\n  type InvoiceRef,\n  CoreResourceType,\n  CoreResourceOperation,\n  SubscriptionStatus,\n  deriveTrustedSystemWritePreservedFields,\n} from '@wildo-ai/saas-models';\nimport type { ResourceType } from '@wildo-ai/saas-models';\nimport { currencyMinorUnitDecimals } from '@wildo-ai/zod-decorators';\nimport type {\n  StandardBilling_Interface,\n  StandardBilling_SubscriptionData,\n  StandardBilling_InvoiceData,\n} from '@wildo-ai/external-connectors-models';\nimport type { ServiceOptions } from '~wildo-backend-lib/base-classes/models/repositories.backend.schemas';\nimport { AbstractBillingBackendService } from '~wildo-backend-lib/billing/services/back-office/abstract-billing.backend.service';\nimport { TERMINAL_SUBSCRIPTION_STATUSES } from '~wildo-backend-lib/billing/services/back-office/billing-subject-erasure-effect.backend';\nimport {\n  BILLING_SCOPE_TO_VARIANTS,\n  type BillingResolvedVariants,\n} from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-impl-utils.backend';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';\nimport type { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\n\n// =====================================================\n// Policy constants\n// =====================================================\n\n/**\n * How recently a local write must have happened for the sweep to leave a row alone.\n *\n * Ten minutes, and the number is chosen to dominate the widest window a local mutation can hold:\n * a plan change is one provider round-trip plus one local write, so seconds in the ordinary case\n * and at most a request timeout in the worst. Ten minutes buys a wide margin at the cost of one\n * postponed repair — the next tick reconciles the row, and a subscription that has just been\n * written is the least likely one in the application to be stale.\n */\nexport const RECENT_MUTATION_QUIET_PERIOD_MS = 10 * 60 * 1000;\n\n/**\n * The provider-AUTHORITATIVE field set — the only fields a sweep may write on a subscription.\n *\n * Named, exported and iterated rather than spelled out at the comparison site, so the set that\n * gets compared and the set that gets written cannot drift apart. It mirrors\n * `syncSubscriptionFromProvider` in the webhook router exactly; if that grows a field, this list\n * is the other end of the pair and the pin below is what fails.\n */\nexport const PROVIDER_AUTHORITATIVE_SUBSCRIPTION_FIELDS = [\n  'status',\n  'currentPeriodStart',\n  'currentPeriodEnd',\n  'cancelAtPeriodEnd',\n  'discount',\n] as const;\n\n/** How many subscriptions or billing accounts one page reads. */\nconst RECONCILIATION_PAGE_SIZE = 200;\n\n/**\n * Page ceiling per scope. Unlike the usage flush's runaway guard, hitting this is NOT a refusal:\n * reconciliation is idempotent and order-independent, so stopping after N pages reconciles a\n * prefix and leaves the rest for the next tick. It exists to bound one tick's provider calls, not\n * to protect a correctness invariant.\n */\nconst MAX_RECONCILIATION_PAGES = 50;\n\n/** Invoices per customer one tick looks back over. */\nconst INVOICE_LOOKBACK_PAGE_SIZE = 20;\n\n// =====================================================\n// Result\n// =====================================================\n\n/**\n * What one run did — stated as separate counts rather than a single \"reconciled\" number, because\n * the interesting quantity is not how many rows were examined but how many DISAGREED. A healthy\n * application drifts on zero rows; a steady non-zero `subscriptionsRepaired` means webhooks are\n * being lost and the sweep is papering over it.\n */\nexport interface BillingReconciliationResult {\n  subscriptionsExamined: number;\n  /** Rows left alone because a local mutation had just touched them (rule 3). */\n  subscriptionsSkippedRecentlyMutated: number;\n  /** Rows where at least one provider-authoritative field disagreed. */\n  subscriptionsDrifted: number;\n  /** Rows actually written. Equals `subscriptionsDrifted` unless a write failed. */\n  subscriptionsRepaired: number;\n  /** Rows whose provider state could not be read. Reported, never acted on (rule 4). */\n  subscriptionsUnreadable: number;\n  billingAccountsExamined: number;\n  invoicesExamined: number;\n  /** Invoices that existed at the provider and nowhere locally, now recorded. */\n  invoicesRecovered: number;\n  invoiceStatusesRepaired: number;\n  /**\n   * One line per drift and per failure, naming the row and the field. A count tells an operator\n   * something is wrong; only the line says whose subscription it was.\n   */\n  errors: string[];\n}\n\n// =====================================================\n// Service\n// =====================================================\n\n@injectable()\nexport class BillingReconciliationBackendService extends AbstractBillingBackendService {\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) servicesRegistry: ServicesRegistryHandlerBackendService,\n    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService) executionContextCreator: ExecutionContextCreatorBackendService,\n    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) resourcesRegistry: ResourcesRegistryBackendService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: ErrorBuilderBackendService,\n  ) {\n    super(logger, servicesRegistry, executionContextCreator, resourcesRegistry, errorBuilder);\n  }\n\n  public async initialize(provider: StandardBilling_Interface): Promise<void> {\n    if (this.isInitialized) return;\n    this.initializeProvider(provider);\n    this.logDebug('Billing reconciliation initialized');\n  }\n\n  // ════════════════════════════════════════════════════════════\n  // Public entry point\n  // ════════════════════════════════════════════════════════════\n\n  /**\n   * Reconcile every billing scope against the provider.\n   *\n   * Returns rather than throws on a provider fault, for the same reason the usage flush does: one\n   * account's unreachable subscription must not stop every other account's drift from being\n   * repaired, and every row left unreconciled is selectable by the next tick at no cost.\n   */\n  public async reconcile(): Promise<BillingReconciliationResult> {\n    const result: BillingReconciliationResult = {\n      subscriptionsExamined: 0,\n      subscriptionsSkippedRecentlyMutated: 0,\n      subscriptionsDrifted: 0,\n      subscriptionsRepaired: 0,\n      subscriptionsUnreadable: 0,\n      billingAccountsExamined: 0,\n      invoicesExamined: 0,\n      invoicesRecovered: 0,\n      invoiceStatusesRepaired: 0,\n      errors: [],\n    };\n\n    if (!this.billingProvider) {\n      result.errors.push('Provider not initialized');\n      return result;\n    }\n\n    for (const [scopeKey, scopeData] of Object.entries(BILLING_SCOPE_TO_VARIANTS)) {\n      const variants: BillingResolvedVariants = { scopeKey, ...scopeData };\n      try {\n        await this.reconcileSubscriptionsForScope(variants, result);\n      } catch (error) {\n        result.errors.push(`Subscription reconciliation failed for scope ${variants.scopeType}: ${(error as Error).message}`);\n      }\n      try {\n        await this.reconcileInvoicesForScope(variants, result);\n      } catch (error) {\n        result.errors.push(`Invoice reconciliation failed for scope ${variants.scopeType}: ${(error as Error).message}`);\n      }\n    }\n\n    this.logDebug('Billing reconciliation complete', { ...result, errors: result.errors.length });\n    return result;\n  }\n\n  // ════════════════════════════════════════════════════════════\n  // Subscriptions\n  // ════════════════════════════════════════════════════════════\n\n  private async reconcileSubscriptionsForScope(\n    variants: BillingResolvedVariants,\n    result: BillingReconciliationResult,\n  ): Promise<void> {\n    // Context construction stays OUTSIDE the loop's try for the reason `AbstractBillingBackendService`\n    // gives: failing to resolve the INTERNAL_CALL path is a wiring fault, never \"no subscriptions\".\n    const listCtx = await this.internalCtx(variants.subscription as CoreResourceType, CoreResourceOperation.LIST);\n    const quietPeriodCutoff = Date.now() - RECENT_MUTATION_QUIET_PERIOD_MS;\n\n    for (let page = 1; page <= MAX_RECONCILIATION_PAGES; page += 1) {\n      const subscriptions = await this.servicesRegistry.list<BillingSubscriptionBase>(\n        variants.subscription as CoreResourceType,\n        listCtx,\n        // Terminal subscriptions are excluded on purpose: `CANCELLED` and `INCOMPLETE_EXPIRED` can\n        // never become anything else, so re-reading them from the provider forever buys nothing and\n        // costs one API call per dead subscription per tick, for the life of the application.\n        { status: { $nin: TERMINAL_SUBSCRIPTION_STATUSES } },\n        { page, limit: RECONCILIATION_PAGE_SIZE },\n      ) as BillingSubscriptionBase[];\n\n      for (const subscription of subscriptions) {\n        await this.reconcileOneSubscription(variants, subscription, quietPeriodCutoff, result);\n      }\n\n      if (subscriptions.length < RECONCILIATION_PAGE_SIZE) return;\n    }\n\n    result.errors.push(\n      `Subscription reconciliation stopped after ${MAX_RECONCILIATION_PAGES} pages for scope ${variants.scopeType}. ` +\n      `The remaining rows were not examined this tick and will be picked up by the next one.`,\n    );\n  }\n\n  private async reconcileOneSubscription(\n    variants: BillingResolvedVariants,\n    subscription: BillingSubscriptionBase,\n    quietPeriodCutoff: number,\n    result: BillingReconciliationResult,\n  ): Promise<void> {\n    const providerSubscriptionId = subscription.providerSubscriptionId;\n    if (!providerSubscriptionId) {\n      // A subscription with no provider link is not drift — it is a local row the provider has\n      // never heard of, and there is no authority to compare it against.\n      return;\n    }\n\n    result.subscriptionsExamined += 1;\n\n    // RULE 3 — a row a local mutation currently owns.\n    const updatedAt = subscription.updatedAt ? new Date(subscription.updatedAt).getTime() : 0;\n    if (updatedAt > quietPeriodCutoff) {\n      result.subscriptionsSkippedRecentlyMutated += 1;\n      return;\n    }\n\n    let providerData: StandardBilling_SubscriptionData;\n    try {\n      providerData = await this.billingProvider!.retrieveSubscription(providerSubscriptionId);\n    } catch (error) {\n      // RULE 4 — reported, never acted on. Note in particular that a provider answering \"no such\n      // subscription\" lands here and changes nothing.\n      result.subscriptionsUnreadable += 1;\n      result.errors.push(\n        `Subscription ${subscription._id} (provider ${providerSubscriptionId}) could not be read from the provider: ` +\n        `${(error as Error).message}. Local state is UNCHANGED — a failed read is not evidence the subscription ended.`,\n      );\n      return;\n    }\n\n    const drift = this.computeSubscriptionDrift(subscription, providerData);\n    if (Object.keys(drift.updateData).length === 0) return;\n\n    result.subscriptionsDrifted += 1;\n    result.errors.push(\n      `DRIFT REPAIRED — subscription ${subscription._id} (provider ${providerSubscriptionId}) disagreed with the ` +\n      `provider on: ${drift.fields.join(', ')}. A webhook for this subscription was very likely never delivered.`,\n    );\n\n    try {\n      const updateCtx = await this.internalCtx(variants.subscription as CoreResourceType, CoreResourceOperation.UPDATE);\n      await this.servicesRegistry.update(\n        variants.subscription as CoreResourceType,\n        updateCtx,\n        subscription._id,\n        drift.updateData,\n        this.trustedWriteOptions(variants.subscription as ResourceType, drift.updateData),\n      );\n      result.subscriptionsRepaired += 1;\n      // Feature sync is NOT called here: the subscription UPDATE post-operation hook fires it, which\n      // is the same seam the webhook router relies on. Calling it directly would recompute twice.\n    } catch (error) {\n      result.errors.push(\n        `Failed to write the reconciled state of subscription ${subscription._id}: ${(error as Error).message}`,\n      );\n    }\n  }\n\n  /**\n   * The comparison, over {@link PROVIDER_AUTHORITATIVE_SUBSCRIPTION_FIELDS} and nothing else.\n   *\n   * Returns only the fields that actually differ, so the update payload is minimal and the\n   * `preserveServerInjectedFields` allowlist derived from it stays minimal with it.\n   */\n  private computeSubscriptionDrift(\n    local: BillingSubscriptionBase,\n    provider: StandardBilling_SubscriptionData,\n  ): { updateData: Record<string, unknown>; fields: string[] } {\n    const providerView: Record<string, unknown> = {\n      status: provider.status,\n      currentPeriodStart: provider.currentPeriodStart,\n      currentPeriodEnd: provider.currentPeriodEnd,\n      cancelAtPeriodEnd: provider.cancelAtPeriodEnd,\n      // `null` and not `undefined`: a discount that has ENDED must clear the local one, and an\n      // omitted key would leave the stale discount in place. Same choice `syncSubscriptionFromProvider`\n      // makes, for the same reason.\n      discount: provider.discount\n        ? {\n          providerCouponId: provider.discount.providerCouponId,\n          percentOff: provider.discount.percentOff,\n          amountOff: provider.discount.amountOff,\n          currency: provider.discount.currency,\n          duration: provider.discount.duration,\n          durationInMonths: provider.discount.durationInMonths,\n          end: provider.discount.end,\n        }\n        : null,\n    };\n\n    const updateData: Record<string, unknown> = {};\n    const fields: string[] = [];\n\n    for (const field of PROVIDER_AUTHORITATIVE_SUBSCRIPTION_FIELDS) {\n      const localValue = (local as unknown as Record<string, unknown>)[field];\n      const providerValue = providerView[field];\n      if (this.valuesAgree(localValue, providerValue)) continue;\n      updateData[field] = providerValue;\n      fields.push(field);\n    }\n\n    return { updateData, fields };\n  }\n\n  /**\n   * Equality that survives the three shapes these fields actually take.\n   *\n   * A naive `===` reports drift on EVERY row, forever: `currentPeriodEnd` comes back from the\n   * repository as a `Date` instance (or, depending on the adapter and whether the row came through\n   * a JSON column or a cache, as an ISO STRING) while the provider hands back a fresh `Date`, and\n   * `discount` is an object. A sweep that always sees drift is worse than no sweep — it writes every\n   * subscription every tick, recomputes every account's entitlements, and buries a real divergence\n   * in a report where every row is listed.\n   *\n   * Absent and `null` are treated as agreeing: a local row that has never carried a discount and a\n   * provider with no discount are the same state, and distinguishing them would write `null` over\n   * `undefined` on every discount-free subscription in the application.\n   */\n  private valuesAgree(local: unknown, provider: unknown): boolean {\n    if (local === provider) return true;\n    if (local == null && provider == null) return true;\n    if (local == null || provider == null) return false;\n    // A Date on ONE side and a string on the other. This is the branch that earns its place:\n    // two Date INSTANCES are already handled structurally below, but a repository that hands back\n    // an ISO string — a JSON column, a serialising adapter, a cached document — against a provider\n    // `Date` would otherwise compare unequal on every row, forever, and the sweep would rewrite\n    // every subscription on every tick while reporting the whole application as drifted.\n    if (local instanceof Date || provider instanceof Date) {\n      const localTime = new Date(local as string | number | Date).getTime();\n      const providerTime = new Date(provider as string | number | Date).getTime();\n      return Number.isFinite(localTime) && Number.isFinite(providerTime) && localTime === providerTime;\n    }\n    if (typeof local === 'object' && typeof provider === 'object') {\n      return this.stableStringify(local) === this.stableStringify(provider);\n    }\n    return false;\n  }\n\n  /**\n   * Key-order-independent structural comparison for the `discount` object.\n   *\n   * Key order is not a difference: the local row comes back from a document store or a JSONB column\n   * and the provider view is built by an object literal here, so a plain `JSON.stringify` compare\n   * would report drift on ordering alone. `undefined` members are dropped so an absent optional and\n   * an explicitly-undefined one compare equal, which is the same reading `valuesAgree` takes above.\n   */\n  private stableStringify(value: unknown): string {\n    if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined';\n    if (value instanceof Date) return `D${value.getTime()}`;\n    if (Array.isArray(value)) return `[${value.map(entry => this.stableStringify(entry)).join(',')}]`;\n    const entries = Object.entries(value as Record<string, unknown>)\n      .filter(([, entryValue]) => entryValue !== undefined)\n      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n      .map(([key, entryValue]) => `${key}:${this.stableStringify(entryValue)}`);\n    return `{${entries.join(',')}}`;\n  }\n\n  // ════════════════════════════════════════════════════════════\n  // Invoices\n  // ════════════════════════════════════════════════════════════\n\n  private async reconcileInvoicesForScope(\n    variants: BillingResolvedVariants,\n    result: BillingReconciliationResult,\n  ): Promise<void> {\n    const accountsCtx = await this.internalCtx(variants.billingAccount as CoreResourceType, CoreResourceOperation.LIST);\n\n    for (let page = 1; page <= MAX_RECONCILIATION_PAGES; page += 1) {\n      const accounts = await this.servicesRegistry.list<BillingAccount>(\n        variants.billingAccount as CoreResourceType,\n        accountsCtx,\n        {},\n        { page, limit: RECONCILIATION_PAGE_SIZE },\n      ) as BillingAccount[];\n\n      for (const account of accounts) {\n        const providerCustomerId = (account as unknown as Record<string, unknown>).providerCustomerId as string | undefined;\n        if (!providerCustomerId) continue;\n        result.billingAccountsExamined += 1;\n        try {\n          await this.reconcileInvoicesForAccount(variants, account._id, providerCustomerId, result);\n        } catch (error) {\n          result.errors.push(\n            `Invoice reconciliation failed for billing account ${account._id}: ${(error as Error).message}`,\n          );\n        }\n      }\n\n      if (accounts.length < RECONCILIATION_PAGE_SIZE) return;\n    }\n\n    result.errors.push(\n      `Invoice reconciliation stopped after ${MAX_RECONCILIATION_PAGES} pages of billing accounts for scope ` +\n      `${variants.scopeType}. The remaining accounts will be examined by the next tick.`,\n    );\n  }\n\n  private async reconcileInvoicesForAccount(\n    variants: BillingResolvedVariants,\n    billingAccountId: string,\n    providerCustomerId: string,\n    result: BillingReconciliationResult,\n  ): Promise<void> {\n    const providerInvoices = await this.billingProvider!.listInvoices(providerCustomerId, {\n      limit: INVOICE_LOOKBACK_PAGE_SIZE,\n    });\n    if (providerInvoices.length === 0) return;\n\n    const listCtx = await this.internalCtx(variants.invoiceRef as CoreResourceType, CoreResourceOperation.LIST);\n\n    for (const providerInvoice of providerInvoices) {\n      result.invoicesExamined += 1;\n\n      const existing = await this.servicesRegistry.list<InvoiceRef>(\n        variants.invoiceRef as CoreResourceType,\n        listCtx,\n        { providerInvoiceId: providerInvoice.providerInvoiceId },\n        { limit: 1 },\n      ) as InvoiceRef[];\n\n      if (existing.length === 0) {\n        await this.recoverMissingInvoice(variants, billingAccountId, providerInvoice, result);\n        continue;\n      }\n\n      const localInvoice = existing[0];\n      if (localInvoice.status === providerInvoice.status) continue;\n\n      // The ONLY field a sweep updates on an existing invoice. `total` is deliberately excluded, and\n      // stays excluded now that the webhook router reads the same provider `total` this sweep does:\n      // agreement is not a reason for two writers to both write. Re-deriving it here would bump\n      // `updatedAt` and file an audit row for money that did not change, on every tick.\n      const statusUpdate = { status: providerInvoice.status };\n      try {\n        const updateCtx = await this.internalCtx(variants.invoiceRef as CoreResourceType, CoreResourceOperation.UPDATE);\n        await this.servicesRegistry.update(\n          variants.invoiceRef as CoreResourceType,\n          updateCtx,\n          localInvoice._id,\n          statusUpdate,\n          this.trustedWriteOptions(variants.invoiceRef as ResourceType, statusUpdate),\n        );\n        result.invoiceStatusesRepaired += 1;\n        result.errors.push(\n          `DRIFT REPAIRED — invoice ${localInvoice._id} (provider ${providerInvoice.providerInvoiceId}) was recorded ` +\n          `as \"${localInvoice.status}\" and the provider holds \"${providerInvoice.status}\".`,\n        );\n      } catch (error) {\n        result.errors.push(\n          `Failed to correct the status of invoice ${localInvoice._id}: ${(error as Error).message}`,\n        );\n      }\n    }\n  }\n\n  private async recoverMissingInvoice(\n    variants: BillingResolvedVariants,\n    billingAccountId: string,\n    providerInvoice: StandardBilling_InvoiceData,\n    result: BillingReconciliationResult,\n  ): Promise<void> {\n    /*\n     * The scale is the CURRENCY's, exactly as the webhook path resolves it (#515). A zero-decimal\n     * currency recorded at scale 2 stores a hundredth of the real amount; an unresolvable currency\n     * falls back to 2 with a loud line rather than dropping the invoice, because losing the record\n     * of an invoice that exists is worse than recording it at a scale somebody can correct.\n     */\n    const resolvedDecimals = currencyMinorUnitDecimals(providerInvoice.currency.toUpperCase());\n    if (resolvedDecimals === undefined) {\n      result.errors.push(\n        `Recovered invoice ${providerInvoice.providerInvoiceId} at an ASSUMED scale of 2: currency ` +\n        `\"${providerInvoice.currency}\" has no resolvable minor unit.`,\n      );\n    }\n\n    const invoiceData: Record<string, unknown> = {\n      [variants.billingAccountFkField]: billingAccountId,\n      providerInvoiceId: providerInvoice.providerInvoiceId,\n      status: providerInvoice.status,\n      total: {\n        amount: BigInt(Math.trunc(providerInvoice.total)),\n        currency: providerInvoice.currency,\n        decimals: resolvedDecimals ?? 2,\n      },\n      hostedInvoiceUrl: providerInvoice.hostedInvoiceUrl,\n      invoicePdfUrl: providerInvoice.invoicePdfUrl,\n    };\n\n    try {\n      const createCtx = await this.internalCtx(variants.invoiceRef as CoreResourceType, CoreResourceOperation.CREATE);\n      await this.servicesRegistry.create(\n        variants.invoiceRef as CoreResourceType,\n        createCtx,\n        invoiceData,\n        this.trustedWriteOptions(variants.invoiceRef as ResourceType, invoiceData, CoreResourceOperation.CREATE),\n      );\n      result.invoicesRecovered += 1;\n      result.errors.push(\n        `INVOICE RECOVERED — provider invoice ${providerInvoice.providerInvoiceId} for billing account ` +\n        `${billingAccountId} existed at the provider and nowhere locally. Its webhook was never delivered.`,\n      );\n    } catch (error) {\n      result.errors.push(\n        `Failed to record recovered invoice ${providerInvoice.providerInvoiceId}: ${(error as Error).message}`,\n      );\n    }\n  }\n\n  // ════════════════════════════════════════════════════════════\n  // Private — trusted-system write\n  // ════════════════════════════════════════════════════════════\n\n  /**\n   * `ServiceOptions` that re-attach the fields a client-shaped request DTO would strip.\n   *\n   * The same seam the webhook router and the catalog sync use, and it is not optional here: every\n   * period field on a subscription is `.isNotEditable()` and `providerInvoiceId` is\n   * `.isBackendOnly()`, so without the allowlist the write \"succeeds\" and persists nothing — a\n   * repair that silently repairs nothing, which is the worst possible outcome for a sweep whose\n   * whole job is to make local state true.\n   */\n  private trustedWriteOptions(\n    resourceType: ResourceType,\n    payload: Record<string, unknown>,\n    verb: CoreResourceOperation.CREATE | CoreResourceOperation.UPDATE = CoreResourceOperation.UPDATE,\n  ): ServiceOptions {\n    const { mainSchema } = this.resourcesRegistry.getResourceConfiguration(resourceType);\n    return {\n      preserveServerInjectedFields: deriveTrustedSystemWritePreservedFields(\n        mainSchema,\n        Object.keys(payload),\n        verb,\n      ),\n    };\n  }\n}\n\n/**\n * Statuses a reconciliation sweep considers LIVE — everything `TERMINAL_SUBSCRIPTION_STATUSES` does\n * not claim.\n *\n * DERIVED, so the partition is exhaustive by construction and no pin could ever prove it: a member\n * added to the enum lands in the swept half automatically. That default is the right one (a new\n * status is presumed live until someone says otherwise), but it is a default rather than a decision,\n * so the pin beside this asserts the RESULTING MEMBERSHIP literally. Adding an enum member, or\n * moving one across the boundary, reddens it and puts the decision in front of a person — which is\n * the only thing a test can actually contribute here.\n */\nexport const RECONCILED_SUBSCRIPTION_STATUSES: readonly SubscriptionStatus[] =\n  Object.values(SubscriptionStatus).filter(status => !TERMINAL_SUBSCRIPTION_STATUSES.includes(status));\n"]}

package/dist/esm/billing/services/back-office/billing-state.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"billing-state.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/billing/services/back-office/billing-state.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAQL,KAAK,oBAAoB,EAIzB,oBAAoB,EAIrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAE5G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,6FAA6F,CAAC;AACzJ,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AAC3I,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0EAA0E,CAAC;AAChI,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AACnH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iFAAiF,CAAC;AAClI,OAAO,EAAE,6BAA6B,EAAE,MAAM,kFAAkF,CAAC;AACjI,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,gFAAgF,CAAC;AAQlI,qBACa,0BAA2B,SAAQ,6BAA6B;IAOxB,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IACtC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;gBANjD,MAAM,EAAE,aAAa,EACG,gBAAgB,EAAE,qCAAqC,EAChD,uBAAuB,EAAE,qCAAqC,EAC5E,iBAAiB,EAAE,+BAA+B,EACtD,YAAY,EAAE,0BAA0B,EACtB,oBAAoB,EAAE,2BAA2B,EAClD,mBAAmB,EAAE,0BAA0B;IAKlH;;;;;;;;;;;;;OAaG;IACU,QAAQ,CACnB,SAAS,EAAE,oBAAoB,EAC/B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,oBAAoB,EAAE,EACrC,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,oBAAoB,CAAC;YA0ElB,6BAA6B;YAoD7B,kBAAkB;YA4BlB,qBAAqB;YAsBrB,cAAc;YAUd,YAAY;YAUZ,WAAW;YAoBX,cAAc;YA2Bd,eAAe;IAmC7B;;;;;;;;;;OAUG;YACW,mBAAmB;CAuBlC"}
+{"version":3,"file":"billing-state.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/billing/services/back-office/billing-state.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAQL,KAAK,oBAAoB,EAIzB,oBAAoB,EAIrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAE5G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,6FAA6F,CAAC;AACzJ,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AAC3I,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0EAA0E,CAAC;AAChI,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AACnH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iFAAiF,CAAC;AAClI,OAAO,EAAE,6BAA6B,EAAE,MAAM,kFAAkF,CAAC;AACjI,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,gFAAgF,CAAC;AASlI,qBACa,0BAA2B,SAAQ,6BAA6B;IAOxB,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IACtC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;gBANjD,MAAM,EAAE,aAAa,EACG,gBAAgB,EAAE,qCAAqC,EAChD,uBAAuB,EAAE,qCAAqC,EAC5E,iBAAiB,EAAE,+BAA+B,EACtD,YAAY,EAAE,0BAA0B,EACtB,oBAAoB,EAAE,2BAA2B,EAClD,mBAAmB,EAAE,0BAA0B;IAKlH;;;;;;;;;;;;;OAaG;IACU,QAAQ,CACnB,SAAS,EAAE,oBAAoB,EAC/B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,oBAAoB,EAAE,EACrC,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,oBAAoB,CAAC;YAqFlB,6BAA6B;YAoD7B,kBAAkB;YA4BlB,qBAAqB;YAsBrB,cAAc;YAUd,YAAY;YAUZ,WAAW;YAoBX,cAAc;YA2Bd,eAAe;IAmC7B;;;;;;;;;;OAUG;YACW,mBAAmB;CAuBlC"}

package/dist/esm/billing/services/back-office/billing-state.backend.service.js

@@ -25,7 +25,7 @@ import { injectable, inject } from 'inversify';
 import { CoreResourceType, CoreResourceOperation, SubscriptionStatus, ErrorType, ErrorCustomMessageReference, } from '@wildo-ai/saas-models';
 import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
 import { AbstractBillingBackendService } from '../../../billing/services/back-office/abstract-billing.backend.service.js';
-import { resolveBillingVariantsFromScopeType, } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
+import { isProductAcquirable, resolveBillingVariantsFromScopeType, } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
 // ── Service ─────────────────────────────────────────────────────────
 let BillingStateBackendService = class BillingStateBackendService extends AbstractBillingBackendService {
     usageMeteringService;
@@ -91,6 +91,15 @@ let BillingStateBackendService = class BillingStateBackendService extends Abstra
             billingAccountId ? this.getCreditPools(billingAccountId, variants) : {},
         ]);
         const products = allProducts.filter((p) => !p.targetScopes || p.targetScopes.includes(scopeType));
+        // The ACQUISITION half of catalogue retirement. `products` deliberately keeps every
+        // scope-visible row — including retired ones — so a customer already ON a retired plan can
+        // still be shown what they hold; this set is what an acquisition surface offers.
+        //
+        // Derived by `isProductAcquirable`, the SAME predicate `readProductByKey`'s ACQUIRE arm
+        // applies, so a plan this set offers is a plan checkout will accept: the listing cannot drift
+        // from the gate the way a re-derived `p.isActive` filter can. Total over `products` by
+        // construction rather than a second list to keep.
+        const acquirableProductKeys = products.filter(isProductAcquirable).map(product => product.key);
         const activePromotions = await this.getActivePromotions(new Set(products.map(product => product.key)));
         const usage = billingAccountId
             ? await this.getUsageSummary(variants, billingAccountId, subscription)
@@ -104,6 +113,7 @@ let BillingStateBackendService = class BillingStateBackendService extends Abstra
             usage,
             creditPools,
             activePromotions,
+            acquirableProductKeys,
             scopeType,
         };
     }