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

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

@@ -6,7 +6,7 @@
  *
  * Flow:
  * 1. Operation hook calls recordUsage() after successful operation
- * 2. Usage records are stored in DB (reportedToProvider: false)
+ * 2. Usage records are stored in DB (flushState: pending)
  * 3. Periodic flush (cron) aggregates and reports to provider
  * 4. Provider bills at the end of the billing period
  *
@@ -24,16 +24,39 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+var UsageMeteringBackendService_1;
 import { injectable, inject } from 'inversify';
-import { ProductType, SubscriptionStatus, CoreResourceType, CoreResourceOperation, } from '@wildo-ai/saas-models';
+import { createHash } from 'node:crypto';
+import { UsageSourceType, UsageRecordFlushState, UsageRecordUnreportableReason, ProductType, SubscriptionStatus, MeteringAggregationWindow, CoreResourceType, CoreResourceOperation, } from '@wildo-ai/saas-models';
 import { AbstractBillingBackendService } from '../../../billing/services/back-office/abstract-billing.backend.service.js';
-import { BILLING_SCOPE_TO_VARIANTS } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
+import { BILLING_SCOPE_TO_VARIANTS, resolveBillingVariants } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
 import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
 // =====================================================
 // Service
 // =====================================================
 let UsageMeteringBackendService = class UsageMeteringBackendService extends AbstractBillingBackendService {
+    static { UsageMeteringBackendService_1 = this; }
     repositoriesRegistry;
+    /**
+     * How many rows one LIST page fetches while draining the pending set.
+     *
+     * A page size, never a cap: the drain pages until exhausted. It exists because a single query for an
+     * unbounded set is the shape that produced the `limit: 10000` this replaced.
+     */
+    static FLUSH_PAGE_SIZE = 500;
+    /**
+     * The runaway guard, in PAGES. Reaching it aborts the scope and reports nothing — see
+     * `listAllUnreportedRecords` for why a partial flush is worse than none.
+     *
+     * 2,000 pages is a million pending rows. That is not a busy hour, it is a flush that has not run for
+     * a long time, and the right response is a person rather than a bigger number.
+     */
+    static MAX_FLUSH_PAGES = 2_000;
+    /** First retry delay; each subsequent one multiplies by the product's `backoffMultiplier`. */
+    static RETRY_BASE_DELAY_MS = 250;
+    /** Per-run caches, held only for the duration of one `flushToProvider`. `null` means "looked up, absent". */
+    flushProductCache;
+    flushPeriodCache;
     constructor(logger, servicesRegistry, executionContextCreator, resourcesRegistry, errorBuilder, repositoriesRegistry) {
         super(logger, servicesRegistry, executionContextCreator, resourcesRegistry, errorBuilder);
         this.repositoriesRegistry = repositoriesRegistry;
@@ -55,6 +78,15 @@ let UsageMeteringBackendService = class UsageMeteringBackendService extends Abst
      * Stores locally — NOT reported to provider immediately.
      *
      * @param variants — resolved billing polymorphic variants for the target scope
+     * @returns whether a usage row was actually written.
+     *
+     * The return type was `void` until 2026-09-08 (#415), which was harmless only while nothing called
+     * this: the method DECLINES silently when the account holds no active metered subscription, so a
+     * caller could not distinguish "recorded" from "declined". The first real caller then reported the
+     * quantity it had ASKED for whichever happened — an operational counter claiming usage that was
+     * never written, the same shape as the discarded `modifiedCount` this file already fixed once in
+     * the flush. Caught by a pin rather than by a reading, which is the argument for writing the
+     * refusal cases as carefully as the success ones.
      */
     async recordUsage(variants, billingAccountId, productKey, quantity, options) {
         this.logDebug('Recording usage', { billingAccountId, productKey, quantity, scope: variants.scopeType });
@@ -65,7 +97,7 @@ let UsageMeteringBackendService = class UsageMeteringBackendService extends Abst
                 productKey,
                 scope: variants.scopeType,
             });
-            return;
+            return false;
         }
         const ctx = await this.internalCtx(variants.usageRecord, CoreResourceOperation.CREATE);
         await this.servicesRegistry.create(variants.usageRecord, ctx, {
@@ -74,9 +106,109 @@ let UsageMeteringBackendService = class UsageMeteringBackendService extends Abst
             quantity,
             timestamp: new Date(),
             source: options?.source,
-            reportedToProvider: false,
+            flushState: UsageRecordFlushState.PENDING,
             metadata: options?.metadata,
         });
+        return true;
+    }
+    /**
+     * Record usage declared by an OPERATION, resolving the scope, the billing account and the quantity
+     * from the operation's own execution context and result (#415).
+     *
+     * This is the caller `recordUsage` never had. Until it existed, a product could be declared METERED,
+     * priced and synced to the provider while nothing in the framework ever wrote a usage row — the
+     * only way to meter was to reach into this service by hand from a custom implementation, which is a
+     * workaround rather than an authoring surface.
+     *
+     * **Never throws.** It runs after a write has already committed, so a failure here must not turn a
+     * successful operation into an error the caller sees. Every refusal is a warning naming the product
+     * and the reason, because an unrecorded unit is revenue that will not be billed and the log line is
+     * the only thing that will ever say so.
+     *
+     * @returns the quantity recorded, or 0 when nothing was recorded — so a caller can log the outcome
+     *   rather than assume it.
+     */
+    async recordDeclaredOperationUsage(declaration, executionContext, operationResult) {
+        try {
+            const variants = resolveBillingVariants(executionContext);
+            if (!variants) {
+                this.logger.warn('Declared metered usage not recorded: no billing scope on the execution context', {
+                    productKey: declaration.productKey,
+                });
+                return 0;
+            }
+            const quantity = this.resolveDeclaredQuantity(declaration, operationResult);
+            if (quantity === undefined)
+                return 0;
+            // Zero is a legitimate outcome of a result-derived quantity — an export of nothing — and
+            // reporting it would be a meter event carrying no usage.
+            if (quantity === 0)
+                return 0;
+            const billingAccountId = await this.resolveBillingAccountIdForScope(variants, executionContext);
+            if (!billingAccountId) {
+                this.logger.warn('Declared metered usage not recorded: no billing account for this scope', {
+                    productKey: declaration.productKey,
+                    scope: variants.scopeType,
+                });
+                return 0;
+            }
+            // Honour what `recordUsage` REPORTS rather than what was asked for: it declines silently when
+            // the account holds no active metered subscription, and returning the requested quantity there
+            // would make the hook's own log claim usage that was never written.
+            const recorded = await this.recordUsage(variants, billingAccountId, declaration.productKey, quantity, {
+                source: {
+                    // OPERATION, and this declaration is what that member was always for: usage generated by a
+                    // resource operation succeeding, as opposed to a periodic RESOURCE_COUNT or a CUSTOM
+                    // recording an application makes for itself.
+                    type: UsageSourceType.OPERATION,
+                    resourceType: String(executionContext.operation?.resourceIdentifier ?? ''),
+                    operationIdentifier: String(executionContext.operation?.operationIdentifier ?? ''),
+                    description: 'Declared on the operation configuration',
+                },
+            });
+            return recorded ? quantity : 0;
+        }
+        catch (error) {
+            this.logger.error('Failed to record declared metered usage', {
+                productKey: declaration.productKey,
+                message: error.message,
+            });
+            return 0;
+        }
+    }
+    /**
+     * The declared quantity: fixed, or read from the written row.
+     *
+     * A `quantityFromResultField` that does not resolve to a finite non-negative number records NOTHING
+     * and warns, rather than falling back to 1. Silently billing the wrong amount is worse than billing
+     * nothing and saying so — a fallback here would be a wrong number nobody could distinguish from a
+     * right one.
+     */
+    resolveDeclaredQuantity(declaration, operationResult) {
+        if (declaration.quantityFromResultField === undefined) {
+            return declaration.quantity ?? 1;
+        }
+        const raw = declaration.quantityFromResultField
+            .split('.')
+            .reduce((value, segment) => (value !== null && typeof value === 'object' ? value[segment] : undefined), operationResult);
+        if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) {
+            this.logger.warn('Declared metered usage not recorded: quantity field did not resolve to a usable number', {
+                productKey: declaration.productKey,
+                quantityFromResultField: declaration.quantityFromResultField,
+                resolvedType: typeof raw,
+            });
+            return undefined;
+        }
+        return raw;
+    }
+    /** The scope's billing account, addressed by the scope entity rather than by an id the caller supplies. */
+    async resolveBillingAccountIdForScope(variants, executionContext) {
+        const scopeEntityId = executionContext[variants.scopeKey];
+        if (!scopeEntityId)
+            return undefined;
+        const ctx = await this.internalCtx(variants.billingAccount, CoreResourceOperation.LIST);
+        const accounts = await this.servicesRegistry.list(variants.billingAccount, ctx, { [variants.scopeEntityDocField]: scopeEntityId }, { page: 1, limit: 1 });
+        return accounts[0]?._id;
     }
     /**
      * Get usage summary for a billing account.
@@ -95,6 +227,12 @@ let UsageMeteringBackendService = class UsageMeteringBackendService extends Abst
             }),
         };
         const ctx = await this.internalCtx(variants.usageRecord, CoreResourceOperation.LIST);
+        /*
+         * A SUMMARY read, and its cap is honest about being one: `getUsage` answers "roughly how much has
+         * this account used", for a dashboard. It is not the billing path — `flushToProvider` drains the
+         * pending set by paging and never truncates, because money depends on it. Keeping a cap here and
+         * removing it there is the distinction, not an inconsistency.
+         */
         const records = await this.servicesRegistry.list(variants.usageRecord, ctx, filters, { limit: 10000 });
         // Aggregate by product key
         const usage = {};
@@ -112,15 +250,23 @@ let UsageMeteringBackendService = class UsageMeteringBackendService extends Abst
      */
     async flushToProvider() {
         if (!this.billingProvider) {
-            return { totalRecords: 0, reported: 0, failed: 0, errors: ['Provider not initialized'] };
+            return { totalRecords: 0, reported: 0, failed: 0, unreportable: 0, errors: ['Provider not initialized'], quantityRecorded: 0, quantityReported: 0, quantityUnreportable: 0 };
         }
         this.logDebug('Starting usage flush to provider');
         const result = {
             totalRecords: 0,
             reported: 0,
             failed: 0,
+            unreportable: 0,
             errors: [],
+            quantityRecorded: 0,
+            quantityReported: 0,
+            quantityUnreportable: 0,
         };
+        // Per-run caches. A flush touches the same handful of products and subscriptions repeatedly, and
+        // both lookups are needed PER GROUP; without these the policy read alone is one query per group.
+        this.flushProductCache = new Map();
+        this.flushPeriodCache = new Map();
         // Process each billing scope independently — usage records live in per-scope collections
         for (const [scopeKey, scopeData] of Object.entries(BILLING_SCOPE_TO_VARIANTS)) {
             const variants = { scopeKey, ...scopeData };
@@ -131,6 +277,34 @@ let UsageMeteringBackendService = class UsageMeteringBackendService extends Abst
                 result.errors.push(`Flush error for scope ${variants.scopeType}: ${error.message}`);
             }
         }
+        /*
+         * The reconciliation check, stated as an ERROR rather than left to a reader of two numbers.
+         * Anything not reported is money not billed, and the run is the only moment at which the two
+         * quantities are both known.
+         */
+        /*
+         * Unreportable quantity is stated on its OWN line, and always — it is not an anomaly to be
+         * inferred from a mismatch. This is usage a customer generated and will never be billed for,
+         * which somebody may want to write off, invoice out of band, or simply know about. It appears
+         * exactly once per row, on the run that made the determination, because the row leaves the
+         * pending set at the same moment (#512).
+         */
+        if (result.quantityUnreportable > 0) {
+            result.errors.push(`UNREPORTABLE USAGE — ${result.quantityUnreportable} unit(s) across ${result.unreportable} record(s) were ` +
+                `permanently abandoned this run and will never be billed. The per-group lines above name the billing ` +
+                `accounts and the reason. Those rows are now marked unreportable and will not be selected again, so ` +
+                `THIS IS THE ONLY RUN THAT WILL REPORT THEM.`);
+        }
+        const quantityAccountedFor = result.quantityReported + result.quantityUnreportable;
+        if (quantityAccountedFor !== result.quantityRecorded) {
+            const shortfall = result.quantityRecorded - quantityAccountedFor;
+            result.errors.push(`RECONCILIATION MISMATCH — ${result.quantityRecorded} unit(s) of usage were pending, ` +
+                `${result.quantityReported} were reported to the provider and ${result.quantityUnreportable} were ` +
+                `determined unreportable (${shortfall > 0 ? `${shortfall} NEITHER billed nor accounted for` : `${-shortfall} billed in EXCESS`}). ` +
+                `The per-group errors above name which groups; every row left pending stays selectable by the next run.`);
+        }
+        this.flushProductCache = undefined;
+        this.flushPeriodCache = undefined;
         this.logDebug('Usage flush complete', { ...result });
         return result;
     }
@@ -138,83 +312,383 @@ let UsageMeteringBackendService = class UsageMeteringBackendService extends Abst
     // Private — Flush per scope
     // ════════════════════════════════════════════════════════════
     async flushScopeToProvider(variants, result) {
-        // List unreported records from this scope's usage record collection
-        const listCtx = await this.internalCtx(variants.usageRecord, CoreResourceOperation.LIST);
-        const records = await this.servicesRegistry.list(variants.usageRecord, listCtx, { reportedToProvider: false }, { limit: 10000 });
+        const pending = await this.listAllUnreportedRecords(variants, result);
+        if (pending.length === 0)
+            return;
+        const records = await this.selectDueRecords(pending);
         result.totalRecords += records.length;
+        for (const record of records)
+            result.quantityRecorded += record.quantity;
         if (records.length === 0)
             return;
-        // Aggregate by (billingAccountFkField value, productKey)
+        const groups = await this.buildFlushGroups(variants, records);
+        for (const group of groups) {
+            await this.reportGroup(variants, group, result);
+        }
+    }
+    /**
+     * Page through EVERY unreported row in this scope.
+     *
+     * The whole set is read before anything is reported, because aggregation is defined over the whole
+     * pending set and a page is not a meaningful unit of it.
+     *
+     * This replaced a single `{ limit: 10000 }` (#415). That cap did not fail when it was reached — it
+     * returned the first ten thousand rows and the run looked healthy, so the eleven-thousandth unit of
+     * usage was simply never billed and nothing anywhere said so. A cap that is reached is money not
+     * billed; the only honest cap is one that REFUSES.
+     */
+    async listAllUnreportedRecords(variants, result) {
+        const listCtx = await this.internalCtx(variants.usageRecord, CoreResourceOperation.LIST);
+        const collected = [];
+        for (let page = 1; page <= UsageMeteringBackendService_1.MAX_FLUSH_PAGES; page += 1) {
+            const pageRecords = await this.servicesRegistry.list(variants.usageRecord, listCtx, { flushState: UsageRecordFlushState.PENDING }, { page, limit: UsageMeteringBackendService_1.FLUSH_PAGE_SIZE });
+            collected.push(...pageRecords);
+            if (pageRecords.length < UsageMeteringBackendService_1.FLUSH_PAGE_SIZE)
+                return collected;
+        }
+        /*
+         * The runaway guard, and it reports NOTHING rather than reporting what it has. A partial flush
+         * would mark those rows reported and leave the rest for a next run that would hit the same wall,
+         * so the backlog would never drain while every run looked partially successful. Refusing keeps
+         * every row selectable and puts a human in front of the reason.
+         */
+        result.errors.push(`FLUSH ABORTED for scope ${variants.scopeType}: more than ` +
+            `${UsageMeteringBackendService_1.MAX_FLUSH_PAGES * UsageMeteringBackendService_1.FLUSH_PAGE_SIZE} unreported usage rows. ` +
+            `Nothing was reported for this scope — every row remains pending. This is a backlog, not a spike: ` +
+            `investigate why the scheduled flush stopped running before draining it.`);
+        return [];
+    }
+    /**
+     * Keep only the rows whose PRODUCT is due to be flushed, per its authored `flushIntervalMinutes`
+     * (#415).
+     *
+     * The field means "usage for this product should reach the provider within N minutes of being
+     * recorded", so a product is due when its OLDEST pending row has waited that long. Derived from the
+     * rows already in hand — no last-flush timestamp is stored anywhere, because storing one would be a
+     * second source of truth for something the rows already say, and one that can go stale.
+     *
+     * The batch runs on a cadence at least as fast as the shortest interval any product can author; this
+     * is what turns one shared schedule into per-product intervals. A product authoring 1440 accumulates
+     * for a day and produces one provider event instead of 288, which is what its author asked for.
+     *
+     * Note the ASYMMETRY, and it is deliberate: waiting is per product, but once ONE product is due its
+     * rows go now rather than at the next tick. Reporting sooner than authored is never wrong; later is.
+     */
+    async selectDueRecords(records) {
+        const oldestByProduct = new Map();
+        for (const record of records) {
+            const at = (record.timestamp instanceof Date ? record.timestamp : new Date(record.timestamp)).getTime();
+            const seen = oldestByProduct.get(record.productKey);
+            if (seen === undefined || at < seen)
+                oldestByProduct.set(record.productKey, at);
+        }
+        const now = Date.now();
+        const dueProducts = new Set();
+        for (const [productKey, oldest] of oldestByProduct) {
+            const policy = await this.resolveMeteringPolicy(productKey);
+            const intervalMinutes = policy?.flushIntervalMinutes;
+            // No authored policy means no authored patience: flush it on this tick, which is what every
+            // product did before the field was read.
+            if (intervalMinutes === undefined || now - oldest >= intervalMinutes * 60_000) {
+                dueProducts.add(productKey);
+            }
+        }
+        return records.filter((record) => dueProducts.has(record.productKey));
+    }
+    // ════════════════════════════════════════════════════════════
+    // Private — Grouping (the authored metering policy is READ here)
+    // ════════════════════════════════════════════════════════════
+    /**
+     * Turn pending rows into the groups that will each become one provider meter event, honouring the
+     * product's authored `metering` policy (#415).
+     *
+     * Until this existed the policy block was declared, defaulted, documented and read by NOTHING: every
+     * row was merged by (account, product) whatever the product said, so `preFlushAggregation: false`
+     * was unrepresentable and `aggregationWindow` chose between two behaviours that were the same one.
+     * Its own JSDoc said so and asked that the gap stay visible, which is why this comment says what
+     * replaced it.
+     *
+     * The policy is per PRODUCT, so two products flushing in the same run are grouped by their own
+     * rules — that is why the policy is resolved inside the loop rather than once for the run.
+     */
+    async buildFlushGroups(variants, records) {
         const billingAccountFk = variants.billingAccountFkField;
-        const aggregateKey = (r) => `${r[billingAccountFk]}::${r.productKey}`;
-        const aggregated = new Map();
+        const grouped = new Map();
+        const ungrouped = [];
         for (const record of records) {
-            const key = aggregateKey(record);
-            const existing = aggregated.get(key);
+            const billingAccountId = record[billingAccountFk];
+            const timestamp = record.timestamp instanceof Date ? record.timestamp : new Date(record.timestamp);
+            const policy = await this.resolveMeteringPolicy(record.productKey);
+            /*
+             * `preFlushAggregation: false` means exactly what it says: report each row on its own. It is the
+             * shape a product picks when the provider must see every event — because the provider's own
+             * aggregation differs from a sum, or because each event carries a distinct instant. Merging
+             * locally destroys both, irreversibly, before the provider ever sees them.
+             */
+            if (policy?.preFlushAggregation === false) {
+                ungrouped.push({
+                    billingAccountId,
+                    productKey: record.productKey,
+                    quantity: record.quantity,
+                    recordIds: [record._id],
+                    latestTimestamp: timestamp,
+                });
+                continue;
+            }
+            /*
+             * `PER_BILLING_PERIOD` splits a group at a billing-period boundary. It is not a preference: a
+             * merged group carries ONE timestamp, and the provider assigns a meter event to the period that
+             * timestamp falls in — so merging across a boundary bills a whole period's usage into the wrong
+             * period. `PER_FLUSH` merges everything pending, which is right when a product's periods do not
+             * matter to how it is priced.
+             */
+            const periodStart = policy?.aggregationWindow === MeteringAggregationWindow.PER_BILLING_PERIOD
+                ? await this.resolvePeriodStartFor(variants, billingAccountId, record.productKey, timestamp)
+                : undefined;
+            const key = `${billingAccountId}::${record.productKey}::${periodStart?.toISOString() ?? 'all'}`;
+            const existing = grouped.get(key);
             if (existing) {
                 existing.quantity += record.quantity;
                 existing.recordIds.push(record._id);
+                if (timestamp > existing.latestTimestamp)
+                    existing.latestTimestamp = timestamp;
             }
             else {
-                aggregated.set(key, {
-                    billingAccountId: record[billingAccountFk],
+                grouped.set(key, {
+                    billingAccountId,
                     productKey: record.productKey,
                     quantity: record.quantity,
                     recordIds: [record._id],
+                    latestTimestamp: timestamp,
+                    periodStart,
                 });
             }
         }
-        // Report each aggregated group to provider via billing meter events
-        for (const [, group] of aggregated) {
+        return [...grouped.values(), ...ungrouped];
+    }
+    // ════════════════════════════════════════════════════════════
+    // Private — Reporting one group
+    // ════════════════════════════════════════════════════════════
+    async reportGroup(variants, group, result) {
+        try {
+            const { accountExists, providerCustomerId } = await this.resolveProviderCustomer(variants, group.billingAccountId);
+            /*
+             * The billing account is GONE — permanent, and the reason the rows get a terminal state
+             * instead of another failure count (#512). Usage rows are RETAINED when their subject is
+             * erased, so this is a designed outcome rather than corruption; what was not designed was the
+             * flush treating it as retryable, which re-selected the same rows on every five-minute run,
+             * failed identically, and grew an error backlog no operator action could drain.
+             */
+            if (!accountExists) {
+                result.errors.push(`UNREPORTABLE — billing account ${group.billingAccountId} no longer exists (scope: ${variants.scopeType}), so ` +
+                    `${group.quantity} unit(s) of ${group.productKey} usage across ${group.recordIds.length} record(s) can never be ` +
+                    `reported. The rows are RETAINED for the tax/audit obligation and are being marked unreportable so the flush ` +
+                    `stops re-selecting them.`);
+                await this.markGroupUnreportable(variants, group, UsageRecordUnreportableReason.BILLING_ACCOUNT_DELETED, result);
+                return;
+            }
+            /*
+             * The account exists but has no provider customer yet — TRANSIENT. Provisioning may still
+             * complete, so the rows stay pending and this stays a failure. Do not be tempted to reuse the
+             * terminal state here: it would abandon billable usage the moment a flush overtook an
+             * in-progress customer creation.
+             */
+            if (!providerCustomerId) {
+                result.errors.push(`No provider customer ID for billing account ${group.billingAccountId} (scope: ${variants.scopeType})`);
+                result.failed += group.recordIds.length;
+                return;
+            }
+            const policy = await this.resolveMeteringPolicy(group.productKey);
+            /*
+             * The meterEventName is derived from the product key.
+             * Convention: product key IS the meter event name (configured when creating the meter in Stripe).
+             *
+             * `timestamp` and `identifier` were BOTH omitted until 2026-09-08 (#415), and each omission was
+             * its own defect:
+             *
+             *   - Without a timestamp the provider stamps the event with the moment the FLUSH ran, so usage
+             *     recorded before a period boundary and flushed after it is billed to the wrong period. Every
+             *     metered product was exposed to that, on every run that crossed a boundary.
+             *   - Without an identifier a re-report is a SECOND charge. The whole duplicate-charge apparatus
+             *     below exists because of that, and an identifier is the provider's own answer to it: a meter
+             *     event carrying one that has already been seen is discarded. So a re-report of an identical
+             *     group is now a no-op at the provider rather than money moving twice — which is a far better
+             *     property than detecting the risk after the fact.
+             *
+             * The identifier is DERIVED FROM THE ROWS, not from the attempt, so a retry of the same group
+             * sends the same identifier while a genuinely different group cannot collide with it.
+             */
+            await this.reportWithRetry(policy, {
+                meterEventName: group.productKey,
+                providerCustomerId,
+                value: group.quantity,
+                timestamp: group.latestTimestamp,
+                identifier: this.buildUsageEventIdentifier(variants, group),
+            });
+            // Bulk-mark all records in this group as reported (single DB call).
+            //
+            // The `reportUsage` above ALREADY moved money — it is not retryable-for-free. The marking is
+            // what stops the next sweep from re-reporting the same usage, because the sweep selects on
+            // `flushState: pending`. So a PARTIAL marking is a duplicate-charge condition: any record
+            // that stayed unmarked will be picked up again and billed to the customer a second time.
+            //
+            // Honour `modifiedCount` rather than assuming success. Previously the return value was
+            // discarded and `result.reported` was incremented by the full group size, which made a partial
+            // marking both invisible and unfalsifiable — the operational counter reported success for
+            // records that were about to be re-billed.
+            const markedCount = await this.repositoriesRegistry.bulkUpdateForInfrastructure(variants.usageRecord, { _id: { $in: group.recordIds } }, 
+            // The adapter-neutral guarded-mutation descriptor. This was `{ $set: … }` — raw MongoDB —
+            // until `bulkUpdateForInfrastructure` became adapter-neutral; on a PostgreSQL-backed usage
+            // record the old path threw before marking anything, which is the duplicate-charge
+            // condition the block below exists to detect.
+            { set: { flushState: UsageRecordFlushState.REPORTED, reportedAt: new Date() } });
+            // Reported is reported: the provider has the quantity whatever the marking did.
+            result.quantityReported += group.quantity;
+            const unmarkedCount = group.recordIds.length - markedCount;
+            if (unmarkedCount > 0) {
+                /*
+                 * Still loud, and still not a "retry me" — but no longer a duplicate CHARGE, because the
+                 * identifier above makes the provider discard a repeat of this exact group. What survives is a
+                 * repeat of a DIFFERENT group: the next sweep re-selects the unmarked rows, and if new usage
+                 * has arrived meanwhile it aggregates them together into a group with a different identifier,
+                 * which the provider will accept. So this is still an operator's problem, one step less severe.
+                 */
+                result.errors.push(`PARTIAL MARKING — ${group.billingAccountId}/${group.productKey} (scope: ${variants.scopeType}): ` +
+                    `usage of ${group.quantity} was REPORTED to the provider, but only ${markedCount}/${group.recordIds.length} ` +
+                    `records could be marked as reported. A re-report of this exact group is idempotent at the provider ` +
+                    `(same event identifier), but the next sweep may aggregate the ${unmarkedCount} unmarked record(s) with ` +
+                    `NEW usage into a different group, which would be accepted and double-count them. Mark them manually.`);
+                result.failed += unmarkedCount;
+            }
+            result.reported += markedCount;
+        }
+        catch (error) {
+            result.errors.push(`${group.billingAccountId}/${group.productKey} (scope: ${variants.scopeType}): ${error.message}`);
+            result.failed += group.recordIds.length;
+        }
+    }
+    /**
+     * Report one meter event, honouring the product's authored `retryPolicy` (#415).
+     *
+     * `maxRetries` and `backoffMultiplier` were authored, defaulted and read by nothing — a provider
+     * blip failed the whole group and left it for the next scheduled run, which on a 60-minute schedule
+     * is an hour of unbilled usage for a fault that would have cleared in a second.
+     *
+     * The retry is SAFE only because of the idempotency identifier the caller supplies: a retry after a
+     * response that was lost in transit re-sends the same identifier, and the provider discards it. Retry
+     * without that is how a timeout becomes a double charge, which is why the two landed together.
+     */
+    async reportWithRetry(policy, request) {
+        const maxRetries = Math.max(0, policy?.retryPolicy?.maxRetries ?? 0);
+        const backoffMultiplier = policy?.retryPolicy?.backoffMultiplier ?? 2;
+        let attempt = 0;
+        for (;;) {
             try {
-                // Resolve provider customer ID from billing account
-                const providerCustomerId = await this.resolveProviderCustomerId(variants, group.billingAccountId);
-                if (!providerCustomerId) {
-                    result.errors.push(`No provider customer ID for billing account ${group.billingAccountId} (scope: ${variants.scopeType})`);
-                    result.failed += group.recordIds.length;
-                    continue;
-                }
-                // The meterEventName is derived from the product key
-                // Convention: product key IS the meter event name (configured when creating the meter in Stripe)
-                await this.billingProvider.reportUsage({
-                    meterEventName: group.productKey,
-                    providerCustomerId,
-                    value: group.quantity,
+                await this.billingProvider.reportUsage(request);
+                return;
+            }
+            catch (error) {
+                if (attempt >= maxRetries)
+                    throw error;
+                const delayMs = UsageMeteringBackendService_1.RETRY_BASE_DELAY_MS * Math.pow(backoffMultiplier, attempt);
+                this.logger.warn('Usage report failed, retrying', {
+                    meterEventName: request.meterEventName,
+                    attempt: attempt + 1,
+                    maxRetries,
+                    delayMs,
                 });
-                // Bulk-mark all records in this group as reported (single DB call).
-                //
-                // The `reportUsage` above ALREADY moved money — it is not retryable-for-free. The marking is
-                // what stops the next sweep from re-reporting the same usage, because the sweep selects on
-                // `reportedToProvider: false`. So a PARTIAL marking is a duplicate-charge condition: any record
-                // that stayed unmarked will be picked up again and billed to the customer a second time.
-                //
-                // Honour `modifiedCount` rather than assuming success. Previously the return value was
-                // discarded and `result.reported` was incremented by the full group size, which made a partial
-                // marking both invisible and unfalsifiable — the operational counter reported success for
-                // records that were about to be re-billed.
-                const markedCount = await this.repositoriesRegistry.bulkUpdateForInfrastructure(variants.usageRecord, { _id: { $in: group.recordIds } }, 
-                // The adapter-neutral guarded-mutation descriptor. This was `{ $set: … }` — raw MongoDB —
-                // until `bulkUpdateForInfrastructure` became adapter-neutral; on a PostgreSQL-backed usage
-                // record the old path threw before marking anything, which is the duplicate-charge
-                // condition the block below exists to detect.
-                { set: { reportedToProvider: true, reportedAt: new Date() } });
-                const unmarkedCount = group.recordIds.length - markedCount;
-                if (unmarkedCount > 0) {
-                    // Loud + specific: usage is already reported to the provider, so this is NOT a "retry me"
-                    // error — re-running the sweep is precisely what would double-charge.
-                    result.errors.push(`DUPLICATE-CHARGE RISK — ${group.billingAccountId}/${group.productKey} (scope: ${variants.scopeType}): ` +
-                        `usage of ${group.quantity} was REPORTED to the provider, but only ${markedCount}/${group.recordIds.length} ` +
-                        `records could be marked as reported. The ${unmarkedCount} unmarked record(s) remain selectable by the next ` +
-                        `sweep and would be billed AGAIN. Investigate before the next run; mark them manually if the report succeeded.`);
-                    result.failed += unmarkedCount;
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+                attempt += 1;
+            }
+        }
+    }
+    /**
+     * A stable, bounded idempotency key for one meter event.
+     *
+     * Derived from the ROWS the event carries — sorted, so ordering cannot change it — and hashed, so a
+     * group of ten thousand rows produces the same short key as a group of one. Two different groups
+     * cannot collide; the same group retried, or re-reported after a partial marking, produces the same
+     * key and the provider discards the repeat.
+     */
+    buildUsageEventIdentifier(variants, group) {
+        const material = [
+            variants.scopeType,
+            group.billingAccountId,
+            group.productKey,
+            ...[...group.recordIds].sort(),
+        ].join('|');
+        return `wildo-usage-${createHash('sha256').update(material).digest('hex').slice(0, 32)}`;
+    }
+    // ════════════════════════════════════════════════════════════
+    // Private — Policy and period resolution (per-run cached)
+    // ════════════════════════════════════════════════════════════
+    /** The product's authored metering policy, or `undefined` when it authored none. */
+    async resolveMeteringPolicy(productKey) {
+        const cached = this.flushProductCache?.get(productKey);
+        if (cached !== undefined)
+            return cached ?? undefined;
+        const ctx = await this.internalCtx(CoreResourceType.PRODUCTS, CoreResourceOperation.LIST);
+        let policy;
+        try {
+            const products = await this.servicesRegistry.list(CoreResourceType.PRODUCTS, ctx, { key: productKey }, { page: 1, limit: 1 });
+            policy = products[0]?.behaviorPolicy?.metering;
+        }
+        catch (error) {
+            // A policy that cannot be read is not a reason to stop billing: fall through to the merged
+            // default, which is what every product got before the policy was read at all.
+            this.logger.warn('Failed to read metering policy; flushing this product with default aggregation', {
+                productKey,
+                message: error.message,
+            });
+        }
+        this.flushProductCache?.set(productKey, policy ?? null);
+        return policy;
+    }
+    /**
+     * The start of the billing period containing `timestamp`, for `PER_BILLING_PERIOD` grouping.
+     *
+     * Derived from the subscription's own `currentPeriodStart` / `currentPeriodEnd` — real data, not a
+     * calendar rule invented here — stepping backwards by the period's own length for usage older than
+     * the current period. Returns `undefined` when no subscription can be resolved, which merges the
+     * rows exactly as `PER_FLUSH` would: an unknown boundary must not silently invent one.
+     */
+    async resolvePeriodStartFor(variants, billingAccountId, productKey, timestamp) {
+        const cacheKey = `${variants.scopeType}::${billingAccountId}`;
+        let boundaries = this.flushPeriodCache?.get(cacheKey);
+        if (boundaries === undefined) {
+            boundaries = null;
+            const ctx = await this.internalCtx(variants.subscription, CoreResourceOperation.LIST);
+            try {
+                const subscriptions = await this.servicesRegistry.list(variants.subscription, ctx, {
+                    [variants.billingAccountFkField]: billingAccountId,
+                    status: { $in: [SubscriptionStatus.ACTIVE, SubscriptionStatus.TRIALING] },
+                });
+                const subscription = subscriptions[0];
+                if (subscription?.currentPeriodStart && subscription?.currentPeriodEnd) {
+                    boundaries = {
+                        start: new Date(subscription.currentPeriodStart),
+                        end: new Date(subscription.currentPeriodEnd),
+                    };
                 }
-                result.reported += markedCount;
             }
             catch (error) {
-                result.errors.push(`${group.billingAccountId}/${group.productKey} (scope: ${variants.scopeType}): ${error.message}`);
-                result.failed += group.recordIds.length;
+                this.logger.warn('Failed to resolve billing period for per-period aggregation; merging as PER_FLUSH', {
+                    billingAccountId, productKey, message: error.message,
+                });
             }
+            this.flushPeriodCache?.set(cacheKey, boundaries);
         }
+        if (!boundaries)
+            return undefined;
+        const periodLengthMs = boundaries.end.getTime() - boundaries.start.getTime();
+        if (periodLengthMs <= 0)
+            return boundaries.start;
+        // Step backwards whole periods until the timestamp is inside one. Usage newer than the current
+        // period end belongs to the current period — the subscription simply has not rolled over yet.
+        let start = boundaries.start.getTime();
+        while (timestamp.getTime() < start)
+            start -= periodLengthMs;
+        return new Date(start);
     }
     // ════════════════════════════════════════════════════════════
     // Private — Resolution
@@ -258,19 +732,74 @@ let UsageMeteringBackendService = class UsageMeteringBackendService extends Abst
         }
         return false;
     }
-    async resolveProviderCustomerId(variants, billingAccountId) {
+    /**
+     * Resolve the provider customer for a billing account, distinguishing the two ways it can fail.
+     *
+     * This used to return `string | null`, and that single `null` fused a PERMANENT condition with a
+     * TRANSIENT one (#512):
+     *
+     * - the account row is GONE — legitimately reachable, because usage rows are RETAINED when their
+     *   subject is erased, so a deleted account leaves rows behind. Nothing will ever restore the
+     *   mapping, and a flush that keeps retrying is building a backlog it cannot drain;
+     * - the account EXISTS but carries no `providerCustomerId` yet — provisioning may still complete,
+     *   and abandoning those rows would throw away billable usage.
+     *
+     * They lead to opposite actions, so the caller must be able to tell them apart. Two plain fields
+     * rather than a discriminated union deliberately: `engine/tsconfig.common.json` sets
+     * `strict: false`, under which narrowing a union on a boolean-literal discriminant does not work,
+     * and a caller that cannot narrow reads the wrong field with no diagnostic.
+     *
+     * A read that THROWS is treated as transient — `degradeOrRethrow` has already decided the error is
+     * survivable, and a storage failure says nothing about whether the row exists.
+     */
+    async resolveProviderCustomer(variants, billingAccountId) {
         const readCtx = await this.internalCtx(variants.billingAccount, CoreResourceOperation.READ);
         try {
             const billingAccount = await this.servicesRegistry.read(variants.billingAccount, readCtx, billingAccountId);
-            return billingAccount?.providerCustomerId ?? null;
+            if (!billingAccount)
+                return { accountExists: false, providerCustomerId: null };
+            return { accountExists: true, providerCustomerId: billingAccount.providerCustomerId ?? null };
         }
         catch (error) {
             this.degradeOrRethrow(error, 'Failed to resolve provider customer ID', { billingAccountId, scope: variants.scopeType });
         }
-        return null;
+        return { accountExists: true, providerCustomerId: null };
+    }
+    /**
+     * Move a group's rows to the terminal `unreportable` state so the flush stops re-selecting them.
+     *
+     * NO money moved and none ever will, which is why this is its own state rather than a convenient
+     * `reported: true`. The reason and the instant are written beside it, because the row is a
+     * RETAINED financial record and the next reader of it — an auditor, an operator reconciling a
+     * period — needs to know why a measured quantity was never billed.
+     *
+     * A marking that does not fully land is reported and NOT retried here: the rows that stayed
+     * pending are simply selected again next run, which is harmless (unlike the reported case, where
+     * a partial marking risks double-billing). The counters follow what the write actually did.
+     */
+    async markGroupUnreportable(variants, group, reason, result) {
+        const markedCount = await this.repositoriesRegistry.bulkUpdateForInfrastructure(variants.usageRecord, { _id: { $in: group.recordIds } }, { set: { flushState: UsageRecordFlushState.UNREPORTABLE, unreportableReason: reason, unreportableAt: new Date() } });
+        result.unreportable += markedCount;
+        result.quantityUnreportable += markedCount === group.recordIds.length
+            ? group.quantity
+            : 0;
+        const unmarkedCount = group.recordIds.length - markedCount;
+        if (unmarkedCount > 0) {
+            /*
+             * The quantity is credited only on a COMPLETE marking, above. A group's quantity is an
+             * aggregate over its rows and this class does not carry per-row quantities into the group, so
+             * a partial marking cannot be apportioned — and guessing would corrupt the reconciliation
+             * identity in the direction that hides unbilled usage. The rows that stayed pending will be
+             * re-selected, re-grouped and accounted for then.
+             */
+            result.errors.push(`PARTIAL UNREPORTABLE MARKING — ${group.billingAccountId}/${group.productKey} (scope: ${variants.scopeType}): ` +
+                `only ${markedCount}/${group.recordIds.length} record(s) could be marked unreportable. The ${unmarkedCount} ` +
+                `unmarked record(s) stay pending and will be re-selected next run; no usage was reported to the provider.`);
+            result.failed += unmarkedCount;
+        }
     }
 };
-UsageMeteringBackendService = __decorate([
+UsageMeteringBackendService = UsageMeteringBackendService_1 = __decorate([
     injectable(),
     __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
     __param(1, inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService)),