@billfn/core 0.2.0 → 0.4.0

package/dist/service.js

@@ -1,7 +1,9 @@
+import { createHash } from 'node:crypto';
 import { DuplicateKeyError } from '@superfunctions/db';
 import { ok } from '@superfunctions/envelope';
 import { createNamespacedEmitter, createMetricsEmitter } from '@superfunctions/metrics';
 import { createBillFnError } from './errors.js';
+import { applyGrants, insertGrant, listRepairedGrants, readCreateGrantInput, repairGrantEvents, requireFutureExpiry, revokeGrant, toGrantSummary } from './grants.js';
 import { createDefaultBillingAccountResolver, defaultIdFactory, resolvePlan, resolvePrice, toIsoString } from './helpers.js';
 const TABLES = {
     billingAccounts: 'billingAccounts',
@@ -33,6 +35,23 @@ const UNLINKED_WEBHOOK_EVENT_REPLAY_LEASE_MS = 15 * 60 * 1000;
 const UNLINKED_WEBHOOK_EVENT_REPLAY_MAX_EVENTS = 500;
 /** Provider metadata key naming the billing account that owns a provider record. */
 const BILLING_ACCOUNT_METADATA_KEY = 'billfn_billing_account_id';
+/**
+ * Subscription metadata key set when an operator imported the subscription:
+ * when it was first imported. Its binding to the billing account is the
+ * operator's, so a provider adapter does not expect the BillFn ownership
+ * metadata a subscription created outside BillFn lacks.
+ */
+export const BILLFN_IMPORTED_AT_METADATA_KEY = 'billfnImportedAt';
+/**
+ * Subscription metadata key set on the row an import creates until its
+ * binding is accepted (`settleImportBinding`). A pending row is not usable:
+ * webhooks and replays leave events for it unlinked, other writes refuse it
+ * (retryably) and subject, account and sync lookups skip it. A refusal deletes
+ * it, on the import's first run or on any rerun, so it never becomes durable.
+ */
+export const BILLFN_IMPORT_PENDING_METADATA_KEY = 'billfnImportPending';
+/** `details.reason` of the retryable `BILLFN_CONFLICT` an import raises when its replay did not finish. */
+export const BILLFN_IMPORT_REPLAY_UNFINISHED_REASON = 'import_replay_unfinished';
 /** Deliveries of one queue message refused by lease conflicts before it is dead-lettered. */
 const RECONCILIATION_QUEUE_MAX_LEASE_CONFLICT_ATTEMPTS = 5;
 /**
@@ -78,6 +97,34 @@ function createBillFnServiceWithInternals(config) {
         queue: config.queue
     };
     deps.reconcileProviderState = (subscription, event) => reconcileWindowEvent(subscription, event);
+    const grantDeps = {
+        ...deps,
+        recordBillingEvent: (event, db) => recordBillingEvent(db ? { ...deps, db } : deps, event),
+        isDuplicateRecordError
+    };
+    /**
+     * The account's entitlements: its paid snapshot, or an active grant while that snapshot is `inactive`, and the
+     * grants they were derived from. The grants' missing events are repaired on every read (see
+     * `repairGrantEvents`). While the paid snapshot decides and the grants are not asked for, that repair is all
+     * that reads them, and it never fails the read; otherwise their status is derived after the paid snapshot read
+     * and the repair (see `listRepairedGrants`).
+     */
+    async function readEntitlements(billingAccountId, withGrantList = false) {
+        const paid = await findEntitlementSnapshot(deps, billingAccountId);
+        if (!withGrantList && paid && paid.status !== 'inactive') {
+            await repairGrantEvents(grantDeps, billingAccountId);
+            return { entitlements: paid, grants: [] };
+        }
+        const grants = await listRepairedGrants(grantDeps, billingAccountId);
+        return { entitlements: await applyGrants(grantDeps, billingAccountId, paid, grants), grants };
+    }
+    async function findEffectiveEntitlements(billingAccountId) {
+        return (await readEntitlements(billingAccountId)).entitlements;
+    }
+    /** A write's paid snapshot as the account's entitlements (see `applyGrants`). */
+    async function withGrants(billingAccountId, paid) {
+        return (await applyGrants(grantDeps, billingAccountId, paid)) ?? paid;
+    }
     const subscriptionProvider = {
         getActiveSubscription: async (subject) => {
             const billingAccount = await findBillingAccountForSubject(deps, requireSubject(subject));
@@ -91,7 +138,7 @@ function createBillFnServiceWithInternals(config) {
             if (!billingAccount) {
                 return null;
             }
-            return findEntitlementSnapshot(deps, billingAccount.id);
+            return findEffectiveEntitlements(billingAccount.id);
         },
         isActive: async (subject) => {
             const snapshot = await subscriptionProvider.getEntitlementSnapshot(subject);
@@ -112,8 +159,10 @@ function createBillFnServiceWithInternals(config) {
                 tenantId: input.tenantId
             };
             const resource = input.resource ?? 'storage';
-            const entitlements = await subscriptionProvider.getEntitlementSnapshot(subject);
-            if (!entitlements || entitlements.status === 'inactive') {
+            // Status and limit come from one entitlements read, so a grant ending between reads cannot mix them.
+            const billingAccount = await findBillingAccountForSubject(deps, requireSubject(subject));
+            const entitlements = billingAccount ? await findEffectiveEntitlements(billingAccount.id) : null;
+            if (!billingAccount || !entitlements || entitlements.status === 'inactive') {
                 return {
                     allowed: false,
                     current: 0,
@@ -121,19 +170,20 @@ function createBillFnServiceWithInternals(config) {
                     reason: 'subscription_inactive'
                 };
             }
-            const usage = await quotaProvider.getUsage(input.principalId, input.tenantId, resource);
-            const limit = usage.limit;
-            if (limit >= 0 && usage.current + input.requestedBytes > limit) {
+            const meter = await findUsageMeter(deps, billingAccount.id, resource);
+            const current = meter?.current ?? 0;
+            const limit = entitlements.limits[resource] ?? 0;
+            if (limit >= 0 && current + input.requestedBytes > limit) {
                 return {
                     allowed: false,
-                    current: usage.current,
+                    current,
                     limit,
                     reason: 'quota_exceeded'
                 };
             }
             return {
                 allowed: true,
-                current: usage.current,
+                current,
                 limit
             };
         },
@@ -152,7 +202,7 @@ function createBillFnServiceWithInternals(config) {
             };
             const billingAccount = await findBillingAccountForSubject(deps, requireSubject(subject));
             const meter = billingAccount ? await findUsageMeter(deps, billingAccount.id, resource) : null;
-            const entitlements = billingAccount ? await findEntitlementSnapshot(deps, billingAccount.id) : null;
+            const entitlements = billingAccount ? await findEffectiveEntitlements(billingAccount.id) : null;
             return {
                 current: meter?.current ?? 0,
                 limit: entitlements?.limits[resource] ?? 0
@@ -315,7 +365,7 @@ function createBillFnServiceWithInternals(config) {
         });
         return {
             subscription: projection.subscription,
-            entitlements: projection.entitlements,
+            entitlements: await withGrants(billingAccount.id, projection.entitlements),
             operationStatus: operation.operationStatus,
             clientAction: operation.clientAction
         };
@@ -595,7 +645,7 @@ function createBillFnServiceWithInternals(config) {
             return ok({
                 checkoutSession: result.checkoutSession,
                 subscription: result.subscription,
-                entitlements: result.entitlements
+                entitlements: await withGrants(billingAccount.id, result.entitlements)
             });
         },
         async cancelSubscription(input) {
@@ -791,7 +841,7 @@ function createBillFnServiceWithInternals(config) {
             return ok({
                 refund,
                 subscription: projectedSubscription,
-                entitlements: projectedEntitlements,
+                entitlements: await applyGrants(grantDeps, billingAccount.id, projectedEntitlements),
                 operationStatus: operation.operationStatus,
                 clientAction: operation.clientAction
             });
@@ -809,7 +859,7 @@ function createBillFnServiceWithInternals(config) {
             const applied = await syncSubscriptionById(subscription.id);
             const response = {
                 subscription: applied.subscription,
-                entitlements: applied.entitlements
+                entitlements: await withGrants(billingAccount.id, applied.entitlements)
             };
             return ok(response);
         },
@@ -869,7 +919,7 @@ function createBillFnServiceWithInternals(config) {
                     });
                     const response = {
                         subscription: applied.subscription,
-                        entitlements: applied.entitlements
+                        entitlements: await withGrants(billingAccount.id, applied.entitlements)
                     };
                     return ok(response);
                 }
@@ -887,7 +937,7 @@ function createBillFnServiceWithInternals(config) {
                 });
                 const response = {
                     subscription: applied.subscription,
-                    entitlements: applied.entitlements
+                    entitlements: await withGrants(billingAccount.id, applied.entitlements)
                 };
                 return ok(response);
             }
@@ -896,6 +946,155 @@ function createBillFnServiceWithInternals(config) {
                 message: 'No restored purchase could be linked to the resolved billing account'
             });
         },
+        async importSubscription(input) {
+            const { provider: providerName, reference, operator } = readImportRequest(input);
+            const plan = requirePlan(deps.catalog, input.planKey);
+            if (!plan.prices.some((price) => price.provider === providerName && price.kind === 'subscription')) {
+                throw createBillFnError({
+                    code: 'BILLFN_VALIDATION_ERROR',
+                    message: `Plan ${plan.planKey} has no ${providerName} subscription price`
+                });
+            }
+            const provider = requireProvider(deps, providerName, 'importSubscription');
+            // A reference replaced by a subscription write, or bound to another billing account, fails before the provider is read.
+            // A pending row (an import not yet accepted, perhaps interrupted) is checked like an unbound reference and
+            // removed when the reference is retired, so a rerun of a refused import converges to no binding.
+            const bound = await findSubscriptionByProviderRef(deps, providerName, reference);
+            if (!bound || isImportPending(bound)) {
+                await refuseRetiredImportReference(deps, providerName, reference, bound);
+            }
+            if (bound && bound.billingAccountId !== input.billingAccountId) {
+                throw importBoundElsewhere(providerName);
+            }
+            // Resolved after the checks above, so an import they refuse never creates the subject's billing account;
+            // one refused after the provider read keeps it.
+            const billingAccount = await resolveOperatorBillingAccount(deps, input);
+            // Events that occurred before this live read are already reflected in its state.
+            const importObservedAt = toIsoString(deps.now());
+            const state = await readImportState(provider, providerName, { providerReference: reference, billingAccount, plan });
+            if (!state) {
+                throw createBillFnError({
+                    code: 'BILLFN_NOT_FOUND',
+                    message: 'Provider did not return the subscription to import'
+                });
+            }
+            if (state.providerSubscriptionId !== reference) {
+                throw createBillFnError({
+                    code: 'BILLFN_PROVIDER_ERROR',
+                    message: 'The provider record does not match the imported reference'
+                });
+            }
+            const selection = requireImportPrice(plan, providerName, state);
+            // One audit event per import run and state it records, never changed once written. The run is the operator's
+            // request (a rerun of it that records a state it already recorded adds none, even after another state) or,
+            // without a requestId, this call. The state is every field the event shows and whether the row carries the
+            // import marker (not its value, which a rerun that adds it sets to its own read time).
+            const run = operator.requestId ? ['request', operator.requestId] : ['call', deps.generateId('run')];
+            const importAudit = (subscription) => ({
+                id: `evt_import_${createHash('sha256')
+                    .update(JSON.stringify([
+                    providerName,
+                    reference,
+                    billingAccount.id,
+                    operator.id,
+                    operator.type ?? null,
+                    ...run,
+                    plan.planKey,
+                    input.reason ?? null,
+                    subscription.id,
+                    subscription.planKey,
+                    subscription.priceId,
+                    subscription.status,
+                    subscription.currentPeriodStart ?? null,
+                    subscription.currentPeriodEnd ?? null,
+                    subscription.autoRenew,
+                    subscription.metadata?.[BILLFN_IMPORTED_AT_METADATA_KEY] !== undefined
+                ]))
+                    .digest('base64url')}`,
+                billingAccountId: billingAccount.id,
+                type: 'billfn.subscription.imported',
+                payload: {
+                    subscriptionId: subscription.id,
+                    provider: providerName,
+                    providerReference: reference,
+                    planKey: subscription.planKey,
+                    priceId: subscription.priceId,
+                    status: subscription.status,
+                    currentPeriodStart: subscription.currentPeriodStart ?? null,
+                    currentPeriodEnd: subscription.currentPeriodEnd ?? null,
+                    autoRenew: subscription.autoRenew,
+                    operator,
+                    ...(input.reason ? { reason: input.reason } : {})
+                },
+                createdAt: toIsoString(deps.now())
+            });
+            let applied;
+            try {
+                // Racing imports end with one row: the loser of the unique reference insert applies an ordered update,
+                // or fails as bound elsewhere when the winner bound another billing account.
+                applied = await applyVerificationState(deps, {
+                    billingAccount,
+                    plan: selection.plan,
+                    price: selection.price,
+                    state,
+                    liveStateObservedAt: importObservedAt,
+                    // A rerun or a racing import keeps the first import's time.
+                    metadataDefaults: { [BILLFN_IMPORTED_AT_METADATA_KEY]: importObservedAt },
+                    // A write may retire the reference while the provider is read (the check above ran before the read).
+                    importReference: reference,
+                    importAudit
+                });
+            }
+            catch (error) {
+                if (hasErrorCode(error, 'BILLFN_CONFLICT') && (await isBoundElsewhere(deps, providerName, state, billingAccount.id))) {
+                    throw importBoundElsewhere(providerName);
+                }
+                throw error;
+            }
+            // Each write that left the row usable recorded its state's audit first. A run that wrote nothing (a read an
+            // event superseded, or another run's accepted row) records the state it applied here, before the replay
+            // changes anything, so a replay that does not finish still leaves this operator's event.
+            await recordBillingEvent(deps, importAudit(applied.subscription));
+            // A replay that does not finish fails the import; calling it again finishes the replay.
+            try {
+                await replayUnlinkedWebhookEventsOrThrow(deps, applied.subscription);
+            }
+            catch (error) {
+                if (isReconciliationLeaseConflict(error)) {
+                    throw importReplayUnfinished();
+                }
+                throw error;
+            }
+            const refreshed = await refreshProjectionAfterReplay(deps, applied);
+            // The event returned is the one for the state returned (after the replay), recorded here when the replay
+            // changed it. The first write wins, so a rerun returns it as recorded.
+            const recorded = importAudit(refreshed.subscription);
+            await recordBillingEvent(deps, recorded);
+            const billingEvent = (await deps.db.findOne({
+                model: TABLES.billingEvents,
+                where: [{ field: 'id', operator: 'eq', value: recorded.id }],
+                namespace: deps.namespace
+            })) ?? recorded;
+            deps.metrics.track('subscription.imported', { provider: providerName });
+            return ok({
+                subscription: refreshed.subscription,
+                entitlements: await withGrants(refreshed.subscription.billingAccountId, refreshed.entitlements),
+                billingEvent
+            });
+        },
+        async createGrant(input) {
+            const grantInput = readCreateGrantInput(grantDeps, input);
+            // Before the expiry check, so a refused request still records events an interrupted call left unrecorded.
+            await repairGrantEvents(grantDeps, input.billingAccountId);
+            requireFutureExpiry(grantDeps, grantInput);
+            const billingAccount = await resolveOperatorBillingAccount(deps, input);
+            const grant = await insertGrant(grantDeps, billingAccount.id, grantInput);
+            return ok({ grant, entitlements: await findEffectiveEntitlements(billingAccount.id) });
+        },
+        async revokeGrant(input) {
+            const grant = await revokeGrant(grantDeps, input);
+            return ok({ grant, entitlements: await findEffectiveEntitlements(grant.billingAccountId) });
+        },
         async getEntitlements(subject) {
             const resolved = await resolveBillingAccountReference(deps, requireSubject(subject));
             const billingAccount = await getBillingAccountById(deps, resolved.billingAccountId);
@@ -903,22 +1102,24 @@ function createBillFnServiceWithInternals(config) {
                 return ok({
                     billingAccount: buildVirtualBillingAccount(resolved, deps),
                     entitlements: null,
-                    subscription: null
+                    subscription: null,
+                    grants: []
                 });
             }
-            const entitlements = await findEntitlementSnapshot(deps, billingAccount.id);
+            const { entitlements, grants } = await readEntitlements(billingAccount.id, true);
             const subscription = await findActiveSubscription(deps, billingAccount.id);
             const response = {
                 billingAccount,
                 entitlements,
-                subscription
+                subscription,
+                grants: grants.map(toGrantSummary)
             };
             return ok(response);
         },
         async getUsage(subject, resource) {
             const resolved = await resolveBillingAccountReference(deps, requireSubject(subject));
             const billingAccount = await getBillingAccountById(deps, resolved.billingAccountId);
-            const entitlements = billingAccount ? await findEntitlementSnapshot(deps, billingAccount.id) : null;
+            const entitlements = billingAccount ? await findEffectiveEntitlements(billingAccount.id) : null;
             const meters = billingAccount
                 ? resource
                     ? await findUsageMeters(deps, billingAccount.id, resource)
@@ -1427,7 +1628,7 @@ async function processReconciliationJob(deps, job, assertLease) {
 }
 async function syncSubscriptionByIdForJob(deps, subscriptionId, assertLease, candidatePriceId) {
     const subscription = await getSubscriptionById(deps, subscriptionId);
-    if (!subscription) {
+    if (!subscription || isImportPending(subscription)) {
         return;
     }
     const billingAccount = await getBillingAccountById(deps, subscription.billingAccountId);
@@ -1623,6 +1824,287 @@ function requireProvider(deps, providerName, capability) {
     }
     return provider;
 }
+function readImportRequest(input) {
+    const invalid = (message) => createBillFnError({ code: 'BILLFN_VALIDATION_ERROR', message });
+    const optionalReference = (value, name) => {
+        if (value === undefined) {
+            return undefined;
+        }
+        if (typeof value !== 'string' || value.trim().length === 0 || value !== value.trim()) {
+            throw invalid(`${name} must be a non-empty string without surrounding whitespace`);
+        }
+        return value;
+    };
+    const providerSubscriptionId = optionalReference(input.providerSubscriptionId, 'providerSubscriptionId');
+    const originalTransactionId = optionalReference(input.originalTransactionId, 'originalTransactionId');
+    if (originalTransactionId !== undefined && input.provider !== 'apple') {
+        throw invalid('originalTransactionId identifies Apple subscriptions only');
+    }
+    if (providerSubscriptionId !== undefined && originalTransactionId !== undefined && providerSubscriptionId !== originalTransactionId) {
+        throw invalid('providerSubscriptionId and originalTransactionId name different subscriptions');
+    }
+    const reference = providerSubscriptionId ?? originalTransactionId;
+    if (reference === undefined) {
+        throw invalid('Importing a subscription requires providerSubscriptionId or originalTransactionId');
+    }
+    if (typeof input.billingAccountId !== 'string' || input.billingAccountId.length === 0) {
+        throw invalid('billingAccountId must be a non-empty string');
+    }
+    if (typeof input.planKey !== 'string' || input.planKey.length === 0) {
+        throw invalid('planKey must be a non-empty string');
+    }
+    const operator = input.operator;
+    if (!operator || typeof operator.id !== 'string' || operator.id.length === 0) {
+        throw invalid('Importing a subscription requires the operator identity');
+    }
+    if (input.reason !== undefined && typeof input.reason !== 'string') {
+        throw invalid('reason must be a string');
+    }
+    return {
+        provider: input.provider,
+        reference,
+        operator: {
+            id: operator.id,
+            ...(typeof operator.type === 'string' ? { type: operator.type } : {}),
+            ...(typeof operator.requestId === 'string' ? { requestId: operator.requestId } : {})
+        }
+    };
+}
+/**
+ * Reads the provider record to import. A BillFn error from the adapter keeps its classification; any other failure
+ * (the provider was not reached, or the adapter failed without classifying it) is a retryable provider error whose
+ * message names only the provider, so no raw error text reaches the operator.
+ */
+async function readImportState(provider, providerName, input) {
+    try {
+        return await provider.importSubscription(input);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (typeof code === 'string' && code.startsWith('BILLFN_')) {
+            throw error;
+        }
+        throw createBillFnError({
+            code: 'BILLFN_PROVIDER_ERROR',
+            message: `Provider ${providerName} could not be read for the imported subscription`
+        });
+    }
+}
+/** The billing account an import or grant binds to: created for the subject when one is given, otherwise existing. */
+async function resolveOperatorBillingAccount(deps, input) {
+    if (input.subject) {
+        const subject = requireSubject(input.subject);
+        const resolved = await resolveBillingAccountReference(deps, subject);
+        if (resolved.billingAccountId !== input.billingAccountId) {
+            throw createBillFnError({
+                code: 'BILLFN_VALIDATION_ERROR',
+                message: 'The subject resolves to a different billing account'
+            });
+        }
+        return (await getOrCreateBillingAccount(deps, subject)).billingAccount;
+    }
+    const billingAccount = await getBillingAccountById(deps, input.billingAccountId);
+    if (!billingAccount) {
+        throw createBillFnError({
+            code: 'BILLFN_NOT_FOUND',
+            message: 'Billing account not found'
+        });
+    }
+    return billingAccount;
+}
+/**
+ * The plan's subscription price the provider record's product names. Every reference (the adapter's
+ * `providerProductId`, then the record's `product_id`/`productId`) is a provider product id here, so it is matched
+ * only against `providerProductId`, never against a catalog `priceId` another plan's product could equal.
+ */
+function requireImportPrice(plan, provider, state) {
+    const raw = asRecord(state.raw);
+    const records = [raw, asRecord(raw?.transaction)];
+    const references = [
+        state.providerProductId,
+        ...records.flatMap((record) => (record ? ['product_id', 'productId'].map((key) => readString(record, key)) : []))
+    ].filter((reference) => Boolean(reference));
+    const prices = plan.prices.filter((price) => price.provider === provider && price.kind === 'subscription');
+    for (const reference of references) {
+        const price = prices.find((candidate) => candidate.providerProductId === reference);
+        if (price) {
+            return { plan, price };
+        }
+    }
+    throw createBillFnError({
+        code: 'BILLFN_VALIDATION_ERROR',
+        message: `The provider subscription's product is not a ${provider} subscription price of plan ${plan.planKey}`,
+        details: { planKey: plan.planKey, providerProductIds: references }
+    });
+}
+function importBoundElsewhere(provider) {
+    return createBillFnError({
+        code: 'BILLFN_CONFLICT',
+        message: `The ${provider} subscription is already bound to a different billing account`
+    });
+}
+/** Whether a subscription of another billing account holds a reference the provider record names. */
+async function isBoundElsewhere(deps, provider, state, billingAccountId) {
+    const holder = await findSubscriptionByProviderRef(deps, provider, state.providerSubscriptionId, state.providerChargeId);
+    return Boolean(holder && holder.billingAccountId !== billingAccountId);
+}
+/**
+ * The import is bound and recorded, but another run holds the reference's
+ * unlinked events (including a run interrupted before it released them) or the
+ * replay reached its bound. Unlike a bound-elsewhere conflict it is retryable:
+ * calling import again, after the holder's lease expires, finishes the replay.
+ */
+function importReplayUnfinished() {
+    return createBillFnError({
+        code: 'BILLFN_CONFLICT',
+        message: 'The import is recorded but replaying its unlinked webhook events did not finish; import again to finish it',
+        details: { reason: BILLFN_IMPORT_REPLAY_UNFINISHED_REASON },
+        retryable: true
+    });
+}
+function importReferenceReplaced() {
+    return createBillFnError({
+        code: 'BILLFN_CONFLICT',
+        message: 'The provider reference was replaced by another subscription and cannot be imported'
+    });
+}
+/**
+ * Refuses an import of a reference a subscription write retired: deletes
+ * `holder` when it is a pending import row holding the reference (whichever
+ * import run created it), then fails with a non-retryable `BILLFN_CONFLICT`.
+ * An accepted row is never deleted: the delete is ordered against a fresh
+ * read that is still pending, so a stale `holder` another run has accepted
+ * since survives.
+ */
+async function refuseRetiredImportReference(deps, provider, reference, holder) {
+    if (!(await isReplacedProviderReference(deps, provider, reference, holder?.id))) {
+        return;
+    }
+    const stored = holder && isImportPending(holder) ? await getSubscriptionById(deps, holder.id) : null;
+    if (stored && isImportPending(stored) && stored.providerSubscriptionId === reference) {
+        await deps.db.deleteMany({
+            model: TABLES.subscriptions,
+            where: [
+                { field: 'id', operator: 'eq', value: stored.id },
+                { field: 'providerSubscriptionId', operator: 'eq', value: reference },
+                { field: 'updatedAt', operator: 'eq', value: stored.updatedAt }
+            ],
+            namespace: deps.namespace
+        });
+    }
+    deps.metrics.track('subscription.import.replaced_reference_refused', { provider });
+    throw importReferenceReplaced();
+}
+/**
+ * After an import's write to `subscription`, which holds `reference`: refuses
+ * the binding when a write of another subscription retired the reference, or
+ * accepts it by clearing the pending marker, and returns the accepted row:
+ * `ownState` when that row carries this write's state, and `acceptedHere` when
+ * this call cleared its pending marker. A lost acceptance write re-finds the
+ * row, which then carries another run's state (accepted by it or here), so the
+ * caller publishes that row's plan, never its own. Every row, the first and
+ * each reload, is checked the same way before it is accepted or returned: it
+ * holds the reference, belongs to `billingAccountId` (another account's row
+ * fails as bound elsewhere, untouched) and its reference is not retired.
+ * Nothing uses a pending row, so no entitlement or lifecycle event exists for
+ * it until this accepts it. The import's audit event (`audit`) for the row it
+ * accepts is recorded just before each acceptance write, so an accepted
+ * binding always has it (an event for a write that then does not land stays);
+ * a refusal deletes the row, and an interrupted run leaves it pending for the
+ * rerun to settle.
+ *
+ * Why the check after the write is enough: a reference is held by at most one
+ * row (unique index), so a writer that retired it took it off its row before
+ * this write held it, and recorded it before that, or saved it pending in that
+ * same write. Read pending, then recorded, now, one of the reads sees it. Every
+ * import that holds the row therefore reaches the same answer.
+ */
+async function settleImportBinding(deps, subscription, reference, billingAccountId, audit) {
+    let current = subscription;
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+        // Only the first attempt holds this run's write; a reload holds whatever wrote the row after it.
+        const ownState = attempt === 0;
+        if (current?.providerSubscriptionId !== reference) {
+            throw createBillFnError({
+                code: 'BILLFN_CONFLICT',
+                message: 'The imported subscription changed while its import was accepted',
+                retryable: true
+            });
+        }
+        if (current.billingAccountId !== billingAccountId) {
+            throw importBoundElsewhere(current.provider);
+        }
+        await refuseRetiredImportReference(deps, current.provider, reference, current);
+        if (!isImportPending(current)) {
+            return { subscription: current, ownState, acceptedHere: false };
+        }
+        const accepted = {
+            ...current,
+            metadata: withoutImportPending(current.metadata),
+            updatedAt: nextSubscriptionUpdatedAt(deps.now(), current.updatedAt)
+        };
+        if (await updateSubscriptionAfterImportAudit(deps, current, accepted, audit)) {
+            return { subscription: accepted, ownState, acceptedHere: true };
+        }
+        current = await findSubscriptionByProviderRef(deps, subscription.provider, reference);
+        await Promise.resolve();
+    }
+    throw createBillFnError({
+        code: 'BILLFN_CONFLICT',
+        message: 'Unable to accept the imported subscription after multiple retries',
+        retryable: true
+    });
+}
+/** Whether the row is an import's binding not yet accepted (see `BILLFN_IMPORT_PENDING_METADATA_KEY`). */
+function isImportPending(subscription) {
+    return subscription?.metadata?.[BILLFN_IMPORT_PENDING_METADATA_KEY] === true;
+}
+function withoutImportPending(metadata) {
+    if (!metadata) {
+        return metadata;
+    }
+    const { [BILLFN_IMPORT_PENDING_METADATA_KEY]: _pending, ...rest } = metadata;
+    return rest;
+}
+/** A write other than an import's reached a pending import row: retried once the import settles it. */
+function importPendingConflict() {
+    return createBillFnError({
+        code: 'BILLFN_CONFLICT',
+        message: 'The subscription is being imported',
+        details: { reason: 'subscription_import_pending' },
+        retryable: true
+    });
+}
+/**
+ * Whether a subscription write dropped this reference (still pending on the
+ * subscription, or recorded). A writer records the reference before it clears
+ * pending, so pending is read first, as `namesReplacedReference` does: a writer
+ * that clears pending between the reads has already recorded it. `holderId`,
+ * the row that holds the reference now, is not counted: a reference it dropped
+ * and holds again, or one a write that lost its race on it recorded, is held.
+ */
+async function isReplacedProviderReference(deps, provider, reference, holderId) {
+    const pending = await deps.db.findMany({
+        model: TABLES.subscriptions,
+        where: [
+            { field: 'provider', operator: 'eq', value: provider },
+            { field: 'replacedReferencesPending', operator: 'eq', value: true }
+        ],
+        namespace: deps.namespace
+    });
+    if (pending.some((subscription) => subscription.id !== holderId && pendingReplacedReferencesOf(subscription).includes(reference))) {
+        return true;
+    }
+    const replaced = await deps.db.findOne({
+        model: TABLES.replacedProviderReferences,
+        where: [
+            { field: 'provider', operator: 'eq', value: provider },
+            { field: 'providerReference', operator: 'eq', value: reference }
+        ],
+        namespace: deps.namespace
+    });
+    return Boolean(replaced && replaced.subscriptionId !== holderId);
+}
 function requireSubject(subject) {
     if (!subject) {
         throw createBillFnError({
@@ -1678,7 +2160,7 @@ async function getSubscriptionById(deps, id) {
 }
 async function getSubscriptionForAccount(deps, billingAccountId, subscriptionId) {
     if (subscriptionId) {
-        return deps.db.findOne({
+        const subscription = await deps.db.findOne({
             model: TABLES.subscriptions,
             where: [
                 { field: 'id', operator: 'eq', value: subscriptionId },
@@ -1686,6 +2168,7 @@ async function getSubscriptionForAccount(deps, billingAccountId, subscriptionId)
             ],
             namespace: deps.namespace
         });
+        return isImportPending(subscription) ? null : subscription;
     }
     return findActiveSubscription(deps, billingAccountId);
 }
@@ -1699,7 +2182,8 @@ async function findActiveSubscription(deps, billingAccountId) {
         orderBy: [{ field: 'updatedAt', direction: 'desc' }],
         namespace: deps.namespace
     });
-    return candidates[0] ?? null;
+    // A pending import row is not the account's until its import accepts it.
+    return candidates.find((candidate) => !isImportPending(candidate)) ?? null;
 }
 async function findSubscriptionByProviderRef(deps, provider, providerSubscriptionId, providerChargeId, checkoutReferenceId) {
     const whereSets = [];
@@ -1999,12 +2483,23 @@ async function applyVerificationState(deps, input) {
     // A read is superseded by an event newer than its start; a committed mutation only by one after its commit.
     const supersededBefore = input.committedAt ?? input.liveStateObservedAt;
     for (let attempt = 0; attempt < 50; attempt += 1) {
+        if (!input.importReference && isImportPending(baseSubscription)) {
+            // Only the import settles its pending row; anything else applies once it is accepted (or deleted).
+            throw importPendingConflict();
+        }
         if (baseSubscription && baseSubscription.billingAccountId !== input.billingAccount.id) {
             throw createBillFnError({
                 code: 'BILLFN_CONFLICT',
                 message: 'Provider billing reference belongs to a different billing account'
             });
         }
+        if (input.importReference && baseSubscription && baseSubscription.providerSubscriptionId !== input.importReference) {
+            // Found by another reference the provider record names: an import never moves its reference onto such a row.
+            throw createBillFnError({
+                code: 'BILLFN_CONFLICT',
+                message: 'The provider record names a reference another subscription holds'
+            });
+        }
         const order = baseSubscription && input.occurredAt ? orderProviderEvent(baseSubscription, input.occurredAt) : 'apply';
         if (baseSubscription && order === 'skip') {
             // The older event's state is skipped, but a reference it adds still belongs to this subscription.
@@ -2037,21 +2532,13 @@ async function applyVerificationState(deps, input) {
                 subscription = baseSubscription;
                 break;
             }
-            const updated = await deps.db.updateMany({
-                model: TABLES.subscriptions,
-                where: [
-                    { field: 'id', operator: 'eq', value: baseSubscription.id },
-                    { field: 'updatedAt', operator: 'eq', value: baseSubscription.updatedAt }
-                ],
-                data: linked,
-                namespace: deps.namespace
-            });
-            if (updated === 1) {
+            // An import that adds its marker or references to an accepted row records its audit first.
+            if (await updateSubscriptionAfterImportAudit(deps, baseSubscription, linked, input.importAudit)) {
                 subscription = linked;
                 break;
             }
-            const current = await getSubscriptionById(deps, baseSubscription.id);
-            if (!current) {
+            const current = await reloadAfterLostWrite(deps, input, baseSubscription);
+            if (!current && !input.importReference) {
                 throw createBillFnError({
                     code: 'BILLFN_CONFLICT',
                     message: 'Subscription changed while applying provider state'
@@ -2062,16 +2549,20 @@ async function applyVerificationState(deps, input) {
             continue;
         }
         // A state write closes the window of an earlier committed mutation; a committed mutation opens its own.
-        const merged = mergeJson(baseSubscription?.metadata, input.state.raw);
+        const merged = mergeJson(mergeJson(input.metadataDefaults, baseSubscription?.metadata), input.state.raw);
         const mergedMetadata = input.keepMutationWindow ? merged : withoutMutationWindow(merged);
         const providerStateAt = providerStateTimeFor(input.occurredAt, supersededBefore, baseSubscription);
-        const metadata = providerStateAt
-            ? {
-                ...mergedMetadata,
-                [PROVIDER_EVENT_OCCURRED_AT_METADATA_KEY]: providerStateAt,
-                ...(input.committedAt ? { [PROVIDER_MUTATION_STARTED_AT_METADATA_KEY]: input.liveStateObservedAt } : {})
-            }
-            : mergedMetadata;
+        const metadata = {
+            ...mergedMetadata,
+            ...(providerStateAt
+                ? {
+                    [PROVIDER_EVENT_OCCURRED_AT_METADATA_KEY]: providerStateAt,
+                    ...(input.committedAt ? { [PROVIDER_MUTATION_STARTED_AT_METADATA_KEY]: input.liveStateObservedAt } : {})
+                }
+                : {}),
+            // A row an import creates stays pending until `settleImportBinding` accepts it.
+            ...(input.importReference && !baseSubscription ? { [BILLFN_IMPORT_PENDING_METADATA_KEY]: true } : {})
+        };
         const subscriptionId = baseSubscription?.id ?? deps.generateId('sub');
         const record = {
             id: subscriptionId,
@@ -2101,23 +2592,15 @@ async function applyVerificationState(deps, input) {
             const pending = await recordDroppedReferences(deps, baseSubscription, record, Boolean(input.committedAt));
             Object.assign(record, withPendingReplacements(record.metadata, pending));
             // Every update is ordered against the row it was computed from, so a provider-state time and the
-            // pending references it clears always come from the row it replaces.
-            const updated = await deps.db.updateMany({
-                model: TABLES.subscriptions,
-                where: [
-                    { field: 'id', operator: 'eq', value: baseSubscription.id },
-                    { field: 'updatedAt', operator: 'eq', value: baseSubscription.updatedAt }
-                ],
-                data: record,
-                namespace: deps.namespace
-            });
-            if (updated === 1) {
+            // pending references it clears always come from the row it replaces. A re-import of an accepted row
+            // records its audit first.
+            if (await updateSubscriptionAfterImportAudit(deps, baseSubscription, record, input.importAudit)) {
                 subscription = record;
                 break;
             }
             // A lost race leaves its records: a reference the winner keeps is held, so its events still link to it.
-            const current = await getSubscriptionById(deps, baseSubscription.id);
-            if (!current) {
+            const current = await reloadAfterLostWrite(deps, input, baseSubscription);
+            if (!current && !input.importReference) {
                 throw createBillFnError({
                     code: 'BILLFN_CONFLICT',
                     message: 'Subscription changed while applying provider event state'
@@ -2153,6 +2636,16 @@ async function applyVerificationState(deps, input) {
             message: 'Unable to apply provider event state after multiple retries'
         });
     }
+    // Whether the row carries this call's state; otherwise it publishes the row's own plan, never `input.plan`.
+    let ownState = !liveStateSuperseded;
+    // Whether this call records the row's lifecycle event (an import that accepts another run's state records it).
+    let recordLifecycle = ownState;
+    if (input.importReference) {
+        const settled = await settleImportBinding(deps, subscription, input.importReference, input.billingAccount.id, input.importAudit);
+        subscription = settled.subscription;
+        ownState = ownState && settled.ownState;
+        recordLifecycle = ownState || settled.acceptedHere;
+    }
     const checkoutSession = input.checkoutSession
         ? await updateCheckoutSession(deps, input.checkoutSession.checkoutSessionId, {
             status: input.state.checkoutStatus,
@@ -2162,9 +2655,10 @@ async function applyVerificationState(deps, input) {
             metadata: mergeJson(input.checkoutSession.metadata, input.state.raw)
         })
         : input.checkoutSession;
-    if (liveStateSuperseded) {
-        // The subscription's state did not change, so its entitlements stand and no lifecycle event is recorded.
-        const entitlements = await upsertEntitlements(deps, input.billingAccount.id, requirePlan(deps.catalog, subscription.planKey), subscription, timestamp);
+    // A superseded read leaves the subscription's state, so its entitlements stand and no lifecycle event is recorded;
+    // an import that ends on another run's state publishes that state's plan.
+    const entitlements = await upsertEntitlements(deps, input.billingAccount.id, ownState ? input.plan : requirePlan(deps.catalog, subscription.planKey), subscription, timestamp);
+    if (!recordLifecycle) {
         return {
             checkoutSession: checkoutSession ?? input.checkoutSession,
             subscription,
@@ -2172,7 +2666,6 @@ async function applyVerificationState(deps, input) {
             providerStateRaced
         };
     }
-    const entitlements = await upsertEntitlements(deps, input.billingAccount.id, input.plan, subscription, timestamp);
     await recordBillingEvent(deps, {
         // A provider event keys its lifecycle entry, so applying it again (a reclaimed replay) records it once.
         id: input.providerEventId
@@ -2198,6 +2691,17 @@ async function applyVerificationState(deps, input) {
         providerStateRaced
     };
 }
+/**
+ * The row to retry a lost ordered write against: the row again, or for an
+ * import the row that holds its reference now (null when none does, and the
+ * import creates one), so the import never writes its reference back onto a
+ * row a writer took it from.
+ */
+function reloadAfterLostWrite(deps, input, subscription) {
+    return input.importReference
+        ? findSubscriptionByProviderRef(deps, input.price.provider, input.importReference)
+        : getSubscriptionById(deps, subscription.id);
+}
 /**
  * The provider-state time a write saves: the event's time, or for live state
  * the read start (a committed mutation: its commit), never moving the stored
@@ -2209,19 +2713,22 @@ function providerStateTimeFor(occurredAt, liveStateAt, subscription) {
 }
 /**
  * The subscription row after a live provider read that an applied event has
- * superseded: missing provider references from the read are added and every
- * state field is kept. Returns null when the read adds no reference.
+ * superseded: missing provider references and metadata keys from the read are
+ * added and every state field is kept. Returns null when the read adds neither.
  */
 function linkLiveReadReferences(subscription, input, timestamp) {
     const providerSubscriptionId = subscription.providerSubscriptionId ?? input.state.providerSubscriptionId;
     const providerCheckoutId = subscription.providerCheckoutId ?? input.checkoutSession?.providerCheckoutId;
     const providerChargeId = subscription.providerChargeId ?? input.state.providerChargeId;
+    const addsMetadata = Object.keys(input.metadataDefaults ?? {}).some((key) => subscription.metadata?.[key] === undefined);
     if (providerSubscriptionId === subscription.providerSubscriptionId &&
         providerCheckoutId === subscription.providerCheckoutId &&
-        providerChargeId === subscription.providerChargeId) {
+        providerChargeId === subscription.providerChargeId &&
+        !addsMetadata) {
         return null;
     }
-    return { ...subscription, providerSubscriptionId, providerCheckoutId, providerChargeId, updatedAt: timestamp };
+    const metadata = addsMetadata ? { ...input.metadataDefaults, ...subscription.metadata } : subscription.metadata;
+    return { ...subscription, providerSubscriptionId, providerCheckoutId, providerChargeId, metadata, updatedAt: timestamp };
 }
 /**
  * Links the provider references of an event skipped as older than the
@@ -2274,6 +2781,28 @@ async function linkableMissingReferences(deps, subscription, state) {
     }
     return data;
 }
+/**
+ * The ordered update of an existing row that `applyVerificationState` (state and superseded-read link updates)
+ * and an import's acceptance (`settleImportBinding`) go through. With an import's audit, a write that leaves the
+ * row usable (not pending) records the run's audit for the state it publishes first, so no later failure or
+ * interruption leaves an import's change without its operator. The row an import creates is pending, so it is
+ * audited when this accepts it.
+ */
+async function updateSubscriptionAfterImportAudit(deps, current, next, importAudit) {
+    if (importAudit && !isImportPending(next)) {
+        await recordBillingEvent(deps, importAudit(next));
+    }
+    const updated = await deps.db.updateMany({
+        model: TABLES.subscriptions,
+        where: [
+            { field: 'id', operator: 'eq', value: current.id },
+            { field: 'updatedAt', operator: 'eq', value: current.updatedAt }
+        ],
+        data: next,
+        namespace: deps.namespace
+    });
+    return updated === 1;
+}
 /** Writes a subscription row ordered against the row it was computed from; false when that row changed. */
 async function writeOrderedSubscription(deps, current, next) {
     try {
@@ -2376,7 +2905,8 @@ async function recordBillingEvent(deps, event) {
         });
     }
     catch (error) {
-        // A provider-event-keyed entry already recorded by an earlier apply of the same event.
+        // Already recorded: a provider-event-keyed entry by an earlier apply of the same event, or a digest-keyed
+        // import event by an earlier write of the same import run and state. The first write wins.
         if (!isDuplicateRecordError(error)) {
             throw error;
         }
@@ -2536,6 +3066,10 @@ async function appendUsageLedgerEntry(deps, billingAccountId, resource, amount)
 }
 async function resolveProjectionContextForProviderState(deps, input) {
     const subscription = await findSubscriptionByProviderRef(deps, input.provider, input.state.providerSubscriptionId, input.state.providerChargeId, input.checkoutReferenceId);
+    if (isImportPending(subscription)) {
+        // Not usable until its import accepts it: the event is stored unlinked and replayed then.
+        return null;
+    }
     if (subscription) {
         const billingAccount = await getBillingAccountById(deps, subscription.billingAccountId);
         if (!billingAccount) {
@@ -2694,7 +3228,12 @@ async function bootstrapOrStoreUnlinkedWebhookEvent(deps, providerName, event, s
     const metadataBillingAccountId = readBillingAccountMetadata(event, state);
     const existing = await findSubscriptionByProviderRef(deps, providerName, state.providerSubscriptionId, state.providerChargeId, event.checkoutReferenceId);
     let reason;
-    if (existing) {
+    const importPending = isImportPending(existing);
+    if (importPending) {
+        // Its import replays this event once it accepts the row; a refused import leaves it unlinked.
+        reason = 'subscription_import_pending';
+    }
+    else if (existing) {
         // A link that committed after this event's first lookup is applied to like any linked reference.
         const projection = await resolveProjectionContextForProviderState(deps, {
             provider: providerName,
@@ -2726,10 +3265,11 @@ async function bootstrapOrStoreUnlinkedWebhookEvent(deps, providerName, event, s
         reason,
         metadataBillingAccountId
     });
-    if (existing) {
+    if (existing && !importPending) {
         return { handled: null };
     }
-    // A link that committed while this event was being stored would have missed it; replay it now.
+    // A link (or an import's acceptance) that committed while this event was being stored would have missed it;
+    // replay it now. The replay skips a row still pending.
     const linked = await findSubscriptionByProviderRef(deps, providerName, state.providerSubscriptionId, state.providerChargeId, event.checkoutReferenceId);
     if (linked) {
         await replayUnlinkedWebhookEventsOrThrow(deps, linked);
@@ -2878,6 +3418,10 @@ async function purgeExpiredUnlinkedWebhookEvents(deps, timestamp) {
  */
 async function replayUnlinkedWebhookEvents(deps, subscription) {
     const result = { applied: 0, skipped: 0, pending: 0 };
+    if (isImportPending(subscription)) {
+        // A pending import row is not linked yet: its import replays the events once it accepts the row.
+        return result;
+    }
     const queue = createUnlinkedReplayQueue(deps, subscription.provider);
     let latest = subscription;
     await queue.discover(subscription);