@codelitdev/billing 0.3.0 → 0.4.1

package/dist/workflows/engine.js

@@ -64,6 +64,20 @@ export function createBilling(options) {
         store.noteProviderCall();
         return fn();
     }
+    /**
+     * Applies the provider's current subscription after a mutation, so read
+     * models reflect it before the webhook arrives. A failure is ignored: the
+     * webhook and reconciliation project the same state later.
+     */
+    async function readBackSubscription(sub) {
+        try {
+            const snapshot = await callProvider(() => provider(sub.provider).retrieveSubscription(sub.providerSubscriptionId));
+            await projectSnapshot(snapshot, {});
+        }
+        catch {
+            telemetry.event("readback.failed", { provider: sub.provider });
+        }
+    }
     async function publicCatalog() {
         if (options.mode === "oss")
             return null;
@@ -109,6 +123,10 @@ export function createBilling(options) {
                     return existing.revision;
                 }
                 const revisions = await store.listRevisions();
+                // Revision numbers are unique across providers.
+                if (revisions.some((revision) => revision.revision === options.requestedRevision)) {
+                    throw new BillingCompositionError("catalog_revision_used_by_another_provider");
+                }
                 const newer = revisions.find((revision) => revision.revision > options.requestedRevision);
                 if (newer) {
                     throw new BillingWorkflowError("catalog_changed", {
@@ -438,6 +456,35 @@ export function createBilling(options) {
         }
         return store.withTransaction(() => enqueueJobInTransaction(subject));
     }
+    /**
+     * Closes the payer's open checkout when they choose another offer. A
+     * subscription that still arrives for it marks it `conflicted`.
+     */
+    async function abandonSupersededCheckout(id) {
+        const latest = await store.findCheckoutById(id);
+        if (!latest)
+            return;
+        const decision = decideCheckoutTransition(latest.status, "abandoned", {
+            now: clock.now(),
+            expiresAt: latest.expiresAt,
+        });
+        if (!decision.allowed) {
+            throw new BillingWorkflowError("operation_conflicted");
+        }
+        const previous = latest.status;
+        latest.status = "abandoned";
+        latest.completedAt = clock.now();
+        latest.checkoutUrlEncrypted = null;
+        await store.saveCheckout(latest);
+        await requireAudit({
+            effectId: `checkout:${latest.id}:abandoned`,
+            actor: { kind: "user", id: latest.payerId },
+            previous: { status: previous },
+            next: { status: "abandoned" },
+            correlationIds: { attemptId: latest.attemptId },
+        });
+        telemetry.event("checkout.superseded", { attemptId: latest.attemptId });
+    }
     async function startCheckout(input) {
         if (options.mode === "oss") {
             throw new BillingWorkflowError("unsupported_operation");
@@ -473,8 +520,12 @@ export function createBilling(options) {
         if (existingSub && retainsPaidEntitlement(existingSub, clock.now())) {
             throw new BillingWorkflowError("active_subscription_exists");
         }
+        if (existingSub) {
+            // Paid access lapsed but the deadline batch has not run yet.
+            await releaseLapsedEntitlement(existingSub.id, "checkout");
+        }
         const adapter = provider(options.checkoutProvider);
-        const checkoutIdempotencyKey = `checkout:${input.entity.id}:${input.offerKey}:${catalog.revision.revision}`;
+        let checkoutIdempotencyKey = `checkout:${input.entity.id}:${input.offerKey}:${catalog.revision.revision}`;
         const resumable = await store.findResumableCheckout(input.entity.id);
         if (resumable?.providerCheckoutSessionId && resumable.payerId === input.payer.id) {
             try {
@@ -498,21 +549,32 @@ export function createBilling(options) {
                     throw error;
             }
         }
-        const liveCheckout = await store.findLiveCheckout(input.entity.id);
+        let liveCheckout = await store.findLiveCheckout(input.entity.id);
         let resumeAttempt;
+        // The payer's open checkout for another offer, replaced by this one.
+        let superseded;
+        const sameRequest = (attempt) => attempt.payerId === input.payer.id &&
+            attempt.offerKey === input.offerKey &&
+            attempt.catalogRevision === catalog.revision.revision;
         if (liveCheckout && liveCheckout.expiresAt.getTime() <= clock.now().getTime()) {
             liveCheckout.status = "expired";
             liveCheckout.completedAt = clock.now();
             liveCheckout.checkoutUrlEncrypted = null;
             await store.saveCheckout(liveCheckout);
-            resumeAttempt = liveCheckout;
+            if (sameRequest(liveCheckout))
+                resumeAttempt = liveCheckout;
+            liveCheckout = undefined;
         }
         else if (liveCheckout) {
-            if (liveCheckout.payerId !== input.payer.id ||
-                liveCheckout.offerKey !== input.offerKey ||
-                liveCheckout.catalogRevision !== catalog.revision.revision) {
+            if (liveCheckout.payerId !== input.payer.id) {
                 throw new BillingWorkflowError("checkout_pending");
             }
+            if (!sameRequest(liveCheckout)) {
+                superseded = liveCheckout;
+                liveCheckout = undefined;
+            }
+        }
+        if (liveCheckout) {
             if (liveCheckout.status === "open" &&
                 liveCheckout.checkoutUrlEncrypted &&
                 options.sensitiveValues) {
@@ -527,6 +589,11 @@ export function createBilling(options) {
         if (!resumeAttempt) {
             const existing = await store.findCheckoutByIdempotencyKey(checkoutIdempotencyKey);
             if (existing &&
+                (existing.status === "abandoned" || existing.status === "conflicted")) {
+                // A replaced checkout keeps its key, so the new attempt needs another.
+                checkoutIdempotencyKey = `${checkoutIdempotencyKey}:${newId()}`;
+            }
+            else if (existing &&
                 existing.payerId === input.payer.id &&
                 existing.offerKey === input.offerKey &&
                 existing.catalogRevision === catalog.revision.revision) {
@@ -602,6 +669,7 @@ export function createBilling(options) {
                     catalogKey: liveCheckout.offerKey,
                     trialDays: input.trialDays ?? 0,
                     idempotencyKey: liveCheckout.idempotencyKey,
+                    expiresAt: liveCheckout.expiresAt,
                 }));
                 if (options.sensitiveValues) {
                     const encrypted = await options.sensitiveValues.encrypt(remote.checkoutUrl);
@@ -634,6 +702,8 @@ export function createBilling(options) {
         else {
             try {
                 attempt = await store.withTransaction(async () => {
+                    if (superseded)
+                        await abandonSupersededCheckout(superseded.id);
                     const row = {
                         id: newId(),
                         attemptId: store.newAttemptId(),
@@ -667,23 +737,26 @@ export function createBilling(options) {
             catch (error) {
                 const raced = (await store.findLiveCheckout(input.entity.id)) ??
                     (await store.findCheckoutByIdempotencyKey(checkoutIdempotencyKey));
-                if (!raced ||
-                    raced.payerId !== input.payer.id ||
-                    raced.offerKey !== input.offerKey ||
-                    raced.catalogRevision !== catalog.revision.revision) {
+                if (!raced || error instanceof BillingWorkflowError)
                     throw error;
+                if (!sameRequest(raced)) {
+                    throw new BillingWorkflowError("checkout_pending");
                 }
                 attempt = raced;
             }
         }
         const reopenExpiredOrUnpaidCompleted = attempt.status === "expired" || attempt.status === "completed";
         if (reopenExpiredOrUnpaidCompleted) {
-            attempt.status = "creating";
-            attempt.completedAt = null;
-            attempt.checkoutUrlEncrypted = null;
-            attempt.lastError = null;
-            attempt.expiresAt = new Date(clock.now().getTime() + 60 * 60 * 1000);
-            await store.saveCheckout(attempt);
+            await store.withTransaction(async () => {
+                if (superseded)
+                    await abandonSupersededCheckout(superseded.id);
+                attempt.status = "creating";
+                attempt.completedAt = null;
+                attempt.checkoutUrlEncrypted = null;
+                attempt.lastError = null;
+                attempt.expiresAt = new Date(clock.now().getTime() + 60 * 60 * 1000);
+                await store.saveCheckout(attempt);
+            });
         }
         const providerCheckoutKey = reopenExpiredOrUnpaidCompleted
             ? `${attempt.idempotencyKey}:reopen:${attempt.id}`
@@ -713,6 +786,7 @@ export function createBilling(options) {
                 catalogKey: item.offerKey,
                 trialDays: input.trialDays ?? 0,
                 idempotencyKey: providerCheckoutKey,
+                expiresAt: attempt.expiresAt,
             }));
             const encrypted = options.sensitiveValues
                 ? await options.sensitiveValues.encrypt(remote.checkoutUrl)
@@ -848,6 +922,15 @@ export function createBilling(options) {
             !adapter.capabilities.proratedPlanChanges) {
             throw new BillingWorkflowError("plan_change_not_supported");
         }
+        if (input.effectiveAt === "next_billing_date" &&
+            adapter.capabilities.immediatePlanChangesOnly) {
+            throw new BillingWorkflowError("plan_change_not_supported");
+        }
+        if (input.prorationMode === "do_not_bill" &&
+            target.price.interval !== sub.interval &&
+            adapter.capabilities.intervalChangesBillImmediately) {
+            throw new BillingWorkflowError("plan_change_not_supported");
+        }
         let providerProduct;
         try {
             providerProduct = await callProvider(() => adapter.retrieveProduct(target.price.providerProductId));
@@ -886,15 +969,18 @@ export function createBilling(options) {
         let attempt;
         try {
             attempt = await store.withTransaction(async () => {
+                const changeId = store.newChangeId();
                 const row = {
                     id: newId(),
-                    changeId: store.newChangeId(),
+                    changeId,
                     billableEntityId: input.entity.id,
                     subscriptionId: sub.id,
                     actorId: input.payer.id,
                     payerId: input.payer.id,
                     provider: sub.provider,
-                    idempotencyKey: `plan-change:${sub.id}:${input.offerKey}:${catalog.revision.revision}`,
+                    // One key per attempt: a later change back to the same offer is a
+                    // new request, while retries of this one reuse the stored key.
+                    idempotencyKey: `plan-change:${sub.id}:${input.offerKey}:${catalog.revision.revision}:${changeId}`,
                     currentCatalogRevision: sub.catalogRevision,
                     currentPriceEntryId: sub.priceEntryId,
                     currentPlan: sub.plan,
@@ -934,7 +1020,7 @@ export function createBilling(options) {
             const paymentUrl = remote.paymentUrl && options.sensitiveValues
                 ? await options.sensitiveValues.encrypt(remote.paymentUrl)
                 : null;
-            return await store.withTransaction(async () => {
+            const pending = await store.withTransaction(async () => {
                 const latest = (await store.findPlanChangeById(attempt.id)) ?? attempt;
                 const decision = decidePlanChangeTransition(latest.status, "pending");
                 if (!decision.allowed)
@@ -952,6 +1038,8 @@ export function createBilling(options) {
                 });
                 return latest;
             });
+            await readBackSubscription(sub);
+            return (await store.findPlanChangeById(pending.id)) ?? pending;
         }
         catch (error) {
             await enqueueJob({
@@ -981,7 +1069,7 @@ export function createBilling(options) {
         if (sub.payerId !== input.payer.id) {
             throw new BillingWorkflowError("payer_mismatch");
         }
-        if (sub.status === "cancelled") {
+        if (sub.status === "cancelled" || sub.cancelAtPeriodEnd) {
             return { accepted: true, subscriptionId: sub.id };
         }
         if (provider(sub.provider).capabilities.mutationRecovery.cancellation ===
@@ -990,7 +1078,7 @@ export function createBilling(options) {
         }
         await store.withTransaction(async () => {
             await requireAudit({
-                effectId: `cancellation:${sub.id}:requested`,
+                effectId: `cancellation:${sub.id}:${sub.providerVersion ?? "0"}:requested`,
                 actor: { kind: "user", id: input.payer.id },
                 previous: { status: sub.status },
                 next: { requested: "provider_cancel" },
@@ -1003,7 +1091,78 @@ export function createBilling(options) {
             });
         });
         try {
-            await callProvider(() => provider(sub.provider).cancelSubscription(sub.providerSubscriptionId, `cancel:${sub.id}`));
+            await callProvider(() => provider(sub.provider).cancelSubscription(sub.providerSubscriptionId, cancellationKey(sub)));
+        }
+        catch (error) {
+            if (error instanceof BillingWorkflowError)
+                throw error;
+            throw new BillingWorkflowError("provider_unavailable", {
+                retryable: true,
+            });
+        }
+        await readBackSubscription(sub);
+        return { accepted: true, subscriptionId: sub.id };
+    }
+    /**
+     * Clears a cancellation scheduled for the end of the paid period. Uses the
+     * `cancellation` grant, because it reverses that action.
+     */
+    async function resumeCancellation(input) {
+        if (options.mode === "oss") {
+            throw new BillingWorkflowError("unsupported_operation");
+        }
+        await consumeGrant(input.grant, "cancellation", {
+            kind: input.entity.kind,
+            id: input.entity.id,
+        }, input.payer.id);
+        const sub = await store.findEntitlementSubscription(input.entity.id);
+        // Some providers, such as Lemon Squeezy, report a scheduled cancellation
+        // as `cancelled` until the period ends; that one can still be resumed.
+        if (!sub ||
+            sub.status === "expired" ||
+            (sub.status === "cancelled" && !sub.cancelAtPeriodEnd)) {
+            throw new BillingWorkflowError("subscription_required");
+        }
+        if (sub.payerId !== input.payer.id) {
+            throw new BillingWorkflowError("payer_mismatch");
+        }
+        if (!sub.cancelAtPeriodEnd) {
+            return { accepted: true, subscriptionId: sub.id };
+        }
+        await store.withTransaction(async () => {
+            // A worker already sending the cancellation would cancel again after
+            // this resume, so the caller retries once that job has finished.
+            const running = await store.findLiveJob({
+                provider: sub.provider,
+                subscriptionId: sub.id,
+            });
+            if (running?.operation === "cancellation" &&
+                running.status === "processing" &&
+                running.leaseExpiresAt !== null &&
+                running.leaseExpiresAt.getTime() > clock.now().getTime()) {
+                throw new BillingWorkflowError("operation_conflicted", { retryable: true });
+            }
+            await requireAudit({
+                effectId: `resumption:${sub.id}:${sub.providerVersion ?? "0"}:requested`,
+                actor: { kind: "user", id: input.payer.id },
+                previous: { cancelAtPeriodEnd: true },
+                next: { requested: "provider_resume" },
+                correlationIds: { subscriptionId: sub.id },
+            });
+            // A pending cancellation retry must not cancel again after this. If the
+            // resume call below fails, reconciling reads back the provider's state
+            // and the caller can resume again.
+            const job = await enqueueJobInTransaction({
+                provider: sub.provider,
+                subscriptionId: sub.id,
+            });
+            if (job.operation === "cancellation") {
+                job.operation = "reconcile";
+                await store.saveJob(job);
+            }
+        });
+        try {
+            await callProvider(() => provider(sub.provider).resumeSubscription(sub.providerSubscriptionId, `resume:${sub.id}:${sub.providerVersion ?? "0"}`));
         }
         catch (error) {
             if (error instanceof BillingWorkflowError)
@@ -1012,6 +1171,7 @@ export function createBilling(options) {
                 retryable: true,
             });
         }
+        await readBackSubscription(sub);
         return { accepted: true, subscriptionId: sub.id };
     }
     async function ingestWebhook(input) {
@@ -1061,13 +1221,16 @@ export function createBilling(options) {
             payloadEncrypted: encryptedPayload?.ciphertext ?? null,
             payloadKeyVersion: encryptedPayload?.keyVersion ?? null,
             verifiedKeyVersion: envelope.verifiedKeyVersion,
-            status: "pending",
+            // Another product's event is kept for deduplication and audit, but is
+            // never processed, retried, or quarantined.
+            status: envelope.foreign ? "ignored" : "pending",
             processingAttempts: 0,
             lastError: null,
             availableAt: clock.now(),
             lockedAt: null,
             leaseExpiresAt: null,
             workerId: null,
+            ...(envelope.foreign ? { processedAt: clock.now() } : {}),
         };
         try {
             await store.withTransaction(async () => store.insertWebhook(record));
@@ -1087,6 +1250,27 @@ export function createBilling(options) {
     async function projectSnapshot(snapshot, correlation, reconcile = false) {
         return store.withTransaction(() => projectSnapshotInTransaction(snapshot, correlation, reconcile));
     }
+    /**
+     * Points the payer's customer at the one the provider chose during checkout.
+     * Only for a first subscription correlated to that payer's checkout.
+     */
+    async function relinkCheckoutCustomer(customerRowId, payerId, providerCustomerId) {
+        const row = await store.findCustomerById(customerRowId);
+        if (!row || row.payerId !== payerId || row.status !== "active")
+            return undefined;
+        const previous = row.providerCustomerId;
+        row.providerCustomerId = providerCustomerId;
+        await store.saveCustomer(row);
+        await requireAudit({
+            effectId: `customer:${row.id}:relinked:${providerCustomerId}`,
+            actor: { kind: "system", id: "billing" },
+            previous: { providerCustomerId: previous },
+            next: { providerCustomerId },
+            correlationIds: { customerId: row.id },
+        });
+        telemetry.event("customer.relinked", { customerId: row.id });
+        return row;
+    }
     async function projectSnapshotInTransaction(snapshot, correlation, reconcile = false) {
         if (!isBoundedOpaqueId(snapshot.provider) ||
             !isBoundedOpaqueId(snapshot.providerSubscriptionId) ||
@@ -1119,9 +1303,18 @@ export function createBilling(options) {
             ? await store.findCheckoutById(existing.originCheckoutAttemptId)
             : undefined;
         const attempt = correlatedAttempt ?? originAttempt;
-        const billableEntityId = existing?.billableEntityId ?? attempt?.billableEntityId;
-        const payerId = existing?.payerId ?? attempt?.payerId;
-        const customer = await store.findCustomerByProviderCustomerId(snapshot.provider, snapshot.providerCustomerId);
+        const billableEntityId = existing?.billableEntityId ??
+            attempt?.billableEntityId ??
+            correlation.adopted?.billableEntityId;
+        const payerId = existing?.payerId ?? attempt?.payerId ?? correlation.adopted?.payerId;
+        let customer = await store.findCustomerByProviderCustomerId(snapshot.provider, snapshot.providerCustomerId);
+        if (!customer &&
+            !existing &&
+            correlatedAttempt?.providerCustomerRowId &&
+            correlatedAttempt.provider === snapshot.provider &&
+            provider(snapshot.provider).capabilities.checkoutAssignsCustomer) {
+            customer = await relinkCheckoutCustomer(correlatedAttempt.providerCustomerRowId, correlatedAttempt.payerId, snapshot.providerCustomerId);
+        }
         if (!billableEntityId || !payerId || !customer) {
             throw new BillingWorkflowError("operation_quarantined");
         }
@@ -1176,7 +1369,10 @@ export function createBilling(options) {
         }
         const lineageRevision = pendingChange
             ? pendingChange.targetCatalogRevision
-            : (existing?.catalogRevision ?? attempt?.catalogRevision ?? 0);
+            : (existing?.catalogRevision ??
+                attempt?.catalogRevision ??
+                correlation.adopted?.catalogRevision ??
+                0);
         const lineageOffer = pendingChange
             ? pendingChange.targetOfferKey
             : (existing?.offerKey ?? attempt?.offerKey ?? price.offerKey);
@@ -1377,10 +1573,18 @@ export function createBilling(options) {
         const limit = workLimit(input.limit);
         return store.claimClaimableJobs(clock.now(), limit, input.workerId);
     }
+    /**
+     * Processes queued reconciliation jobs. Unless `discover` is false, it first
+     * queues stuck work (see `enqueueStuckWork`), so products need no sweep of
+     * their own.
+     */
     async function runReconciliationBatch(input) {
         const limit = workLimit(input.limit);
+        if (input.discover !== false && options.mode === "cloud") {
+            await enqueueStuckWork(limit);
+        }
         const claimed = await claimReconciliationJobs({
-            ...input,
+            workerId: input.workerId,
             limit,
         });
         for (const job of claimed) {
@@ -1443,29 +1647,11 @@ export function createBilling(options) {
                 return processed;
             const subscriptions = await store.listDueSubscriptionDeadlines(now, remaining);
             for (const subscription of subscriptions) {
-                const state = await store.ensurePlanState(subscription.billableEntityId);
-                if (state.activeSubscriptionId !== subscription.id) {
-                    throw new BillingWorkflowError("operation_conflicted");
-                }
-                const previous = { ...subscription };
-                subscription.isEntitlementSource = false;
-                state.activeSubscriptionId = null;
-                state.projectionVersion += 1;
-                await store.upsertSubscription(subscription);
-                await store.savePlanState(state);
-                const effectId = `projection:${subscription.id}:${state.projectionVersion}`;
-                await requireAudit({
-                    effectId,
-                    actor: { kind: "system", id: "deadline_worker" },
-                    previous,
-                    next: subscription,
-                    correlationIds: { subscriptionId: subscription.id },
-                });
-                await lifecycle?.afterProjection?.({
-                    material: true,
-                    previous,
-                    next: subscription,
-                    planState: state,
+                await releaseLapsedEntitlementInTransaction(subscription.id, "deadline_worker");
+                // Confirm the final state with the provider in case its last event was missed.
+                await enqueueJobInTransaction({
+                    provider: subscription.provider,
+                    subscriptionId: subscription.id,
                 });
                 processed += 1;
             }
@@ -1618,6 +1804,7 @@ export function createBilling(options) {
                 catalogKey: attempt.offerKey,
                 trialDays: 0,
                 idempotencyKey: attempt.idempotencyKey,
+                expiresAt: attempt.expiresAt,
             }));
             await store.withTransaction(async () => {
                 const latest = (await store.findCheckoutById(attempt.id)) ?? attempt;
@@ -1665,7 +1852,7 @@ export function createBilling(options) {
                 if (adapter.capabilities.mutationRecovery.cancellation === "unsupported") {
                     throw new BillingWorkflowError("operation_quarantined");
                 }
-                await callProvider(() => adapter.cancelSubscription(sub.providerSubscriptionId, `cancel:${sub.id}`));
+                await callProvider(() => adapter.cancelSubscription(sub.providerSubscriptionId, cancellationKey(sub)));
             }
             const snapshot = await callProvider(() => adapter.retrieveSubscription(sub.providerSubscriptionId));
             await projectSnapshot(snapshot, {}, true);
@@ -1830,7 +2017,18 @@ export function createBilling(options) {
             },
         });
     }
-    async function commercialState(entityId) {
+    /**
+     * Reads the entity's paid state. Pass `transaction` to read inside the
+     * caller's open transaction; the Drizzle store then locks the rows it reads
+     * until that transaction ends, so quota checks can rely on it.
+     */
+    async function commercialState(entityId, readOptions = {}) {
+        if (readOptions.transaction !== undefined) {
+            return store.runInTransaction(readOptions.transaction, () => readCommercialState(entityId));
+        }
+        return readCommercialState(entityId);
+    }
+    async function readCommercialState(entityId) {
         const state = (await store.findPlanState(entityId)) ?? {
             billableEntityId: entityId,
             activeSubscriptionId: null,
@@ -1839,9 +2037,13 @@ export function createBilling(options) {
         const pointed = state.activeSubscriptionId
             ? await store.findSubscriptionById(state.activeSubscriptionId)
             : undefined;
-        const sub = pointed?.isEntitlementSource ? pointed : undefined;
+        // Re-check the clock: paid access may have lapsed since the last projection.
+        const sub = pointed?.isEntitlementSource && retainsPaidEntitlement(pointed, clock.now())
+            ? pointed
+            : undefined;
         return {
             activePaidPlan: sub?.plan ?? null,
+            provider: sub?.provider ?? null,
             billingInterval: sub?.interval ?? null,
             subscriptionStatus: sub?.status ?? null,
             providerTrialEndsAt: sub?.trialEndsAt ?? null,
@@ -1853,6 +2055,148 @@ export function createBilling(options) {
             projectionVersion: state.projectionVersion,
         };
     }
+    /** Stops a subscription whose paid access has lapsed from granting entitlement. */
+    async function releaseLapsedEntitlement(subscriptionId, actorId) {
+        await store.withTransaction(() => releaseLapsedEntitlementInTransaction(subscriptionId, actorId));
+    }
+    async function releaseLapsedEntitlementInTransaction(subscriptionId, actorId) {
+        const subscription = await store.findSubscriptionById(subscriptionId);
+        if (!subscription?.isEntitlementSource ||
+            retainsPaidEntitlement(subscription, clock.now())) {
+            return;
+        }
+        const state = await store.ensurePlanState(subscription.billableEntityId);
+        if (state.activeSubscriptionId !== subscription.id) {
+            throw new BillingWorkflowError("operation_conflicted");
+        }
+        const previous = { ...subscription };
+        subscription.isEntitlementSource = false;
+        state.activeSubscriptionId = null;
+        state.projectionVersion += 1;
+        await store.upsertSubscription(subscription);
+        await store.savePlanState(state);
+        await requireAudit({
+            effectId: `projection:${subscription.id}:${state.projectionVersion}`,
+            actor: { kind: "system", id: actorId },
+            previous,
+            next: subscription,
+            correlationIds: { subscriptionId: subscription.id },
+        });
+        await lifecycle?.afterProjection?.({
+            material: true,
+            previous,
+            next: subscription,
+            planState: state,
+        });
+    }
+    /**
+     * Queues reconciliation for work that stalled without an event: checkouts
+     * stuck while being created, plan changes interrupted by an error, and
+     * subscriptions not checked with the provider recently.
+     */
+    async function enqueueStuckWork(limit) {
+        const now = clock.now().getTime();
+        const stale = options.reconciliation ?? {};
+        let queued = 0;
+        const checkouts = await store.listStuckCreatingCheckouts(new Date(now - (stale.checkoutStaleAfterMs ?? 60 * 1000)), clock.now(), limit);
+        for (const attempt of checkouts) {
+            await enqueueJob({ provider: attempt.provider, checkoutAttemptId: attempt.id });
+            queued += 1;
+        }
+        const changes = await store.listStuckPlanChanges(new Date(now - (stale.planChangeStaleAfterMs ?? 60 * 60 * 1000)), Math.max(0, limit - queued));
+        for (const change of changes) {
+            await enqueueJob({ provider: change.provider, planChangeAttemptId: change.id });
+            queued += 1;
+        }
+        const subscriptions = await store.listUnreconciledSubscriptions(new Date(now - (stale.subscriptionStaleAfterMs ?? 60 * 60 * 1000)), Math.max(0, limit - queued));
+        for (const subscription of subscriptions) {
+            await enqueueJob({
+                provider: subscription.provider,
+                subscriptionId: subscription.id,
+            });
+            queued += 1;
+        }
+        return queued;
+    }
+    /**
+     * Takes over a subscription created outside this engine, for example one
+     * started with the provider before the product used this package. Links the
+     * provider's customer to the payer, then projects the subscription like any
+     * other. Its product must be in the provider's active catalog. Repeating it
+     * for the same entity is safe.
+     */
+    async function adoptProviderSubscription(context, input) {
+        if (options.mode === "oss") {
+            throw new BillingWorkflowError("unsupported_operation");
+        }
+        assertOperatorContext(context);
+        if (!isBoundedOpaqueId(input.providerName) ||
+            !isBoundedOpaqueId(input.providerSubscriptionId) ||
+            !isBoundedOpaqueId(input.entity.id) ||
+            !isBoundedOpaqueId(input.payer.id) ||
+            !input.payer.email) {
+            throw new BillingWorkflowError("operation_quarantined");
+        }
+        const adapter = provider(input.providerName);
+        const catalog = await store.getActiveCatalog(input.providerName);
+        if (!catalog)
+            throw new BillingWorkflowError("catalog_unavailable");
+        const snapshot = await callProvider(() => adapter.retrieveSubscription(input.providerSubscriptionId));
+        // A product from a retired revision still has a price entry, so check the
+        // active catalog itself.
+        if (!catalog.items.some((item) => item.price.providerProductId === snapshot.providerProductId)) {
+            throw new BillingWorkflowError("operation_quarantined");
+        }
+        return store.withTransaction(async () => {
+            const known = await store.findSubscriptionByProviderIds(snapshot.provider, snapshot.providerSubscriptionId);
+            if (known &&
+                (known.billableEntityId !== input.entity.id || known.payerId !== input.payer.id)) {
+                throw new BillingWorkflowError("operation_conflicted");
+            }
+            let customer = await store.findCustomerByProviderCustomerId(snapshot.provider, snapshot.providerCustomerId);
+            if (customer && customer.payerId !== input.payer.id) {
+                throw new BillingWorkflowError("payer_mismatch");
+            }
+            if (!customer) {
+                const payerCustomer = await store.findCustomerByPayer(snapshot.provider, input.payer.id);
+                if (payerCustomer?.providerCustomerId &&
+                    payerCustomer.providerCustomerId !== snapshot.providerCustomerId) {
+                    throw new BillingWorkflowError("operation_conflicted");
+                }
+                if (payerCustomer) {
+                    payerCustomer.providerCustomerId = snapshot.providerCustomerId;
+                    payerCustomer.status = "active";
+                    await store.saveCustomer(payerCustomer);
+                    customer = payerCustomer;
+                }
+                else {
+                    customer = {
+                        id: newId(),
+                        provider: snapshot.provider,
+                        payerId: input.payer.id,
+                        payerEmail: input.payer.email,
+                        providerCustomerId: snapshot.providerCustomerId,
+                        idempotencyKey: `adopt:${snapshot.provider}:${snapshot.providerCustomerId}`,
+                        status: "active",
+                        lastError: null,
+                    };
+                    await store.insertCustomer(customer);
+                }
+            }
+            const write = await projectSnapshotInTransaction(snapshot, {
+                adopted: {
+                    billableEntityId: input.entity.id,
+                    payerId: input.payer.id,
+                    catalogRevision: catalog.revision.revision,
+                },
+            });
+            await recordOperatorAudit(context, `operator:adopt:${snapshot.provider}:${snapshot.providerSubscriptionId}`, known ?? null, write.subscription, {
+                subscriptionId: write.subscription.id,
+                billableEntityId: input.entity.id,
+            });
+            return write;
+        });
+    }
     async function operatorCancel(context, subscriptionId) {
         if (options.mode === "oss") {
             throw new BillingWorkflowError("unsupported_operation");
@@ -1863,6 +2207,8 @@ export function createBilling(options) {
             throw new BillingWorkflowError("subscription_required");
         if (sub.status === "cancelled" || sub.status === "expired")
             return;
+        if (sub.cancelAtPeriodEnd)
+            return;
         if (provider(sub.provider).capabilities.mutationRecovery.cancellation ===
             "unsupported") {
             throw new BillingWorkflowError("unsupported_operation");
@@ -1876,7 +2222,7 @@ export function createBilling(options) {
             });
         });
         try {
-            await callProvider(() => provider(sub.provider).cancelSubscription(sub.providerSubscriptionId, `operator-cancel:${sub.id}`));
+            await callProvider(() => provider(sub.provider).cancelSubscription(sub.providerSubscriptionId, `operator-${cancellationKey(sub)}`));
         }
         catch (error) {
             if (error instanceof BillingWorkflowError)
@@ -1928,15 +2274,23 @@ export function createBilling(options) {
         });
     }
     return {
+        /**
+         * @internal The engine's own persistence. Products must not read or write
+         * billing state through it: use the workflows and read models
+         * (`commercialState`, `publicCatalog`, `health`) instead, so projections,
+         * audit, and lifecycle hooks stay consistent.
+         */
         store,
         startCheckout,
         startPortal,
         startPlanChange,
         cancel,
+        resumeCancellation,
         ingestWebhook,
         processWebhookByEventId,
         runWebhookInboxBatch,
         runReconciliationBatch,
+        enqueueStuckWork,
         runDeadlineBatch,
         purgeExpiredSensitiveValues,
         claimReconciliationJobs,
@@ -1950,11 +2304,20 @@ export function createBilling(options) {
         verifyRequestedCatalog,
         abandonRequestedCatalog,
         operatorCancel,
+        adoptProviderSubscription,
         recordOperatorAudit,
         enqueueJob,
         resolveCustomer,
     };
 }
+/**
+ * Provider idempotency key for a cancellation. It includes the subscription's
+ * provider version so that cancelling again after a resume is a new request,
+ * while retries of the same request reuse the key.
+ */
+function cancellationKey(sub) {
+    return `cancel:${sub.id}:${sub.providerVersion ?? "0"}`;
+}
 function catalogShapeIsComplete(catalog, requiredOfferKeys) {
     if (!catalog)
         return false;