@billfn/core 0.1.0 → 0.3.0

package/dist/service.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { DuplicateKeyError } from '@superfunctions/db';
 import { ok } from '@superfunctions/envelope';
 import { createNamespacedEmitter, createMetricsEmitter } from '@superfunctions/metrics';
@@ -15,11 +16,41 @@ const TABLES = {
     refunds: 'refunds',
     subscriptionChangeRequests: 'subscriptionChangeRequests',
     reconciliationJobs: 'reconciliationJobs',
-    reconciliationCursors: 'reconciliationCursors'
+    reconciliationCursors: 'reconciliationCursors',
+    unlinkedWebhookEvents: 'unlinkedWebhookEvents',
+    replacedProviderReferences: 'replacedProviderReferences'
 };
 const PROVIDER_EVENT_OCCURRED_AT_METADATA_KEY = 'billfnProviderEventOccurredAt';
+/** When the committed provider mutation that set the provider-state time started; it opens that mutation's window. */
+const PROVIDER_MUTATION_STARTED_AT_METADATA_KEY = 'billfnProviderMutationStartedAt';
+/** References a committed mutation's write dropped but could not record as replaced (`replacedReferencesPending`). */
+const PENDING_REPLACED_REFERENCES_METADATA_KEY = 'billfnPendingReplacedReferences';
 const WEBHOOK_RECEIPT_CLAIM_LEASE_MS = 15 * 60 * 1000;
 const RECONCILIATION_JOB_CLAIM_LEASE_MS = 15 * 60 * 1000;
+/** Unlinked webhook events are kept this long for a later link to replay them. */
+const UNLINKED_WEBHOOK_EVENT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+const UNLINKED_WEBHOOK_EVENT_REPLAY_LEASE_MS = 15 * 60 * 1000;
+/** Bounds the events one replay run applies; the rest are left for the retried operation's next run. */
+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;
 /**
@@ -64,6 +95,7 @@ function createBillFnServiceWithInternals(config) {
         metrics,
         queue: config.queue
     };
+    deps.reconcileProviderState = (subscription, event) => reconcileWindowEvent(subscription, event);
     const subscriptionProvider = {
         getActiveSubscription: async (subject) => {
             const billingAccount = await findBillingAccountForSubject(deps, requireSubject(subject));
@@ -145,7 +177,8 @@ function createBillFnServiceWithInternals(config) {
             };
         }
     };
-    async function syncSubscriptionById(subscriptionId) {
+    /** Reads the subscription from the provider (see `fetchLiveSubscription`). */
+    async function readProviderSubscription(subscriptionId, candidate) {
         const subscription = await getSubscriptionById(deps, subscriptionId);
         if (!subscription) {
             throw createBillFnError({
@@ -160,26 +193,162 @@ function createBillFnServiceWithInternals(config) {
                 message: 'Billing account not found'
             });
         }
-        const plan = requirePlan(deps.catalog, subscription.planKey);
-        const price = requirePriceById(plan, subscription.priceId);
-        const provider = requireProvider(deps, subscription.provider, 'fetchSubscription');
-        const verification = await provider.fetchSubscription({
-            subscription,
-            plan,
-            price
-        });
-        if (!verification) {
+        const live = await fetchLiveSubscription(deps, subscription, candidate);
+        if (!live) {
             throw createBillFnError({
                 code: 'BILLFN_NOT_FOUND',
                 message: 'Provider did not return subscription state'
             });
         }
-        return applyVerificationState(deps, {
-            billingAccount,
-            plan,
-            price,
-            subscription,
-            state: verification
+        return { billingAccount, subscription, ...live };
+    }
+    async function syncSubscriptionById(subscriptionId) {
+        return applyLiveProviderState(deps, await readProviderSubscription(subscriptionId));
+    }
+    /**
+     * Reconciles an event inside a committed mutation's window with a provider
+     * read for the committed plan and price, or for the event's price when that
+     * fails and the live record confirms it (`fetchLiveSubscription`). When no
+     * read succeeds, the committed state stands: with a queue a subscription-sync
+     * job carrying the event's price is enqueued, otherwise a window-read error is
+     * thrown so the delivery, job or replay trigger is retried. The window stays
+     * open until the read's entitlements and its lifecycle entry, keyed by the
+     * event, are written, so a retry after a failure there reconciles again.
+     */
+    async function reconcileWindowEvent(subscription, event) {
+        let read;
+        try {
+            read = await readProviderSubscription(subscription.id, event.selection);
+        }
+        catch (error_) {
+            deps.metrics.track('subscription.mutation.window_event_unreconciled', {
+                provider: subscription.provider,
+                subscriptionId: subscription.id,
+                reason: 'read_failed',
+                error: error_ instanceof Error ? error_.message : String(error_)
+            });
+            if (!deps.queue) {
+                throw windowReadFailed(error_);
+            }
+            await scheduleSubscriptionSync(subscription, event.selection);
+            return;
+        }
+        await applyVerificationState(deps, {
+            ...read,
+            keepMutationWindow: true,
+            providerEventId: event.providerEventId ? `${event.providerEventId}#window-read` : undefined
+        });
+        await closeMutationWindow(deps, subscription.id, readMutationStartedAt(subscription));
+    }
+    /**
+     * Applies the provider state a committed provider mutation (cancel, change,
+     * resume, refund) returned. `committedAt` is taken as soon as the provider
+     * call returns, before any other write.
+     * Retained events that cannot be replayed now do not fail the mutation; with a
+     * queue and a provider that supports sync, a subscription-sync job is enqueued
+     * to replay them. When a provider event was applied while the mutation was in
+     * flight, the subscription is reconciled with an authoritative provider read.
+     */
+    async function applyMutationProviderState(input) {
+        const projection = await applyLiveProviderState(deps, input, { onReplayDeferred: scheduleSubscriptionSync });
+        if (!projection.providerStateRaced) {
+            return projection;
+        }
+        deps.metrics.track('subscription.mutation.raced_event', {
+            provider: projection.subscription.provider,
+            subscriptionId: projection.subscription.id
+        });
+        return (await reconcileCommittedMutation(projection.subscription, projection.providerStateRaced.priceId)) ?? projection;
+    }
+    /**
+     * Reads the subscription from the provider after a mutation an event raced:
+     * a queued sync job when a queue is configured, otherwise an inline sync. It
+     * never repeats the mutation and never fails it. Returns the inline result.
+     * The price the raced event wrote is the read's candidate (`fetchLiveSubscription`).
+     */
+    async function reconcileCommittedMutation(subscription, racedPriceId) {
+        const candidate = findCatalogPriceReference(deps.catalog, subscription.provider, [racedPriceId]) ?? undefined;
+        try {
+            if (deps.queue) {
+                await scheduleSubscriptionSync(subscription, candidate);
+                return null;
+            }
+            if (typeof deps.providers[subscription.provider]?.fetchSubscription !== 'function') {
+                return null;
+            }
+            return await applyLiveProviderState(deps, await readProviderSubscription(subscription.id, candidate));
+        }
+        catch (error) {
+            deps.metrics.track('subscription.mutation.reconcile_failed', {
+                provider: subscription.provider,
+                subscriptionId: subscription.id,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return null;
+        }
+    }
+    /** Loads the caller's subscription, plan and price for a subscription mutation. */
+    async function loadMutationSubscription(input) {
+        const subject = requireSubject(input.subject);
+        const { billingAccount } = await getOrCreateBillingAccount(deps, subject);
+        const subscription = await getSubscriptionForAccount(deps, billingAccount.id, input.subscriptionId);
+        if (!subscription) {
+            throw createBillFnError({
+                code: 'BILLFN_NOT_FOUND',
+                message: 'Subscription not found'
+            });
+        }
+        const plan = requirePlan(deps.catalog, subscription.planKey);
+        const price = requirePriceById(plan, subscription.priceId);
+        return { billingAccount, subscription, plan, price };
+    }
+    /**
+     * Completes a committed cancel, change or resume: applies the state the
+     * provider returned (or keeps the stored subscription and entitlements when it
+     * returned none) and records the requested billing event.
+     */
+    async function finishSubscriptionMutation(input) {
+        const { billingAccount, subscription, operation } = input;
+        const projection = operation.billingState
+            ? await applyMutationProviderState({
+                billingAccount,
+                plan: input.plan,
+                price: input.price,
+                subscription,
+                state: operation.billingState,
+                liveStateObservedAt: input.liveStateObservedAt,
+                committedAt: input.timestamp
+            })
+            : {
+                subscription,
+                entitlements: (await findEntitlementSnapshot(deps, billingAccount.id)) ??
+                    (await upsertEntitlements(deps, billingAccount.id, input.entitlementPlan, subscription, input.timestamp))
+            };
+        await recordBillingEvent(deps, {
+            id: deps.generateId('evt'),
+            billingAccountId: billingAccount.id,
+            type: input.eventType,
+            payload: { subscriptionId: subscription.id, ...input.eventPayload, operationStatus: operation.operationStatus },
+            createdAt: input.timestamp
+        });
+        return {
+            subscription: projection.subscription,
+            entitlements: projection.entitlements,
+            operationStatus: operation.operationStatus,
+            clientAction: operation.clientAction
+        };
+    }
+    /** `candidate` is the catalog price an unreconciled window event names; the job reads it if the stored one fails. */
+    async function scheduleSubscriptionSync(subscription, candidate) {
+        if (!deps.queue || typeof deps.providers[subscription.provider]?.fetchSubscription !== 'function') {
+            return;
+        }
+        await enqueueReconciliationJobInternal({
+            kind: 'subscription-sync',
+            provider: subscription.provider,
+            billingAccountId: subscription.billingAccountId,
+            subscriptionId: subscription.id,
+            payload: candidate ? { candidatePriceId: candidate.price.priceId } : undefined
         });
     }
     async function createReconciliationJobRecord(input) {
@@ -418,6 +587,8 @@ function createBillFnServiceWithInternals(config) {
             const plan = requirePlan(deps.catalog, checkoutSession.planKey);
             const price = requirePriceById(plan, checkoutSession.priceId);
             const provider = requireProvider(deps, checkoutSession.provider, 'verifyCheckout');
+            // Events that occurred before this live read are already reflected in its state.
+            const verificationObservedAt = toIsoString(deps.now());
             const verification = await provider.verifyCheckout({
                 checkoutSession,
                 billingAccount,
@@ -425,12 +596,13 @@ function createBillFnServiceWithInternals(config) {
                 price,
                 payload: input.payload
             });
-            const result = await applyVerificationState(deps, {
+            const result = await applyLiveProviderState(deps, {
                 billingAccount,
                 plan,
                 price,
                 checkoutSession,
-                state: verification
+                state: verification,
+                liveStateObservedAt: verificationObservedAt
             });
             if (!result.checkoutSession) {
                 throw createBillFnError({
@@ -445,18 +617,9 @@ function createBillFnServiceWithInternals(config) {
             });
         },
         async cancelSubscription(input) {
-            const subject = requireSubject(input.subject);
-            const { billingAccount } = await getOrCreateBillingAccount(deps, subject);
-            const subscription = await getSubscriptionForAccount(deps, billingAccount.id, input.subscriptionId);
-            if (!subscription) {
-                throw createBillFnError({
-                    code: 'BILLFN_NOT_FOUND',
-                    message: 'Subscription not found'
-                });
-            }
-            const plan = requirePlan(deps.catalog, subscription.planKey);
-            const price = requirePriceById(plan, subscription.priceId);
+            const { billingAccount, subscription, plan, price } = await loadMutationSubscription(input);
             const provider = requireProvider(deps, subscription.provider, 'cancelSubscription');
+            const liveStateObservedAt = toIsoString(deps.now());
             const operation = (await provider.cancelSubscription({
                 subscription,
                 reason: input.reason
@@ -472,48 +635,22 @@ function createBillFnServiceWithInternals(config) {
                     currentPeriodEnd: subscription.currentPeriodEnd
                 }
             };
-            const projection = operation.billingState
-                ? await applyVerificationState(deps, {
-                    billingAccount,
-                    plan,
-                    price,
-                    subscription,
-                    state: operation.billingState
-                })
-                : {
-                    subscription,
-                    entitlements: (await findEntitlementSnapshot(deps, billingAccount.id)) ?? await upsertEntitlements(deps, billingAccount.id, plan, subscription, toIsoString(deps.now()))
-                };
-            await recordBillingEvent(deps, {
-                id: deps.generateId('evt'),
-                billingAccountId: billingAccount.id,
-                type: 'billfn.subscription.cancel.requested',
-                payload: {
-                    subscriptionId: subscription.id,
-                    operationStatus: operation.operationStatus,
-                    reason: input.reason
-                },
-                createdAt: toIsoString(deps.now())
-            });
-            return ok({
-                subscription: projection.subscription,
-                entitlements: projection.entitlements,
-                operationStatus: operation.operationStatus,
-                clientAction: operation.clientAction
-            });
+            const committedAt = toIsoString(deps.now());
+            return ok(await finishSubscriptionMutation({
+                billingAccount,
+                subscription,
+                plan,
+                price,
+                entitlementPlan: plan,
+                operation,
+                liveStateObservedAt,
+                timestamp: committedAt,
+                eventType: 'billfn.subscription.cancel.requested',
+                eventPayload: { reason: input.reason }
+            }));
         },
         async changeSubscription(input) {
-            const subject = requireSubject(input.subject);
-            const { billingAccount } = await getOrCreateBillingAccount(deps, subject);
-            const subscription = await getSubscriptionForAccount(deps, billingAccount.id, input.subscriptionId);
-            if (!subscription) {
-                throw createBillFnError({
-                    code: 'BILLFN_NOT_FOUND',
-                    message: 'Subscription not found'
-                });
-            }
-            const currentPlan = requirePlan(deps.catalog, subscription.planKey);
-            const currentPrice = requirePriceById(currentPlan, subscription.priceId);
+            const { billingAccount, subscription, plan: currentPlan, price: currentPrice } = await loadMutationSubscription(input);
             const target = requirePriceReference(deps.catalog, input.targetPriceId);
             if (target.price.provider !== subscription.provider) {
                 throw createBillFnError({
@@ -529,6 +666,7 @@ function createBillFnServiceWithInternals(config) {
             const provider = requireProvider(deps, subscription.provider, 'changeSubscription');
             const effectiveAt = input.effectiveAt ?? 'immediate';
             const prorationBehavior = input.prorationBehavior ?? 'provider_default';
+            const liveStateObservedAt = toIsoString(deps.now());
             const operation = await provider.changeSubscription({
                 subscription,
                 currentPlan,
@@ -556,82 +694,40 @@ function createBillFnServiceWithInternals(config) {
                 updatedAt: timestamp
             });
             const appliesTargetImmediately = operation.operationStatus === 'applied' && effectiveAt === 'immediate';
-            const projection = operation.billingState
-                ? await applyVerificationState(deps, {
-                    billingAccount,
-                    plan: appliesTargetImmediately ? target.plan : currentPlan,
-                    price: appliesTargetImmediately ? target.price : currentPrice,
-                    subscription,
-                    state: operation.billingState
-                })
-                : {
-                    subscription,
-                    entitlements: (await findEntitlementSnapshot(deps, billingAccount.id)) ?? await upsertEntitlements(deps, billingAccount.id, currentPlan, subscription, timestamp)
-                };
-            await recordBillingEvent(deps, {
-                id: deps.generateId('evt'),
-                billingAccountId: billingAccount.id,
-                type: 'billfn.subscription.change.requested',
-                payload: {
-                    subscriptionId: subscription.id,
-                    currentPriceId: currentPrice.priceId,
-                    targetPriceId: target.price.priceId,
-                    operationStatus: operation.operationStatus
-                },
-                createdAt: timestamp
-            });
-            return ok({
-                subscription: projection.subscription,
-                entitlements: projection.entitlements,
-                operationStatus: operation.operationStatus,
-                clientAction: operation.clientAction,
-                changeRequest
+            const result = await finishSubscriptionMutation({
+                billingAccount,
+                subscription,
+                plan: appliesTargetImmediately ? target.plan : currentPlan,
+                price: appliesTargetImmediately ? target.price : currentPrice,
+                entitlementPlan: currentPlan,
+                operation,
+                liveStateObservedAt,
+                timestamp,
+                eventType: 'billfn.subscription.change.requested',
+                eventPayload: { currentPriceId: currentPrice.priceId, targetPriceId: target.price.priceId }
             });
+            return ok({ ...result, changeRequest });
         },
         async resumeSubscription(input) {
-            const subject = requireSubject(input.subject);
-            const { billingAccount } = await getOrCreateBillingAccount(deps, subject);
-            const subscription = await getSubscriptionForAccount(deps, billingAccount.id, input.subscriptionId);
-            if (!subscription) {
-                throw createBillFnError({
-                    code: 'BILLFN_NOT_FOUND',
-                    message: 'Subscription not found'
-                });
-            }
-            const plan = requirePlan(deps.catalog, subscription.planKey);
-            const price = requirePriceById(plan, subscription.priceId);
+            const { billingAccount, subscription, plan, price } = await loadMutationSubscription(input);
             const provider = requireProvider(deps, subscription.provider, 'resumeSubscription');
+            const liveStateObservedAt = toIsoString(deps.now());
             const operation = await provider.resumeSubscription({
                 subscription
             });
-            const projection = operation.billingState
-                ? await applyVerificationState(deps, {
-                    billingAccount,
-                    plan,
-                    price,
-                    subscription,
-                    state: operation.billingState
-                })
-                : {
-                    subscription,
-                    entitlements: (await findEntitlementSnapshot(deps, billingAccount.id)) ?? await upsertEntitlements(deps, billingAccount.id, plan, subscription, toIsoString(deps.now()))
-                };
-            await recordBillingEvent(deps, {
-                id: deps.generateId('evt'),
-                billingAccountId: billingAccount.id,
-                type: 'billfn.subscription.resume.requested',
-                payload: {
-                    subscriptionId: subscription.id,
-                    operationStatus: operation.operationStatus
-                },
-                createdAt: toIsoString(deps.now())
-            });
-            return ok({
-                subscription: projection.subscription,
-                entitlements: projection.entitlements,
-                operationStatus: operation.operationStatus,
-                clientAction: operation.clientAction
-            });
+            const committedAt = toIsoString(deps.now());
+            return ok(await finishSubscriptionMutation({
+                billingAccount,
+                subscription,
+                plan,
+                price,
+                entitlementPlan: plan,
+                operation,
+                liveStateObservedAt,
+                timestamp: committedAt,
+                eventType: 'billfn.subscription.resume.requested',
+                eventPayload: {}
+            }));
         },
         async refundCharge(input) {
             const subject = requireSubject(input.subject);
@@ -655,6 +751,7 @@ function createBillFnServiceWithInternals(config) {
             const provider = requireProvider(deps, providerName, 'refundCharge');
             const mode = input.mode ?? 'full';
             const providerChargeId = input.providerChargeId ?? subscription.providerChargeId;
+            const liveStateObservedAt = toIsoString(deps.now());
             const operation = await provider.refundCharge({
                 subscription,
                 billingAccount,
@@ -685,12 +782,14 @@ function createBillFnServiceWithInternals(config) {
             if (subscription && operation.billingState) {
                 const plan = requirePlan(deps.catalog, subscription.planKey);
                 const price = requirePriceById(plan, subscription.priceId);
-                const projection = await applyVerificationState(deps, {
+                const projection = await applyMutationProviderState({
                     billingAccount,
                     plan,
                     price,
                     subscription,
-                    state: operation.billingState
+                    state: operation.billingState,
+                    liveStateObservedAt,
+                    committedAt: timestamp
                 });
                 projectedSubscription = projection.subscription;
                 projectedEntitlements = projection.entitlements;
@@ -757,6 +856,8 @@ function createBillFnServiceWithInternals(config) {
                 });
             }
             const provider = requireProvider(deps, input.provider, 'restorePurchases');
+            // Events that occurred before this live read are already reflected in its state.
+            const restoreObservedAt = toIsoString(deps.now());
             const states = await provider.restorePurchases({
                 billingAccount,
                 plan,
@@ -777,11 +878,12 @@ function createBillFnServiceWithInternals(config) {
                     checkoutReferenceId: input.purchaseReference
                 });
                 if (!projection) {
-                    const applied = await applyVerificationState(deps, {
+                    const applied = await applyLiveProviderState(deps, {
                         billingAccount,
                         plan,
                         price,
-                        state
+                        state,
+                        liveStateObservedAt: restoreObservedAt
                     });
                     const response = {
                         subscription: applied.subscription,
@@ -792,13 +894,14 @@ function createBillFnServiceWithInternals(config) {
                 if (projection.billingAccount.id !== billingAccount.id) {
                     continue;
                 }
-                const applied = await applyVerificationState(deps, {
+                const applied = await applyLiveProviderState(deps, {
                     billingAccount: projection.billingAccount,
                     plan: projection.plan,
                     price: projection.price,
                     checkoutSession: projection.checkoutSession ?? undefined,
                     subscription: projection.subscription ?? undefined,
-                    state
+                    state,
+                    liveStateObservedAt: restoreObservedAt
                 });
                 const response = {
                     subscription: applied.subscription,
@@ -811,6 +914,142 @@ 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 resolveImportBillingAccount(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: refreshed.entitlements,
+                billingEvent
+            });
+        },
         async getEntitlements(subject) {
             const resolved = await resolveBillingAccountReference(deps, requireSubject(subject));
             const billingAccount = await getBillingAccountById(deps, resolved.billingAccountId);
@@ -1056,7 +1295,13 @@ export function createBillFnReconciliationWorker(config) {
                 // The queue rejects an empty dead-letter reason, which would mask the run's error.
                 const reason = (error instanceof Error ? error.message || error.name : String(error)) || 'reconciliation run failed';
                 try {
-                    if (isReconciliationLeaseConflict(error) &&
+                    if (isProductiveReplayBound(error)) {
+                        // A replay that finished events before its bound continues in a fresh message, so a long
+                        // backlog never uses up the lease-conflict budget; one that finished none counts against it.
+                        await queue.enqueue(RECONCILIATION_QUEUE, claimed.payload);
+                        await queue.ack(claimed.id, fence);
+                    }
+                    else if (isReconciliationLeaseConflict(error) &&
                         claimed.attempt < RECONCILIATION_QUEUE_MAX_LEASE_CONFLICT_ATTEMPTS) {
                         // Another runner holds or took over the job's processing lease; retry once it has finished or expired.
                         await queue.fail(claimed.id, {
@@ -1162,7 +1407,8 @@ async function processReconciliationJob(deps, job, assertLease) {
                     message: 'Subscription sync job requires subscriptionId'
                 });
             }
-            await syncSubscriptionByIdForJob(deps, job.subscriptionId, assertLease);
+            const candidatePriceId = readString(job.payload ?? {}, 'candidatePriceId');
+            await syncSubscriptionByIdForJob(deps, job.subscriptionId, assertLease, candidatePriceId);
             return;
         }
         case 'account-scan': {
@@ -1333,34 +1579,67 @@ async function processReconciliationJob(deps, job, assertLease) {
         }
     }
 }
-async function syncSubscriptionByIdForJob(deps, subscriptionId, 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);
     if (!billingAccount) {
         return;
     }
-    const plan = requirePlan(deps.catalog, subscription.planKey);
-    const price = requirePriceById(plan, subscription.priceId);
-    const provider = requireProvider(deps, subscription.provider, 'fetchSubscription');
-    const verification = await provider.fetchSubscription({
-        subscription,
-        plan,
-        price
-    });
-    if (!verification) {
+    const candidate = candidatePriceId
+        ? findCatalogPriceReference(deps.catalog, subscription.provider, [candidatePriceId])
+        : null;
+    const live = await fetchLiveSubscription(deps, subscription, candidate ?? undefined);
+    if (!live) {
         return;
     }
     await assertLease();
-    await applyVerificationState(deps, {
-        billingAccount,
-        plan,
-        price,
-        subscription,
-        state: verification
-    });
+    await applyLiveProviderState(deps, { billingAccount, subscription, ...live });
+}
+/**
+ * Reads the subscription from the provider for its stored plan and price. If
+ * that read fails or returns no state and `candidate` names another catalog
+ * price, it reads for that price (a provider such as Apple reads only the live
+ * product); such a read counts only when the state it returns names a catalog
+ * price (`providerProductId` or the raw record), whatever the stored read's
+ * failure was, else it counts as failed. The catalog price the live record
+ * names is the selection applied. Returns null when every read returned no
+ * state, and otherwise throws the first failure.
+ */
+async function fetchLiveSubscription(deps, subscription, candidate) {
+    const plan = requirePlan(deps.catalog, subscription.planKey);
+    const stored = { plan, price: requirePriceById(plan, subscription.priceId) };
+    const provider = requireProvider(deps, subscription.provider, 'fetchSubscription');
+    const selections = candidate?.price.priceId && candidate.price.priceId !== stored.price.priceId ? [stored, candidate] : [stored];
+    const failures = [];
+    for (const selection of selections) {
+        const liveStateObservedAt = toIsoString(deps.now());
+        try {
+            const state = await provider.fetchSubscription({ subscription, plan: selection.plan, price: selection.price });
+            const live = state
+                ? await resolveProviderEventPriceReference(deps, subscription.provider, { type: 'subscription.read', billingState: state }, subscription)
+                : null;
+            // A read for another price counts only when the provider confirms that price.
+            if (state && (live || selection === stored)) {
+                return { ...(live ?? selection), state, liveStateObservedAt };
+            }
+            if (state) {
+                failures.push(createBillFnError({
+                    code: 'BILLFN_PROVIDER_ERROR',
+                    message: 'The live provider record does not confirm the requested catalog price'
+                }));
+            }
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length > 0) {
+        throw failures[0];
+    }
+    return null;
 }
 async function getOrCreateBillingAccount(deps, subject) {
     const resolved = await resolveBillingAccountReference(deps, subject);
@@ -1498,23 +1777,304 @@ function requireProvider(deps, providerName, capability) {
     }
     return provider;
 }
-function requireSubject(subject) {
-    if (!subject) {
-        throw createBillFnError({
-            code: 'BILLFN_VALIDATION_ERROR',
-            message: 'A billing subject is required'
-        });
+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');
     }
-    const hasIdentifier = Boolean(subject.actorId || subject.principalId || subject.organizationId || subject.tenantId);
-    if (!hasIdentifier) {
+    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_VALIDATION_ERROR',
-            message: 'A billing subject must include an actor, principal, tenant, or organization identifier'
+            code: 'BILLFN_PROVIDER_ERROR',
+            message: `Provider ${providerName} could not be read for the imported subscription`
         });
     }
-    return subject;
 }
-async function createCheckoutSessionRecord(deps, session) {
+/** The billing account an import binds to: created for the subject when one is given, otherwise existing. */
+async function resolveImportBillingAccount(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({
+            code: 'BILLFN_VALIDATION_ERROR',
+            message: 'A billing subject is required'
+        });
+    }
+    const hasIdentifier = Boolean(subject.actorId || subject.principalId || subject.organizationId || subject.tenantId);
+    if (!hasIdentifier) {
+        throw createBillFnError({
+            code: 'BILLFN_VALIDATION_ERROR',
+            message: 'A billing subject must include an actor, principal, tenant, or organization identifier'
+        });
+    }
+    return subject;
+}
+async function createCheckoutSessionRecord(deps, session) {
     await deps.db.create({
         model: TABLES.checkoutSessions,
         data: session,
@@ -1553,7 +2113,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 },
@@ -1561,6 +2121,7 @@ async function getSubscriptionForAccount(deps, billingAccountId, subscriptionId)
             ],
             namespace: deps.namespace
         });
+        return isImportPending(subscription) ? null : subscription;
     }
     return findActiveSubscription(deps, billingAccountId);
 }
@@ -1574,7 +2135,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 = [];
@@ -1869,26 +2431,91 @@ async function applyVerificationState(deps, input) {
         (await findSubscriptionByProviderRef(deps, input.price.provider, input.state.providerSubscriptionId, input.state.providerChargeId, input.checkoutSession?.checkoutSessionId));
     let subscription = null;
     let timestamp = toIsoString(deps.now());
+    let liveStateSuperseded = false;
+    let providerStateRaced;
+    // 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 (baseSubscription &&
-            input.occurredAt &&
-            isProviderEventOlderThanSubscription(baseSubscription, input.occurredAt)) {
+        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.
+            await linkSkippedEventReferences(deps, baseSubscription, input.state);
+            return null;
+        }
+        if (baseSubscription && order === 'reconcile') {
+            // Never applied over the committed mutation; without a queue a failed read fails this call, so it is retried.
+            await reconcileMutationWindowEvent(deps, baseSubscription, input);
             return null;
         }
+        // An event applied after a live read started is newer than what the read returned: the read
+        // only links its references and the subscription keeps the event's state.
+        liveStateSuperseded = Boolean(baseSubscription &&
+            !input.occurredAt &&
+            supersededBefore &&
+            isProviderEventOlderThanSubscription(baseSubscription, supersededBefore));
+        // An event applied while a committed mutation was in flight is reconciled by the caller.
+        providerStateRaced =
+            baseSubscription &&
+                input.committedAt &&
+                input.liveStateObservedAt &&
+                isProviderEventOlderThanSubscription(baseSubscription, input.liveStateObservedAt)
+                ? { priceId: baseSubscription.priceId }
+                : undefined;
         timestamp = nextSubscriptionUpdatedAt(deps.now(), baseSubscription?.updatedAt);
-        const mergedMetadata = mergeJson(baseSubscription?.metadata, input.state.raw);
-        const metadata = input.occurredAt
-            ? {
-                ...mergedMetadata,
-                [PROVIDER_EVENT_OCCURRED_AT_METADATA_KEY]: input.occurredAt
+        if (baseSubscription && liveStateSuperseded) {
+            const linked = linkLiveReadReferences(baseSubscription, input, timestamp);
+            if (!linked) {
+                subscription = baseSubscription;
+                break;
+            }
+            // 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 reloadAfterLostWrite(deps, input, baseSubscription);
+            if (!current && !input.importReference) {
+                throw createBillFnError({
+                    code: 'BILLFN_CONFLICT',
+                    message: 'Subscription changed while applying provider state'
+                });
             }
-            : mergedMetadata;
+            baseSubscription = current;
+            await Promise.resolve();
+            continue;
+        }
+        // A state write closes the window of an earlier committed mutation; a committed mutation opens its own.
+        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 = {
+            ...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,
@@ -1911,38 +2538,30 @@ async function applyVerificationState(deps, input) {
             trialEnd: baseSubscription?.trialEnd
         };
         if (baseSubscription) {
-            if (input.occurredAt) {
-                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
+            // A reference this write drops is recorded as replaced before it, so no failure or interruption
+            // after the write lets an event on it bootstrap another subscription; one a committed mutation
+            // cannot record is saved pending with the write. A pending one is recorded before this write
+            // clears it, the order `namesReplacedReference` reads against.
+            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. 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 reloadAfterLostWrite(deps, input, baseSubscription);
+            if (!current && !input.importReference) {
+                throw createBillFnError({
+                    code: 'BILLFN_CONFLICT',
+                    message: 'Subscription changed while applying provider event state'
                 });
-                if (updated === 1) {
-                    subscription = record;
-                    break;
-                }
-                const current = await getSubscriptionById(deps, baseSubscription.id);
-                if (!current) {
-                    throw createBillFnError({
-                        code: 'BILLFN_CONFLICT',
-                        message: 'Subscription changed while applying provider event state'
-                    });
-                }
-                baseSubscription = current;
-                await Promise.resolve();
-                continue;
             }
-            subscription = await deps.db.update({
-                model: TABLES.subscriptions,
-                where: [{ field: 'id', operator: 'eq', value: baseSubscription.id }],
-                data: record,
-                namespace: deps.namespace
-            });
-            break;
+            baseSubscription = current;
+            await Promise.resolve();
+            continue;
         }
         try {
             subscription = await deps.db.create({
@@ -1970,6 +2589,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,
@@ -1979,9 +2608,22 @@ async function applyVerificationState(deps, input) {
             metadata: mergeJson(input.checkoutSession.metadata, input.state.raw)
         })
         : input.checkoutSession;
-    const entitlements = await upsertEntitlements(deps, input.billingAccount.id, input.plan, 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,
+            entitlements,
+            providerStateRaced
+        };
+    }
     await recordBillingEvent(deps, {
-        id: deps.generateId('evt'),
+        // A provider event keys its lifecycle entry, so applying it again (a reclaimed replay) records it once.
+        id: input.providerEventId
+            ? buildProviderEventBillingEventId(subscription.provider, input.providerEventId)
+            : deps.generateId('evt'),
         billingAccountId: input.billingAccount.id,
         type: `billfn.subscription.${subscription.status}`,
         payload: {
@@ -1998,9 +2640,159 @@ async function applyVerificationState(deps, input) {
     return {
         checkoutSession: checkoutSession ?? input.checkoutSession,
         subscription,
-        entitlements
+        entitlements,
+        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
+ * time backwards on any path. Null when the state carries no time.
+ */
+function providerStateTimeFor(occurredAt, liveStateAt, subscription) {
+    const stateAt = occurredAt ?? liveStateAt;
+    return stateAt ? laterProviderEventTime(readProviderStateOccurredAt(subscription), stateAt) : null;
+}
+/**
+ * The subscription row after a live provider read that an applied event has
+ * 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 &&
+        !addsMetadata) {
+        return null;
+    }
+    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
+ * subscription's provider state (the last applied event or a live provider
+ * read). The state, entitlements and provider-state time are kept; only a
+ * missing provider subscription or charge id is filled, never replaced, and a
+ * reference another subscription already holds is left alone. The write is
+ * ordered against the row it was computed from. Returns the subscription after
+ * the write, or the current row when nothing was added; the caller replays the
+ * events retained for an added reference.
+ */
+async function linkSkippedEventReferences(deps, subscription, state) {
+    let current = subscription;
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+        const data = await linkableMissingReferences(deps, current, state);
+        if (Object.keys(data).length === 0) {
+            return current;
+        }
+        const linked = {
+            ...current,
+            ...data,
+            updatedAt: nextSubscriptionUpdatedAt(deps.now(), current.updatedAt)
+        };
+        if (await writeOrderedSubscription(deps, current, linked)) {
+            deps.metrics.track('reconciliation.event.references_linked', {
+                provider: current.provider,
+                subscriptionId: current.id
+            });
+            return linked;
+        }
+        const reread = await getSubscriptionById(deps, current.id);
+        if (!reread) {
+            return current;
+        }
+        current = reread;
+        await Promise.resolve();
+    }
+    throw createBillFnError({
+        code: 'BILLFN_CONFLICT',
+        message: 'Unable to link provider references after multiple retries'
+    });
+}
+/** The references the subscription lacks that the state names and no other subscription holds. */
+async function linkableMissingReferences(deps, subscription, state) {
+    const data = {};
+    for (const field of ['providerSubscriptionId', 'providerChargeId']) {
+        if (await isMissingReferenceLinkable(deps, subscription, field, state[field])) {
+            data[field] = state[field];
+        }
+    }
+    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 {
+        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;
+    }
+    catch (error) {
+        // Another subscription took the reference between the check and the write: re-check it.
+        if (!isDuplicateRecordError(error)) {
+            throw error;
+        }
+        return false;
+    }
+}
+/** Whether the subscription lacks this reference and no other subscription holds it. */
+async function isMissingReferenceLinkable(deps, subscription, field, reference) {
+    return Boolean(!subscription[field] && reference && !(await isProviderReferenceHeldElsewhere(deps, subscription, field, reference)));
+}
+async function isProviderReferenceHeldElsewhere(deps, subscription, field, reference) {
+    const holder = await deps.db.findOne({
+        model: TABLES.subscriptions,
+        where: [
+            { field: 'provider', operator: 'eq', value: subscription.provider },
+            { field, operator: 'eq', value: reference }
+        ],
+        namespace: deps.namespace
+    });
+    return Boolean(holder && holder.id !== subscription.id);
+}
 async function upsertEntitlements(deps, billingAccountId, plan, subscription, timestamp) {
     for (let attempt = 0; attempt < 50; attempt += 1) {
         const existing = await findEntitlementSnapshot(deps, billingAccountId);
@@ -2058,11 +2850,23 @@ async function upsertEntitlements(deps, billingAccountId, plan, subscription, ti
     });
 }
 async function recordBillingEvent(deps, event) {
-    await deps.db.create({
-        model: TABLES.billingEvents,
-        data: event,
-        namespace: deps.namespace
-    });
+    try {
+        await deps.db.create({
+            model: TABLES.billingEvents,
+            data: event,
+            namespace: deps.namespace
+        });
+    }
+    catch (error) {
+        // 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;
+        }
+    }
+}
+function buildProviderEventBillingEventId(provider, providerEventId) {
+    return `evt_${provider}_${Buffer.from(providerEventId).toString('base64url')}`;
 }
 async function createRefundRecord(deps, input) {
     const refund = {
@@ -2215,6 +3019,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) {
@@ -2250,23 +3058,81 @@ async function resolveProjectionContextForProviderState(deps, input) {
     };
 }
 async function processParsedWebhookEvent(deps, providerName, event) {
-    if (!event.billingState) {
+    const state = event.billingState;
+    if (!state) {
         return null;
     }
-    const projection = await resolveProjectionContextForProviderState(deps, {
+    let projection = await resolveProjectionContextForProviderState(deps, {
         provider: providerName,
-        state: event.billingState,
+        state,
         checkoutReferenceId: event.checkoutReferenceId
     });
     if (!projection) {
-        throw createBillFnError({
-            code: 'BILLFN_NOT_FOUND',
-            message: `Webhook event could not be linked to a billing account: ${event.providerEventId}`
+        const outcome = await bootstrapOrStoreUnlinkedWebhookEvent(deps, providerName, event, state);
+        if (!('linked' in outcome)) {
+            return outcome.handled;
+        }
+        projection = outcome.linked;
+    }
+    if (projection.subscription) {
+        return applyEventToLinkedSubscription(deps, providerName, { ...event, billingState: state }, projection.subscription);
+    }
+    // The event resolved only through a checkout session, so applying it links the reference:
+    // events stored for it before now are replayed after it, newer ones applied and older ones skipped.
+    const applied = await applyParsedWebhookEvent(deps, providerName, { ...event, billingState: state }, projection);
+    const linked = applied?.subscription ??
+        (await findSubscriptionByProviderRef(deps, providerName, state.providerSubscriptionId, state.providerChargeId, event.checkoutReferenceId));
+    if (linked) {
+        await replayUnlinkedWebhookEventsOrThrow(deps, linked);
+    }
+    return applied;
+}
+/**
+ * Applies an event that resolved to a subscription. Events stored before its
+ * reference was linked go first, so provider event-time order holds; an unread
+ * window event does not hold this event back and is retried after it.
+ */
+async function applyEventToLinkedSubscription(deps, providerName, event, subscription) {
+    const state = event.billingState;
+    const { windowUnread } = await replayUnlinkedWebhookEventsOrThrow(deps, subscription, { deferWindowUnread: true });
+    // This run's replay, or one another run finished, may have replaced the reference this event matched.
+    const refreshed = await resolveProjectionContextForProviderState(deps, {
+        provider: providerName,
+        state,
+        checkoutReferenceId: event.checkoutReferenceId
+    });
+    if (!refreshed) {
+        // The event is retained, never applied to the subscription it matched nor used to bootstrap another.
+        await storeUnlinkedWebhookEvent(deps, providerName, event, {
+            providerReference: (state.providerSubscriptionId ?? state.providerChargeId),
+            reason: 'provider_reference_replaced',
+            metadataBillingAccountId: readBillingAccountMetadata(event, state)
         });
+        if (windowUnread) {
+            // The replay that replaced the reference closed the window, so the unread event is now skipped;
+            // this delivery's redelivery would no longer reach the subscription, so it is replayed here.
+            await replayUnlinkedWebhookEventsOrThrow(deps, subscription);
+        }
+        return null;
+    }
+    const linkedBefore = refreshed.subscription;
+    const applied = await applyParsedWebhookEvent(deps, providerName, event, refreshed);
+    // An event that adds a provider reference links the events stored for it, including an event
+    // skipped as older than the subscription's state, which still links its missing references.
+    const linkedAfter = applied?.subscription ?? (linkedBefore ? await getSubscriptionById(deps, linkedBefore.id) : null);
+    const replayAgain = linkedAfter ?? linkedBefore;
+    // A newer event closes the window, so the unread event is then skipped; one still unread fails this
+    // delivery. One on a reference this event replaced was recorded as replaced by its write.
+    if (replayAgain && (windowUnread || (linkedAfter && addsProviderReference(linkedBefore, linkedAfter)))) {
+        await replayUnlinkedWebhookEventsOrThrow(deps, replayAgain);
     }
+    return applied;
+}
+async function applyParsedWebhookEvent(deps, providerName, event, projection) {
     if (projection.subscription &&
         event.occurredAt &&
-        isProviderEventOlderThanSubscription(projection.subscription, event.occurredAt)) {
+        orderProviderEvent(projection.subscription, event.occurredAt) === 'skip') {
+        await linkSkippedEventReferences(deps, projection.subscription, event.billingState);
         deps.metrics.track('reconciliation.event.skipped', {
             provider: providerName,
             providerEventId: event.providerEventId,
@@ -2282,7 +3148,9 @@ async function processParsedWebhookEvent(deps, providerName, event) {
         checkoutSession: projection.checkoutSession ?? undefined,
         subscription: projection.subscription ?? undefined,
         state: event.billingState,
-        occurredAt: event.occurredAt
+        occurredAt: event.occurredAt,
+        // The provider event keys its lifecycle entry, so a delivery and a replay of it record it once.
+        providerEventId: event.providerEventId
     });
     if (!applied) {
         deps.metrics.track('reconciliation.event.skipped', {
@@ -2293,33 +3161,835 @@ async function processParsedWebhookEvent(deps, providerName, event) {
     }
     return applied;
 }
-async function resolveProviderEventPriceReference(deps, provider, event, subscription) {
-    const normalizedType = event.type.toLowerCase();
-    const schedulingOnly = normalizedType.includes('change_renewal_pref');
-    if (!schedulingOnly) {
-        const raw = asRecord(event.billingState?.raw);
-        const references = [
-            event.priceId,
-            raw ? readString(raw, 'product_id') : null,
-            raw ? readString(raw, 'productId') : null,
-            raw ? readString(raw, 'price_id') : null,
-            raw ? readString(raw, 'priceId') : null
-        ];
-        for (const reference of references) {
-            if (!reference) {
-                continue;
-            }
-            const resolved = findCatalogPriceReference(deps.catalog, provider, reference);
-            if (resolved) {
-                return resolved;
-            }
-        }
+/**
+ * Handles a verified event whose provider reference matches no local
+ * subscription or checkout. Provider metadata naming an existing billing
+ * account bootstraps the subscription from the provider record; any other
+ * event is stored as unlinked, so the webhook is acknowledged and the event is
+ * replayed once the reference is linked.
+ */
+async function bootstrapOrStoreUnlinkedWebhookEvent(deps, providerName, event, state) {
+    const providerReference = state.providerSubscriptionId ?? state.providerChargeId;
+    if (!providerReference) {
+        deps.metrics.track('reconciliation.event.skipped', {
+            provider: providerName,
+            providerEventId: event.providerEventId,
+            reason: 'provider_reference_missing'
+        });
+        return { handled: null };
     }
-    if (!subscription || (!normalizedType.includes('renew') && !normalizedType.includes('plan_changed'))) {
-        return null;
+    const metadataBillingAccountId = readBillingAccountMetadata(event, state);
+    const existing = await findSubscriptionByProviderRef(deps, providerName, state.providerSubscriptionId, state.providerChargeId, event.checkoutReferenceId);
+    let reason;
+    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';
     }
-    const changeRequests = await deps.db.findMany({
-        model: TABLES.subscriptionChangeRequests,
+    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,
+            state,
+            checkoutReferenceId: event.checkoutReferenceId
+        });
+        if (projection) {
+            return { linked: projection };
+        }
+        // The subscription's billing account is gone; the reference must not be rebound to another one.
+        reason = 'billing_account_unavailable';
+    }
+    else if (await namesReplacedReference(deps, providerName, event, state)) {
+        // No subscription holds a reference a write replaced: the event never bootstraps another one.
+        reason = 'provider_reference_replaced';
+    }
+    else if (metadataBillingAccountId) {
+        const bootstrap = await bootstrapFromMetadata(deps, providerName, event, state, metadataBillingAccountId);
+        if (typeof bootstrap !== 'string') {
+            return bootstrap;
+        }
+        reason = bootstrap;
+    }
+    else {
+        reason = 'billing_account_metadata_missing';
+    }
+    await storeUnlinkedWebhookEvent(deps, providerName, event, {
+        providerReference,
+        reason,
+        metadataBillingAccountId
+    });
+    if (existing && !importPending) {
+        return { handled: null };
+    }
+    // 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);
+    }
+    return { handled: null };
+}
+/** Bootstraps the subscription for the account the metadata names, or returns why the event is stored unlinked. */
+async function bootstrapFromMetadata(deps, providerName, event, state, billingAccountId) {
+    const billingAccount = await getBillingAccountById(deps, billingAccountId);
+    if (!billingAccount) {
+        return 'billing_account_not_found';
+    }
+    const eventPrice = await resolveProviderEventPriceReference(deps, providerName, event, null);
+    if (!eventPrice) {
+        return 'price_not_found';
+    }
+    return {
+        handled: await bootstrapSubscriptionFromWebhookEvent(deps, providerName, event, {
+            billingAccount,
+            plan: eventPrice.plan,
+            price: eventPrice.price,
+            state
+        })
+    };
+}
+async function bootstrapSubscriptionFromWebhookEvent(deps, providerName, event, input) {
+    // A concurrent delivery that creates the same reference first makes this an ordered update.
+    const applied = await applyVerificationState(deps, {
+        billingAccount: input.billingAccount,
+        plan: input.plan,
+        price: input.price,
+        state: input.state,
+        occurredAt: event.occurredAt,
+        providerEventId: event.providerEventId
+    });
+    deps.metrics.track('webhook.subscription.bootstrapped', {
+        provider: providerName,
+        applied: Boolean(applied)
+    });
+    if (!applied) {
+        deps.metrics.track('reconciliation.event.skipped', {
+            provider: providerName,
+            providerEventId: event.providerEventId,
+            reason: 'out_of_order'
+        });
+    }
+    const subscription = applied?.subscription ??
+        (await findSubscriptionByProviderRef(deps, providerName, input.state.providerSubscriptionId, input.state.providerChargeId));
+    if (subscription) {
+        await replayUnlinkedWebhookEventsOrThrow(deps, subscription);
+    }
+    return applied;
+}
+async function storeUnlinkedWebhookEvent(deps, providerName, event, input) {
+    const now = deps.now();
+    const timestamp = toIsoString(now);
+    const record = {
+        id: buildUnlinkedWebhookEventId(providerName, event.providerEventId),
+        provider: providerName,
+        providerEventId: event.providerEventId,
+        providerReference: input.providerReference,
+        // The charge of an event that also names its subscription, so linking either reference finds it.
+        providerSecondaryReference: event.billingState?.providerChargeId && event.billingState.providerChargeId !== input.providerReference
+            ? event.billingState.providerChargeId
+            : null,
+        eventType: event.type,
+        occurredAt: event.occurredAt ?? null,
+        reason: input.reason,
+        metadataBillingAccountId: input.metadataBillingAccountId,
+        status: 'unlinked',
+        event: serializeParsedWebhookEvent(event),
+        replayClaimId: null,
+        replayClaimedAt: null,
+        replayedAt: null,
+        subscriptionId: null,
+        error: null,
+        expiresAt: toIsoString(new Date(now.getTime() + UNLINKED_WEBHOOK_EVENT_RETENTION_MS)),
+        createdAt: timestamp,
+        updatedAt: timestamp
+    };
+    try {
+        await deps.db.create({
+            model: TABLES.unlinkedWebhookEvents,
+            data: record,
+            namespace: deps.namespace
+        });
+    }
+    catch (error) {
+        // A redelivered or replayed event keeps the row it already has, but a replaced reference is recorded
+        // on it, so the event never bootstraps a subscription later.
+        if (!isDuplicateRecordError(error)) {
+            throw error;
+        }
+        if (input.reason === 'provider_reference_replaced') {
+            await deps.db.updateMany({
+                model: TABLES.unlinkedWebhookEvents,
+                where: [{ field: 'id', operator: 'eq', value: record.id }],
+                data: { reason: input.reason, updatedAt: timestamp },
+                namespace: deps.namespace
+            });
+        }
+        return;
+    }
+    deps.metrics.track('webhook.event.unlinked', {
+        provider: providerName,
+        reason: input.reason
+    });
+    await purgeExpiredUnlinkedWebhookEvents(deps, timestamp);
+}
+async function purgeExpiredUnlinkedWebhookEvents(deps, timestamp) {
+    try {
+        await deps.db.deleteMany({
+            model: TABLES.unlinkedWebhookEvents,
+            where: [{ field: 'expiresAt', operator: 'lt', value: timestamp }],
+            namespace: deps.namespace
+        });
+    }
+    catch (error) {
+        // Retention cleanup must not make the provider redeliver an event that is already stored.
+        deps.metrics.track('webhook.unlinked.purge_failed', {
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Applies unexpired unlinked events for the subscription's provider references
+ * in provider event-time order, as one ordered queue. When an applied or
+ * skipped event gives the subscription a provider reference, including one it
+ * held earlier in the run, the events stored for that reference (as primary or
+ * secondary reference) are merged into the queue in order before the next
+ * event, so an event naming a reference the subscription held only between two
+ * replayed events is still found. An event
+ * older than the subscription's current provider state (the last applied
+ * event, or a live provider read) is marked skipped. An event that no longer
+ * resolves to a subscription, because an earlier replayed event replaced its
+ * reference, stays unlinked with reason `provider_reference_replaced` and the
+ * replay continues past it. Every write that drops a reference records it as
+ * replaced (`recordReplacedProviderReferences`) and marks the events still
+ * unlinked on it, as does the end of the pass for one held during it and lost
+ * since; they no longer count as left at the bound. An event inside a
+ * committed mutation's window whose provider read fails (no queue) stays
+ * unlinked with the error, the replay continues, and the operation fails
+ * afterwards so it is retried. A
+ * replay stops at the first event another replay holds or that fails to apply,
+ * leaving it and later events for the next replay, so the order is kept.
+ */
+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);
+    for (let processed = 0; processed < UNLINKED_WEBHOOK_EVENT_REPLAY_MAX_EVENTS; processed += 1) {
+        const candidate = queue.next();
+        if (!candidate) {
+            break;
+        }
+        const step = await replayUnlinkedWebhookEvent(deps, candidate, result);
+        if (step === 'stopped') {
+            result.pending = queue.remaining() + 1;
+            break;
+        }
+        if (step === 'continue') {
+            // Left unlinked (or finished elsewhere): it is queued again if its reference is regained.
+            queue.release(candidate);
+        }
+        // Applied events, skipped ones that linked a missing reference, and events another run finished
+        // (which may have stopped before replaying what they linked) can add a reference.
+        const current = await getSubscriptionById(deps, subscription.id);
+        if (current) {
+            latest = current;
+            await queue.discover(current);
+        }
+    }
+    // Events on a reference held earlier in the pass and lost since (including to another run) are
+    // marked replaced; they are no longer replayable.
+    const latestReferences = providerReferencesOf(latest);
+    const lost = queue.heldReferences().filter((reference) => !latestReferences.includes(reference));
+    await recordReplacedReferenceEvents(deps, subscription.provider, lost, latestReferences);
+    // An unread event on a reference the subscription no longer holds is recorded as replaced, not retried.
+    result.windowUnread = result.unreadRows?.find((unread) => namesAnyReference(unread.row, latestReferences));
+    const remaining = queue.remaining(latestReferences);
+    if (!result.held && !result.failure && remaining > 0) {
+        // The bound was reached with replayable events left: the replay is unfinished, so the operation is retried.
+        result.pending = remaining;
+        result.bounded = true;
+    }
+    if (result.applied > 0 || result.skipped > 0) {
+        deps.metrics.track('webhook.unlinked.replayed', {
+            provider: subscription.provider,
+            applied: result.applied,
+            skipped: result.skipped
+        });
+    }
+    return result;
+}
+/**
+ * The ordered replay queue. `discover` merges the unexpired events stored for
+ * every reference the subscription gained since the previous discovery (a
+ * first gain or a regain); `release` lets a visited event that stayed unlinked
+ * be queued again. `heldReferences` lists every reference seen in the pass.
+ */
+function createUnlinkedReplayQueue(deps, provider) {
+    const timestamp = toIsoString(deps.now());
+    let observed = new Set();
+    const held = new Set();
+    const queued = new Set();
+    let pending = [];
+    return {
+        async discover(subscription) {
+            const current = providerReferencesOf(subscription);
+            const gained = current.filter((reference) => !observed.has(reference));
+            observed = new Set(current);
+            current.forEach((reference) => held.add(reference));
+            if (gained.length === 0) {
+                return;
+            }
+            const found = await findUnlinkedWebhookEventsForReferences(deps, provider, gained, timestamp);
+            const added = found.filter((row) => !queued.has(row.id));
+            added.forEach((row) => queued.add(row.id));
+            pending = [...pending, ...added].sort(compareUnlinkedWebhookEvents);
+        },
+        release: (row) => queued.delete(row.id),
+        /** Every reference the subscription held during the pass. */
+        heldReferences: () => [...held],
+        next: () => pending.shift(),
+        /** Queued events, or with `references` only those naming one: the ones a later replay still finds. */
+        remaining: (references) => references ? pending.filter((row) => namesAnyReference(row, references)).length : pending.length
+    };
+}
+/**
+ * Marks every unfinished event stored for a reference a subscription dropped,
+ * and naming none it kept, with reason `provider_reference_replaced`, whatever
+ * it was left as (window-unread, unresolved, not visited, or claimed by a
+ * replay run that may never release it). The recorded reference, not this
+ * reason, keeps such an event from bootstrapping. Only the reason (and an
+ * unclaimed event's last error) is written, never on an event another run
+ * finished, so a run holding the event
+ * keeps its claim. A regain still replays it, since discovery ignores the
+ * reason, as does the subscription that holds a reference it names.
+ */
+async function recordReplacedReferenceEvents(deps, provider, dropped, kept) {
+    if (dropped.length === 0) {
+        return;
+    }
+    const timestamp = toIsoString(deps.now());
+    const rows = await findUnlinkedWebhookEventsForReferences(deps, provider, dropped, timestamp);
+    const stale = rows.filter((row) => row.reason !== 'provider_reference_replaced' && !namesAnyReference(row, kept));
+    const replaced = { reason: 'provider_reference_replaced', updatedAt: timestamp };
+    const record = (row, statuses, data) => deps.db.updateMany({
+        model: TABLES.unlinkedWebhookEvents,
+        where: [
+            { field: 'id', operator: 'eq', value: row.id },
+            { field: 'status', operator: 'in', value: statuses }
+        ],
+        data,
+        namespace: deps.namespace
+    });
+    // An unclaimed event also drops its last replay error; a claimed one gets only the reason.
+    await Promise.all(stale.map(async (row) => {
+        if ((await record(row, ['unlinked'], { ...replaced, error: null })) === 0) {
+            await record(row, ['unlinked', 'replaying'], replaced);
+        }
+    }));
+}
+/**
+ * Before a write from `before` to `after`, records each reference it drops, and
+ * each one `before` has pending that `after` does not hold, as replaced
+ * (`recordReplacedProviderReferences`), then marks the retained events on them.
+ * A failure throws, except during a committed provider mutation, which is never
+ * failed by it: the references it could not record are returned, and its write
+ * saves them pending (`withPendingReplacements`). Pending references are
+ * recorded here before the caller's write clears them, so a guard that reads
+ * pending and then recorded references never misses one
+ * (`namesReplacedReference`).
+ */
+async function recordDroppedReferences(deps, before, after, committed) {
+    const kept = providerReferencesOf(after);
+    const dropped = [...new Set([...providerReferencesOf(before), ...pendingReplacedReferencesOf(before)])].filter((reference) => !kept.includes(reference));
+    if (dropped.length === 0) {
+        return [];
+    }
+    try {
+        await recordReplacedProviderReferences(deps, before, dropped);
+    }
+    catch (error) {
+        if (!committed) {
+            throw error;
+        }
+        return dropped;
+    }
+    try {
+        await recordReplacedReferenceEvents(deps, before.provider, dropped, kept);
+    }
+    catch (error) {
+        // Once the reference is recorded, the events' reason is informational.
+        if (!committed) {
+            throw error;
+        }
+    }
+    return [];
+}
+/**
+ * Records references a subscription dropped in `replacedProviderReferences`,
+ * one row per provider and reference, naming the subscription that dropped it
+ * last. While no subscription holds the reference, no event naming it, with
+ * any event id or billing account metadata, bootstraps a subscription.
+ */
+async function recordReplacedProviderReferences(deps, subscription, references) {
+    const timestamp = toIsoString(deps.now());
+    const data = { subscriptionId: subscription.id, billingAccountId: subscription.billingAccountId, replacedAt: timestamp, updatedAt: timestamp };
+    await Promise.all(references.map(async (providerReference) => {
+        const id = `rpr_${subscription.provider}_${Buffer.from(providerReference).toString('base64url')}`;
+        const update = () => deps.db.updateMany({
+            model: TABLES.replacedProviderReferences,
+            where: [{ field: 'id', operator: 'eq', value: id }],
+            data,
+            namespace: deps.namespace
+        });
+        if ((await update()) > 0) {
+            return;
+        }
+        try {
+            await deps.db.create({
+                model: TABLES.replacedProviderReferences,
+                data: { id, provider: subscription.provider, providerReference, ...data, createdAt: timestamp },
+                namespace: deps.namespace
+            });
+        }
+        catch (error) {
+            // A concurrent write recorded it first.
+            if (!isDuplicateRecordError(error)) {
+                throw error;
+            }
+            await update();
+        }
+    }));
+}
+/** The references a subscription's write saved pending, without any it holds again. */
+function pendingReplacedReferencesOf(subscription) {
+    const pending = subscription.metadata?.[PENDING_REPLACED_REFERENCES_METADATA_KEY];
+    const held = new Set(providerReferencesOf(subscription));
+    return Array.isArray(pending)
+        ? pending.filter((reference) => typeof reference === 'string' && !held.has(reference))
+        : [];
+}
+/** A write's metadata and flag for the references it saves pending; both are cleared once none are. */
+function withPendingReplacements(metadata, pending) {
+    const { [PENDING_REPLACED_REFERENCES_METADATA_KEY]: _previous, ...rest } = metadata ?? {};
+    return pending.length > 0
+        ? { metadata: { ...rest, [PENDING_REPLACED_REFERENCES_METADATA_KEY]: pending }, replacedReferencesPending: true }
+        : { metadata: rest, replacedReferencesPending: null };
+}
+/**
+ * Whether an event that resolves to no subscription names a replaced
+ * reference, whatever its event id or the account its metadata names: one a
+ * subscription write dropped and recorded, one a committed mutation's write
+ * saved pending (any subscription of the provider), or the one it was
+ * retained on when a replay replaced it. A reference a subscription holds
+ * again resolves to it first. Only bootstrap is gated by it.
+ *
+ * Linearization contract with the writers: a write that drops a held
+ * reference either records it (`recordDroppedReferences`) before the write or
+ * saves it pending in that same write; a later write records a pending
+ * reference before its write clears the pending flag; recorded references are
+ * never deleted. The reads therefore run one after another in the opposite
+ * order, after the caller found no holder: pending, then recorded, then the
+ * retained event. A writer that clears pending between them has already
+ * recorded the reference, so one of the reads sees it.
+ */
+async function namesReplacedReference(deps, provider, event, state) {
+    const references = [state.providerSubscriptionId, state.providerChargeId].filter((reference) => typeof reference === 'string' && reference.length > 0);
+    const named = new Set(references);
+    if (named.size > 0) {
+        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) => pendingReplacedReferencesOf(subscription).some((reference) => named.has(reference)))) {
+            return true;
+        }
+        const replaced = await deps.db.findMany({
+            model: TABLES.replacedProviderReferences,
+            where: [
+                { field: 'provider', operator: 'eq', value: provider },
+                { field: 'providerReference', operator: 'in', value: references }
+            ],
+            namespace: deps.namespace
+        });
+        if (replaced.length > 0) {
+            return true;
+        }
+    }
+    const retained = await deps.db.findOne({
+        model: TABLES.unlinkedWebhookEvents,
+        where: [{ field: 'id', operator: 'eq', value: buildUnlinkedWebhookEventId(provider, event.providerEventId) }],
+        namespace: deps.namespace
+    });
+    return retained?.reason === 'provider_reference_replaced';
+}
+function namesAnyReference(row, references) {
+    return [row.providerReference, row.providerSecondaryReference].some((reference) => typeof reference === 'string' && references.includes(reference));
+}
+async function findUnlinkedWebhookEventsForReferences(deps, provider, references, timestamp) {
+    const byField = await Promise.all(['providerReference', 'providerSecondaryReference'].map((field) => deps.db.findMany({
+        model: TABLES.unlinkedWebhookEvents,
+        where: [
+            { field: 'provider', operator: 'eq', value: provider },
+            { field, operator: 'in', value: references },
+            { field: 'status', operator: 'in', value: ['unlinked', 'replaying'] }
+        ],
+        namespace: deps.namespace
+    })));
+    const rows = new Map(byField.flat().map((row) => [row.id, row]));
+    return [...rows.values()].filter((row) => row.expiresAt > timestamp);
+}
+/**
+ * Claims and applies one retained event, then finishes or releases its row.
+ * `finished`: applied or skipped; `continue`: finished by another run, or
+ * displaced, unresolved or window-unread and left unlinked; `stopped`: held by
+ * another run or failed.
+ * The caller looks for newly linked references after every step but `stopped`.
+ */
+async function replayUnlinkedWebhookEvent(deps, candidate, result) {
+    const claimId = deps.generateId('uwr');
+    const claim = await claimUnlinkedWebhookEvent(deps, candidate, claimId);
+    if (claim === 'finished') {
+        return 'continue';
+    }
+    if (claim === 'held') {
+        result.held = true;
+        return 'stopped';
+    }
+    let outcome = null;
+    let failure = null;
+    try {
+        outcome = await applyUnlinkedWebhookEvent(deps, candidate);
+    }
+    catch (error) {
+        // Stop on any failure, whatever its message: a later event must not advance past this one.
+        failure = errorMessage(error);
+        result.failure = { error };
+    }
+    const finishedAt = toIsoString(deps.now());
+    await deps.db.updateMany({
+        model: TABLES.unlinkedWebhookEvents,
+        where: [
+            { field: 'id', operator: 'eq', value: candidate.id },
+            { field: 'replayClaimId', operator: 'eq', value: claimId }
+        ],
+        data: unlinkedReplayRowUpdate(outcome, failure, finishedAt),
+        namespace: deps.namespace
+    });
+    if (!outcome) {
+        deps.metrics.track('webhook.unlinked.replay_stopped', {
+            provider: candidate.provider,
+            providerEventId: candidate.providerEventId,
+            reason: 'error'
+        });
+        return 'stopped';
+    }
+    if (outcome.kind === 'replayed' || outcome.kind === 'skipped') {
+        result[outcome.kind === 'replayed' ? 'applied' : 'skipped'] += 1;
+        return 'finished';
+    }
+    if (outcome.kind === 'window_unread') {
+        // Retained with its error; the operation fails after the pass, so its retry reads the provider again.
+        result.unreadRows = [...(result.unreadRows ?? []), { row: candidate, error: outcome.error }];
+    }
+    // A displaced event, delivered in order, would have been stored unlinked as well, so it stays
+    // unlinked (and replays if its reference is linked again) and does not hold back later events.
+    deps.metrics.track('webhook.unlinked.replay_unresolved', {
+        provider: candidate.provider,
+        providerEventId: candidate.providerEventId,
+        reason: outcome.kind
+    });
+    return 'continue';
+}
+/** Finishes a replayed or skipped row, or releases it as unlinked with its error and, if displaced, reason. */
+function unlinkedReplayRowUpdate(outcome, failure, finishedAt) {
+    const released = { replayClaimId: null, replayClaimedAt: null, updatedAt: finishedAt };
+    if (outcome?.kind === 'replayed' || outcome?.kind === 'skipped') {
+        return { ...released, status: outcome.kind, subscriptionId: outcome.subscriptionId, replayedAt: finishedAt, error: null };
+    }
+    return {
+        ...released,
+        status: 'unlinked',
+        error: outcome?.kind === 'window_unread' ? errorMessage(outcome.error) : failure,
+        // A replaced reference is recorded, so the event never bootstraps another subscription later.
+        ...(outcome?.kind === 'displaced' ? { reason: 'provider_reference_replaced' } : {})
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function providerReferencesOf(subscription) {
+    return [...new Set([subscription.providerSubscriptionId, subscription.providerChargeId])].filter((reference) => typeof reference === 'string' && reference.length > 0);
+}
+/** Whether a write gave the subscription a provider reference it did not have, linking events stored for it. */
+function addsProviderReference(before, after) {
+    const previous = before ? providerReferencesOf(before) : [];
+    return providerReferencesOf(after).some((reference) => !previous.includes(reference));
+}
+async function applyUnlinkedWebhookEvent(deps, row) {
+    const event = deserializeParsedWebhookEvent(row.event);
+    const state = event?.billingState;
+    if (!event || !state) {
+        return { kind: 'unresolved' };
+    }
+    const projection = await resolveProjectionContextForProviderState(deps, {
+        provider: row.provider,
+        state,
+        checkoutReferenceId: event.checkoutReferenceId
+    });
+    if (!projection?.subscription) {
+        // The row was found by a reference of the subscription, which an event replayed before it replaced.
+        return { kind: 'displaced' };
+    }
+    // An event without a provider time is ordered by when it was stored, through the same ordered write.
+    const occurredAt = event.occurredAt ?? row.createdAt;
+    let applied;
+    try {
+        applied = await applyParsedWebhookEvent(deps, row.provider, { ...event, occurredAt, billingState: state }, projection);
+    }
+    catch (error) {
+        // An unread event inside a mutation window stays retained without holding back the events after it.
+        if (isWindowReadFailure(error)) {
+            return { kind: 'window_unread', error };
+        }
+        throw error;
+    }
+    return applied
+        ? { kind: 'replayed', subscriptionId: applied.subscription.id }
+        : { kind: 'skipped', subscriptionId: projection.subscription.id };
+}
+/**
+ * Claims a row for this replay run. `finished` means another run completed it
+ * since it was read; `held` means another run holds an unexpired claim on it,
+ * or released it after a failure, so it is not finished.
+ */
+async function claimUnlinkedWebhookEvent(deps, row, claimId) {
+    const claimTime = deps.now();
+    const where = [
+        { field: 'id', operator: 'eq', value: row.id },
+        { field: 'status', operator: 'eq', value: row.status }
+    ];
+    if (row.status === 'replaying') {
+        const previousClaimedAt = row.replayClaimedAt ? Date.parse(row.replayClaimedAt) : Number.NaN;
+        if (Number.isFinite(previousClaimedAt) &&
+            claimTime.getTime() - previousClaimedAt < UNLINKED_WEBHOOK_EVENT_REPLAY_LEASE_MS) {
+            return 'held';
+        }
+        where.push({ field: 'replayClaimId', operator: 'eq', value: row.replayClaimId ?? null });
+    }
+    const claimed = await deps.db.updateMany({
+        model: TABLES.unlinkedWebhookEvents,
+        where,
+        data: {
+            status: 'replaying',
+            replayClaimId: claimId,
+            replayClaimedAt: toIsoString(claimTime),
+            updatedAt: toIsoString(claimTime)
+        },
+        namespace: deps.namespace
+    });
+    if (claimed === 1) {
+        return 'claimed';
+    }
+    const current = await deps.db.findOne({
+        model: TABLES.unlinkedWebhookEvents,
+        where: [{ field: 'id', operator: 'eq', value: row.id }],
+        namespace: deps.namespace
+    });
+    return !current || current.status === 'replayed' || current.status === 'skipped' ? 'finished' : 'held';
+}
+function compareUnlinkedWebhookEvents(left, right) {
+    const leftTime = left.occurredAt ? parseProviderEventTime(left.occurredAt) : null;
+    const rightTime = right.occurredAt ? parseProviderEventTime(right.occurredAt) : null;
+    if (leftTime !== rightTime) {
+        // Events without a provider time cannot be ordered against timed ones and go last.
+        if (leftTime === null) {
+            return 1;
+        }
+        if (rightTime === null) {
+            return -1;
+        }
+        return leftTime - rightTime;
+    }
+    if (left.createdAt !== right.createdAt) {
+        return left.createdAt < right.createdAt ? -1 : 1;
+    }
+    if (left.id === right.id) {
+        return 0;
+    }
+    return left.id < right.id ? -1 : 1;
+}
+/**
+ * Replays and fails the operation that linked the reference unless every
+ * retained event for it is finished, so that operation is retried (a webhook
+ * receipt stays unprocessed and the provider redelivers it, a queued webhook
+ * job is retried after the replay lease expires, and checkout verification or
+ * restore can be called again). An event that could not be applied is
+ * released first and its error rethrown; an event another replay run still
+ * holds, including a run interrupted before it released the event, raises a
+ * lease conflict. An event inside a mutation window whose read failed raises
+ * that window-read error once the rest of the replay is done, unless its
+ * reference was replaced meanwhile or `deferWindowUnread` returns it for the
+ * caller to raise later.
+ */
+async function replayUnlinkedWebhookEventsOrThrow(deps, subscription, options = {}) {
+    const result = await replayUnlinkedWebhookEvents(deps, subscription);
+    if (result.failure) {
+        throw result.failure.error;
+    }
+    if (result.held) {
+        throw reconciliationLeaseConflict('Unlinked webhook events for this provider reference are being replayed');
+    }
+    if (result.bounded) {
+        throw unlinkedReplayBounded(result.applied + result.skipped > 0);
+    }
+    if (result.windowUnread && !options.deferWindowUnread) {
+        throw result.windowUnread.error;
+    }
+    return result;
+}
+const unlinkedReplayBoundErrors = new WeakSet();
+const productiveReplayBoundErrors = new WeakSet();
+/**
+ * An unfinished replay that reached its bound, reported as `bounded`. One that
+ * finished events (`productive`) is continued by a queue worker in a fresh
+ * message; otherwise, and without a queue, it is retried like a lease conflict.
+ */
+function unlinkedReplayBounded(productive) {
+    const error = reconciliationLeaseConflict('Unlinked webhook event replay reached its bound with events left');
+    unlinkedReplayBoundErrors.add(error);
+    if (productive) {
+        productiveReplayBoundErrors.add(error);
+    }
+    return error;
+}
+function isProductiveReplayBound(error) {
+    return typeof error === 'object' && error !== null && productiveReplayBoundErrors.has(error);
+}
+function replayDeferredReason(error) {
+    if (typeof error === 'object' && error !== null && unlinkedReplayBoundErrors.has(error)) {
+        return 'bounded';
+    }
+    return isReconciliationLeaseConflict(error) ? 'held' : 'error';
+}
+/**
+ * Applies state from a live provider read or a provider mutation response
+ * (checkout verification, restore, sync, cancel, change, resume, refund).
+ * `liveStateObservedAt` is when the provider call started: a read saves it as
+ * the subscription's provider-state time, and a state an event newer than it
+ * has superseded only links its references. A committed mutation is ordered by
+ * `committedAt`, when the provider call returned, instead. The retained unlinked events for the
+ * resulting reference set are then replayed every time, not only when this
+ * call added a reference, so a retry after an interrupted replay applies them;
+ * events older than the read are skipped. Returns the projection after replay.
+ *
+ * A read (verification, restore, sync) fails when the replay does not finish,
+ * so the read is retried. After a provider mutation has committed, the replay
+ * is best-effort (`onReplayDeferred` set): an unfinished replay is recorded and
+ * handed to `onReplayDeferred`, its events stay retained for the next webhook,
+ * sync or live read, and the mutation still returns its result, because
+ * retrying it would repeat the provider mutation.
+ */
+async function applyLiveProviderState(deps, input, options = {}) {
+    const result = await applyVerificationState(deps, input);
+    if (!options.onReplayDeferred) {
+        await replayUnlinkedWebhookEventsOrThrow(deps, result.subscription);
+        return refreshProjectionAfterReplay(deps, result);
+    }
+    await replayAfterCommittedMutation(deps, result, options.onReplayDeferred);
+    try {
+        return { ...(await refreshProjectionAfterReplay(deps, result)), providerStateRaced: result.providerStateRaced };
+    }
+    catch (error) {
+        // The provider mutation and its state are committed; a failed re-read returns the written state.
+        deps.metrics.track('webhook.unlinked.replay_refresh_failed', {
+            provider: result.subscription.provider,
+            subscriptionId: result.subscription.id,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return result;
+    }
+}
+/** A replay after a committed provider mutation that cannot finish now is deferred, never failing the mutation. */
+async function replayAfterCommittedMutation(deps, { subscription }, onReplayDeferred) {
+    try {
+        await replayUnlinkedWebhookEventsOrThrow(deps, subscription);
+    }
+    catch (error) {
+        deps.metrics.track('webhook.unlinked.replay_deferred', {
+            provider: subscription.provider,
+            subscriptionId: subscription.id,
+            reason: replayDeferredReason(error),
+            error: error instanceof Error ? error.message : String(error)
+        });
+        try {
+            await onReplayDeferred(subscription);
+        }
+        catch (deferError) {
+            deps.metrics.track('webhook.unlinked.replay_defer_failed', {
+                provider: subscription.provider,
+                subscriptionId: subscription.id,
+                error: deferError instanceof Error ? deferError.message : String(deferError)
+            });
+        }
+    }
+}
+/** Another run may have replayed events for these references since the write, so the state is read again. */
+async function refreshProjectionAfterReplay(deps, result) {
+    const subscription = (await getSubscriptionById(deps, result.subscription.id)) ?? result.subscription;
+    const entitlements = (await findEntitlementSnapshot(deps, subscription.billingAccountId)) ?? result.entitlements;
+    const checkoutSession = result.checkoutSession
+        ? ((await getCheckoutSession(deps, result.checkoutSession.checkoutSessionId)) ?? result.checkoutSession)
+        : undefined;
+    return { checkoutSession, subscription, entitlements };
+}
+function readBillingAccountMetadata(event, state) {
+    const stateRaw = asRecord(state.raw);
+    const candidates = [
+        asRecord(stateRaw?.metadata),
+        asRecord(event.raw.metadata),
+        asRecord(asRecord(event.raw.data)?.metadata)
+    ];
+    for (const metadata of candidates) {
+        const value = metadata ? readString(metadata, BILLING_ACCOUNT_METADATA_KEY) : null;
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function buildUnlinkedWebhookEventId(provider, providerEventId) {
+    return `uwe_${provider}_${Buffer.from(providerEventId).toString('base64url')}`;
+}
+async function resolveProviderEventPriceReference(deps, provider, event, subscription) {
+    const normalizedType = event.type.toLowerCase();
+    const schedulingOnly = normalizedType.includes('change_renewal_pref');
+    if (!schedulingOnly) {
+        const raw = asRecord(event.billingState?.raw);
+        // A provider record may carry its product on the transaction it describes (Apple).
+        const records = [raw, asRecord(raw?.transaction)];
+        const references = [
+            event.billingState?.providerProductId,
+            event.priceId,
+            ...records.flatMap((record) => record ? ['product_id', 'productId', 'price_id', 'priceId'].map((key) => readString(record, key)) : [])
+        ];
+        const resolved = findCatalogPriceReference(deps.catalog, provider, references, subscription?.priceId);
+        if (resolved) {
+            return resolved;
+        }
+    }
+    if (!subscription || (!normalizedType.includes('renew') && !normalizedType.includes('plan_changed'))) {
+        return null;
+    }
+    const changeRequests = await deps.db.findMany({
+        model: TABLES.subscriptionChangeRequests,
         where: [
             { field: 'subscriptionId', operator: 'eq', value: subscription.id },
             { field: 'effectiveAt', operator: 'eq', value: 'next_renewal' },
@@ -2331,12 +4001,26 @@ async function resolveProviderEventPriceReference(deps, provider, event, subscri
     const latest = changeRequests[0];
     return latest ? requirePriceReference(deps.catalog, latest.targetPriceId) : null;
 }
-function findCatalogPriceReference(catalog, provider, reference) {
-    for (const plan of catalog.plans) {
-        const price = plan.prices.find((candidate) => candidate.provider === provider &&
-            (candidate.priceId === reference || candidate.providerProductId === reference));
-        if (price) {
-            return { plan, price };
+/**
+ * The catalog price the references name: an exact catalog price id first, then
+ * a provider product id. A product several prices share names the current
+ * price if it is one of them, else the first of them when they are all in one
+ * plan; across plans it names none, so the caller keeps its stored selection.
+ */
+function findCatalogPriceReference(catalog, provider, references, currentPriceId) {
+    const prices = catalog.plans.flatMap((plan) => plan.prices.filter((price) => price.provider === provider).map((price) => ({ plan, price })));
+    const named = references.filter((reference) => Boolean(reference));
+    for (const reference of named) {
+        const exact = prices.find((candidate) => candidate.price.priceId === reference);
+        if (exact) {
+            return exact;
+        }
+    }
+    for (const reference of named) {
+        const products = prices.filter((candidate) => candidate.price.providerProductId === reference);
+        const current = products.find((candidate) => candidate.price.priceId === currentPriceId);
+        if (current || new Set(products.map((candidate) => candidate.plan.planKey)).size === 1) {
+            return current ?? products[0];
         }
     }
     return null;
@@ -2421,9 +4105,21 @@ function readString(record, key) {
     const value = record[key];
     return typeof value === 'string' && value.length > 0 ? value : null;
 }
+function readProviderStateOccurredAt(subscription) {
+    const metadata = asRecord(subscription?.metadata);
+    return metadata ? readString(metadata, PROVIDER_EVENT_OCCURRED_AT_METADATA_KEY) : null;
+}
+/** The later of two provider-state times; an unparsable current time is replaced. */
+function laterProviderEventTime(current, candidate) {
+    const currentTime = current ? parseProviderEventTime(current) : null;
+    const candidateTime = parseProviderEventTime(candidate);
+    if (currentTime === null || candidateTime === null) {
+        return currentTime === null ? candidate : current;
+    }
+    return candidateTime > currentTime ? candidate : current;
+}
 function isProviderEventOlderThanSubscription(subscription, occurredAt) {
-    const metadata = asRecord(subscription.metadata);
-    const lastOccurredAt = metadata ? readString(metadata, PROVIDER_EVENT_OCCURRED_AT_METADATA_KEY) : null;
+    const lastOccurredAt = readProviderStateOccurredAt(subscription);
     if (!lastOccurredAt) {
         return false;
     }
@@ -2431,6 +4127,94 @@ function isProviderEventOlderThanSubscription(subscription, occurredAt) {
     const currentTime = parseProviderEventTime(lastOccurredAt);
     return incomingTime !== null && currentTime !== null && incomingTime < currentTime;
 }
+/**
+ * Orders an event against the subscription's provider state. A newer event is
+ * applied and an older one skipped; one at the same time is applied. An event
+ * inside the open window of the committed provider mutation that set that
+ * state (after the provider call started, up to and including when it
+ * returned) cannot be ordered against the mutation and is never applied over
+ * it: the subscription is reconciled with a provider read instead.
+ */
+function orderProviderEvent(subscription, occurredAt) {
+    const startedAt = readMutationStartedAt(subscription);
+    const stateAt = readProviderStateOccurredAt(subscription);
+    const startTime = startedAt ? parseProviderEventTime(startedAt) : null;
+    const stateTime = stateAt ? parseProviderEventTime(stateAt) : null;
+    const incomingTime = parseProviderEventTime(occurredAt);
+    if (startTime !== null && stateTime !== null && incomingTime !== null && incomingTime > startTime && incomingTime <= stateTime) {
+        return 'reconcile';
+    }
+    return isProviderEventOlderThanSubscription(subscription, occurredAt) ? 'skip' : 'apply';
+}
+function readMutationStartedAt(subscription) {
+    const metadata = asRecord(subscription.metadata);
+    return metadata ? readString(metadata, PROVIDER_MUTATION_STARTED_AT_METADATA_KEY) : null;
+}
+const windowReadFailures = new WeakSet();
+/** No provider read succeeded for an event inside a committed mutation's window and no sync could be queued. */
+function windowReadFailed(cause) {
+    const error = createBillFnError({
+        code: 'BILLFN_PROVIDER_ERROR',
+        message: `Provider read for an event inside a committed mutation window failed: ${cause instanceof Error ? cause.message : String(cause)}`
+    });
+    windowReadFailures.add(error);
+    return error;
+}
+function isWindowReadFailure(error) {
+    return typeof error === 'object' && error !== null && windowReadFailures.has(error);
+}
+function withoutMutationWindow(metadata) {
+    if (!metadata || !(PROVIDER_MUTATION_STARTED_AT_METADATA_KEY in metadata)) {
+        return metadata;
+    }
+    const { [PROVIDER_MUTATION_STARTED_AT_METADATA_KEY]: _closed, ...rest } = metadata;
+    return rest;
+}
+/**
+ * Handles an event inside a committed mutation's window: links its missing
+ * references and reconciles the subscription with an inline provider read
+ * (`reconcileProviderState`). When the provider cannot be read, the committed
+ * mutation's state stands. The event is never applied over the mutation.
+ */
+async function reconcileMutationWindowEvent(deps, subscription, input) {
+    const linked = await linkSkippedEventReferences(deps, subscription, input.state);
+    const readable = Boolean(deps.reconcileProviderState) && typeof deps.providers[linked.provider]?.fetchSubscription === 'function';
+    deps.metrics.track(readable ? 'subscription.mutation.window_event' : 'subscription.mutation.window_event_unreconciled', {
+        provider: linked.provider,
+        subscriptionId: linked.id
+    });
+    if (readable) {
+        await deps.reconcileProviderState?.(linked, {
+            providerEventId: input.providerEventId,
+            selection: { plan: input.plan, price: input.price }
+        });
+    }
+}
+/**
+ * Closes the committed mutation window a reconcile read covered, once its
+ * effects are recorded; a newer mutation's window is left open.
+ */
+async function closeMutationWindow(deps, subscriptionId, startedAt) {
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+        const current = await getSubscriptionById(deps, subscriptionId);
+        const metadata = asRecord(current?.metadata);
+        if (!current || !metadata || !startedAt || readMutationStartedAt(current) !== startedAt) {
+            return;
+        }
+        const closed = {
+            ...current,
+            metadata: withoutMutationWindow(metadata),
+            updatedAt: nextSubscriptionUpdatedAt(deps.now(), current.updatedAt)
+        };
+        if (await writeOrderedSubscription(deps, current, closed)) {
+            return;
+        }
+    }
+    throw createBillFnError({
+        code: 'BILLFN_CONFLICT',
+        message: 'Unable to close the mutation window after multiple retries'
+    });
+}
 function nextSubscriptionUpdatedAt(now, previous) {
     const currentTime = now.getTime();
     const previousTime = previous ? Date.parse(previous) : Number.NaN;