@cosmicdrift/kumiko-bundled-features 0.320.0 → 0.321.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.320.0",
+  "version": "0.321.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -134,12 +134,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.320.0",
-    "@cosmicdrift/kumiko-framework": "0.320.0",
-    "@cosmicdrift/kumiko-headless": "0.320.0",
-    "@cosmicdrift/kumiko-renderer": "0.320.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.320.0",
-    "@cosmicdrift/kumiko-types": "0.320.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.321.0",
+    "@cosmicdrift/kumiko-framework": "0.321.0",
+    "@cosmicdrift/kumiko-headless": "0.321.0",
+    "@cosmicdrift/kumiko-renderer": "0.321.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.321.0",
+    "@cosmicdrift/kumiko-types": "0.321.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -168,8 +168,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.320.0",
-    "@cosmicdrift/kumiko-locale-es": "0.320.0",
+    "@cosmicdrift/kumiko-locale-de": "0.321.0",
+    "@cosmicdrift/kumiko-locale-es": "0.321.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/billing-foundation/__tests__/billing-plans.integration.test.ts

@@ -232,6 +232,7 @@ async function createSubscription(
     tier: string;
     providerSubscriptionId: string;
     providerCustomerId: string;
+    cancelAtIso: string | null;
   }> = {},
   onStack: TestStack = stack,
 ) {
@@ -247,6 +248,7 @@ async function createSubscription(
       status: overrides.status ?? SubscriptionStatuses.active,
       tier: overrides.tier ?? "starter",
       currentPeriodEndIso: "2026-06-01T00:00:00Z",
+      ...(overrides.cancelAtIso !== undefined && { cancelAtIso: overrides.cancelAtIso }),
       rawPayload: '{"raw":"payload"}',
     },
     admin,
@@ -503,6 +505,31 @@ describe("switch-plan", () => {
     expect(error.httpStatus).toBe(409);
   });
 
+  test("switching a subscription that is scheduled to cancel is a conflict, and the query offers unavailable instead of switch", async () => {
+    const admin = adminFor(7034);
+    await createSubscription(admin.tenantId, {
+      tier: "starter",
+      providerSubscriptionId: "sub_switch_7034",
+      cancelAtIso: "2026-07-01T00:00:00Z",
+    });
+
+    const result = (await stack.http.queryOk(
+      "billing-foundation:query:billing-plans",
+      {},
+      admin,
+    )) as { plans: Array<{ tier: string; action: string }> };
+    expect(result.plans.find((p) => p.tier === "pro")?.action).toBe("unavailable");
+
+    const error = await stack.http.writeErr(
+      SubscriptionFoundationHandlers.switchPlan,
+      { tier: "pro" },
+      admin,
+    );
+    expect(error.httpStatus).toBe(409);
+    expect(error.i18nKey).toBe("billing-foundation.errors.cancellationScheduled");
+    expect(switchCalls).toHaveLength(0);
+  });
+
   test("the provider rejecting the switch because two tiers share one Stripe product surfaces as a 422, not a 500", async () => {
     const admin = adminFor(7024);
     await createSubscription(admin.tenantId, {

package/src/billing-foundation/__tests__/checkout-core.test.ts

@@ -1,15 +1,18 @@
 import { describe, expect, test } from "bun:test";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { UnconfiguredError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 // Aliased — an un-aliased `Temporal` would shadow the ambient global
 // `Temporal` TYPE `SubscriptionView.lastChangedAt` resolves against.
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import {
   assertRedirectOrigins,
+  isBillingEnabled,
   isNonEmptyStringArray,
   isOwnProviderCustomer,
   joinBaseUrl,
 } from "../checkout-core";
 import type { SubscriptionView } from "../get-subscription-for-tenant";
+import type { SubscriptionProviderPlugin } from "../types";
 
 function subscriptionView(overrides: Partial<SubscriptionView> = {}): SubscriptionView {
   return {
@@ -151,3 +154,35 @@ describe("isOwnProviderCustomer", () => {
     expect(isOwnProviderCustomer(subscriptionView(), "mock", "cus_own")).toBe(true);
   });
 });
+
+function fakeCtxWithProvider(
+  entries: ReadonlyArray<{ readonly entityName: string; readonly options: unknown }>,
+): HandlerContext {
+  return {
+    registry: {
+      getExtensionUsages: () => entries,
+    },
+  } as unknown as HandlerContext; // @cast-boundary test-fixture — only registry is exercised
+}
+
+describe("isBillingEnabled", () => {
+  test("false when no provider with that name is registered", async () => {
+    const ctx = fakeCtxWithProvider([]);
+    expect(await isBillingEnabled(ctx, "stripe")).toBe(false);
+  });
+
+  test("false when the registered plugin's own isBillingEnabled reports false", async () => {
+    const plugin: SubscriptionProviderPlugin = {
+      verifyAndParseWebhook: async () => null,
+      isBillingEnabled: async () => false,
+    };
+    const ctx = fakeCtxWithProvider([{ entityName: "stripe", options: plugin }]);
+    expect(await isBillingEnabled(ctx, "stripe")).toBe(false);
+  });
+
+  test("true when the registered plugin has no isBillingEnabled (defaults to enabled)", async () => {
+    const plugin: SubscriptionProviderPlugin = { verifyAndParseWebhook: async () => null };
+    const ctx = fakeCtxWithProvider([{ entityName: "stripe", options: plugin }]);
+    expect(await isBillingEnabled(ctx, "stripe")).toBe(true);
+  });
+});

package/src/billing-foundation/__tests__/sync-subscription.integration.test.ts

@@ -0,0 +1,469 @@
+// Integration-test for the sync-subscription write-handler (the
+// sync-subscriptions job's backfill target) — real HTTP dispatch through
+// setupTestStack, never createTestDispatcher. Provider-specific
+// retrieveSubscription mapping (Stripe) is covered in subscription-stripe's
+// own plugin-methods.test.ts; this only proves the foundation's own
+// no-live-subscription/provider_cannot_retrieve/not_found/unchanged/synced
+// branching and that a synced drift lands as a real subscription.updated
+// event on the aggregate stream.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetPiiSubjectKmsForTests, waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { TenantHandlers } from "../../tenant/constants";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import { subscriptionAggregateId } from "../aggregate-id";
+import {
+  SubscriptionFoundationHandlers,
+  SubscriptionFoundationQueries,
+  SubscriptionStatuses,
+} from "../constants";
+import { createBillingFoundationFeature } from "../feature";
+import type { ProviderSubscriptionSnapshot, SubscriptionProviderPlugin } from "../types";
+
+let retrieveSnapshot: ProviderSubscriptionSnapshot | null = null;
+// Keyed by providerSubscriptionId — the job-path test fans the same
+// dispatch out to multiple tenants concurrently, each needing its own
+// snapshot; the single `retrieveSnapshot` above only serves the
+// sequential single-tenant tests.
+const retrieveSnapshotsById = new Map<string, ProviderSubscriptionSnapshot>();
+const retrieveCalls: string[] = [];
+
+const mockSyncProviderFeature = defineFeature("test-mock-sync-provider", (r) => {
+  r.requires("billing-foundation");
+  const plugin: SubscriptionProviderPlugin = {
+    verifyAndParseWebhook: async () => null,
+    retrieveSubscription: async (_ctx, providerSubscriptionId) => {
+      retrieveCalls.push(providerSubscriptionId);
+      return retrieveSnapshotsById.get(providerSubscriptionId) ?? retrieveSnapshot;
+    },
+  };
+  r.useExtension("subscriptionProvider", "mock-sync-provider", plugin);
+});
+
+// No `retrieveSubscription` — exercises the "provider_cannot_retrieve" branch.
+const mockNoRetrieveProviderFeature = defineFeature("test-mock-no-retrieve-provider", (r) => {
+  r.requires("billing-foundation");
+  const plugin: SubscriptionProviderPlugin = { verifyAndParseWebhook: async () => null };
+  r.useExtension("subscriptionProvider", "mock-no-retrieve-provider", plugin);
+});
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      createBillingFoundationFeature({ baseUrl: "https://example.com" }),
+      mockSyncProviderFeature,
+      mockNoRetrieveProviderFeature,
+    ],
+    // Only the job-path describe-block below needs a real worker — every
+    // other test dispatches syncSubscription directly. `getActiveTenantIds`
+    // is omitted: the tenant feature is mounted, so the framework resolves
+    // active tenants via tenant:query:active-tenant-ids itself, same as prod.
+    jobs: { consumerLane: "worker" },
+  });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, tenantEntity);
+  await unsafeCreateEntityTable(db, tenantComplianceProfileEntity);
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+  resetPiiSubjectKmsForTests();
+});
+
+beforeEach(() => {
+  retrieveSnapshot = null;
+  retrieveSnapshotsById.clear();
+  retrieveCalls.length = 0;
+});
+
+function adminFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+}
+
+async function createSubscription(
+  tenantId: string,
+  overrides: Partial<{
+    providerEventId: string;
+    providerName: string;
+    status: string;
+    tier: string;
+    providerSubscriptionId: string;
+    providerCustomerId: string;
+    currentPeriodEndIso: string;
+    cancelAtIso: string | null;
+  }> = {},
+) {
+  const admin = createTestUser({ id: 0, tenantId, roles: ["TenantAdmin", "SystemAdmin"] });
+  return stack.http.writeOk(
+    SubscriptionFoundationHandlers.processEvent,
+    {
+      providerEventId: overrides.providerEventId ?? `evt_${tenantId}_create`,
+      providerName: overrides.providerName ?? "mock-sync-provider",
+      type: "subscription.created",
+      providerCustomerId: overrides.providerCustomerId ?? `cus_${tenantId}`,
+      providerSubscriptionId: overrides.providerSubscriptionId ?? `sub_${tenantId}`,
+      status: overrides.status ?? SubscriptionStatuses.active,
+      tier: overrides.tier ?? "pro",
+      currentPeriodEndIso: overrides.currentPeriodEndIso ?? "2026-06-01T00:00:00Z",
+      ...(overrides.cancelAtIso !== undefined && { cancelAtIso: overrides.cancelAtIso }),
+      rawPayload: '{"raw":"payload"}',
+    },
+    admin,
+  );
+}
+
+describe("sync-subscription", () => {
+  test("no subscription for the tenant → no_live_subscription, provider never called", async () => {
+    const admin = adminFor(6001);
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      admin,
+    )) as { synced: boolean; reason?: string };
+    expect(result).toEqual({ synced: false, reason: "no_live_subscription" });
+    expect(retrieveCalls).toHaveLength(0);
+  });
+
+  test("provider drift (new cancel_at) → synced, projection updated, a sync:-prefixed updated event appended; a same-state re-sync then reports unchanged with no new event", async () => {
+    const admin = adminFor(6002);
+    await createSubscription(admin.tenantId, {
+      providerSubscriptionId: "sub_6002",
+      providerCustomerId: "cus_6002",
+      tier: "pro",
+    });
+
+    retrieveSnapshot = {
+      providerCustomerId: "cus_6002",
+      providerSubscriptionId: "sub_6002",
+      status: SubscriptionStatuses.active,
+      tier: "pro",
+      currentPeriodEnd: "2026-06-01T00:00:00Z",
+      cancelAt: "2026-05-01T00:00:00Z",
+      rawPayload: '{"raw":"provider-drift"}',
+    };
+
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      admin,
+    )) as { synced: boolean };
+    expect(result).toEqual({ synced: true });
+    expect(retrieveCalls).toEqual(["sub_6002"]);
+
+    const subs = (await stack.http.queryOk(
+      "billing-foundation:query:subscription:list",
+      {},
+      admin,
+    )) as { rows: Array<Record<string, unknown>> };
+    expect(String(subs.rows[0]?.["cancelAt"])).toBe(
+      Temporal.Instant.from("2026-05-01T00:00:00Z").toString(),
+    );
+
+    const esEvents = await loadAggregate(
+      db,
+      subscriptionAggregateId(admin.tenantId),
+      admin.tenantId,
+    );
+    expect(esEvents).toHaveLength(2); // create + sync-update
+    expect(esEvents[1]?.type).toBe("billing-foundation:event:subscription-updated");
+    expect(esEvents[1]?.metadata.headers?.["providerEventId"]).toMatch(/^sync:/);
+
+    // Round-trip: dispatching again against the SAME provider state (now
+    // read back from the DB, not the seed) must compare as unchanged and
+    // append nothing — proves the instant-comparison, not just the initial
+    // string-equality-by-luck.
+    const secondResult = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      admin,
+    )) as { synced: boolean; reason?: string };
+    expect(secondResult).toEqual({ synced: false, reason: "unchanged" });
+
+    const esEventsAfterSecondSync = await loadAggregate(
+      db,
+      subscriptionAggregateId(admin.tenantId),
+      admin.tenantId,
+    );
+    expect(esEventsAfterSecondSync).toHaveLength(2);
+  });
+
+  test("cancel → sync → reactivate → sync → cancel-again → sync appends a third update, not a duplicate-hash skip", async () => {
+    const admin = adminFor(6007);
+    await createSubscription(admin.tenantId, {
+      providerSubscriptionId: "sub_6007",
+      providerCustomerId: "cus_6007",
+      tier: "pro",
+    });
+
+    const cancelSnapshot: ProviderSubscriptionSnapshot = {
+      providerCustomerId: "cus_6007",
+      providerSubscriptionId: "sub_6007",
+      status: SubscriptionStatuses.active,
+      tier: "pro",
+      currentPeriodEnd: "2026-06-01T00:00:00Z",
+      cancelAt: "2026-05-01T00:00:00Z",
+      rawPayload: '{"raw":"cancel"}',
+    };
+    const reactivatedSnapshot: ProviderSubscriptionSnapshot = { ...cancelSnapshot, cancelAt: null };
+
+    retrieveSnapshot = cancelSnapshot;
+    expect(
+      (await stack.http.writeOk(SubscriptionFoundationHandlers.syncSubscription, {}, admin)) as {
+        synced: boolean;
+      },
+    ).toEqual({ synced: true });
+
+    retrieveSnapshot = reactivatedSnapshot;
+    expect(
+      (await stack.http.writeOk(SubscriptionFoundationHandlers.syncSubscription, {}, admin)) as {
+        synced: boolean;
+      },
+    ).toEqual({ synced: true });
+
+    retrieveSnapshot = cancelSnapshot; // same content as the FIRST sync's snapshot
+    const thirdResult = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      admin,
+    )) as { synced: boolean };
+    expect(thirdResult).toEqual({ synced: true });
+
+    const esEvents = await loadAggregate(
+      db,
+      subscriptionAggregateId(admin.tenantId),
+      admin.tenantId,
+    );
+    expect(esEvents).toHaveLength(4); // create + 3 syncs, none skipped as a hash-duplicate
+  });
+
+  test("the sync-subscriptions job's own SYSTEM_ROLE-only actor (no SystemAdmin) can dispatch sync-subscription", async () => {
+    const tenantId = testTenantId(6008);
+    await createSubscription(tenantId, {
+      providerSubscriptionId: "sub_6008",
+      providerCustomerId: "cus_6008",
+      tier: "pro",
+    });
+
+    retrieveSnapshot = {
+      providerCustomerId: "cus_6008",
+      providerSubscriptionId: "sub_6008",
+      status: SubscriptionStatuses.active,
+      tier: "pro",
+      currentPeriodEnd: "2026-06-01T00:00:00Z",
+      cancelAt: "2026-05-01T00:00:00Z",
+      rawPayload: '{"raw":"system-actor"}',
+    };
+
+    // Mirrors createSystemUser(tenantId) exactly — no extraRoles — matching
+    // what the sync-subscriptions job's JobContext.write actually dispatches
+    // as (job-runner.ts), unlike every other test here which authenticates
+    // as a SystemAdmin over HTTP.
+    const systemUser = createSystemUser(tenantId);
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      systemUser,
+    )) as { synced: boolean };
+    expect(result).toEqual({ synced: true });
+  });
+
+  test("the resolved provider plugin has no retrieveSubscription → provider_cannot_retrieve", async () => {
+    const admin = adminFor(6004);
+    await createSubscription(admin.tenantId, {
+      providerName: "mock-no-retrieve-provider",
+      providerSubscriptionId: "sub_6004",
+      providerCustomerId: "cus_6004",
+    });
+
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      admin,
+    )) as { synced: boolean; reason?: string };
+    expect(result).toEqual({ synced: false, reason: "provider_cannot_retrieve" });
+  });
+
+  test("the provider no longer knows the subscription → not_found", async () => {
+    const admin = adminFor(6005);
+    await createSubscription(admin.tenantId, {
+      providerSubscriptionId: "sub_6005",
+      providerCustomerId: "cus_6005",
+    });
+    retrieveSnapshot = null;
+
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      admin,
+    )) as { synced: boolean; reason?: string };
+    expect(result).toEqual({ synced: false, reason: "not_found" });
+  });
+
+  test("provider snapshot has gone terminal (canceled) → appends a canceled-type event, not updated", async () => {
+    const admin = adminFor(6009);
+    await createSubscription(admin.tenantId, {
+      providerSubscriptionId: "sub_6009",
+      providerCustomerId: "cus_6009",
+      tier: "pro",
+    });
+
+    retrieveSnapshot = {
+      providerCustomerId: "cus_6009",
+      providerSubscriptionId: "sub_6009",
+      status: SubscriptionStatuses.canceled,
+      tier: "pro",
+      currentPeriodEnd: "2026-06-01T00:00:00Z",
+      cancelAt: "2026-05-01T00:00:00Z",
+      rawPayload: '{"raw":"provider-canceled"}',
+    };
+
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      admin,
+    )) as { synced: boolean };
+    expect(result).toEqual({ synced: true });
+
+    const esEvents = await loadAggregate(
+      db,
+      subscriptionAggregateId(admin.tenantId),
+      admin.tenantId,
+    );
+    expect(esEvents).toHaveLength(2); // create + sync-cancel
+    expect(esEvents[1]?.type).toBe("billing-foundation:event:subscription-canceled");
+
+    const subs = (await stack.http.queryOk(
+      SubscriptionFoundationQueries.listSubscriptions,
+      {},
+      admin,
+    )) as { rows: Array<Record<string, unknown>> };
+    expect(subs.rows[0]?.["status"]).toBe(SubscriptionStatuses.canceled);
+  });
+
+  test("a terminal (canceled) subscription → no_live_subscription, provider never called", async () => {
+    const admin = adminFor(6006);
+    await createSubscription(admin.tenantId, {
+      providerSubscriptionId: "sub_6006",
+      providerCustomerId: "cus_6006",
+      status: SubscriptionStatuses.canceled,
+    });
+
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.syncSubscription,
+      {},
+      admin,
+    )) as { synced: boolean; reason?: string };
+    expect(result).toEqual({ synced: false, reason: "no_live_subscription" });
+    expect(retrieveCalls).toHaveLength(0);
+  });
+});
+
+// --- The actual `sync-subscriptions` job (perTenant fan-out via a real
+// jobRunner/BullMQ worker), not the handler dispatched directly — every test
+// above proves the handler's own branching; this proves the job wrapper
+// resolves active tenants and fans out to each of them independently. ---
+describe("sync-subscriptions job (perTenant fan-out)", () => {
+  test("dispatching the job syncs every active tenant's own live subscription independently", async () => {
+    if (!stack.jobRunner) {
+      throw new Error("stack.jobRunner not wired — setupTestStack's `jobs` option is required");
+    }
+    const admin1 = adminFor(6020);
+    const admin2 = adminFor(6021);
+    // active-tenant-ids (the framework's own perTenant fan-out source, since
+    // this stack mounts the tenant feature) only returns rows that actually
+    // exist in tenantTable — adminFor()'s tenantId alone is not enough.
+    await stack.http.writeOk(
+      TenantHandlers.create,
+      { id: admin1.tenantId, key: `t-${admin1.tenantId}`, name: "Job-Fanout Tenant A" },
+      admin1,
+    );
+    await stack.http.writeOk(
+      TenantHandlers.create,
+      { id: admin2.tenantId, key: `t-${admin2.tenantId}`, name: "Job-Fanout Tenant B" },
+      admin2,
+    );
+
+    await createSubscription(admin1.tenantId, {
+      providerSubscriptionId: "sub_6020",
+      providerCustomerId: "cus_6020",
+      tier: "pro",
+    });
+    await createSubscription(admin2.tenantId, {
+      providerSubscriptionId: "sub_6021",
+      providerCustomerId: "cus_6021",
+      tier: "pro",
+    });
+
+    retrieveSnapshotsById.set("sub_6020", {
+      providerCustomerId: "cus_6020",
+      providerSubscriptionId: "sub_6020",
+      status: SubscriptionStatuses.active,
+      tier: "pro",
+      currentPeriodEnd: "2026-06-01T00:00:00Z",
+      cancelAt: "2026-05-01T00:00:00Z",
+      rawPayload: '{"raw":"job-fanout-a"}',
+    });
+    retrieveSnapshotsById.set("sub_6021", {
+      providerCustomerId: "cus_6021",
+      providerSubscriptionId: "sub_6021",
+      status: SubscriptionStatuses.active,
+      tier: "pro",
+      currentPeriodEnd: "2026-06-01T00:00:00Z",
+      cancelAt: "2026-04-15T00:00:00Z",
+      rawPayload: '{"raw":"job-fanout-b"}',
+    });
+
+    await stack.jobRunner.dispatch("billing-foundation:job:sync-subscriptions", {});
+
+    async function cancelAtFor(admin: ReturnType<typeof adminFor>): Promise<unknown> {
+      const subs = (await stack.http.queryOk(
+        SubscriptionFoundationQueries.listSubscriptions,
+        {},
+        admin,
+      )) as { rows: Array<Record<string, unknown>> };
+      return subs.rows[0]?.["cancelAt"];
+    }
+
+    await waitFor(async () => {
+      expect(await cancelAtFor(admin1)).not.toBeNull();
+      expect(await cancelAtFor(admin2)).not.toBeNull();
+    });
+
+    expect(await cancelAtFor(admin1)).toBe(
+      Temporal.Instant.from("2026-05-01T00:00:00Z").toString(),
+    );
+    expect(await cancelAtFor(admin2)).toBe(
+      Temporal.Instant.from("2026-04-15T00:00:00Z").toString(),
+    );
+  });
+});

package/src/billing-foundation/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "breaking",
+    "title": "switch-plan rejects a subscription with a scheduled cancellation",
+    "detail": "`billing-foundation:write:switch-plan` now throws a `409 ConflictError`\n(`billing-foundation.errors.cancellationScheduled`) when the tenant's\nsubscription already has `cancelAt` set — switching plans mid-cancellation\npreviously silently proceeded and could leave the new plan itself\nscheduled to cancel. `billing-foundation:query:billing-plans` now resolves every\nnon-current plan's `action` to `unavailable` (instead of `switch`) while a\ncancellation is scheduled, and the billing-plans panel shows a\n`switchRequiresReactivation` message alongside the existing\n`cancelScheduled` banner.",
+    "migration": "A tenant that switches plans while their subscription is scheduled to\ncancel now gets a 409 instead of a successful switch. Callers driving\n`switch-plan` directly (not through the bundled panel) must reactivate the\nsubscription first (`create-portal-session` / the provider's own\nreactivation flow) before retrying the switch."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "past_due banner on the billing-plans panel; sync-subscription backfill for provider-side drift",
+    "detail": "`billing-plans-panel` renders a `past_due`-status warning banner\n(`billing-foundation.plans.pastDue`) alongside the existing\npayment-pending/cancel-scheduled ones. `SubscriptionProviderPlugin` gained\nan optional `retrieveSubscription(ctx, providerSubscriptionId)` method\nreturning a `ProviderSubscriptionSnapshot`; the new\n`billing-foundation:write:sync-subscription` handler (`agent.expose:\nfalse`, `SYSTEM_ROLE`/`SystemAdmin`-only — the `sync-subscriptions` job's\nown systemUser only carries `SYSTEM_ROLE`) compares the live snapshot\nagainst `read_subscriptions` and appends a `subscription.updated` (or\n`subscription.canceled`, when the snapshot's own status is terminal)\nevent with a deterministic `sync:<sha256>` providerEventId when it has\ndrifted, a no-op otherwise. The `sync-subscriptions` job (manual-trigger +\nrunOnBoot, perTenant) dispatches it and is registered unconditionally.\n`isBillingEnabled(ctx, providerName)` returns `false` instead of throwing\nwhen `providerName` isn't registered.",
+    "migration": "No action needed — every part is additive. Apps on `subscription-stripe`\nautomatically get `retrieveSubscription` wired; a custom provider plugin\nwithout one makes `sync-subscription` report\n`{ synced: false, reason: \"provider_cannot_retrieve\" }` instead of syncing.\nOn the next deploy, `sync-subscriptions`' `runOnBoot` fires once per Redis\ndataset (not once per replica) with one provider API call per tenant that\nhas a live subscription. If that run is interrupted (deploy killed\nmid-fan-out, Redis restart), it is not re-run automatically on the next\nboot — trigger it manually via `billing-foundation:job:sync-subscriptions`\n(`jobs:write:trigger`) to catch up."
+  },
   {
     "version": "0.319.0",
     "type": "improvement",

package/src/billing-foundation/checkout-core.ts

@@ -141,15 +141,19 @@ export async function assertBillingEnabled(
   }
 }
 
-/** Public readiness-probe for a named provider — `resolveProviderPlugin` +
+/** Public readiness-probe for a named provider — `findProviderPlugin` +
  *  `isPluginBillingEnabled`, re-exported from index.ts so an app-owner can
- *  check billing readiness without reaching into checkout-core internals. */
+ *  check billing readiness without reaching into checkout-core internals.
+ *  An unregistered provider is a "not live" state, not a config error here
+ *  (unlike `resolveProviderPlugin`'s throw) — a readiness probe should
+ *  answer false, not throw, for a provider that simply isn't mounted yet. */
 export async function isBillingEnabled(
   ctx: HandlerContext,
   providerName: string,
 ): Promise<boolean> {
-  const { plugin } = resolveProviderPlugin(ctx, providerName);
-  return isPluginBillingEnabled(ctx, plugin);
+  const found = findProviderPlugin(ctx, providerName);
+  if (!found) return false;
+  return isPluginBillingEnabled(ctx, found.plugin);
 }
 
 /** `create-portal-session`'s returnUrl, built server-side (the client no

package/src/billing-foundation/constants.ts

@@ -44,6 +44,12 @@ export const SubscriptionFoundationHandlers = {
    *  subscription to another plan tier via the provider's confirmation
    *  page. Only registered when a `catalog` is configured. */
   switchPlan: "billing-foundation:write:switch-plan",
+  /** Backfill entry-point for the `sync-subscriptions` job (and any
+   *  SystemAdmin that wants an on-demand reconciliation). Pulls the live
+   *  provider-side state via the plugin's `retrieveSubscription` and
+   *  appends drift as a `subscription.updated` event. `agent.expose: false`
+   *  — programmatic only. */
+  syncSubscription: "billing-foundation:write:sync-subscription",
 } as const;
 
 // Qualified query handler names.