@cosmicdrift/kumiko-bundled-features 0.224.2 → 0.225.0

package/src/cap-overview/feature.ts

@@ -0,0 +1,77 @@
+// cap-overview — read-only tier/cap-usage visibility per tenant.
+//
+// **What this feature does:**
+//   1. tenant-caps:list query + tenant-cap-list screen — SystemAdmin-only
+//      platform-wide table of every tenant's tier, billing status, and
+//      usage against a configurable set of caps.
+//   2. caps:usage query + my-caps / platform-tenant-caps dashboards —
+//      per-tenant usage cards. TenantAdmin sees their own tenant;
+//      SystemAdmin can additionally view any tenant via `tenantId`.
+//
+// **What this feature does NOT do:**
+//   - No writes. Reads tier-engine's read_tier_assignments, billing-
+//     foundation's read_subscriptions, tenant's read_tenants, plus
+//     app-owned usage tables via the caller-supplied `CapSpec` callbacks.
+//   - No nav wiring — a separate cut adds `r.nav(...)` entries.
+//
+// **Boot-Dependencies:** tenant, tier-engine, billing-foundation.
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { CAP_OVERVIEW_FEATURE } from "./constants";
+import { createCapsUsageQuery } from "./handlers/caps-usage.query";
+import { createTenantCapsListQuery } from "./handlers/tenant-caps-list.query";
+import { tenantOptionsQuery } from "./handlers/tenant-options.query";
+import { CAP_OVERVIEW_I18N } from "./i18n";
+import { createTenantCapListScreen, myCapsScreen, platformTenantCapsScreen } from "./screens";
+import type { CapSpec } from "./types";
+
+export type CreateCapOverviewOptions = {
+  readonly caps: readonly CapSpec[];
+  /** Caps shown as columns on the platform-wide tenant-cap-list screen.
+   *  Defaults to the first three caps when omitted. */
+  readonly listCaps?: readonly string[];
+  /** Options for the tenant-cap-list tier facet. Omitted → no facet — the
+   *  engine itself carries no enumerated tier vocabulary to derive one
+   *  from (see screens.ts doc). "Filter by tier" was explicitly requested;
+   *  omitting `tiers` silently drops that filter, not a supported default. */
+  readonly tiers?: readonly string[];
+};
+
+export function createCapOverviewFeature(opts: CreateCapOverviewOptions): FeatureDefinition {
+  if (opts.caps.length === 0) {
+    throw new Error("createCapOverviewFeature: `caps` must not be empty.");
+  }
+  const capIds = new Set(opts.caps.map((cap) => cap.id));
+  const listCaps = opts.listCaps ?? opts.caps.slice(0, 3).map((cap) => cap.id);
+  for (const id of listCaps) {
+    if (!capIds.has(id)) {
+      throw new Error(
+        `createCapOverviewFeature: listCaps references unknown cap id "${id}" — known ids: ${[...capIds].join(", ")}`,
+      );
+    }
+  }
+
+  return defineFeature(CAP_OVERVIEW_FEATURE, (r) => {
+    r.describe(
+      "Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; TenantAdmin gets their own usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.",
+    );
+    r.uiHints({
+      displayLabel: "Cap Overview · Tier & Usage Visibility",
+      category: "operations",
+      recommended: false,
+    });
+    r.systemScope();
+    r.requires("tenant");
+    r.requires("tier-engine");
+    r.requires("billing-foundation");
+
+    r.queryHandler(createTenantCapsListQuery(opts.caps, listCaps));
+    r.queryHandler(createCapsUsageQuery(opts.caps));
+    r.queryHandler(tenantOptionsQuery);
+
+    r.screen(createTenantCapListScreen(opts.caps, listCaps, opts.tiers));
+    r.screen(myCapsScreen);
+    r.screen(platformTenantCapsScreen);
+
+    r.translations({ keys: CAP_OVERVIEW_I18N });
+  });
+}

package/src/cap-overview/handlers/caps-usage.query.ts

@@ -0,0 +1,86 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  crossTenantOverrideDenied,
+  defineQueryHandler,
+  type QueryHandlerDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { tierAssignmentEntity } from "../../tier-engine";
+import type { CapSpec, CapUsageWithMeta } from "../types";
+import { computeFraction, computeTone, computeUnclampedFraction } from "../usage-math";
+
+type TierAssignmentRow = { readonly tenantId: string; readonly tier: string };
+
+const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
+
+export function createCapsUsageQuery(caps: readonly CapSpec[]): QueryHandlerDefinition {
+  return defineQueryHandler({
+    name: "caps:usage",
+    schema: z.object({ tenantId: z.string().min(1).optional() }),
+    access: { roles: access.admin },
+    handler: async (query, ctx) => {
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message: "cap-overview:query:caps:usage requires ctx.systemDb — is r.systemScope() set?",
+        });
+      }
+      const override = query.payload.tenantId;
+      const overrideDenied = crossTenantOverrideDenied(
+        query.user,
+        override,
+        "cap-overview.errors.tenantOverrideRequiresSystemAdmin",
+      );
+      if (overrideDenied) throw overrideDenied;
+
+      const targetTenantId = override ?? query.user.tenantId;
+      // Both branches return the SAME unfiltered system-mode db —
+      // assertTenantMatch is a self-check on the caller, not a query
+      // filter (see tenant-db.ts). Every read below carries its own
+      // explicit `tenantId` WHERE regardless of which branch ran.
+      const db =
+        override !== undefined
+          ? ctx.systemDb.acknowledgeCrossTenant(
+              `cap-overview:caps:usage — SystemAdmin cross-tenant read for tenant ${targetTenantId}`,
+            )
+          : ctx.systemDb.assertTenantMatch(query.user.tenantId);
+
+      const assignmentRows = await selectMany<TierAssignmentRow>(db, tierAssignmentTable, {
+        tenantId: [targetTenantId],
+      });
+      // Defense-in-depth on the own-tenant path only: assertRowsTenant
+      // checks rows against the CALLER's own tenantId, which is only
+      // meaningful when the caller is reading their own tenant — on the
+      // SystemAdmin override path the target tenant legitimately differs
+      // from the caller's own tenantId, so the check would misfire there.
+      const checkedRows =
+        override === undefined
+          ? ctx.systemDb.assertRowsTenant(assignmentRows, "tenantId")
+          : assignmentRows;
+      const tier = checkedRows[0]?.tier ?? "";
+
+      const rows: CapUsageWithMeta[] = await Promise.all(
+        caps.map(async (cap) => {
+          const used = await cap.usage(db, targetTenantId);
+          const limit = cap.limit(tier);
+          const fraction = computeFraction(used, limit);
+          return {
+            id: cap.id,
+            label: cap.label,
+            used,
+            limit,
+            fraction,
+            tone: computeTone(fraction),
+            percent: Math.round(computeUnclampedFraction(used, limit) * 100),
+            ...(cap.icon !== undefined && { icon: cap.icon }),
+            ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }),
+          };
+        }),
+      );
+
+      return { rows };
+    },
+  });
+}

package/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -0,0 +1,224 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable, decodeCursor, encodeCursor } from "@cosmicdrift/kumiko-framework/db";
+import { definePagedQueryHandler, MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { subscriptionsProjectionTable } from "../../billing-foundation";
+import { tenantTable } from "../../tenant";
+import { tierAssignmentEntity } from "../../tier-engine";
+import { capFieldName } from "../constants";
+import type { CapSpec, CapUsage } from "../types";
+import { computeFraction } from "../usage-math";
+
+type TenantRow = { readonly id: string; readonly name: string };
+type TierAssignmentRow = {
+  readonly tenantId: string;
+  readonly tier: string;
+  readonly source: string | null;
+};
+type SubscriptionRow = {
+  readonly tenantId: string;
+  readonly providerName: string;
+  readonly status: string;
+};
+
+type TenantCapsListRow = {
+  readonly tenantId: string;
+  readonly name: string;
+  readonly tier: string;
+  readonly billing: string;
+  readonly [capField: string]: unknown;
+};
+
+// tier-resolver.ts rebuilds the same drizzle table locally rather than
+// importing a pre-built one — tier-engine's public barrel only exports the
+// entity, not a built table (see tier-engine/tier-resolver.ts).
+const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
+
+function billingLabel(
+  subscription: SubscriptionRow | undefined,
+  tierSource: string | null,
+): string {
+  if (subscription) return `${subscription.providerName} · ${subscription.status}`;
+  if (tierSource === "manual") return "manual";
+  return "—";
+}
+
+const FILTER_OP = z.enum(["eq", "ne", "lt", "gt", "in"]);
+type FilterOp = z.infer<typeof FILTER_OP>;
+
+const SORTABLE_FIELDS = ["name", "tier", "billing"] as const;
+type SortableField = (typeof SORTABLE_FIELDS)[number];
+
+function isSortableField(field: string): field is SortableField {
+  return (SORTABLE_FIELDS as readonly string[]).includes(field);
+}
+
+// tier is a plain string with no defined ordering — lt/gt have no meaning
+// on it and are rejected rather than silently treated as "no filter".
+function assertSupportedTierFilterOp(op: FilterOp): void {
+  if (op === "lt" || op === "gt") {
+    throw new ValidationError({
+      fields: [
+        {
+          path: "filters",
+          code: "unsupported_op",
+          i18nKey: "cap-overview.errors.tierFilterOpUnsupported",
+          params: { op },
+        },
+      ],
+    });
+  }
+}
+
+function matchesTierFilter(
+  tier: string,
+  filter: { readonly op: FilterOp; readonly value: unknown } | undefined,
+): boolean {
+  if (filter === undefined) return true;
+  switch (filter.op) {
+    case "eq":
+      return tier === filter.value;
+    case "ne":
+      return tier !== filter.value;
+    case "in":
+      return Array.isArray(filter.value) && filter.value.includes(tier);
+    case "lt":
+    case "gt":
+      // unreachable in practice — assertSupportedTierFilterOp rejects these before this runs
+      return true;
+  }
+}
+
+export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: readonly string[]) {
+  const listedCaps = caps.filter((cap) => listCaps.includes(cap.id));
+
+  return definePagedQueryHandler({
+    name: "tenant-caps:list",
+    schema: z.object({
+      cursor: z.string().optional(),
+      limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(50),
+      sort: z.string().optional(),
+      sortDirection: z.enum(["asc", "desc"]).optional(),
+      search: z.string().optional(),
+      filters: z
+        .array(z.object({ field: z.string(), op: FILTER_OP, value: z.unknown() }))
+        .optional(),
+      totalCount: z.boolean().optional(),
+    }),
+    access: { roles: ["SystemAdmin"] },
+    handler: async (query, ctx) => {
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message:
+            "cap-overview:query:tenant-caps:list requires ctx.systemDb — is r.systemScope() set?",
+        });
+      }
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "cap-overview:tenant-caps:list — SystemAdmin platform-wide tenant overview",
+      );
+
+      const tenants = await selectMany<TenantRow>(db, tenantTable, {});
+      const assignments = await selectMany<TierAssignmentRow>(db, tierAssignmentTable, {});
+      const subscriptions = await selectMany<SubscriptionRow>(db, subscriptionsProjectionTable, {});
+
+      const assignmentByTenant = new Map(assignments.map((row) => [row.tenantId, row]));
+      const subscriptionByTenant = new Map(subscriptions.map((row) => [row.tenantId, row]));
+
+      // Case-insensitive substring search has no `ilike` operator in the
+      // query builder (only `like`, SQL-LIKE case-sensitive) — filtered here
+      // in JS, same as tenant/team-list.query.ts's search.
+      const search = query.payload.search?.trim().toLowerCase();
+      const filters = query.payload.filters ?? [];
+      const tierFilter = filters.find((f) => f.field === "tier");
+      if (tierFilter !== undefined) assertSupportedTierFilterOp(tierFilter.op);
+
+      const merged = tenants
+        .filter(
+          (tenant) =>
+            search === undefined || search === "" || tenant.name.toLowerCase().includes(search),
+        )
+        .map((tenant) => {
+          const assignment = assignmentByTenant.get(tenant.id);
+          return {
+            tenantId: tenant.id,
+            name: tenant.name,
+            tier: assignment?.tier ?? "",
+            source: assignment?.source ?? null,
+            billing: billingLabel(subscriptionByTenant.get(tenant.id), assignment?.source ?? null),
+          };
+        })
+        .filter((row) => matchesTierFilter(row.tier, tierFilter));
+
+      const sortField = query.payload.sort ?? "name";
+      if (!isSortableField(sortField)) {
+        throw new ValidationError({
+          fields: [
+            {
+              path: "sort",
+              code: "unsupported_field",
+              i18nKey: "cap-overview.errors.sortFieldUnsupported",
+              params: { field: sortField },
+            },
+          ],
+        });
+      }
+      const sortDirection = query.payload.sortDirection ?? "asc";
+      const directionMultiplier = sortDirection === "asc" ? 1 : -1;
+      const sorted = [...merged].sort(
+        (a, b) => a[sortField].localeCompare(b[sortField]) * directionMultiplier,
+      );
+
+      // ponytail: base64-wrapped offset, not a SQL keyset — rows come from a
+      // JS merge of three tables (tenant/tier-assignment/subscription), same
+      // rationale as tenant/team-list.query.ts. Holds up to tier-engine's
+      // documented "single-pass scan" scale (a few thousand tenants); past
+      // that the fix is a real combined read-projection, not a cursor
+      // bolted onto this merge.
+      const offset = query.payload.cursor ? Number(decodeCursor(query.payload.cursor)) : 0;
+      const limit = query.payload.limit;
+      const page = sorted.slice(offset, offset + limit);
+
+      // N+1 avoidance: usage is computed only for this page's tenant ids,
+      // never for the full tenant set.
+      const pageTenantIds = page.map((row) => row.tenantId);
+      const usageByCap = new Map<string, Map<string, number>>();
+      for (const cap of listedCaps) {
+        if (cap.usageBatch) {
+          usageByCap.set(cap.id, await cap.usageBatch(db, pageTenantIds));
+        } else {
+          const perTenant = new Map<string, number>();
+          for (const tenantId of pageTenantIds) {
+            perTenant.set(tenantId, await cap.usage(db, tenantId));
+          }
+          usageByCap.set(cap.id, perTenant);
+        }
+      }
+
+      const rows: TenantCapsListRow[] = page.map((row) => {
+        const capFields: Record<string, CapUsage> = {};
+        for (const cap of listedCaps) {
+          const used = usageByCap.get(cap.id)?.get(row.tenantId) ?? 0;
+          const limit = cap.limit(row.tier);
+          capFields[capFieldName(cap.id)] = { used, limit, fraction: computeFraction(used, limit) };
+        }
+        return {
+          tenantId: row.tenantId,
+          name: row.name,
+          tier: row.tier,
+          billing: row.billing,
+          ...capFields,
+        };
+      });
+
+      const nextCursor =
+        offset + limit < sorted.length ? encodeCursor(String(offset + limit)) : null;
+
+      return {
+        rows,
+        nextCursor,
+        ...(query.payload.totalCount === true && { total: merged.length }),
+      };
+    },
+  });
+}

package/src/cap-overview/handlers/tenant-options.query.ts

@@ -0,0 +1,33 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { tenantTable } from "../../tenant";
+
+type TenantRow = { readonly id: string; readonly name: string };
+
+export const tenantOptionsQuery = defineQueryHandler({
+  name: "tenant-options",
+  schema: z.object({}),
+  access: { roles: ["SystemAdmin"] },
+  handler: async (_query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "cap-overview:query:tenant-options requires ctx.systemDb — is r.systemScope() set?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "cap-overview:tenant-options — SystemAdmin dashboard tenant-filter options",
+    );
+    const tenants = await selectMany<TenantRow>(
+      db,
+      tenantTable,
+      {},
+      {
+        orderBy: { col: "name", direction: "asc" },
+      },
+    );
+    return { rows: tenants.map((tenant) => ({ value: tenant.id, label: tenant.name })) };
+  },
+});

package/src/cap-overview/i18n.ts

@@ -0,0 +1,25 @@
+type LocalizedString = { readonly en: string };
+
+export const CAP_OVERVIEW_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:tenant-cap-list.title": { en: "Tenant caps" },
+  "screen:my-caps.title": { en: "My usage" },
+  "screen:platform-tenant-caps.title": { en: "Tenant dashboard" },
+  "cap-overview.list.col.name": { en: "Tenant" },
+  "cap-overview.list.col.tier": { en: "Tier" },
+  "cap-overview.list.col.billing": { en: "Billing" },
+  "cap-overview.list.filter.tier": { en: "Tier" },
+  "cap-overview.list.action.open": { en: "Open dashboard" },
+  "cap-overview.platform.filter.tenant": { en: "Tenant" },
+  "cap-overview.cards.empty": { en: "No caps configured for this tenant." },
+  "cap-overview.cards.loading": { en: "Loading usage…" },
+  "cap-overview.errors.progressPrimitiveMissing": {
+    en: "Usage bar unavailable — Progress primitive is not registered.",
+  },
+  "cap-overview.errors.sortFieldUnsupported": { en: "Sorting by this field is not supported." },
+  "cap-overview.errors.tenantOverrideRequiresSystemAdmin": {
+    en: "Only SystemAdmin may query another tenant's data.",
+  },
+  "cap-overview.errors.tierFilterOpUnsupported": {
+    en: "This filter operator is not supported for tier.",
+  },
+};

package/src/cap-overview/index.ts

@@ -0,0 +1,20 @@
+// Public API of the cap-overview bundled-feature.
+
+export {
+  CAP_CARDS_PANEL_COMPONENT,
+  CAP_OVERVIEW_FEATURE,
+  CAP_USAGE_CELL_COMPONENT,
+  CapOverviewQueries,
+  capFieldName,
+  MY_CAPS_SCREEN_ID,
+  PLATFORM_TENANT_CAPS_SCREEN_ID,
+  TENANT_CAP_LIST_SCREEN_ID,
+} from "./constants";
+export { type CreateCapOverviewOptions, createCapOverviewFeature } from "./feature";
+export {
+  createTenantCapListScreen,
+  myCapsScreen,
+  platformTenantCapsScreen,
+} from "./screens";
+export type { CapSpec, CapUsage, CapUsageTone, CapUsageWithMeta } from "./types";
+export { computeFraction, computeTone } from "./usage-math";

package/src/cap-overview/screens.ts

@@ -0,0 +1,101 @@
+import { access, type ScreenDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  CAP_CARDS_PANEL_COMPONENT,
+  CAP_USAGE_CELL_COMPONENT,
+  CapOverviewQueries,
+  capFieldName,
+  MY_CAPS_SCREEN_ID,
+  PLATFORM_TENANT_CAPS_SCREEN_ID,
+  TENANT_CAP_LIST_SCREEN_ID,
+} from "./constants";
+import type { CapSpec } from "./types";
+
+// `tiers` has no room for a separate per-tier display label (it's just
+// `readonly string[]`) — tier-engine itself has no enumerated tier list to
+// derive one from either (it's generic over tier values, see tier-engine's
+// own doc comment). The tier string is used verbatim as the facet option
+// label, same as how tier values already surface untranslated elsewhere
+// (tier-engine's TierMap keys).
+export function createTenantCapListScreen(
+  caps: readonly CapSpec[],
+  listCaps: readonly string[],
+  tiers?: readonly string[],
+): ScreenDefinition {
+  const listedCaps = caps.filter((cap) => listCaps.includes(cap.id));
+
+  return {
+    id: TENANT_CAP_LIST_SCREEN_ID,
+    type: "projectionList",
+    query: CapOverviewQueries.tenantCapsList,
+    columns: [
+      { field: "name", label: "cap-overview.list.col.name" },
+      { field: "tier", label: "cap-overview.list.col.tier" },
+      { field: "billing", label: "cap-overview.list.col.billing" },
+      ...listedCaps.map((cap) => ({
+        field: capFieldName(cap.id),
+        label: cap.label,
+        renderer: { react: { __component: CAP_USAGE_CELL_COMPONENT } },
+      })),
+    ],
+    searchable: true,
+    ...(tiers !== undefined &&
+      tiers.length > 0 && {
+        facets: [
+          {
+            field: "tier",
+            type: "select" as const,
+            label: "cap-overview.list.filter.tier",
+            options: tiers.map((tier) => ({ value: tier, label: tier })),
+          },
+        ],
+      }),
+    // params.map's key ("tenantId") must match platform-tenant-caps's own
+    // `filter.id` — that's how useFilterParams (dashboard-body.tsx) seeds
+    // the tenant filter from the URL on arrival, landing straight on the
+    // clicked tenant's dashboard instead of an empty one (boot-validated).
+    rowActions: [
+      {
+        kind: "navigate" as const,
+        id: "open-dashboard",
+        label: "cap-overview.list.action.open",
+        screen: PLATFORM_TENANT_CAPS_SCREEN_ID,
+        params: { map: { tenantId: "tenantId" } },
+        rowClick: true,
+      },
+    ],
+    defaultSort: { field: "name", dir: "asc" },
+    access: { roles: ["SystemAdmin"] },
+  };
+}
+
+export const myCapsScreen: ScreenDefinition = {
+  id: MY_CAPS_SCREEN_ID,
+  type: "dashboard",
+  panels: [
+    {
+      kind: "custom",
+      id: "cap-cards",
+      component: { react: { __component: CAP_CARDS_PANEL_COMPONENT } },
+    },
+  ],
+  access: { roles: access.admin },
+};
+
+export const platformTenantCapsScreen: ScreenDefinition = {
+  id: PLATFORM_TENANT_CAPS_SCREEN_ID,
+  type: "dashboard",
+  panels: [
+    {
+      kind: "custom",
+      id: "cap-cards",
+      component: { react: { __component: CAP_CARDS_PANEL_COMPONENT } },
+    },
+  ],
+  filter: {
+    id: "tenantId",
+    label: "cap-overview.platform.filter.tenant",
+    kind: "select",
+    optionsQuery: CapOverviewQueries.tenantOptions,
+  },
+  access: { roles: ["SystemAdmin"] },
+};

package/src/cap-overview/types.ts

@@ -0,0 +1,51 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+// Closed vocabulary for the dashboard cards' icon chip — cap-cards-panel.tsx
+// holds the matching lucide-react lookup. Small on purpose (YAGNI): extend
+// both together when a cap needs a shape not covered here.
+export type CapIconKey = "file" | "hash" | "database" | "users" | "mail" | "gauge";
+
+// Consumer-owned cap definition. `usage`/`usageBatch` receive the SAME
+// unfiltered system-mode TenantDb the handler itself reads through — the
+// callback is responsible for scoping its own app-owned tables by tenantId,
+// same obligation the rest of this feature carries (see feature.ts SECURITY
+// note).
+export type CapSpec = {
+  readonly id: string;
+  readonly label: string;
+  readonly limit: (tier: string) => number;
+  readonly usage: (db: TenantDb, tenantId: TenantId) => Promise<number>;
+  // Batched usage lookup for the tenant-caps:list screen — called once per
+  // cap with the current page's tenant ids instead of once per (cap, row).
+  // Optional: falls back to per-row `usage()` when absent.
+  readonly usageBatch?: (
+    db: TenantDb,
+    tenantIds: readonly TenantId[],
+  ) => Promise<Map<TenantId, number>>;
+  readonly unit?: "count" | "mb" | "tokens";
+  /** Icon chip on the dashboard cards. Optional — omitted renders the card
+   *  without an icon, same as before this field existed. */
+  readonly icon?: CapIconKey;
+  /** Icon-chip accent — same raw-CSS-value contract as DashboardStatPanel's
+   *  `accentColor` (packages/types/src/screen.ts): a theme token
+   *  (`var(--color-status-ok)`), not a literal palette hex. Optional. */
+  readonly accentColor?: string;
+};
+
+export type CapUsageTone = "default" | "warn" | "danger";
+
+export type CapUsage = {
+  readonly used: number;
+  readonly limit: number;
+  readonly fraction: number;
+};
+
+export type CapUsageWithMeta = CapUsage & {
+  readonly id: string;
+  readonly label: string;
+  readonly tone: CapUsageTone;
+  readonly percent: number;
+  readonly icon?: CapIconKey;
+  readonly accentColor?: string;
+};

package/src/cap-overview/usage-math.ts

@@ -0,0 +1,32 @@
+// @runtime client
+// Pure math with no runtime deps — both the query handlers (runtime → client
+// is allowed by the compat matrix) and cap-usage-bar.tsx (client → client)
+// import it.
+import type { CapUsageTone } from "./types";
+
+const WARN_THRESHOLD = 0.8;
+const DANGER_THRESHOLD = 1;
+
+// limit <= 0 means "not part of this tier" — 0, never NaN/Infinity.
+function rawFraction(used: number, limit: number): number {
+  if (limit <= 0) return 0;
+  const fraction = used / limit;
+  return Number.isFinite(fraction) ? fraction : 0;
+}
+
+export function computeFraction(used: number, limit: number): number {
+  return Math.min(1, Math.max(0, rawFraction(used, limit)));
+}
+
+// Unclamped — for display of the over-limit case (e.g. "140%"). Bar width
+// and tone still use the clamped computeFraction; only percent shows the
+// real ratio.
+export function computeUnclampedFraction(used: number, limit: number): number {
+  return rawFraction(used, limit);
+}
+
+export function computeTone(fraction: number): CapUsageTone {
+  if (fraction >= DANGER_THRESHOLD) return "danger";
+  if (fraction >= WARN_THRESHOLD) return "warn";
+  return "default";
+}