@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

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

@@ -1,1061 +0,0 @@
-// Integration-test for the catalog-derived billing-plans query + the
-// start-plan-checkout/switch-plan write-handlers (createBillingFoundationFeature
-// with a `catalog`). Foundation-level routing/state-machine test — provider-
-// specific behavior (real Stripe price/portal calls) is covered in
-// subscription-stripe's own tests.
-//
-// Mock-provider strategy: same as billing-foundation.integration.test.ts's
-// scenario 6/7 mock, extended with a `priceToTier` catalog + mutable
-// isBillingEnabled/retrievePrices toggles so every spec branch (disabled,
-// price-lookup failure, legacy inactive price, ...) is reachable per-test
-// without a second setupTestStack.
-
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
-import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
-import {
-  createTestUser,
-  setupTestStack,
-  type TestStack,
-  testTenantId,
-  unsafeCreateEntityTable,
-} from "@cosmicdrift/kumiko-framework/stack";
-import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
-// Aliased — an un-aliased `Temporal` would shadow the ambient global
-// `Temporal` TYPE `createBillingFoundationFeature`'s `now` option resolves
-// against.
-import { Temporal as TemporalPolyfill } from "temporal-polyfill";
-import {
-  createComplianceProfilesFeature,
-  tenantComplianceProfileEntity,
-} from "../../compliance-profiles";
-import { createConfigFeature } from "../../config";
-import { createTenantFeature } from "../../tenant/feature";
-import { tenantEntity } from "../../tenant/schema/tenant";
-import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
-import { subscriptionAggregateId } from "../aggregate-id";
-import { SubscriptionFoundationHandlers, SubscriptionStatuses } from "../constants";
-import { createBillingFoundationFeature } from "../feature";
-import { subscriptionsProjectionTable } from "../projection";
-import type { BillingPlanCatalog, ProviderPrice, SubscriptionProviderPlugin } from "../types";
-
-type PlanTier = "starter" | "pro";
-
-const PRICE_TO_TIER: Readonly<Record<string, string>> = {
-  price_starter: "starter",
-  price_pro: "pro",
-  price_pro_legacy: "pro",
-  price_pilot: "pilot",
-};
-
-function stripePrice(
-  overrides: Partial<ProviderPrice> & { readonly priceId: string },
-): ProviderPrice {
-  return {
-    unitAmount: 1900,
-    currency: "usd",
-    interval: "month",
-    intervalCount: 1,
-    active: true,
-    metadata: {},
-    ...overrides,
-  };
-}
-
-const PRICES: readonly ProviderPrice[] = [
-  stripePrice({ priceId: "price_starter", unitAmount: 900 }),
-  stripePrice({ priceId: "price_pro", unitAmount: 1900 }),
-  // Legacy price for the same tier as price_pro — inactive, so resolvePlanPrices
-  // still picks exactly one active flat-amount price for "pro" (price_pro).
-  stripePrice({ priceId: "price_pro_legacy", unitAmount: 1500, active: false }),
-];
-
-let billingEnabled = true;
-let retrievePricesMode: "ok" | "throw" = "ok";
-// Isolated per-test toggle for switch-plan's provider call — reset in
-// beforeEach so a test that sets it never leaks into the next one.
-let switchPlanErrorMode: "ok" | "plan_tiers_share_product" = "ok";
-const checkoutCalls: Array<{
-  priceId: string;
-  successUrl: string;
-  cancelUrl: string;
-  providerCustomerId?: string;
-  mode?: string;
-}> = [];
-const switchCalls: Array<{
-  providerSubscriptionId: string;
-  targetPriceId: string;
-  allowedPriceIds: readonly string[];
-  returnUrl: string;
-}> = [];
-const portalCalls: Array<{ providerCustomerId: string; returnUrl: string }> = [];
-
-const mockPlanProviderFeature = defineFeature("test-mock-plan-provider", (r) => {
-  r.requires("billing-foundation");
-  const plugin: SubscriptionProviderPlugin = {
-    verifyAndParseWebhook: async () => null,
-    priceToTier: PRICE_TO_TIER,
-    oneOffPriceIds: ["price_topup_credits"],
-    isBillingEnabled: async () => billingEnabled,
-    retrievePrices: async (_ctx, priceIds) => {
-      if (retrievePricesMode === "throw") throw new Error("mock provider price lookup failed");
-      return PRICES.filter((p) => priceIds.includes(p.priceId));
-    },
-    createCheckoutSession: async (_ctx, options) => {
-      checkoutCalls.push({
-        priceId: options.priceId,
-        successUrl: options.successUrl,
-        cancelUrl: options.cancelUrl,
-        ...(options.providerCustomerId && { providerCustomerId: options.providerCustomerId }),
-        ...(options.mode && { mode: options.mode }),
-      });
-      return { url: `https://mock.example/checkout/${options.priceId}` };
-    },
-    createPortalSession: async (_ctx, options) => {
-      portalCalls.push({
-        providerCustomerId: options.providerCustomerId,
-        returnUrl: options.returnUrl,
-      });
-      return { url: `https://mock.example/portal/${options.providerCustomerId}` };
-    },
-    createPlanSwitchSession: async (_ctx, options) => {
-      if (switchPlanErrorMode === "plan_tiers_share_product") {
-        throw new UnprocessableError("plan_tiers_share_product", {
-          i18nKey: "billing-foundation.errors.planTiersShareProduct",
-          message: "mock provider: allowed prices share a Stripe product",
-        });
-      }
-      switchCalls.push(options);
-      return { url: `https://mock.example/portal/switch/${options.targetPriceId}` };
-    },
-  };
-  r.useExtension("subscriptionProvider", "mock-plan-provider", plugin);
-});
-
-// Second registered provider — exists only so a subscription can be created
-// on a DIFFERENT provider than the catalog resolves, exercising switch-plan's
-// providerMismatch conflict. Deliberately minimal: no priceToTier, so it
-// never becomes the catalog's ambiguous default.
-const mockOtherProviderFeature = defineFeature("test-mock-other-provider", (r) => {
-  r.requires("billing-foundation");
-  const plugin: SubscriptionProviderPlugin = {
-    verifyAndParseWebhook: async () => null,
-  };
-  r.useExtension("subscriptionProvider", "mock-other-provider", plugin);
-});
-
-/** Same shape as `BillingInfoQueryDeps.resolveTier` (spec): reads the
- *  subscription projection directly via `TenantDb`, no HandlerContext. A
- *  non-active/trialing subscription (or none at all) resolves to "free" —
- *  deliberately outside `catalog.plans`, matching a tenant that has never
- *  purchased a plan. */
-async function resolveCurrentTier(db: TenantDb, tenantId: string): Promise<string> {
-  const rows = await db.selectMany(
-    subscriptionsProjectionTable,
-    { id: subscriptionAggregateId(tenantId) },
-    { limit: 1 },
-  );
-  const row = rows[0];
-  if (!row) return "free";
-  const status = row["status"] as string;
-  const tier = row["tier"] as string;
-  return status === SubscriptionStatuses.active || status === SubscriptionStatuses.trialing
-    ? tier
-    : "free";
-}
-
-function catalog(
-  overrides: Partial<BillingPlanCatalog<PlanTier>> = {},
-): BillingPlanCatalog<PlanTier> {
-  return {
-    plans: ["starter", "pro"],
-    tierLabelKey: (tier) => `plan.${tier}.label`,
-    benefits: (tier) => [{ labelKey: `plan.${tier}.benefit.core` }],
-    resolveCurrentTier,
-    viewRoles: ["TenantAdmin", "SystemAdmin"],
-    successPath: "/billing/success",
-    cancelPath: "/billing/cancel",
-    providerName: "mock-plan-provider",
-    ...overrides,
-  };
-}
-
-let stack: TestStack;
-
-beforeAll(async () => {
-  stack = await setupTestStack({
-    features: [
-      createConfigFeature(),
-      createTenantFeature(),
-      createComplianceProfilesFeature(),
-      createTenantLifecycleFeature(),
-      createBillingFoundationFeature({ baseUrl: "https://app.example.com", catalog: catalog() }),
-      mockPlanProviderFeature,
-      mockOtherProviderFeature,
-    ],
-  });
-  await unsafeCreateEntityTable(stack.db, tenantEntity);
-  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
-  configurePiiSubjectKms(new InMemoryKmsAdapter());
-});
-
-afterAll(async () => {
-  await stack.cleanup();
-  resetPiiSubjectKmsForTests();
-});
-
-beforeEach(() => {
-  billingEnabled = true;
-  retrievePricesMode = "ok";
-  switchPlanErrorMode = "ok";
-  checkoutCalls.length = 0;
-  switchCalls.length = 0;
-  portalCalls.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;
-    cancelAtIso: string | null;
-  }> = {},
-  onStack: TestStack = stack,
-) {
-  const admin = createTestUser({ id: 0, tenantId, roles: ["TenantAdmin", "SystemAdmin"] });
-  return onStack.http.writeOk(
-    SubscriptionFoundationHandlers.processEvent,
-    {
-      providerEventId: overrides.providerEventId ?? `evt_${tenantId}_create`,
-      providerName: overrides.providerName ?? "mock-plan-provider",
-      type: "subscription.created",
-      providerCustomerId: overrides.providerCustomerId ?? `cus_${tenantId}`,
-      providerSubscriptionId: overrides.providerSubscriptionId ?? `sub_${tenantId}`,
-      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,
-  );
-}
-
-// =============================================================================
-// 1. No subscription — enabled, priced, checkout for both, canPurchase true.
-// =============================================================================
-
-describe("billing-plans query — no subscription", () => {
-  test("both plans priced with checkout action, currentTier free", async () => {
-    const admin = adminFor(7001);
-    const result = (await stack.http.queryOk(
-      "billing-foundation:query:billing-plans",
-      {},
-      admin,
-    )) as {
-      enabled: boolean;
-      currentTier: { tier: string; benefits: Array<{ labelKey: string }> };
-      canPurchase: boolean;
-      subscription: unknown;
-      plans: Array<{ tier: string; action: string; price: { unitAmount: number } | null }>;
-    };
-
-    expect(result.enabled).toBe(true);
-    expect(result.currentTier.tier).toBe("free");
-    // #3316 P2: "free" is outside catalog.plans (["starter", "pro"]) — the
-    // benefits lookup must not be gated on membership in catalog.plans.
-    expect(result.currentTier.benefits).toEqual([{ labelKey: "plan.free.benefit.core" }]);
-    expect(result.subscription).toBeNull();
-    expect(result.canPurchase).toBe(true);
-    expect(result.plans).toHaveLength(2);
-    const starter = result.plans.find((p) => p.tier === "starter");
-    const pro = result.plans.find((p) => p.tier === "pro");
-    expect(starter?.action).toBe("checkout");
-    expect(starter?.price?.unitAmount).toBe(900);
-    expect(pro?.action).toBe("checkout");
-    expect(pro?.price?.unitAmount).toBe(1900);
-  });
-});
-
-// =============================================================================
-// 2. start-plan-checkout — resolves the live (non-legacy) price + builds
-//    baseUrl-origin URLs, preserving a baseUrl path-prefix.
-// =============================================================================
-
-describe("start-plan-checkout — no existing subscription", () => {
-  test("pro tier resolves to price_pro (not the inactive legacy price), URLs use baseUrl + paths", async () => {
-    const admin = adminFor(7002);
-    const result = (await stack.http.writeOk(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      admin,
-    )) as { url: string };
-
-    expect(result.url).toBe("https://mock.example/checkout/price_pro");
-    expect(checkoutCalls).toHaveLength(1);
-    expect(checkoutCalls[0]).toEqual({
-      priceId: "price_pro",
-      successUrl: "https://app.example.com/billing/success",
-      cancelUrl: "https://app.example.com/billing/cancel",
-      mode: "subscription",
-    });
-  });
-});
-
-// =============================================================================
-// 3. Tier outside catalog.plans is rejected by the zod enum before the handler runs.
-// =============================================================================
-
-describe("start-plan-checkout / switch-plan — tier outside the catalog", () => {
-  test("start-plan-checkout rejects a tier not in catalog.plans", async () => {
-    const admin = adminFor(7003);
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pilot" },
-      admin,
-    );
-    // Rejected by the zod z.enum(catalog.plans) schema before the handler runs.
-    expect(error.httpStatus).toBe(400);
-  });
-
-  test("switch-plan rejects a tier not in catalog.plans", async () => {
-    const admin = adminFor(7004);
-    await createSubscription(admin.tenantId, { tier: "starter" });
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.switchPlan,
-      { tier: "free" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(400);
-  });
-});
-
-// =============================================================================
-// 4. Active non-terminal subscription — query shows current/switch, checkout
-//    is blocked, payment-mode checkout on create-checkout-session stays open.
-// =============================================================================
-
-describe("active subscription — checkout blocked, switch offered", () => {
-  test("query: starter is current, pro is switchable", async () => {
-    const admin = adminFor(7005);
-    await createSubscription(admin.tenantId, { tier: "starter" });
-
-    const result = (await stack.http.queryOk(
-      "billing-foundation:query:billing-plans",
-      {},
-      admin,
-    )) as {
-      plans: Array<{ tier: string; action: string; isCurrent: boolean }>;
-    };
-    const starter = result.plans.find((p) => p.tier === "starter");
-    const pro = result.plans.find((p) => p.tier === "pro");
-    expect(starter?.isCurrent).toBe(true);
-    expect(starter?.action).toBe("current");
-    expect(pro?.action).toBe("switch");
-  });
-
-  test("start-plan-checkout is rejected with a conflict while a non-terminal subscription exists", async () => {
-    const admin = adminFor(7006);
-    await createSubscription(admin.tenantId, { tier: "starter" });
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(409);
-  });
-
-  test("create-checkout-session mode:subscription is rejected the same way", async () => {
-    const admin = adminFor(7007);
-    await createSubscription(admin.tenantId, { tier: "starter" });
-    const error = await stack.http.writeErr(
-      "billing-foundation:write:create-checkout-session",
-      {
-        providerName: "mock-plan-provider",
-        priceId: "price_pro",
-        successUrl: "https://app.example.com/s",
-        cancelUrl: "https://app.example.com/c",
-      },
-      admin,
-    );
-    expect(error.httpStatus).toBe(409);
-  });
-
-  test("create-checkout-session mode:payment stays allowed on an active subscription", async () => {
-    checkoutCalls.length = 0;
-    const admin = adminFor(7008);
-    await createSubscription(admin.tenantId, { tier: "starter" });
-    const result = (await stack.http.writeOk(
-      "billing-foundation:write:create-checkout-session",
-      {
-        providerName: "mock-plan-provider",
-        priceId: "price_topup_credits",
-        successUrl: "https://app.example.com/s",
-        cancelUrl: "https://app.example.com/c",
-        mode: "payment",
-      },
-      admin,
-    )) as { url: string };
-    expect(result.url).toBe("https://mock.example/checkout/price_topup_credits");
-    // #3316 P8: the plugin receives mode:"payment", not silently defaulted
-    // to "subscription" or dropped.
-    expect(checkoutCalls[0]?.mode).toBe("payment");
-  });
-
-  test("create-checkout-session mode:payment rejects a priceId outside the provider's oneOffPriceIds allowlist", async () => {
-    const admin = adminFor(7025);
-    const error = await stack.http.writeErr(
-      "billing-foundation:write:create-checkout-session",
-      {
-        providerName: "mock-plan-provider",
-        priceId: "price_not_on_allowlist",
-        successUrl: "https://app.example.com/s",
-        cancelUrl: "https://app.example.com/c",
-        mode: "payment",
-      },
-      admin,
-    );
-    expect(error.httpStatus).toBe(422);
-    expect(error.i18nKey).toBe("billing-foundation.errors.unknownPrice");
-  });
-
-  // Ordering pin: mode:"payment" runs the billing-enabled gate BEFORE the
-  // oneOffPriceIds allowlist check, same as mode:"subscription" already did.
-  // Without this order, a disabled provider would leak "unknown_price" (a
-  // provider-shape detail) instead of the generic "billing disabled" signal.
-  test("create-checkout-session mode:payment with billing disabled fails feature_disabled, not unknown_price", async () => {
-    billingEnabled = false;
-    const admin = adminFor(7026);
-    const error = await stack.http.writeErr(
-      "billing-foundation:write:create-checkout-session",
-      {
-        providerName: "mock-plan-provider",
-        priceId: "price_not_on_allowlist",
-        successUrl: "https://app.example.com/s",
-        cancelUrl: "https://app.example.com/c",
-        mode: "payment",
-      },
-      admin,
-    );
-    expect(error.httpStatus).toBe(403);
-  });
-});
-
-// =============================================================================
-// 5. switch-plan — payload passed to createPlanSwitchSession, self-switch and
-//    no-subscription both rejected.
-// =============================================================================
-
-describe("switch-plan", () => {
-  test("pro switch passes providerSubscriptionId, targetPriceId, allowedPriceIds, returnUrl", async () => {
-    const admin = adminFor(7009);
-    await createSubscription(admin.tenantId, {
-      tier: "starter",
-      providerSubscriptionId: "sub_switch_7009",
-    });
-
-    const result = (await stack.http.writeOk(
-      SubscriptionFoundationHandlers.switchPlan,
-      { tier: "pro" },
-      admin,
-    )) as { url: string };
-
-    expect(result.url).toBe("https://mock.example/portal/switch/price_pro");
-    expect(switchCalls).toHaveLength(1);
-    expect(switchCalls[0]).toEqual({
-      providerSubscriptionId: "sub_switch_7009",
-      targetPriceId: "price_pro",
-      allowedPriceIds: expect.arrayContaining(["price_starter", "price_pro"]),
-      returnUrl: "https://app.example.com/billing/success",
-    });
-  });
-
-  test("switching to the current tier is a conflict", async () => {
-    const admin = adminFor(7010);
-    await createSubscription(admin.tenantId, { tier: "starter" });
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.switchPlan,
-      { tier: "starter" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(409);
-  });
-
-  test("switching without any subscription is a conflict", async () => {
-    const admin = adminFor(7011);
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.switchPlan,
-      { tier: "pro" },
-      admin,
-    );
-    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, {
-      tier: "starter",
-      providerSubscriptionId: "sub_switch_7024",
-    });
-    switchPlanErrorMode = "plan_tiers_share_product";
-
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.switchPlan,
-      { tier: "pro" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(422);
-    expect(error.i18nKey).toBe("billing-foundation.errors.planTiersShareProduct");
-    expect(error.details).toMatchObject({ reason: "plan_tiers_share_product" });
-  });
-});
-
-// =============================================================================
-// 6. Canceled (terminal) subscription — treated like "no subscription" for
-//    checkout purposes, old provider-customer-id carried forward.
-// =============================================================================
-
-describe("canceled subscription — fresh checkout, old customer-id reused", () => {
-  test("query offers checkout again; start-plan-checkout succeeds and forwards providerCustomerId", async () => {
-    const admin = adminFor(7012);
-    await createSubscription(admin.tenantId, {
-      providerEventId: "evt_7012_create",
-      tier: "starter",
-      providerCustomerId: "cus_7012_old",
-    });
-    await createSubscription(admin.tenantId, {
-      providerEventId: "evt_7012_cancel",
-      status: SubscriptionStatuses.canceled,
-      tier: "starter",
-      providerCustomerId: "cus_7012_old",
-    });
-
-    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 === "starter")?.action).toBe("checkout");
-
-    const checkout = (await stack.http.writeOk(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      admin,
-    )) as { url: string };
-    expect(checkout.url).toBe("https://mock.example/checkout/price_pro");
-    expect(checkoutCalls[0]?.providerCustomerId).toBe("cus_7012_old");
-  });
-});
-
-// =============================================================================
-// 7. isBillingEnabled false — disabled, no live prices fetched, checkout gated.
-// =============================================================================
-
-describe("isBillingEnabled: false", () => {
-  test("query reports disabled with no prices; non-current plans are unavailable", async () => {
-    billingEnabled = false;
-    const admin = adminFor(7013);
-    const result = (await stack.http.queryOk(
-      "billing-foundation:query:billing-plans",
-      {},
-      admin,
-    )) as {
-      enabled: boolean;
-      plans: Array<{ tier: string; action: string; price: unknown }>;
-    };
-    expect(result.enabled).toBe(false);
-    for (const plan of result.plans) {
-      expect(plan.price).toBeNull();
-      expect(plan.action).toBe("unavailable");
-    }
-  });
-
-  test("start-plan-checkout throws feature_disabled", async () => {
-    billingEnabled = false;
-    const admin = adminFor(7014);
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(403);
-  });
-
-  test("switch-plan throws feature_disabled", async () => {
-    const admin = adminFor(7017);
-    await createSubscription(admin.tenantId, { tier: "starter" });
-    billingEnabled = false;
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.switchPlan,
-      { tier: "pro" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(403);
-  });
-});
-
-// =============================================================================
-// 7b. switch-plan across providers — the tenant's active subscription lives
-//     on a different provider than the catalog resolves.
-// =============================================================================
-
-describe("switch-plan — subscription on a different provider than the catalog", () => {
-  test("rejected with a conflict instead of calling the wrong provider's plugin", async () => {
-    const admin = adminFor(7018);
-    await createSubscription(admin.tenantId, {
-      tier: "starter",
-      providerName: "mock-other-provider",
-      providerSubscriptionId: "sub_other_7018",
-    });
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.switchPlan,
-      { tier: "pro" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(409);
-    expect(error.i18nKey).toBe("billing-foundation.errors.providerMismatch");
-    expect(switchCalls).toHaveLength(0);
-  });
-});
-
-// =============================================================================
-// 8. retrievePrices throws — query still resolves, prices null, checkout blocked.
-// =============================================================================
-
-describe("retrievePrices throws", () => {
-  test("query stays ok with null prices and unavailable actions", async () => {
-    retrievePricesMode = "throw";
-    const admin = adminFor(7015);
-    const result = (await stack.http.queryOk(
-      "billing-foundation:query:billing-plans",
-      {},
-      admin,
-    )) as {
-      plans: Array<{ tier: string; action: string; price: unknown }>;
-    };
-    for (const plan of result.plans) {
-      expect(plan.price).toBeNull();
-      expect(plan.action).toBe("unavailable");
-    }
-  });
-
-  test("start-plan-checkout rejects with price_unavailable", async () => {
-    retrievePricesMode = "throw";
-    const admin = adminFor(7016);
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(422);
-  });
-});
-
-// =============================================================================
-// 9. create-checkout-session hardening — foreign origin, unknown price,
-//    a price mapping to a tier outside catalog.plans.
-// =============================================================================
-
-describe("create-checkout-session — redirect + price hardening", () => {
-  test("a foreign successUrl origin is rejected", async () => {
-    const admin = adminFor(7017);
-    const error = await stack.http.writeErr(
-      "billing-foundation:write:create-checkout-session",
-      {
-        providerName: "mock-plan-provider",
-        priceId: "price_pro",
-        successUrl: "https://evil.example/success",
-        cancelUrl: "https://app.example.com/cancel",
-      },
-      admin,
-    );
-    expect(error.httpStatus).toBe(422);
-  });
-
-  test("an unknown priceId is rejected", async () => {
-    const admin = adminFor(7018);
-    const error = await stack.http.writeErr(
-      "billing-foundation:write:create-checkout-session",
-      {
-        providerName: "mock-plan-provider",
-        priceId: "price_does_not_exist",
-        successUrl: "https://app.example.com/success",
-        cancelUrl: "https://app.example.com/cancel",
-      },
-      admin,
-    );
-    expect(error.httpStatus).toBe(422);
-  });
-
-  test("a priceId mapping to a tier outside catalog.plans is rejected", async () => {
-    const admin = adminFor(7019);
-    const error = await stack.http.writeErr(
-      "billing-foundation:write:create-checkout-session",
-      {
-        providerName: "mock-plan-provider",
-        priceId: "price_pilot",
-        successUrl: "https://app.example.com/success",
-        cancelUrl: "https://app.example.com/cancel",
-      },
-      admin,
-    );
-    expect(error.httpStatus).toBe(422);
-  });
-});
-
-// =============================================================================
-// 10. Roles — a view-only role sees the catalog read-only, purchase-actions
-//     are 403 for it.
-// =============================================================================
-
-describe("roles — view-only access without purchase rights", () => {
-  let roleStack: TestStack;
-
-  beforeAll(async () => {
-    roleStack = await setupTestStack({
-      features: [
-        createConfigFeature(),
-        createTenantFeature(),
-        createComplianceProfilesFeature(),
-        createTenantLifecycleFeature(),
-        createBillingFoundationFeature({
-          baseUrl: "https://app.example.com",
-          catalog: catalog({ viewRoles: ["TenantAdmin", "SystemAdmin", "Member"] }),
-        }),
-        mockPlanProviderFeature,
-      ],
-    });
-    await unsafeCreateEntityTable(roleStack.db, tenantEntity);
-    await unsafeCreateEntityTable(roleStack.db, tenantComplianceProfileEntity);
-  });
-
-  afterAll(async () => {
-    await roleStack.cleanup();
-  });
-
-  test("a Member (view-only) sees canPurchase:false and unavailable actions", async () => {
-    const member = createTestUser({ id: 7020, tenantId: testTenantId(7020), roles: ["Member"] });
-    const result = (await roleStack.http.queryOk(
-      "billing-foundation:query:billing-plans",
-      {},
-      member,
-    )) as { canPurchase: boolean; plans: Array<{ action: string }> };
-    expect(result.canPurchase).toBe(false);
-    for (const plan of result.plans) expect(plan.action).toBe("unavailable");
-  });
-
-  test("a Member is rejected with 403 on start-plan-checkout", async () => {
-    const member = createTestUser({ id: 7021, tenantId: testTenantId(7021), roles: ["Member"] });
-    const error = await roleStack.http.writeErr(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      member,
-    );
-    expect(error.httpStatus).toBe(403);
-  });
-});
-
-// =============================================================================
-// 11. Stale-incomplete checkout gate — a separate stack with an injectable
-//     `now` (the event's own modified_at/inserted_at stays real, only the
-//     gate's clock is controlled) so both a fresh and a >24h-stale
-//     `incomplete` subscription are reachable without waiting real time.
-// =============================================================================
-
-describe("stale-incomplete subscription — injected clock", () => {
-  let clock: () => Temporal.Instant;
-  let clockStack: TestStack;
-
-  beforeAll(async () => {
-    clock = () => TemporalPolyfill.Now.instant() as unknown as Temporal.Instant;
-    clockStack = await setupTestStack({
-      features: [
-        createConfigFeature(),
-        createTenantFeature(),
-        createComplianceProfilesFeature(),
-        createTenantLifecycleFeature(),
-        createBillingFoundationFeature({
-          baseUrl: "https://app.example.com",
-          catalog: catalog(),
-          now: () => clock(),
-        }),
-        mockPlanProviderFeature,
-      ],
-    });
-    await unsafeCreateEntityTable(clockStack.db, tenantEntity);
-    await unsafeCreateEntityTable(clockStack.db, tenantComplianceProfileEntity);
-  });
-
-  afterAll(async () => {
-    await clockStack.cleanup();
-  });
-
-  beforeEach(() => {
-    clock = () => TemporalPolyfill.Now.instant() as unknown as Temporal.Instant;
-  });
-
-  test("(a) a fresh incomplete subscription still blocks checkout and shows paymentPending", async () => {
-    const admin = adminFor(7022);
-    await createSubscription(
-      admin.tenantId,
-      { tier: "starter", status: SubscriptionStatuses.incomplete },
-      clockStack,
-    );
-
-    const result = (await clockStack.http.queryOk(
-      "billing-foundation:query:billing-plans",
-      {},
-      admin,
-    )) as { plans: Array<{ tier: string; action: string }> };
-    expect(result.plans.find((p) => p.tier === "starter")?.action).toBe("paymentPending");
-
-    const error = await clockStack.http.writeErr(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(409);
-  });
-
-  test("(b) a stale (>24h) incomplete subscription no longer blocks checkout, and offers a fresh checkout for its own tier", async () => {
-    const admin = adminFor(7023);
-    await createSubscription(
-      admin.tenantId,
-      { tier: "starter", status: SubscriptionStatuses.incomplete },
-      clockStack,
-    );
-    clock = () => TemporalPolyfill.Now.instant().add({ hours: 25 }) as unknown as Temporal.Instant;
-
-    const result = (await clockStack.http.queryOk(
-      "billing-foundation:query:billing-plans",
-      {},
-      admin,
-    )) as { plans: Array<{ tier: string; action: string }> };
-    expect(result.plans.find((p) => p.tier === "starter")?.action).toBe("checkout");
-
-    const checkout = (await clockStack.http.writeOk(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      admin,
-    )) as { url: string };
-    expect(checkout.url).toBe("https://mock.example/checkout/price_pro");
-  });
-});
-
-// =============================================================================
-// 12. create-portal-session — returnUrl computation + strict payload (#3316 P4)
-// =============================================================================
-
-describe("create-portal-session — returnUrl computation", () => {
-  test("without catalog.returnPath, returnUrl is baseUrl alone", async () => {
-    const admin = adminFor(7027);
-    await createSubscription(admin.tenantId, { tier: "starter" });
-
-    const result = (await stack.http.writeOk(
-      SubscriptionFoundationHandlers.createPortalSession,
-      {},
-      admin,
-    )) as { url: string };
-    expect(result.url).toBe(`https://mock.example/portal/cus_${admin.tenantId}`);
-    expect(portalCalls).toHaveLength(1);
-    expect(portalCalls[0]?.returnUrl).toBe("https://app.example.com");
-  });
-
-  test("an unknown-key payload (e.g. a client-supplied returnUrl) is rejected — schema is z.object({}).strict()", async () => {
-    const admin = adminFor(7028);
-    const error = await stack.http.writeErr(
-      SubscriptionFoundationHandlers.createPortalSession,
-      { returnUrl: "https://evil.example" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(400);
-    expect(error.code).toBe("validation_error");
-  });
-
-  describe("with catalog.returnPath configured", () => {
-    let returnPathStack: TestStack;
-
-    beforeAll(async () => {
-      returnPathStack = await setupTestStack({
-        features: [
-          createConfigFeature(),
-          createTenantFeature(),
-          createComplianceProfilesFeature(),
-          createTenantLifecycleFeature(),
-          createBillingFoundationFeature({
-            baseUrl: "https://app.example.com",
-            catalog: catalog({ returnPath: "/billing/portal-return" }),
-          }),
-          mockPlanProviderFeature,
-        ],
-      });
-      await unsafeCreateEntityTable(returnPathStack.db, tenantEntity);
-      await unsafeCreateEntityTable(returnPathStack.db, tenantComplianceProfileEntity);
-    });
-
-    afterAll(async () => {
-      await returnPathStack.cleanup();
-    });
-
-    test("returnUrl is baseUrl + returnPath", async () => {
-      const admin = adminFor(7029);
-      await createSubscription(admin.tenantId, { tier: "starter" }, returnPathStack);
-
-      await returnPathStack.http.writeOk(
-        SubscriptionFoundationHandlers.createPortalSession,
-        {},
-        admin,
-      );
-      expect(portalCalls.at(-1)?.returnUrl).toBe("https://app.example.com/billing/portal-return");
-    });
-  });
-});
-
-// =============================================================================
-// 13. create-portal-session — catalog.purchaseRoles gates who may open the
-//     portal (#3316 P3): only that role gets in, everyone else is 403.
-// =============================================================================
-
-describe("create-portal-session — catalog.purchaseRoles", () => {
-  let purchaseRoleStack: TestStack;
-
-  beforeAll(async () => {
-    purchaseRoleStack = await setupTestStack({
-      features: [
-        createConfigFeature(),
-        createTenantFeature(),
-        createComplianceProfilesFeature(),
-        createTenantLifecycleFeature(),
-        createBillingFoundationFeature({
-          baseUrl: "https://app.example.com",
-          catalog: catalog({ purchaseRoles: ["Admin"] }),
-        }),
-        mockPlanProviderFeature,
-      ],
-    });
-    await unsafeCreateEntityTable(purchaseRoleStack.db, tenantEntity);
-    await unsafeCreateEntityTable(purchaseRoleStack.db, tenantComplianceProfileEntity);
-  });
-
-  afterAll(async () => {
-    await purchaseRoleStack.cleanup();
-  });
-
-  test("a user with only the configured purchase-role gets 200", async () => {
-    const tenantId = testTenantId(7030);
-    await createSubscription(tenantId, { tier: "starter" }, purchaseRoleStack);
-    const adminRoleUser = createTestUser({ id: 7030, tenantId, roles: ["Admin"] });
-
-    const result = (await purchaseRoleStack.http.writeOk(
-      SubscriptionFoundationHandlers.createPortalSession,
-      {},
-      adminRoleUser,
-    )) as { url: string };
-    expect(result.url).toBeTruthy();
-  });
-
-  test("a user without the configured purchase-role gets 403", async () => {
-    const tenantId = testTenantId(7031);
-    await createSubscription(tenantId, { tier: "starter" }, purchaseRoleStack);
-    const nonPurchaser = createTestUser({ id: 7031, tenantId, roles: ["TenantAdmin"] });
-
-    const error = await purchaseRoleStack.http.writeErr(
-      SubscriptionFoundationHandlers.createPortalSession,
-      {},
-      nonPurchaser,
-    );
-    expect(error.httpStatus).toBe(403);
-  });
-});
-
-// =============================================================================
-// 14. No provider registered at all — billing-plans stays enabled:false,
-//     every plan unavailable, start-plan-checkout fails feature_disabled
-//     (#3316 P5).
-// =============================================================================
-
-describe("no subscription-provider mounted at all", () => {
-  let noProviderStack: TestStack;
-
-  beforeAll(async () => {
-    noProviderStack = await setupTestStack({
-      features: [
-        createConfigFeature(),
-        createTenantFeature(),
-        createComplianceProfilesFeature(),
-        createTenantLifecycleFeature(),
-        createBillingFoundationFeature({ baseUrl: "https://app.example.com", catalog: catalog() }),
-        // Deliberately no provider plugin mounted.
-      ],
-    });
-    await unsafeCreateEntityTable(noProviderStack.db, tenantEntity);
-    await unsafeCreateEntityTable(noProviderStack.db, tenantComplianceProfileEntity);
-  });
-
-  afterAll(async () => {
-    await noProviderStack.cleanup();
-  });
-
-  test("billing-plans: enabled:false, every plan unavailable", async () => {
-    const admin = adminFor(7032);
-    const result = (await noProviderStack.http.queryOk(
-      "billing-foundation:query:billing-plans",
-      {},
-      admin,
-    )) as { enabled: boolean; plans: Array<{ action: string }> };
-    expect(result.enabled).toBe(false);
-    for (const plan of result.plans) expect(plan.action).toBe("unavailable");
-  });
-
-  test("start-plan-checkout: feature_disabled", async () => {
-    const admin = adminFor(7033);
-    const error = await noProviderStack.http.writeErr(
-      SubscriptionFoundationHandlers.startPlanCheckout,
-      { tier: "pro" },
-      admin,
-    );
-    expect(error.httpStatus).toBe(403);
-    expect(error.i18nKey).toBe("errors.feature.disabled");
-  });
-});