@bugmole/cli 0.5.0 → 0.6.0

package/src/registry-worker/billing/subscriptions.ts

@@ -23,7 +23,7 @@ import { newId } from "../core.js";
 import { emailSender, escapeHtml } from "../email/sender.js";
 import { planChangedHooks } from "../hooks.js";
 import { actorOf, recordAudit } from "../org/audit.js";
-import { getWorkspacePlan, type WorkspacePlan } from "./entitlements.js";
+import { getEntitlements, getWorkspacePlan, type WorkspacePlan } from "./entitlements.js";
 import { periodAnchor, summarize, usagePeriod, usedInPeriod } from "./ledger.js";
 import {
   BillingUnavailableError,
@@ -156,7 +156,7 @@ async function sendBillingEmail(env: Env, workspaceId: string, subject: string,
   const recipients = await billingRecipients(env, workspaceId);
   if (row?.billing_email && !recipients.some((r) => r.email === row.billing_email)) recipients.push({ email: row.billing_email });
   if (!recipients.length) return;
-  const link = `${(env.DASHBOARD_URL || "https://app.bugmole.com").replace(/\/$/, "")}/billing`;
+  const link = `${(env.DASHBOARD_URL || "https://app.bugmole.com").replace(/\/$/, "")}/billing?${new URLSearchParams({ workspace: workspaceId })}`;
   try {
     await emailSender(env).send({
       to: recipients,
@@ -172,11 +172,14 @@ async function sendBillingEmail(env: Env, workspaceId: string, subject: string,
 
 // --- Projects over the limit -----------------------------------------------------------------
 
-/** Locks the newest projects beyond the plan's limit and unlocks what fits again. */
+/**
+ * Locks the projects beyond the plan's limit and unlocks what fits again. The
+ * projects an owner chose to keep come first; otherwise the oldest stay active.
+ */
 export async function applyProjectLimit(env: Env, workspaceId: string, entitlements: Entitlements): Promise<{ locked: number }> {
   const rows = await env.DB.prepare(`
     SELECT id, locked_at AS lockedAt FROM projects
-    WHERE workspace_id = ? AND deleted_at IS NULL ORDER BY created_at ASC, rowid ASC
+    WHERE workspace_id = ? AND deleted_at IS NULL AND inactive_at IS NULL ORDER BY kept_at IS NULL, created_at ASC, rowid ASC
   `).bind(workspaceId).all<{ id: string; lockedAt: string | null }>();
   const limit = entitlements.projects ?? Number.POSITIVE_INFINITY;
   const now = new Date().toISOString();
@@ -193,6 +196,47 @@ export async function applyProjectLimit(env: Env, workspaceId: string, entitleme
   return { locked };
 }
 
+/**
+ * An owner picks which projects stay active within the plan's limit; the rest
+ * become read-only (nothing is deleted). The choice is remembered, so a later
+ * downgrade locks the others rather than the newest.
+ */
+export async function chooseActiveProjects(
+  env: Env,
+  principal: Principal,
+  workspaceId: string,
+  projectIds: string[],
+  request?: Request,
+): Promise<{ active: string[]; locked: string[] }> {
+  const { projects: limit, plan } = await getEntitlements(env, workspaceId);
+  const rows = await env.DB.prepare("SELECT id FROM projects WHERE workspace_id = ? AND deleted_at IS NULL")
+    .bind(workspaceId).all<{ id: string }>();
+  const inWorkspace = new Set(rows.results.map((row) => row.id));
+  const chosen = [...new Set(projectIds)];
+  if (!chosen.length) throw new BillingError(422, "no_projects", "Choose at least one project to keep active.");
+  const foreign = chosen.find((id) => !inWorkspace.has(id));
+  if (foreign) throw new BillingError(422, "unknown_project", `Project ${foreign} isn't in this workspace.`);
+  if (limit !== null && chosen.length > limit) {
+    throw new BillingError(422, "over_limit", `Your plan includes ${limit} project${limit === 1 ? "" : "s"}; choose at most ${limit}.`);
+  }
+  const now = new Date().toISOString();
+  await env.DB.batch([
+    env.DB.prepare("UPDATE projects SET kept_at = NULL WHERE workspace_id = ?").bind(workspaceId),
+    ...chosen.map((id) => env.DB.prepare("UPDATE projects SET kept_at = ? WHERE id = ? AND workspace_id = ?").bind(now, id, workspaceId)),
+  ]);
+  await applyProjectLimit(env, workspaceId, entitlementsFor(plan.plan, plan.overrides));
+  const after = await env.DB.prepare("SELECT id, locked_at AS lockedAt FROM projects WHERE workspace_id = ? AND deleted_at IS NULL ORDER BY created_at ASC, rowid ASC")
+    .bind(workspaceId).all<{ id: string; lockedAt: string | null }>();
+  const result = {
+    active: after.results.filter((row) => !row.lockedAt).map((row) => row.id),
+    locked: after.results.filter((row) => row.lockedAt).map((row) => row.id),
+  };
+  await recordAudit(env, actorOf(principal), {
+    workspaceId, action: "billing.projects_chosen", targetType: "workspace", targetId: workspaceId, data: { kept: chosen, ...result },
+  }, request);
+  return result;
+}
+
 // --- Invoices --------------------------------------------------------------------------------
 
 async function nextInvoiceNumber(env: Env, workspaceId: string, at: Date): Promise<string> {
@@ -513,6 +557,70 @@ export async function cancelAtPeriodEnd(env: Env, principal: Principal, workspac
   return getWorkspacePlan(env, workspaceId);
 }
 
+export const RESUME_REASON = "Resumed on Bugmole";
+
+export type ResumeResult =
+  | { status: "resumed"; plan: WorkspacePlan }
+  | { status: "checkout_required"; plan: PaidPlan; interval: BillingInterval; message: string };
+
+/**
+ * Undoes a pending cancellation (or a scheduled plan change) before the paid
+ * period ends, so the current plan keeps renewing.
+ *
+ * Cancelling stops renewal at PayPal right away (POST .../cancel), and PayPal
+ * can't restart a CANCELLED subscription: only a SUSPENDED one can be
+ * activated again. So when the subscription is still live (or only paused) it
+ * is kept; when PayPal already ended it, the answer is "checkout_required":
+ * the customer approves a new subscription for the same plan that starts when
+ * the paid period ends, so nothing is charged twice.
+ */
+export async function resumeSubscription(env: Env, principal: Principal, workspaceId: string, request?: Request, now = new Date()): Promise<ResumeResult> {
+  const row = await planRow(env, workspaceId);
+  if (!row || !isPaidPlan(row.plan) || row.status === "canceled") throw new BillingError(409, "not_subscribed", "This workspace isn't on a paid plan.");
+  if (!row.cancel_at_period_end) throw new BillingError(409, "not_cancelled", "This plan is already set to renew.");
+  if (row.current_period_end && Date.parse(row.current_period_end) <= now.getTime()) {
+    throw new BillingError(409, "period_ended", "The paid period has ended. Choose a plan to subscribe again.");
+  }
+  const interval: BillingInterval = row.billing_interval === "year" ? "year" : "month";
+  const provider = row.provider && row.provider_subscription_id ? billingProvider(row.provider) : null;
+  if (provider) {
+    let remote = await provider.getSubscription(env, row.provider_subscription_id!);
+    if (remote?.status === "past_due") {
+      await provider.reactivateSubscription(env, remote.id, RESUME_REASON);
+      remote = await provider.getSubscription(env, remote.id);
+    }
+    if (remote?.status !== "active") {
+      await recordAudit(env, actorOf(principal), {
+        workspaceId, action: "billing.resume_needs_checkout", targetType: "workspace", targetId: workspaceId,
+        data: { plan: row.plan, interval, providerStatus: remote?.status ?? null },
+      }, request);
+      return {
+        status: "checkout_required",
+        plan: row.plan,
+        interval,
+        message: "PayPal ended the old subscription when the plan was cancelled, and a cancelled PayPal subscription can't be restarted. "
+          + `Approve a new ${PLANS[row.plan].name} subscription in PayPal; it starts when the current period ends, so nothing is charged twice.`,
+      };
+    }
+  }
+  // The subscription is still live: stop ending it, and drop any scheduled change.
+  const scheduled = await env.DB.prepare("SELECT id, provider, provider_subscription_id AS sub FROM billing_checkouts WHERE workspace_id = ? AND status = 'scheduled'")
+    .bind(workspaceId).all<{ id: string; provider: string; sub: string | null }>();
+  for (const change of scheduled.results) {
+    if (change.sub) await billingProvider(change.provider).cancelSubscription(env, change.sub, RESUME_REASON).catch(() => undefined);
+    await env.DB.prepare("UPDATE billing_checkouts SET status = 'abandoned' WHERE id = ?").bind(change.id).run();
+  }
+  await env.DB.prepare("UPDATE workspace_plans SET cancel_at_period_end = 0, pending_plan = NULL, updated_at = CURRENT_TIMESTAMP WHERE workspace_id = ?")
+    .bind(workspaceId).run();
+  await recordAudit(env, actorOf(principal), {
+    workspaceId, action: "billing.resumed", targetType: "workspace", targetId: workspaceId, data: { plan: row.plan, interval },
+  }, request);
+  await sendBillingEmail(env, workspaceId, "Your Bugmole plan will renew", [
+    `Your ${PLANS[row.plan].name} plan renews on ${row.current_period_end?.slice(0, 10) ?? "the end of the period"} as usual.`,
+  ], "billing-resumed");
+  return { status: "resumed", plan: await getWorkspacePlan(env, workspaceId) };
+}
+
 // --- Keeping in step with the provider -------------------------------------------------------
 
 async function moveToFree(env: Env, workspaceId: string, reason: string): Promise<void> {
@@ -552,8 +660,10 @@ export async function syncWorkspaceBilling(env: Env, workspaceId: string, now =
       if (remote.status === "past_due" && row.status === "active") {
         await env.DB.prepare("UPDATE workspace_plans SET status = 'past_due', grace_until = ?, updated_at = CURRENT_TIMESTAMP WHERE workspace_id = ?")
           .bind(new Date(now.getTime() + GRACE_DAYS * DAY).toISOString(), workspaceId).run();
+        const manage = provider.manageUrl(env);
         await sendBillingEmail(env, workspaceId, "Your Bugmole payment didn't go through", [
           `PayPal couldn't collect your renewal. Update your payment method in PayPal within ${GRACE_DAYS} days to keep using Bugmole Cloud.`,
+          ...(manage ? [`Change the card or bank for this subscription under PayPal's automatic payments: ${manage}`] : []),
           "Runs on your own machines and CI keep working either way.",
         ], "billing-payment-failed");
       }

package/src/registry-worker/core.ts

@@ -14,6 +14,23 @@ export interface Env extends EmailEnv {
   DASHBOARD_URL?: string;
   /** Signs the short-lived tokens hosted runners use; see runner/tokens.ts. */
   RUNNER_TOKEN_SECRET?: string;
+  /**
+   * Root key for project secrets (sign-in for cloud runs): 32 random bytes,
+   * base64. Without it the secrets routes answer 503. See secrets/crypto.ts.
+   */
+  PROJECT_SECRETS_KEY?: string;
+  /** Version of PROJECT_SECRETS_KEY (default 1); raise it when rotating. */
+  PROJECT_SECRETS_KEY_VERSION?: string;
+  /** The key being rotated away from, kept until no value still uses it. */
+  PROJECT_SECRETS_KEY_PREVIOUS?: string;
+  PROJECT_SECRETS_KEY_PREVIOUS_VERSION?: string;
+  /**
+   * RSA private key (PKCS#8 PEM) that signs runners' identity tokens, which
+   * customers' clouds trust instead of a stored key. See identity/oidc.ts.
+   */
+  OIDC_SIGNING_KEY?: string;
+  /** The issuer those tokens name (default https://api.bugmole.com). */
+  OIDC_ISSUER?: string;
   /** Service binding to the valkyrie-runner Worker that starts cloud-run containers. */
   RUNNER?: Fetcher;
   /** Scents (bugmole-scents): checks that a typed referral code belongs to an affiliate. */
@@ -24,6 +41,11 @@ export interface Env extends EmailEnv {
   CLOUD_RUN_MAX_MINUTES?: string;
   /** This registry's public origin, handed to runners (e.g. https://api.bugmole.com). */
   REGISTRY_PUBLIC_URL?: string;
+  /**
+   * Bearer token for the platform-operator routes (/api/platform/…, see
+   * feature-flags/admin.ts). A secret; those routes answer 503 without it.
+   */
+  PLATFORM_ADMIN_TOKEN?: string;
   /** Rollout flags; see flags.ts. */
   [key: `FEATURE_${string}`]: string | undefined;
 }

package/src/registry-worker/devices/policy.ts

@@ -2,9 +2,8 @@
 import type { CloudDevice } from "../../runtime/device-clouds/types.js";
 import type { Env } from "../core.js";
 import { response } from "../core.js";
-import { getEntitlements } from "../billing/entitlements.js";
 import { canSpend } from "../billing/ledger.js";
-import { flagOn } from "../flags.js";
+import { blockedBy, featureState } from "../feature-access.js";
 
 export type BugmoleDeviceEnv = {
   BUGMOLE_DEVICE_FARM_ACCESS_KEY_ID?: string;
@@ -42,9 +41,9 @@ export async function deviceTargetsError(
   executionMode: "self" | "cloud",
 ): Promise<Response | null> {
   if (!workspaceId) return refused("This project isn't in a workspace", "no_workspace");
-  if (!(await flagOn(env, workspaceId, "device_clouds"))) return refused("Device clouds aren't available for this workspace yet.", "device_clouds_unavailable");
-  const { features } = await getEntitlements(env, workspaceId);
-  if (!features.deviceClouds) return refused("Real devices and device clouds are included in Business.", "plan_feature", 402);
+  const blocked = blockedBy(await featureState(env, workspaceId, "device_clouds"));
+  if (blocked === "rollout") return refused("Device clouds aren't available for this workspace yet.", "device_clouds_unavailable");
+  if (blocked === "plan") return refused("Real devices and device clouds are included in Business.", "plan_feature", 402);
   for (const target of targets) {
     if (target.provider === "bugmole") {
       if (executionMode !== "cloud") return refused("Bugmole's own devices are only used by runs on Bugmole Cloud.", "bugmole_devices_need_cloud");

package/src/registry-worker/devices/routes.ts

@@ -15,7 +15,7 @@ import {
 } from "../../integrations/device-farm.js";
 import type { Env, Principal } from "../core.js";
 import { memberOfProject, memberOfWorkspace, newId, requestJson, response, sha256 } from "../core.js";
-import { getEntitlements } from "../billing/entitlements.js";
+import { blockedBy, featureEnabled, featureState } from "../feature-access.js";
 import { canSpend, recordUsage } from "../billing/ledger.js";
 import { registerJob } from "../jobs/index.js";
 import { actorOf, auditProject, recordAudit } from "../org/audit.js";
@@ -37,8 +37,9 @@ function providerFetch(env: Env): Fetcher {
 
 async function manageable(env: Env, principal: Principal, workspaceId: string): Promise<Response | null> {
   if (!(await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"))) return response({ error: "Only owners and admins can manage device clouds" }, 403);
-  const { features } = await getEntitlements(env, workspaceId);
-  if (!features.deviceClouds) return response({ error: "Device clouds are included in Business.", code: "plan_feature", upgradeUrl: "/billing" }, 402);
+  const blocked = blockedBy(await featureState(env, workspaceId, "device_clouds"));
+  if (blocked === "rollout") return response({ error: "Device clouds aren't available for this workspace yet.", code: "device_clouds_unavailable" }, 422);
+  if (blocked === "plan") return response({ error: "Device clouds are included in Business.", code: "plan_feature", upgradeUrl: "/billing" }, 402);
   if (!canStoreSecrets(env)) return response({ error: "Device clouds can't be connected right now." }, 503);
   return null;
 }
@@ -121,11 +122,11 @@ async function listConnections({ env, principal }: AuthedRouteContext, workspace
     SELECT id, provider, label, username, project_arn AS projectArn, created_at AS createdAt, last_verified_at AS lastVerifiedAt
     FROM device_cloud_credentials WHERE workspace_id = ? AND revoked_at IS NULL ORDER BY created_at ASC
   `).bind(workspaceId).all();
-  const { features } = await getEntitlements(env, workspaceId);
+  const available = await featureEnabled(env, workspaceId, "device_clouds");
   return response({
-    available: features.deviceClouds,
+    available,
     canManage: await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"),
-    bugmole: { available: features.deviceClouds && Boolean(bugmoleDeviceCloud(env)) },
+    bugmole: { available: available && Boolean(bugmoleDeviceCloud(env)) },
     connections: rows.results,
   });
 }
@@ -175,8 +176,7 @@ async function devicesFor({ env, principal }: AuthedRouteContext, workspaceId: s
   try {
     if (id === "bugmole") {
       const own = bugmoleDeviceCloud(env);
-      const { features } = await getEntitlements(env, workspaceId);
-      if (!own || !features.deviceClouds) return response({ error: "Bugmole's device cloud isn't available for this workspace" }, 402);
+      if (!own || !(await featureEnabled(env, workspaceId, "device_clouds"))) return response({ error: "Bugmole's device cloud isn't available for this workspace" }, 402);
       return response({ devices: unique(await catalog(env, { provider: "aws_device_farm", username: own.credentials.accessKeyId, secret: own.credentials.secretAccessKey, projectArn: own.projectArn })) });
     }
     const credential = await credentialFor(env, workspaceId, id);

package/src/registry-worker/feature-access.ts

@@ -0,0 +1,165 @@
+// The one answer to "may this workspace use feature X?". Every layer is
+// evaluated in a fixed order, and the first one that decides wins:
+//
+//   1. Global kill switch   FEATURE_<NAME>=off (or shadow)       → off, "flag_off"
+//   2. Beta rollout         FEATURE_<NAME>=beta needs a workspace_flags opt-in,
+//                           otherwise off, "beta_not_enabled"
+//   3. Workspace override   an unexpired workspace_feature_overrides row forces
+//                           it on or off (trials, comps, incidents), "workspace_override"
+//   4. Plan                 the plan's catalog features, "plan"; changed by the
+//                           contract overrides on workspace_plans, "enterprise_override"
+//
+// Features with no plan gate are on for every plan once the rollout allows
+// them (reason "plan"). See docs/feature-flags.md.
+import { LIMIT_KEYS, PLANS, PLAN_IDS, entitlementsFor, type LimitKey, type PlanId } from "../billing/plan-catalog.js";
+import type { Env } from "./core.js";
+import { FEATURES, FEATURE_DEFS, flagMode, type Feature, type FlagMode } from "./flags.js";
+import { freePlan, getWorkspacePlan, type WorkspacePlan } from "./billing/entitlements.js";
+
+export type FeatureReason = "plan" | "flag_off" | "beta_not_enabled" | "workspace_override" | "enterprise_override";
+
+export type FeatureState = {
+  feature: Feature;
+  enabled: boolean;
+  reason: FeatureReason;
+  /** The cheapest plan that includes it, for plan-gated features (null when no self-serve plan does). */
+  requiredPlan?: PlanId;
+  /** The global rollout mode it was evaluated under. */
+  mode: FlagMode;
+  /** When a workspace override decided, when it lapses (null: until cleared). */
+  overrideExpiresAt?: string | null;
+};
+
+export type FeatureOverride = { feature: Feature; enabled: boolean; expiresAt: string | null; reason: string | null; setBy: string; updatedAt: string };
+
+export type FeatureInputs = {
+  env: Omit<Env, "DB"> | Record<string, unknown>;
+  plan: WorkspacePlan;
+  /** Features this workspace opted into while they are in beta. */
+  betaOptIns: ReadonlySet<Feature>;
+  overrides: readonly FeatureOverride[];
+  now?: Date;
+};
+
+/** The cheapest plan whose catalog features include this one. */
+export function requiredPlanFor(feature: Feature): PlanId | undefined {
+  const key = FEATURE_DEFS[feature].planFeature;
+  if (!key) return undefined;
+  return PLAN_IDS.find((plan) => PLANS[plan].features[key]);
+}
+
+export function overrideActive(override: Pick<FeatureOverride, "expiresAt">, now = new Date()): boolean {
+  return !override.expiresAt || Date.parse(override.expiresAt) > now.getTime();
+}
+
+/** Pure evaluation of every feature; the async loaders below feed it. */
+export function evaluateFeatures(inputs: FeatureInputs): Record<Feature, FeatureState> {
+  const now = inputs.now ?? new Date();
+  const entitlements = entitlementsFor(inputs.plan.plan, inputs.plan.overrides);
+  const contract = inputs.plan.overrides.features ?? {};
+  const result = {} as Record<Feature, FeatureState>;
+  for (const feature of FEATURES) {
+    const def = FEATURE_DEFS[feature];
+    const mode = flagMode(inputs.env as Parameters<typeof flagMode>[0], feature);
+    const requiredPlan = requiredPlanFor(feature);
+    const base = { feature, mode, ...(def.planFeature ? { requiredPlan } : {}) } as Pick<FeatureState, "feature" | "mode" | "requiredPlan">;
+    if (mode === "off" || mode === "shadow") {
+      result[feature] = { ...base, enabled: false, reason: "flag_off" };
+      continue;
+    }
+    if (mode === "beta" && !inputs.betaOptIns.has(feature)) {
+      result[feature] = { ...base, enabled: false, reason: "beta_not_enabled" };
+      continue;
+    }
+    const override = inputs.overrides.find((row) => row.feature === feature && overrideActive(row, now));
+    if (override) {
+      result[feature] = { ...base, enabled: override.enabled, reason: "workspace_override", overrideExpiresAt: override.expiresAt };
+      continue;
+    }
+    if (!def.planFeature) {
+      result[feature] = { ...base, enabled: true, reason: "plan" };
+      continue;
+    }
+    const contractSet = contract[def.planFeature] !== undefined;
+    result[feature] = { ...base, enabled: entitlements.features[def.planFeature], reason: contractSet ? "enterprise_override" : "plan" };
+  }
+  return result;
+}
+
+async function betaOptIns(env: Env, workspaceId: string): Promise<Set<Feature>> {
+  const rows = await env.DB.prepare("SELECT flag FROM workspace_flags WHERE workspace_id = ? AND enabled = 1")
+    .bind(workspaceId).all<{ flag: string }>();
+  return new Set(rows.results.map((row) => row.flag).filter((flag): flag is Feature => (FEATURES as readonly string[]).includes(flag)));
+}
+
+/** Override rows for a workspace, expired ones included. Tolerates a registry not yet migrated. */
+export async function loadOverrides(env: Env, workspaceId: string): Promise<FeatureOverride[]> {
+  try {
+    const rows = await env.DB.prepare(`
+      SELECT feature, enabled, expires_at AS expiresAt, reason, set_by AS setBy, updated_at AS updatedAt
+      FROM workspace_feature_overrides WHERE workspace_id = ?
+    `).bind(workspaceId).all<{ feature: string; enabled: number; expiresAt: string | null; reason: string | null; setBy: string; updatedAt: string }>();
+    return rows.results
+      .filter((row) => (FEATURES as readonly string[]).includes(row.feature))
+      .map((row) => ({ ...row, feature: row.feature as Feature, enabled: row.enabled === 1 }));
+  } catch (error) {
+    console.error("[features] workspace_feature_overrides unavailable; is migration 0043 applied?", error);
+    return [];
+  }
+}
+
+export type EffectiveFeatures = {
+  plan: WorkspacePlan;
+  features: Record<Feature, FeatureState>;
+};
+
+/** Every feature for one workspace (three small reads). A null workspace is a Free workspace with no opt-ins. */
+export async function effectiveFeatures(env: Env, workspaceId: string | null | undefined, now = new Date()): Promise<EffectiveFeatures> {
+  if (!workspaceId) {
+    const plan = freePlan("");
+    return { plan, features: evaluateFeatures({ env, plan, betaOptIns: new Set(), overrides: [], now }) };
+  }
+  const [plan, optIns, overrides] = await Promise.all([
+    getWorkspacePlan(env, workspaceId),
+    betaOptIns(env, workspaceId),
+    loadOverrides(env, workspaceId),
+  ]);
+  return { plan, features: evaluateFeatures({ env, plan, betaOptIns: optIns, overrides, now }) };
+}
+
+export async function featureState(env: Env, workspaceId: string | null | undefined, feature: Feature): Promise<FeatureState> {
+  return (await effectiveFeatures(env, workspaceId)).features[feature];
+}
+
+export async function featureEnabled(env: Env, workspaceId: string | null | undefined, feature: Feature): Promise<boolean> {
+  return (await featureState(env, workspaceId, feature)).enabled;
+}
+
+/**
+ * Why a feature is off, in the terms gates answer with: "rollout" (not
+ * available to this workspace yet, or switched off for it) or "plan" (an
+ * upgrade would unlock it, so a 402). Null when it is on.
+ */
+export function blockedBy(state: FeatureState): "rollout" | "plan" | null {
+  if (state.enabled) return null;
+  return state.reason === "plan" || state.reason === "enterprise_override" ? "plan" : "rollout";
+}
+
+export type { LimitKey };
+/** A catalog limit (LIMIT_KEYS). Enforcement reads the same entitlementsFor() values. */
+export type LimitState = { limit: number | null; unlimited: boolean; used?: number };
+
+/** A workspace's limits: its plan's catalog limits with contract overrides applied. */
+export function limitsFor(plan: WorkspacePlan): Record<LimitKey, LimitState> {
+  const entitlements = entitlementsFor(plan.plan, plan.overrides);
+  return Object.fromEntries(LIMIT_KEYS.map((key) => {
+    const limit = entitlements[key];
+    return [key, { limit, unlimited: limit === null }];
+  })) as Record<LimitKey, LimitState>;
+}
+
+/** Where a workspace's plan comes from, for ops and the dashboard. */
+export function planSource(plan: WorkspacePlan): "default" | "subscription" | "contract" {
+  if (plan.provider) return "subscription";
+  return plan.plan === "free" ? "default" : "contract";
+}