@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/cap-overview/feature.js

@@ -0,0 +1,55 @@
+// 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. Every member of a tenant 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 } from "@cosmicdrift/kumiko-framework/engine";
+import { CAP_OVERVIEW_FEATURE } from "./constants.js";
+import { createCapsUsageQuery } from "./handlers/caps-usage.query.js";
+import { createTenantCapsListQuery } from "./handlers/tenant-caps-list.query.js";
+import { tenantOptionsQuery } from "./handlers/tenant-options.query.js";
+import { CAP_OVERVIEW_I18N } from "./i18n.js";
+import { createTenantCapListScreen, myCapsScreen, platformTenantCapsScreen } from "./screens.js";
+export function createCapOverviewFeature(opts) {
+    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; every member of a tenant gets their own tenant's 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/dist/cap-overview/handlers/caps-usage.query.d.ts

@@ -0,0 +1,3 @@
+import { type QueryHandlerDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import type { CapSpec } from "../types.js";
+export declare function createCapsUsageQuery(caps: readonly CapSpec[]): QueryHandlerDefinition;

package/dist/cap-overview/handlers/caps-usage.query.js

@@ -0,0 +1,83 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { crossTenantOverrideDenied, defineQueryHandler, } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { tierAssignmentEntity } from "../../tier-engine/index.js";
+import { MY_CAPS_ACCESS_ROLES } from "../access.js";
+import { computeFraction, computeTone, computeUnclampedFraction } from "../usage-math.js";
+const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
+export function createCapsUsageQuery(caps) {
+    return defineQueryHandler({
+        name: "caps:usage",
+        description: "Returns the calling user's own tenant's configured caps with used amount, tier limit and utilisation fraction; use it to answer how close a tenant is to its quota (only SystemAdmin may target another tenant via tenantId).",
+        schema: z.object({ tenantId: z.string().min(1).optional() }),
+        access: { roles: MY_CAPS_ACCESS_ROLES },
+        // App-owned CapSpec.usage() providers get this handler's db; a SUM has
+        // no TenantDb helper (count() is COUNT(*)-only), so they need raw SQL.
+        escapeHatch: {
+            reason: "cap-overview:caps:usage — grants app-owned CapSpec.usage() providers raw SQL for aggregates TenantDb has no typed helper for (e.g. a SUM)",
+        },
+        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(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 = await Promise.all(caps.map(async (cap) => {
+                const used = await cap.usage(db, targetTenantId);
+                const limit = await cap.limit(tier, { config: ctx.config });
+                if (used === null) {
+                    return {
+                        id: cap.id,
+                        label: cap.label,
+                        used: null,
+                        limit,
+                        fraction: 0,
+                        tone: "default",
+                        percent: null,
+                        ...(cap.icon !== undefined && { icon: cap.icon }),
+                        ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }),
+                    };
+                }
+                const fraction = computeFraction(used, limit);
+                return {
+                    id: cap.id,
+                    label: cap.label,
+                    used,
+                    limit,
+                    fraction,
+                    tone: computeTone(fraction),
+                    percent: limit === null ? null : Math.round(computeUnclampedFraction(used, limit) * 100),
+                    ...(cap.icon !== undefined && { icon: cap.icon }),
+                    ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }),
+                };
+            }));
+            return { rows };
+        },
+    });
+}

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

@@ -0,0 +1,32 @@
+import * as z from "zod";
+import type { CapSpec } from "../types.js";
+type TenantCapsListRow = {
+    readonly tenantId: string;
+    readonly name: string;
+    readonly tier: string;
+    readonly billing: string;
+    readonly [capField: string]: unknown;
+};
+export declare function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: readonly string[]): import("@cosmicdrift/kumiko-framework/engine").PagedQueryHandlerDefinition<"tenant-caps:list", z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    sort: z.ZodOptional<z.ZodString>;
+    sortDirection: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    search: z.ZodOptional<z.ZodString>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            in: "in";
+            lt: "lt";
+            ne: "ne";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>>;
+    totalCount: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, TenantCapsListRow, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export {};

package/dist/cap-overview/handlers/tenant-caps-list.query.js

@@ -0,0 +1,192 @@
+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 * as z from "zod";
+import { subscriptionsProjectionTable } from "../../billing-foundation/index.js";
+import { tenantTable } from "../../tenant/index.js";
+import { tierAssignmentEntity } from "../../tier-engine/index.js";
+import { capFieldName } from "../constants.js";
+import { computeFraction } from "../usage-math.js";
+// 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, tierSource) {
+    if (subscription)
+        return `${subscription.providerName} · ${subscription.status}`;
+    if (tierSource === "manual")
+        return "manual";
+    return "—";
+}
+const FILTER_OP = z.enum(["eq", "ne", "lt", "gt", "in"]);
+const SORTABLE_FIELDS = ["name", "tier", "billing"];
+function capTierKey(capId, tier) {
+    return JSON.stringify([capId, tier]);
+}
+async function resolveLimitsByCapAndTier(caps, tiers, context) {
+    const limitByCapAndTier = new Map();
+    for (const cap of caps) {
+        for (const tier of tiers) {
+            limitByCapAndTier.set(capTierKey(cap.id, tier), await cap.limit(tier, context));
+        }
+    }
+    return limitByCapAndTier;
+}
+function isSortableField(field) {
+    return SORTABLE_FIELDS.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) {
+    if (op === "lt" || op === "gt") {
+        throw new ValidationError({
+            fields: [
+                {
+                    path: "filters",
+                    code: "unsupported_op",
+                    i18nKey: "cap-overview.errors.tierFilterOpUnsupported",
+                    params: { op },
+                },
+            ],
+        });
+    }
+}
+function matchesTierFilter(tier, filter) {
+    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, listCaps) {
+    const listedCaps = caps.filter((cap) => listCaps.includes(cap.id));
+    return definePagedQueryHandler({
+        name: "tenant-caps:list",
+        description: "Lists every tenant on the platform with its tier, billing provider/status and per-cap usage, paged, searchable by name and filterable by tier; use it as the operator-wide capacity overview.",
+        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(db, tenantTable, {});
+            const assignments = await selectMany(db, tierAssignmentTable, {});
+            const subscriptions = await selectMany(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();
+            for (const cap of listedCaps) {
+                if (cap.usageBatch) {
+                    usageByCap.set(cap.id, await cap.usageBatch(db, pageTenantIds));
+                }
+                else {
+                    const perTenant = new Map();
+                    for (const tenantId of pageTenantIds) {
+                        perTenant.set(tenantId, await cap.usage(db, tenantId));
+                    }
+                    usageByCap.set(cap.id, perTenant);
+                }
+            }
+            const limitByCapAndTier = await resolveLimitsByCapAndTier(listedCaps, new Set(page.map((row) => row.tier)), { config: ctx.config });
+            const rows = page.map((row) => {
+                const capFields = {};
+                for (const cap of listedCaps) {
+                    // A tenant absent from the map still means 0 (existing behavior);
+                    // only an explicit `null` value means "not measured".
+                    const rawUsed = usageByCap.get(cap.id)?.get(row.tenantId);
+                    const used = rawUsed === undefined ? 0 : rawUsed;
+                    const limit = limitByCapAndTier.get(capTierKey(cap.id, row.tier)) ?? null;
+                    capFields[capFieldName(cap.id)] =
+                        used === null
+                            ? { used: null, limit, fraction: 0 }
+                            : { 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/dist/cap-overview/handlers/tenant-options.query.d.ts

@@ -0,0 +1,7 @@
+import * as z from "zod";
+export declare const tenantOptionsQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"tenant-options", z.ZodObject<{}, z.core.$strip>, {
+    rows: {
+        value: string;
+        label: string;
+    }[];
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/cap-overview/handlers/tenant-options.query.js

@@ -0,0 +1,23 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { tenantTable } from "../../tenant/index.js";
+export const tenantOptionsQuery = defineQueryHandler({
+    name: "tenant-options",
+    description: "Returns all tenants as id/name option pairs sorted by name; use it to populate the tenant picker of a platform-wide overview.",
+    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(db, tenantTable, {}, {
+            orderBy: { col: "name", direction: "asc" },
+        });
+        return { rows: tenants.map((tenant) => ({ value: tenant.id, label: tenant.name })) };
+    },
+});

package/dist/cap-overview/i18n.d.ts

@@ -0,0 +1,5 @@
+type LocalizedString = {
+    readonly en: string;
+};
+export declare const CAP_OVERVIEW_I18N: Readonly<Record<string, LocalizedString>>;
+export {};

package/dist/cap-overview/i18n.js

@@ -0,0 +1,24 @@
+export const CAP_OVERVIEW_I18N = {
+    "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.notMeasured": { en: "Not measured yet" },
+    "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/dist/cap-overview/index.d.ts

@@ -0,0 +1,6 @@
+export { MY_CAPS_ACCESS_ROLES } from "./access.js";
+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.js";
+export { type CreateCapOverviewOptions, createCapOverviewFeature } from "./feature.js";
+export { createTenantCapListScreen, myCapsScreen, platformTenantCapsScreen, } from "./screens.js";
+export type { CapSpec, CapUsage, CapUsageTone, CapUsageWithMeta } from "./types.js";
+export { computeFraction, computeTone } from "./usage-math.js";

package/dist/cap-overview/index.js

@@ -0,0 +1,6 @@
+// Public API of the cap-overview bundled-feature.
+export { MY_CAPS_ACCESS_ROLES } from "./access.js";
+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.js";
+export { createCapOverviewFeature } from "./feature.js";
+export { createTenantCapListScreen, myCapsScreen, platformTenantCapsScreen, } from "./screens.js";
+export { computeFraction, computeTone } from "./usage-math.js";

package/dist/cap-overview/screens.d.ts

@@ -0,0 +1,5 @@
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import type { CapSpec } from "./types.js";
+export declare function createTenantCapListScreen(caps: readonly CapSpec[], listCaps: readonly string[], tiers?: readonly string[]): ScreenDefinition;
+export declare const myCapsScreen: ScreenDefinition;
+export declare const platformTenantCapsScreen: ScreenDefinition;

package/dist/cap-overview/screens.js

@@ -0,0 +1,90 @@
+import { MY_CAPS_ACCESS_ROLES } from "./access.js";
+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.js";
+// `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, listCaps, tiers) {
+    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",
+                    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",
+                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"] },
+        // No nav wiring yet (see feature.ts header) — no nav area to resolve
+        // in isolation.
+        dormant: true,
+    };
+}
+export const myCapsScreen = {
+    id: MY_CAPS_SCREEN_ID,
+    type: "dashboard",
+    panels: [
+        {
+            kind: "custom",
+            id: "cap-cards",
+            component: { react: { __component: CAP_CARDS_PANEL_COMPONENT } },
+        },
+    ],
+    access: { roles: MY_CAPS_ACCESS_ROLES },
+    // No nav wiring yet (see feature.ts header) — no nav area to resolve in
+    // isolation.
+    dormant: true,
+};
+export const platformTenantCapsScreen = {
+    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/dist/cap-overview/types.d.ts

@@ -0,0 +1,33 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { CapLimitContext } from "../cap-counter/index.js";
+export type CapIconKey = "file" | "hash" | "database" | "users" | "mail" | "gauge";
+export type CapSpec = {
+    readonly id: string;
+    readonly label: string;
+    readonly limit: (tier: string, context: CapLimitContext) => number | null | Promise<number | null>;
+    readonly usage: (db: TenantDb, tenantId: TenantId) => Promise<number | null>;
+    readonly usageBatch?: (db: TenantDb, tenantIds: readonly TenantId[]) => Promise<Map<TenantId, number | null>>;
+    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 | null;
+    readonly limit: number | null;
+    readonly fraction: number;
+};
+export type CapUsageWithMeta = CapUsage & {
+    readonly id: string;
+    readonly label: string;
+    readonly tone: CapUsageTone;
+    readonly percent: number | null;
+    readonly icon?: CapIconKey;
+    readonly accentColor?: string;
+};

package/dist/cap-overview/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cap-overview/usage-math.d.ts

@@ -0,0 +1,4 @@
+import type { CapUsageTone } from "./types.js";
+export declare function computeFraction(used: number, limit: number | null): number;
+export declare function computeUnclampedFraction(used: number, limit: number | null): number;
+export declare function computeTone(fraction: number): CapUsageTone;

package/dist/cap-overview/usage-math.js

@@ -0,0 +1,28 @@
+const WARN_THRESHOLD = 0.8;
+const DANGER_THRESHOLD = 1;
+// limit === null means unlimited (no cap to measure against); limit <= 0
+// means "not part of this tier" — both render as 0, never NaN/Infinity.
+function rawFraction(used, limit) {
+    if (limit === null)
+        return 0;
+    if (limit <= 0)
+        return 0;
+    const fraction = used / limit;
+    return Number.isFinite(fraction) ? fraction : 0;
+}
+export function computeFraction(used, limit) {
+    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, limit) {
+    return rawFraction(used, limit);
+}
+export function computeTone(fraction) {
+    if (fraction >= DANGER_THRESHOLD)
+        return "danger";
+    if (fraction >= WARN_THRESHOLD)
+        return "warn";
+    return "default";
+}

package/dist/cap-overview/web/cap-cards-panel.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionSectionProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+export declare function CapCardsPanel({ filterParams }: ExtensionSectionProps): ReactNode;