@cosmicdrift/kumiko-bundled-features 0.320.0 → 0.321.0

package/src/billing-foundation/feature.ts

@@ -59,7 +59,11 @@ import {
 // `Temporal` TYPE `ResolvedBillingFoundationOptions.now`'s return type
 // resolves against, see event-store.ts's own import comment (#1438).
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
-import { BILLING_FOUNDATION_FEATURE, SUBSCRIPTION_PROVIDER_EXTENSION } from "./constants";
+import {
+  BILLING_FOUNDATION_FEATURE,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  SubscriptionFoundationHandlers,
+} from "./constants";
 import { paymentEntity, subscriptionEntity } from "./entities";
 import {
   INVOICE_PAID_EVENT_QN,
@@ -87,6 +91,7 @@ import { processEventHandler } from "./handlers/process-event.write";
 import { processPaymentEventHandler } from "./handlers/process-payment-event.write";
 import { createStartPlanCheckoutHandler } from "./handlers/start-plan-checkout.write";
 import { createSwitchPlanHandler } from "./handlers/switch-plan.write";
+import { syncSubscriptionHandler } from "./handlers/sync-subscription.write";
 import { BILLING_FOUNDATION_I18N } from "./i18n";
 import {
   applyInvoicePaid,
@@ -137,7 +142,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
 
   return defineFeature(BILLING_FOUNDATION_FEATURE, (r) => {
     r.describe(
-      "Plugin host for subscription billing — manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers and a dormant billing-plans dashboard screen/panel from the catalog. Low-level building block — use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
+      "Plugin host for subscription billing — manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers and a dormant billing-plans dashboard screen/panel from the catalog. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event — catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block — use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
     );
     r.uiHints({
       displayLabel: "Billing · Foundation",
@@ -215,6 +220,12 @@ export function createBillingFoundationFeature<TTier extends string = string>(
     //   - process-payment-event: programmatic entry-point from the webhook-
     //     handler for one-off-payments; appends onto the payment-aggregate
     r.writeHandler(processPaymentEventHandler);
+    //   - sync-subscription: backfill entry-point for the sync-subscriptions
+    //     job below; pulls the live provider state and appends drift as a
+    //     subscription.updated event. Registered unconditionally (not
+    //     catalog-gated) — it operates on whatever subscription already
+    //     exists for the tenant, independent of the billing-plans catalog.
+    r.writeHandler(syncSubscriptionHandler);
 
     // Custom list-query on the subscription-projection (raw drizzle
     // table; no r.entity since writes go through projection-apply).
@@ -233,6 +244,30 @@ export function createBillingFoundationFeature<TTier extends string = string>(
       r.screen(createBillingPlansScreen(catalog.viewRoles));
     }
 
+    // Backfill job: catches provider-side drift (e.g. a cancel_at set on
+    // the provider's own dashboard) that never reached us as a webhook.
+    // manual-trigger + runOnBoot (not cron) — this is an on-demand/boot
+    // reconciliation pass, not a recurring sweep; an app that wants a
+    // recurring sync can dispatch billing-foundation:job:sync-subscriptions
+    // from its own cron job. perTenant + runOnBoot are compatible (only
+    // bootGate is not). Registered unconditionally, same reasoning as the
+    // sync-subscription write-handler above.
+    r.job({
+      name: "sync-subscriptions",
+      trigger: { manual: true },
+      perTenant: true,
+      runOnBoot: true,
+      handler: async (_payload, ctx) => {
+        const result = await ctx.write(SubscriptionFoundationHandlers.syncSubscription, {});
+        if (!result.isSuccess) {
+          throw new Error(
+            `billing-foundation:sync-subscriptions: sync-subscription write failed: ${JSON.stringify(result.error)}`,
+          );
+        }
+        ctx.log.info(`[billing-foundation:sync-subscriptions] ${JSON.stringify(result.data)}`);
+      },
+    });
+
     r.useExtension(EXT_TENANT_DATA, "subscription", {
       destroy: subscriptionTenantDestroyHook,
       escapeHatch: { reason: SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON },

package/src/billing-foundation/handlers/process-event.write.ts

@@ -16,7 +16,7 @@ import {
   configuredPiiSubjectKms,
   encryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { HandlerContext, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id";
 import { SubscriptionEventTypes, SubscriptionStatuses } from "../constants";
@@ -66,7 +66,7 @@ export const processEventSchema = z.object({
   cancelAtIso: z.string().min(1).nullable().optional(),
   rawPayload: z.string().min(1),
 });
-type ProcessEventPayload = z.infer<typeof processEventSchema>;
+export type ProcessEventPayload = z.infer<typeof processEventSchema>;
 
 // Map normalized SubscriptionEventType → fully-qualified ES event-name.
 const NORMALIZED_TO_ES_EVENT: Readonly<Record<string, string>> = {
@@ -77,6 +77,114 @@ const NORMALIZED_TO_ES_EVENT: Readonly<Record<string, string>> = {
   [SubscriptionEventTypes.invoicePaymentFailed]: INVOICE_PAYMENT_FAILED_EVENT_QN,
 } satisfies Readonly<Record<string, string>>;
 
+// =============================================================================
+// appendSubscriptionEvent — the append-body, shared by processEventHandler
+// (webhook path) and sync-subscription.write.ts (backfill path). Both call
+// this with the same normalized payload shape; the difference is only in
+// who constructs `payload` and what `providerEventId` they use.
+// =============================================================================
+
+export async function appendSubscriptionEvent(
+  ctx: HandlerContext,
+  tenantId: string,
+  payload: ProcessEventPayload,
+): Promise<{ readonly duplicate: boolean; readonly subscriptionAggregateId: string }> {
+  const aggId = subscriptionAggregateId(tenantId);
+
+  // ---------------------------------------------------------------
+  // 1. Idempotency: load the subscription stream and check whether this
+  //    providerEventId was already seen. A provider retry storm (Stripe
+  //    resends up to 5x within 4h) hits the same stream and finds the
+  //    event id in metadata.
+  //
+  //    **Performance caveat:** O(N) per stream. With 5 years of history
+  //    (monthly recurring = ~60 events) still <50ms. For much longer
+  //    streams, optimize via snapshot or a per-tenant dedup table as the
+  //    idempotency anchor (like cap-counter).
+  // ---------------------------------------------------------------
+  const existingEvents = await ctx.loadAggregate(aggId);
+  const alreadySeen = existingEvents.some((e) => {
+    const headers = e.metadata.headers ?? {};
+    return (
+      headers["providerEventId"] === payload.providerEventId &&
+      headers["providerName"] === payload.providerName
+    );
+  });
+  if (alreadySeen) {
+    return { duplicate: true, subscriptionAggregateId: aggId };
+  }
+
+  // ---------------------------------------------------------------
+  // 2. Map normalized event-type → ES event-FQN.
+  // ---------------------------------------------------------------
+  const esEventType = NORMALIZED_TO_ES_EVENT[payload.type];
+  if (!esEventType) {
+    // Schema validation above should already catch this; defensive against
+    // drift between the SubscriptionEventTypes enum and the NORMALIZED map.
+    throw new Error(`subscription-foundation: no ES event-type mapping for "${payload.type}"`);
+  }
+
+  // ---------------------------------------------------------------
+  // 3. Encrypt the two provider-subject PII fields before they touch
+  //    storage — this is the ONLY write path onto the subscription
+  //    stream, so encrypting here covers both the event-log payload AND
+  //    (via projection.ts copying the event fields as-is) the
+  //    read_subscriptions row with a single call. The subject is the
+  //    TENANT (tenantOwned) — tenant-destroy's subject-keys stage
+  //    (eraseSubjectKeys) erases exactly this key, so both copies become
+  //    genuinely unreadable (#800) once that stage runs, not just
+  //    "encrypted at rest". No adapter configured = engine off (fields
+  //    stay plaintext, pre-#724-phase-C behavior) — mirrors how the
+  //    event-store-executor treats an absent piiKms().
+  // ---------------------------------------------------------------
+  const piiKms = configuredPiiSubjectKms();
+  const encryptedFields = piiKms
+    ? await encryptPiiFieldValues(
+        {
+          tenantId,
+          providerCustomerId: payload.providerCustomerId,
+          providerSubscriptionId: payload.providerSubscriptionId,
+        },
+        subscriptionEntity,
+        SUBSCRIPTION_PII_FIELDS,
+        piiKms,
+        { requestId: `billing-foundation:process-event:${payload.providerEventId}`, tenantId },
+        { tenantId, entityName: SUBSCRIPTION_AGGREGATE_TYPE },
+      )
+    : {
+        providerCustomerId: payload.providerCustomerId,
+        providerSubscriptionId: payload.providerSubscriptionId,
+      };
+
+  // ---------------------------------------------------------------
+  // 4. Append the event onto the subscription stream. The inline projection
+  //    materializes the read_subscriptions row in the same TX.
+  // ---------------------------------------------------------------
+  const eventPayload: SubscriptionEventPayload = {
+    providerName: payload.providerName,
+    providerCustomerId: encryptedFields["providerCustomerId"] as string,
+    providerSubscriptionId: encryptedFields["providerSubscriptionId"] as string,
+    status: payload.status,
+    tier: payload.tier,
+    currentPeriodEndIso: payload.currentPeriodEndIso,
+    ...(payload.cancelAtIso !== undefined && { cancelAtIso: payload.cancelAtIso }),
+  };
+  const headers: SubscriptionEventHeaders = {
+    providerEventId: payload.providerEventId,
+    providerName: payload.providerName,
+    rawPayload: payload.rawPayload,
+  };
+  await ctx.unsafeAppendEvent({
+    aggregateId: aggId,
+    aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
+    type: esEventType,
+    payload: eventPayload,
+    headers,
+  });
+
+  return { duplicate: false, subscriptionAggregateId: aggId };
+}
+
 // =============================================================================
 // Handler
 // =============================================================================
@@ -92,109 +200,7 @@ export const processEventHandler: WriteHandlerDef = {
   handler: async (event, ctx) => {
     // @cast-boundary engine-payload — dispatcher-zod-validated payload
     const payload = event.payload as ProcessEventPayload;
-    const tenantId = event.user.tenantId;
-    const aggId = subscriptionAggregateId(tenantId);
-
-    // ---------------------------------------------------------------
-    // 1. Idempotency: load subscription-stream + check ob dieser
-    //    providerEventId bereits gesehen wurde. Provider-Retry-Storm
-    //    (Stripe sendet bis zu 5x in 4h) trifft denselben Stream und
-    //    findet den event-id in metadata.
-    //
-    //    **Performance-caveat:** O(N) pro stream. Bei 5 Jahren history
-    //    (recurring monatlich = ~60 events) noch <50ms. Bei deutlich
-    //    längeren streams optimieren via snapshot oder per-tenant
-    //    dedup-table als idempotency-anchor (analog cap-counter).
-    // ---------------------------------------------------------------
-    const existingEvents = await ctx.loadAggregate(aggId);
-    const alreadySeen = existingEvents.some((e) => {
-      const headers = e.metadata.headers ?? {};
-      return (
-        headers["providerEventId"] === payload.providerEventId &&
-        headers["providerName"] === payload.providerName
-      );
-    });
-    if (alreadySeen) {
-      return {
-        isSuccess: true as const,
-        data: { duplicate: true as const, subscriptionAggregateId: aggId },
-      };
-    }
-
-    // ---------------------------------------------------------------
-    // 2. Map normalized event-type → ES event-FQN.
-    // ---------------------------------------------------------------
-    const esEventType = NORMALIZED_TO_ES_EVENT[payload.type];
-    if (!esEventType) {
-      // Schema-validation oben sollte das schon fangen, aber defensive
-      // gegen drift im SubscriptionEventTypes-enum vs NORMALIZED-Map.
-      throw new Error(`subscription-foundation: no ES event-type mapping for "${payload.type}"`);
-    }
-
-    // ---------------------------------------------------------------
-    // 3. Encrypt the two provider-subject PII fields before they touch
-    //    storage — this is the ONLY write path onto the subscription
-    //    stream, so encrypting here covers both the event-log payload AND
-    //    (via projection.ts copying the event fields as-is) the
-    //    read_subscriptions row with a single call. The subject is the
-    //    TENANT (tenantOwned) — tenant-destroy's subject-keys stage
-    //    (eraseSubjectKeys) erases exactly this key, so both copies become
-    //    genuinely unreadable (#800) once that stage runs, not just
-    //    "encrypted at rest". No adapter configured = engine off (fields
-    //    stay plaintext, pre-#724-phase-C behavior) — mirrors how the
-    //    event-store-executor treats an absent piiKms().
-    // ---------------------------------------------------------------
-    const piiKms = configuredPiiSubjectKms();
-    const encryptedFields = piiKms
-      ? await encryptPiiFieldValues(
-          {
-            tenantId,
-            providerCustomerId: payload.providerCustomerId,
-            providerSubscriptionId: payload.providerSubscriptionId,
-          },
-          subscriptionEntity,
-          SUBSCRIPTION_PII_FIELDS,
-          piiKms,
-          { requestId: `billing-foundation:process-event:${payload.providerEventId}`, tenantId },
-          { tenantId, entityName: SUBSCRIPTION_AGGREGATE_TYPE },
-        )
-      : {
-          providerCustomerId: payload.providerCustomerId,
-          providerSubscriptionId: payload.providerSubscriptionId,
-        };
-
-    // ---------------------------------------------------------------
-    // 4. Append event auf den subscription-stream. Inline-projection
-    //    materialisiert die read_subscriptions-row in derselben TX.
-    // ---------------------------------------------------------------
-    const eventPayload: SubscriptionEventPayload = {
-      providerName: payload.providerName,
-      providerCustomerId: encryptedFields["providerCustomerId"] as string,
-      providerSubscriptionId: encryptedFields["providerSubscriptionId"] as string,
-      status: payload.status,
-      tier: payload.tier,
-      currentPeriodEndIso: payload.currentPeriodEndIso,
-      ...(payload.cancelAtIso !== undefined && { cancelAtIso: payload.cancelAtIso }),
-    };
-    const headers: SubscriptionEventHeaders = {
-      providerEventId: payload.providerEventId,
-      providerName: payload.providerName,
-      rawPayload: payload.rawPayload,
-    };
-    await ctx.unsafeAppendEvent({
-      aggregateId: aggId,
-      aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
-      type: esEventType,
-      payload: eventPayload,
-      headers,
-    });
-
-    return {
-      isSuccess: true as const,
-      data: {
-        duplicate: false as const,
-        subscriptionAggregateId: aggId,
-      },
-    };
+    const result = await appendSubscriptionEvent(ctx, event.user.tenantId, payload);
+    return { isSuccess: true as const, data: result };
   },
 };

package/src/billing-foundation/handlers/switch-plan.write.ts

@@ -57,6 +57,13 @@ export function createSwitchPlanHandler(
             "tenant has no switchable subscription; use billing-foundation:write:start-plan-checkout to start one",
         });
       }
+      if (sub.cancelAt !== null) {
+        throw new ConflictError({
+          i18nKey: "billing-foundation.errors.cancellationScheduled",
+          message:
+            "subscription has a scheduled cancellation; reactivate it via billing-foundation:write:create-portal-session before switching plans",
+        });
+      }
       if (payload.tier === sub.tier) {
         throw new ConflictError({
           i18nKey: "billing-foundation.errors.alreadyOnPlan",

package/src/billing-foundation/handlers/sync-subscription.write.ts

@@ -0,0 +1,164 @@
+// sync-subscription — backfill handler for the `sync-subscriptions` job
+// (registered in feature.ts). Pulls the live provider-side state of the
+// tenant's subscription and appends it as a `subscription.updated` (or
+// `subscription.canceled`, when the snapshot's own status is terminal)
+// event when it has drifted from `read_subscriptions` — catches
+// provider-side changes (e.g. a `cancel_at` set on the provider's own
+// dashboard, or a cancellation) that never reached us as a webhook.
+//
+// SYSTEM_ROLE, not just "SystemAdmin": the `sync-subscriptions` job's own
+// systemUser only carries `roles: ["system"]` (createSystemUser(tenantId),
+// no extra roles — see job-runner.ts), unlike the webhook path's
+// dispatchSystemWrite which adds "SystemAdmin". Same access shape as
+// tenant/handlers/memberships.query.ts and active-tenant-ids.query.ts for
+// the same reason. A human SystemAdmin can still dispatch this directly.
+
+import { createHash } from "node:crypto";
+import { SYSTEM_ROLE, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+// Aliased — an un-aliased `Temporal` would shadow the ambient global
+// `Temporal` TYPE `SubscriptionView.currentPeriodEnd`/`.cancelAt` resolve
+// against, same reasoning as constants.ts's own import.
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import * as z from "zod";
+import { findProviderPlugin } from "../checkout-core";
+import { isTerminalSubscriptionStatus, SubscriptionEventTypes } from "../constants";
+import { getSubscriptionForTenant } from "../get-subscription-for-tenant";
+import { appendSubscriptionEvent } from "./process-event.write";
+
+export const syncSubscriptionSchema = z.object({}).strict();
+
+export type SyncSubscriptionSkipReason =
+  | "no_live_subscription"
+  | "provider_cannot_retrieve"
+  | "not_found"
+  | "unchanged";
+
+export type SyncSubscriptionResult =
+  | { readonly synced: true }
+  | { readonly synced: false; readonly reason: SyncSubscriptionSkipReason };
+
+// Parses both sides fresh via the polyfill before comparing — tolerant of a
+// provider snapshot's ISO string using a different (but equivalent)
+// representation than `Temporal.Instant#toString()`'s canonical form
+// (offset spelling, sub-second precision, ...), unlike a plain `===` on the
+// raw strings.
+function isoInstantsEqual(a: string, b: string): boolean {
+  return (
+    TemporalPolyfill.Instant.compare(
+      TemporalPolyfill.Instant.from(a),
+      TemporalPolyfill.Instant.from(b),
+    ) === 0
+  );
+}
+
+// Deterministic per (snapshot-content, current stream head) — not per-call.
+// Folding in `lastChangedAt` (not just the snapshot's own fields) closes a
+// gap a content-only hash has: dashboard-cancel → sync(A) → dashboard-
+// reactivate → sync(B) → dashboard-cancel-again → sync would hash back to
+// A's already-seen providerEventId and get silently treated as a duplicate,
+// leaving the row stuck on B even though the provider is on A again.
+// `lastChangedAt` advances on every applied event, so the third sync's hash
+// differs from the first's even though the snapshot content matches.
+function syncProviderEventId(
+  snapshot: {
+    readonly providerSubscriptionId: string;
+    readonly status: string;
+    readonly tier: string;
+    readonly currentPeriodEnd: string;
+    readonly cancelAt: string | null;
+  },
+  lastChangedAt: string,
+): string {
+  const hashInput = [
+    snapshot.providerSubscriptionId,
+    snapshot.status,
+    snapshot.tier,
+    snapshot.currentPeriodEnd,
+    snapshot.cancelAt ?? "",
+    lastChangedAt,
+  ].join("|");
+  return `sync:${createHash("sha256").update(hashInput).digest("hex")}`;
+}
+
+export const syncSubscriptionHandler: WriteHandlerDef = {
+  name: "sync-subscription",
+  agent: { expose: false },
+  schema: syncSubscriptionSchema,
+  access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const tenantId = event.user.tenantId;
+    const sub = await getSubscriptionForTenant(ctx, tenantId);
+    if (!sub || isTerminalSubscriptionStatus(sub.status)) {
+      return {
+        isSuccess: true as const,
+        data: { synced: false, reason: "no_live_subscription" } satisfies SyncSubscriptionResult,
+      };
+    }
+
+    // Non-throwing — a provider deregistered since the subscription was
+    // created is the same "can't reconcile right now" outcome as a plugin
+    // that never implemented retrieveSubscription, not a hard failure.
+    const found = findProviderPlugin(ctx, sub.providerName);
+    if (!found?.plugin.retrieveSubscription) {
+      return {
+        isSuccess: true as const,
+        data: {
+          synced: false,
+          reason: "provider_cannot_retrieve",
+        } satisfies SyncSubscriptionResult,
+      };
+    }
+
+    const snapshot = await found.plugin.retrieveSubscription(ctx, sub.providerSubscriptionId);
+    if (!snapshot) {
+      return {
+        isSuccess: true as const,
+        data: { synced: false, reason: "not_found" } satisfies SyncSubscriptionResult,
+      };
+    }
+
+    const cancelAtUnchanged =
+      snapshot.cancelAt === null
+        ? sub.cancelAt === null
+        : sub.cancelAt !== null && isoInstantsEqual(snapshot.cancelAt, sub.cancelAt.toString());
+    const unchanged =
+      snapshot.status === sub.status &&
+      snapshot.tier === sub.tier &&
+      isoInstantsEqual(snapshot.currentPeriodEnd, sub.currentPeriodEnd.toString()) &&
+      cancelAtUnchanged;
+    if (unchanged) {
+      return {
+        isSuccess: true as const,
+        data: { synced: false, reason: "unchanged" } satisfies SyncSubscriptionResult,
+      };
+    }
+
+    const appendResult = await appendSubscriptionEvent(ctx, tenantId, {
+      providerEventId: syncProviderEventId(snapshot, sub.lastChangedAt.toString()),
+      providerName: sub.providerName,
+      // A snapshot that already landed on a terminal status (canceled on the
+      // provider's own dashboard, never arrived as a webhook) must append as
+      // a real `canceled` event, not `updated` — anything downstream that
+      // reads the event-log's own type (not just the projection's status
+      // column, which both apply-functions patch the same way) needs the
+      // accurate event-type to react to a cancellation.
+      type: isTerminalSubscriptionStatus(snapshot.status)
+        ? SubscriptionEventTypes.canceled
+        : SubscriptionEventTypes.updated,
+      providerCustomerId: snapshot.providerCustomerId,
+      providerSubscriptionId: snapshot.providerSubscriptionId,
+      status: snapshot.status,
+      tier: snapshot.tier,
+      currentPeriodEndIso: snapshot.currentPeriodEnd,
+      cancelAtIso: snapshot.cancelAt,
+      rawPayload: snapshot.rawPayload,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: (appendResult.duplicate
+        ? { synced: false, reason: "unchanged" }
+        : { synced: true }) satisfies SyncSubscriptionResult,
+    };
+  },
+};

package/src/billing-foundation/i18n.ts

@@ -24,9 +24,15 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.plans.cancelScheduled": {
     en: "Your subscription is scheduled to end on {date}.",
   },
+  "billing-foundation.plans.switchRequiresReactivation": {
+    en: "Reactivate your subscription before switching plans.",
+  },
   "billing-foundation.plans.paymentPending": {
     en: "Payment is still being completed.",
   },
+  "billing-foundation.plans.pastDue": {
+    en: "Your last payment failed. Update your payment method to avoid interruption.",
+  },
   "billing-foundation.plans.priceUnavailable": { en: "Price not available" },
   "billing-foundation.plans.purchaseNotAllowed": {
     en: "Only administrators can change the plan.",
@@ -50,6 +56,9 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.errors.noActiveSubscription": {
     en: "This tenant has no active subscription to switch.",
   },
+  "billing-foundation.errors.cancellationScheduled": {
+    en: "This subscription is scheduled to cancel. Reactivate it before switching plans.",
+  },
   "billing-foundation.errors.alreadyOnPlan": { en: "This tenant is already on that plan." },
   "billing-foundation.errors.planSwitchNotSupported": {
     en: "This provider does not support switching plans.",

package/src/billing-foundation/index.ts

@@ -73,6 +73,7 @@ export {
   KNOWN_RECURRING_INTERVALS,
   type PaymentEvent,
   type ProviderPrice,
+  type ProviderSubscriptionSnapshot,
   type RecurringInterval,
   type SubscriptionEvent,
   type SubscriptionProviderPlugin,

package/src/billing-foundation/plan-catalog.ts

@@ -103,8 +103,27 @@ type ActiveSubscription = {
   readonly status: string;
   readonly tier: string;
   readonly terminal: boolean;
+  readonly cancelAt: string | null;
 };
 
+/** Whether an existing subscription can move to `tier` via the provider's
+ *  plan-switch session — pulled out of resolvePlanAction so that function
+ *  stays under the guard's complexity budget. A pending cancellation
+ *  (`cancelAt` set) must be reactivated via create-portal-session before a
+ *  switch is allowed — same gate `switch-plan.write.ts` enforces server-side. */
+function canSwitchToTier(
+  tier: string,
+  subscription: ActiveSubscription,
+  plugin: SubscriptionProviderPlugin | null,
+): boolean {
+  return (
+    isSwitchableSubscriptionStatus(subscription.status) &&
+    tier !== subscription.tier &&
+    subscription.cancelAt === null &&
+    plugin?.createPlanSwitchSession !== undefined
+  );
+}
+
 /** One plan-row's action — pulled out of `buildBillingPlans`' map callback so
  *  that function's own complexity stays under the guard's budget. paymentPending
  *  is checked before the general unavailable-fallback: the tier a not-yet-
@@ -133,11 +152,9 @@ function resolvePlanAction(
 
   if (!subscription || subscription.terminal) return BillingPlanActions.checkout;
 
-  const canSwitch =
-    isSwitchableSubscriptionStatus(subscription.status) &&
-    tier !== subscription.tier &&
-    plugin?.createPlanSwitchSession;
-  return canSwitch ? BillingPlanActions.switch : BillingPlanActions.unavailable;
+  return canSwitchToTier(tier, subscription, plugin)
+    ? BillingPlanActions.switch
+    : BillingPlanActions.unavailable;
 }
 
 /** `plugin === null` — no provider is registered/resolvable for this

package/src/billing-foundation/types.ts

@@ -281,6 +281,33 @@ export type SubscriptionProviderPlugin = {
       readonly returnUrl: string;
     },
   ) => Promise<{ readonly url: string }>;
+
+  /**
+   * Fetches the live provider-side state of one subscription, for the
+   * `sync-subscriptions` backfill job — catches drift (e.g. a `cancel_at`
+   * set on the provider's own dashboard) that never reached us as a
+   * webhook. Missing → sync-subscription reports `provider_cannot_retrieve`
+   * instead of throwing. Null → the implementation could not resolve a
+   * snapshot for this id — the subscription no longer exists at the
+   * provider (deleted account, ...), or its state no longer maps onto this
+   * app's config (e.g. Stripe's price-to-tier — same silent-drop the
+   * webhook path already applies to an unmapped price).
+   */
+  readonly retrieveSubscription?: (
+    ctx: HandlerContext,
+    providerSubscriptionId: string,
+  ) => Promise<ProviderSubscriptionSnapshot | null>;
+};
+
+export type ProviderSubscriptionSnapshot = {
+  readonly providerCustomerId: string;
+  readonly providerSubscriptionId: string;
+  readonly status: SubscriptionStatus;
+  readonly tier: string;
+  /** ISO instant string, same shape as `SubscriptionEventPayload.currentPeriodEndIso`. */
+  readonly currentPeriodEnd: string;
+  readonly cancelAt: string | null;
+  readonly rawPayload: string;
 };
 
 // =============================================================================

package/src/billing-foundation/web/__tests__/billing-plans-panel.test.tsx

@@ -351,6 +351,34 @@ describe("BillingPlansPanel", () => {
     expect(screen.queryByTestId("billing-plan-card-pro-cta")).toBeNull();
   });
 
+  test("a scheduled cancellation shows cancelScheduled and switchRequiresReactivation together", () => {
+    queryState = {
+      data: result({
+        subscription: subscription({ cancelAt: "2024-03-01T00:00:00Z" }),
+        plans: [plan({ isCurrent: true, action: BillingPlanActions.current })],
+      }),
+      loading: false,
+      error: null,
+    };
+    renderPanel();
+    const banner = screen.getByTestId("billing-plans-panel-cancel-scheduled");
+    expect(banner.textContent).toContain("billing-foundation.plans.cancelScheduled");
+    expect(banner.textContent).toContain("billing-foundation.plans.switchRequiresReactivation");
+  });
+
+  test("past_due status renders the past-due banner", () => {
+    queryState = {
+      data: result({
+        subscription: subscription({ status: "past_due" }),
+        plans: [plan({ isCurrent: true, action: BillingPlanActions.current })],
+      }),
+      loading: false,
+      error: null,
+    };
+    renderPanel();
+    expect(screen.getByTestId("billing-plans-panel-past-due")).toBeTruthy();
+  });
+
   test("price=null renders the price-unavailable fallback and a disabled cta", () => {
     queryState = {
       data: result({ plans: [plan({ price: null, action: BillingPlanActions.unavailable })] }),