cartethyia 2.7.2 → 2.7.3

package/src/console/quota/native-identity.ts

@@ -0,0 +1,189 @@
+/**
+ * Qoder native-identity console operations, shared by the tenant-scoped and
+ * global-admin account route groups.
+ *
+ * The identity is the account's device identity (minted seed). The routes
+ * surface it for export/import/regenerate from the provider-detail screen;
+ * the device-uniqueness invariant lives in the store (and the partial unique
+ * index behind it).
+ */
+import { and, eq, isNull } from "drizzle-orm";
+import { Elysia, t } from "elysia";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { providerAccounts, type NativeIdentityRecord } from "../../persistence/schema";
+import {
+  allocateQoderNativeIdentity,
+  DrizzleQoderNativeIdentityStore,
+  type QoderNativeIdentityStore,
+} from "../../providers/integrations/qoder/qoder-native-identity-store";
+import { ConsoleDomainError, requireGlobalAdmin, requireTenantScope } from "../shared/errors";
+import type { ConsoleAccessResolver } from "../auth/access";
+
+/** True when `token` looks like a plausible machine token. */
+export function isValidNativeIdentityToken(token: string): boolean {
+  return typeof token === "string" && token.length >= 8 && token.length <= 512;
+}
+
+/**
+ * Allocates a fresh device identity for regenerate. Injected so tests can stub
+ * the native bridge; the default runs the real `runtime-info` bridge through
+ * the store.
+ */
+export type NativeIdentityAllocator = (args: {
+  providerId: string;
+  accountId: string;
+  avoidToken?: string;
+}) => Promise<NativeIdentityRecord | null>;
+
+function defaultAllocator(store: QoderNativeIdentityStore): NativeIdentityAllocator {
+  return ({ providerId, accountId, avoidToken }) =>
+    allocateQoderNativeIdentity(store, providerId, accountId, {
+      ...(avoidToken !== undefined ? { avoidToken } : {}),
+    });
+}
+
+/** Loads one account row, scoped by tenant (null = global/shared). */
+async function loadAccount(
+  db: CartethyiaDatabase,
+  accountId: string,
+  tenantId: string | null,
+): Promise<{ providerId: string; nativeIdentity: NativeIdentityRecord | null } | undefined> {
+  const rows = await db
+    .select({
+      providerId: providerAccounts.providerId,
+      nativeIdentity: providerAccounts.nativeIdentity,
+    })
+    .from(providerAccounts)
+    .where(
+      tenantId === null
+        ? and(eq(providerAccounts.id, accountId), isNull(providerAccounts.tenantId))
+        : and(eq(providerAccounts.id, accountId), eq(providerAccounts.tenantId, tenantId)),
+    )
+    .limit(1);
+  return rows[0];
+}
+
+export interface NativeIdentityOps {
+  get(accountId: string, tenantId: string | null): Promise<NativeIdentityRecord | null>;
+  put(accountId: string, tenantId: string | null, record: NativeIdentityRecord): Promise<NativeIdentityRecord>;
+  regenerate(accountId: string, tenantId: string | null): Promise<NativeIdentityRecord | null>;
+}
+
+export function createNativeIdentityOps(
+  db: CartethyiaDatabase,
+  allocator: NativeIdentityAllocator = defaultAllocator(new DrizzleQoderNativeIdentityStore(db)),
+): NativeIdentityOps {
+  const store = new DrizzleQoderNativeIdentityStore(db);
+  return {
+    async get(accountId, tenantId) {
+      const account = await loadAccount(db, accountId, tenantId);
+      // A missing row under the narrowed tenant scope means the account is not
+      // visible to this caller (cross-tenant read) — report not-found, the
+      // same convention the account routes use, rather than echoing null.
+      if (!account) throw new ConsoleDomainError("not_found", 404, "Account not found");
+      return account.nativeIdentity;
+    },
+    async put(accountId, tenantId, record) {
+      const account = await loadAccount(db, accountId, tenantId);
+      if (!account) throw new ConsoleDomainError("not_found", 404, "Account not found");
+      if (!isValidNativeIdentityToken(record.machineToken)) {
+        throw new ConsoleDomainError("invalid_identity", 400, "machineToken must be a non-empty string (8–512 chars)");
+      }
+      if (!record.machineType || !record.machineCode) {
+        throw new ConsoleDomainError("invalid_identity", 400, "machineToken, machineType, and machineCode are required");
+      }
+      // Device uniqueness: another account already owns this token? The pool is
+      // global across Qoder accounts (both realms), matching the unique index.
+      const occupied = await store.occupied(accountId);
+      if (occupied.has(record.machineToken)) {
+        throw new ConsoleDomainError("slot_taken", 409, `Native identity token is already bound to another account`);
+      }
+      await store.bind(account.providerId, accountId, record);
+      return record;
+    },
+    async regenerate(accountId, tenantId) {
+      const account = await loadAccount(db, accountId, tenantId);
+      if (!account) throw new ConsoleDomainError("not_found", 404, "Account not found");
+      return allocator({
+        providerId: account.providerId,
+        accountId,
+        ...(account.nativeIdentity?.machineToken !== undefined ? { avoidToken: account.nativeIdentity.machineToken } : {}),
+      });
+    },
+  };
+}
+
+/**
+ * The authorization decision for one account's native-identity route.
+ *
+ * Account ownership decides which rule applies: shared accounts
+ * (`tenant_id IS NULL`) need platform admin; tenant-owned accounts need the
+ * tenant scope for the owning tenant.
+ */
+export interface NativeIdentityScope {
+  readonly tenantId: string | null;
+}
+
+/**
+ * Registers the native-identity routes on `app` (path
+ * `/provider-accounts/:id/native-identity`).
+ *
+ * `authorize` performs the access check based on the account's owner and
+ * returns the tenant scope to load the row under, so a shared account is
+ * reachable only by a platform admin and a tenant-owned account only by its
+ * tenant.
+ */
+export function registerNativeIdentityRoutes(
+  app: Elysia,
+  deps: { readonly db: CartethyiaDatabase; readonly accessResolver: ConsoleAccessResolver },
+  allocator?: NativeIdentityAllocator,
+): void {
+  const ops = createNativeIdentityOps(deps.db, allocator);
+  const authorize = async (
+    request: Request,
+    accountId: string,
+    scope: "dashboard:read" | "dashboard:write",
+  ): Promise<NativeIdentityScope> => {
+    const rows = await deps.db
+      .select({ tenantId: providerAccounts.tenantId })
+      .from(providerAccounts)
+      .where(eq(providerAccounts.id, accountId))
+      .limit(1);
+    if (rows.length === 0) {
+      throw new ConsoleDomainError("not_found", 404, "Account not found");
+    }
+    const ownerTenantId = rows[0]!.tenantId;
+    if (ownerTenantId === null) {
+      requireGlobalAdmin(deps.accessResolver(request));
+      return { tenantId: null };
+    }
+    const access = requireTenantScope(deps.accessResolver(request), scope);
+    return { tenantId: access.tenantId };
+  };
+  app
+    .get("/provider-accounts/:id/native-identity", async ({ request, params }) => {
+      const { tenantId } = await authorize(request, params.id, "dashboard:read");
+      return { identity: await ops.get(params.id, tenantId) };
+    })
+    .put(
+      "/provider-accounts/:id/native-identity",
+      {
+        body: t.Object({
+          machineToken: t.String(),
+          machineType: t.String(),
+          machineCode: t.String(),
+          seed: t.Optional(t.String()),
+        }),
+      },
+      async ({ request, params, body }) => {
+        const { tenantId } = await authorize(request, params.id, "dashboard:write");
+        const identity = await ops.put(params.id, tenantId, body as NativeIdentityRecord);
+        return { identity };
+      },
+    )
+    .post("/provider-accounts/:id/native-identity/regenerate", async ({ request, params }) => {
+      const { tenantId } = await authorize(request, params.id, "dashboard:write");
+      const identity = await ops.regenerate(params.id, tenantId);
+      return { identity };
+    });
+}

package/src/console/remote-support/contracts.ts

@@ -51,12 +51,18 @@ export interface RemoteSupportStartResponse extends RemoteSupportStatus {
 }
 
 /** Human-readable install guidance, keyed by tool. Never an installer. */
-export const REMOTE_SUPPORT_INSTALL_HINT: Readonly<Record<RemoteSupportTool, string>> = {
-  cloudflared:
-    "cloudflared is not installed. Install it yourself (winget install Cloudflare.cloudflared) and try again.",
-  tailscale:
-    "tailscale is not installed. Install it yourself (winget install Tailscale.Tailscale), run `tailscale up` once, then try again.",
-};
+export function remoteSupportInstallHint(tool: RemoteSupportTool): string {
+  // Cross-OS install hint: pick the host's package manager. A Windows-only
+  // hint on Linux/macOS would be nonsense (and vice versa).
+  const win = process.platform === "win32";
+  const mac = process.platform === "darwin";
+  const installCommand = (pkg: string): string =>
+    win ? `winget install ${pkg}` : mac ? `brew install ${pkg}` : `sudo apt-get install -y ${pkg}`;
+  if (tool === "cloudflared") {
+    return `cloudflared is not installed. Install it yourself (${installCommand("cloudflared")}) and try again.`;
+  }
+  return `tailscale is not installed. Install it yourself (${installCommand("tailscale")}), run \`tailscale up\` once, then try again.`;
+}
 
 export function isRemoteSupportTool(value: unknown): value is RemoteSupportTool {
   return typeof value === "string" && (REMOTE_SUPPORT_TOOLS as readonly string[]).includes(value);

package/src/console/remote-support/service.ts

@@ -18,7 +18,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, write
 import { join } from "node:path";
 import { resolveUserConfigDir } from "../../config/package-paths";
 import {
-  REMOTE_SUPPORT_INSTALL_HINT,
+  remoteSupportInstallHint,
   REMOTE_SUPPORT_TOOLS,
   type RemoteSupportBlocker,
   type RemoteSupportStatus,
@@ -430,7 +430,7 @@ export function createRemoteSupportService(config: RemoteSupportServiceConfig):
           active: null,
           url: null,
           blocker: "not_installed",
-          message: REMOTE_SUPPORT_INSTALL_HINT[tool],
+          message: remoteSupportInstallHint(tool),
           port,
           installed: await detectInstalled(),
         };

package/src/console/share/share-router.ts

@@ -5,7 +5,7 @@ import { globalOrOwnedBy } from "../../persistence/tenant-scope";
 // client IP. The child bearer is returned only by the successful issue call.
 
 import { Elysia } from "elysia";
-import { and, eq } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { apiKeys, models, providers } from "../../persistence/schema";
 import { PublicModelCatalogStore } from "../providers/catalog/public-model-store";
@@ -227,12 +227,20 @@ async function resolveFamilyStats(
   if (resolved === null) return null;
   const templateId = resolved.key.id;
   const tenantId = resolved.key.tenantId;
-  const children = await db
-    .select({ id: apiKeys.id, revokedAt: apiKeys.revokedAt })
+  // Recipient counts come back as one aggregate row: a family minted by the
+  // tenant can carry tens of thousands of children, and materializing their
+  // ids only to count them made every share-page view pay for the family's
+  // size. The fingerprint/quote keys the rollup needs are addressed by the
+  // template id (`familyApiKeyId`), which scopes in SQL without any id list.
+  const [counts] = await db
+    .select({
+      total: sql<number>`count(*)`,
+      active: sql<number>`sum(case when ${apiKeys.revokedAt} is null then 1 else 0 end)`,
+    })
     .from(apiKeys)
     .where(eq(apiKeys.parentKeyId, templateId));
-  const active = children.filter((child) => child.revokedAt === null).length;
-  const keyIds = [templateId, ...children.map((child) => child.id)];
+  const total = Number(counts?.total ?? 0);
+  const active = Number(counts?.active ?? 0);
   // Rank only the models this link grants. A refused request still writes a
   // telemetry row carrying the name the client asked for, so an unfiltered
   // top-models table would list the very names the grant excludes. An
@@ -244,7 +252,12 @@ async function resolveFamilyStats(
     configured !== null && configured.length > 0
       ? await modelsForShare(db, resolved.key)
       : undefined;
-  return stats.getFamilyStats(tenantId, keyIds, { total: children.length, active }, allowedModels);
+  return stats.getFamilyStats(
+    tenantId,
+    { templateKeyId: templateId, memberCount: total + 1 },
+    { total, active },
+    allowedModels,
+  );
 }
 
 /** Creates the public enrollment page and one-time shared-key issuance route. */
@@ -379,6 +392,26 @@ export function createShareRouter(options: ShareRouterOptions): Elysia {
         nameHint,
       });
       if (issued.kind === "link_unavailable") return notFound();
+      if (issued.kind === "slot_full") {
+        return json({
+          error: {
+            code: "template_slot_full",
+            message: "This template has reached its maximum number of recipients.",
+          },
+        }, 429);
+      }
+      if (issued.kind === "already_issued") {
+        // The recipient's IP already enrolled from this link. The original
+        // bearer secret is not stored server-side, so it cannot be returned;
+        // refuse the duplicate mint instead. The share page surfaces this as
+        // a clear message rather than minting an unbounded key set.
+        return json({
+          error: {
+            code: "already_issued",
+            message: "This address already has a key from this share link.",
+          },
+        }, 409);
+      }
       set.status = 201;
       return json({
         key: generated.secret,

package/src/console/share/share-stats.ts

@@ -11,10 +11,15 @@
 // masked addresses. No request or response bodies cross this boundary.
 
 import { createHash } from "node:crypto";
+import { eq } from "drizzle-orm";
 import { maskClientIp } from "../../observability/redaction";
 import { type TelemetryEventRecord } from "../../observability/event-log";
-import { queryTelemetryEvents as querySqlEvents } from "../../observability/event-query";
+import {
+  queryTelemetryEvents as querySqlEvents,
+  sumTelemetryTokens,
+} from "../../observability/event-query";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { apiKeys } from "../../persistence/schema";
 import { isGatewayError } from "../../observability/telemetry-status";
 import type { RedisClient } from "../../persistence/redis";
 import { cachedRead } from "../shared/read-through-cache";
@@ -81,6 +86,14 @@ export interface ShareFamilyStats {
 /** Read-only family rollup for one share link. */
 export interface ShareStatsPort {
   /**
+   * The family is addressed by its template key (`templateKeyId`) plus the
+   * number of keys it covers at call time (`memberCount`), not by an id list:
+   * a family grows with every key the link mints, and enumerating its ids to
+   * build a query — or a cache key — scaled both with the family instead of
+   * with the request. `memberCount` keeps the cache key sensitive to minting:
+   * a newly issued child starts a fresh entry rather than being folded into
+   * the previous one for a full TTL.
+   *
    * `allowedModels`, when supplied, restricts the top-models table to the names
    * the link actually grants. A rejected request still writes a telemetry row
    * (with the requested name), so without this the table would rank models the
@@ -90,7 +103,7 @@ export interface ShareStatsPort {
    */
   getFamilyStats(
     tenantId: string,
-    keyIds: readonly string[],
+    family: { readonly templateKeyId: string; readonly memberCount: number },
     recipients: { readonly total: number; readonly active: number },
     allowedModels?: readonly string[],
   ): Promise<ShareFamilyStats>;
@@ -244,19 +257,21 @@ const HOURS_WINDOW = 24;
 export const SHARE_STATS_CACHE_TTL_SECONDS = 10;
 
 /**
- * Cache key for one family's rollup. Both inputs change the payload — `keyIds`
- * selects the family and `allowedModels` filters the model table — so both are
- * hashed in; the key ids are sorted so key order cannot split one family across
- * two entries.
+ * Cache key for one family's rollup. The family is named by its template key
+ * and the number of keys it covers — both change the payload — and
+ * `allowedModels` filters the model table, so all three are hashed in.
+ * (The key used to hash the sorted list of every family id; on a family with
+ * tens of thousands of minted children that built and sorted a multi-megabyte
+ * string on every page view, before the cache could even answer.)
  */
 function shareFamilyStatsKey(
   tenantId: string,
-  keyIds: readonly string[],
+  family: { readonly templateKeyId: string; readonly memberCount: number },
   allowedModels: readonly string[] | undefined,
 ): string {
   const models = allowedModels === undefined ? "*" : [...allowedModels].sort().join(",");
   const hash = createHash("sha256")
-    .update([...keyIds].sort().join(",") + "|" + models)
+    .update(`${family.templateKeyId}#${family.memberCount}|${models}`)
     .digest("hex");
   return `share:v1:stats:${tenantId}:${hash}`;
 }
@@ -271,12 +286,12 @@ interface ShareStatsPortDeps {
 
 export function createShareStatsPort(deps: ShareStatsPortDeps): ShareStatsPort {
   return {
-    async getFamilyStats(tenantId, keyIds, recipients, allowedModels) {
-      if (keyIds.length === 0) return emptyStats(recipients);
+    async getFamilyStats(tenantId, family, recipients, allowedModels) {
+      if (family.templateKeyId.length === 0) return emptyStats(recipients);
       const cached = await cachedRead<Omit<ShareFamilyStats, "recipients">>(
         deps.redis,
-        shareFamilyStatsKey(tenantId, keyIds, allowedModels),
-        () => computeFamilyStatsBody(deps.db, tenantId, keyIds, allowedModels),
+        shareFamilyStatsKey(tenantId, family, allowedModels),
+        () => computeFamilyStatsBody(deps.db, tenantId, family.templateKeyId, allowedModels),
         SHARE_STATS_CACHE_TTL_SECONDS,
       );
       return { ...cached, recipients };
@@ -288,7 +303,7 @@ export function createShareStatsPort(deps: ShareStatsPortDeps): ShareStatsPort {
 async function computeFamilyStatsBody(
   db: CartethyiaDatabase,
   tenantId: string,
-  keyIds: readonly string[],
+  templateKeyId: string,
   allowedModels: readonly string[] | undefined,
 ): Promise<Omit<ShareFamilyStats, "recipients">> {
   // A share that grants a fixed set ranks only that set. Telemetry keeps the
@@ -304,20 +319,35 @@ async function computeFamilyStatsBody(
   const lastHourStart = new Date(now.getTime() - HOUR_MS);
   const windowStart = new Date(hourStart.getTime() - (HOURS_WINDOW - 1) * HOUR_MS);
 
-  // Rank only names the grant actually authorizes. Telemetry keeps the
-  // requested name even when the request was refused, so an unfiltered table
-  // would list exactly the invalid names an abuser probed. Filtering before
-  // the top-50 cut means refused names cannot hide a model the recipient may
-  // use.
-  //
-  // Bounded by the retention floor, not by the oldest counter: `totalTokens`
-  // is all-time, so cutting at `monthStart` would silently drop the rows that
-  // make it differ from `monthTokens`. Retention already caps the window, and
-  // the rows are read newest-first under a page cap, so a very large family
-  // cannot pull the whole table.
+  // All-time and today's/month's spend come from SQL aggregates, not from the
+  // bounded page below. The page is capped so a very large family cannot pull
+  // the whole table, which means it cannot carry the all-time total. Lifetime,
+  // daily, and monthly are therefore separate bounded sums over the retained
+  // SQL window (each is a single `SUM` aggregate, not a row materialization).
+  // The page's events feed only the hourly chart and the two ranked tables.
+  const [totalTokens, todayTokens, monthTokens, template] = await Promise.all([
+    sumTelemetryTokens(db, tenantId, { familyKeyId: templateKeyId, since: new Date(0) }),
+    sumTelemetryTokens(db, tenantId, { familyKeyId: templateKeyId, since: dayStart }),
+    sumTelemetryTokens(db, tenantId, { familyKeyId: templateKeyId, since: monthStart }),
+    db
+      .select({ lifetime: apiKeys.lifetimeTokensConsumed })
+      .from(apiKeys)
+      .where(eq(apiKeys.id, templateKeyId))
+      .limit(1),
+  ]);
+  // Cumulative family spend: the template's own counter plus the telemetry
+  // total. The counter is a manually-configured seed (an operator limit), not
+  // traffic, and it is never reset; azmetry rows for revoked/deleted children
+  // likewise stay counted, so the running total is monotonic and consistent
+  // across the overview, the share dialog, and this page.
+  const templateLifetime = Number(template[0]?.lifetime ?? 0);
+
+  // The hourly chart covers the last 24 hours, so the page only needs events
+  // in that window — not the whole retained history. Bounded and small.
   const page = await querySqlEvents(db, {
     tenantId,
-    apiKeyIds: [...keyIds],
+    familyApiKeyId: templateKeyId,
+    since: windowStart,
     limit: MAX_FAMILY_EVENTS,
   });
   const events = page.events;
@@ -328,6 +358,15 @@ async function computeFamilyStatsBody(
     windowStart: windowStart.getTime(),
     allowed: allowedSet,
   });
+  rollup.totals = {
+    ...rollup.totals,
+    // The template counter is the seed on the running total, not a distinct
+    // bucket: daily/monthly windows are telemetry-only (the counter has no
+    // time axis), so those keep their own sums.
+    totalTokens: templateLifetime + totalTokens,
+    todayTokens,
+    monthTokens,
+  };
 
   // Fill the 24 buckets in JS: only hours that saw traffic are present, and
   // a chart drawn from sparse rows would silently compress the axis.

package/src/console/share/share-usage.ts

@@ -1,4 +1,4 @@
-import { and, eq, inArray } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import type { ApiKeyRecord } from "../../persistence/stores/api-key-store";
 import { CachedPreferencesReader, DrizzlePreferencesReader } from "../../persistence/tenant-preferences";
@@ -9,7 +9,7 @@ import { isGatewayError } from "../../observability/telemetry-status";
 import type { RedisClient } from "../../persistence/redis";
 import { cachedRead } from "../shared/read-through-cache";
 import { SHARE_STATS_CACHE_TTL_SECONDS } from "./share-stats";
-import { telemetryUsageTotals } from "../../persistence/schema";
+import { apiKeys, telemetryUsageTotals } from "../../persistence/schema";
 import { shouldMaskClientIp } from "../shared/ip-privacy";
 import { utcDayStart } from "../shared/day";
 
@@ -66,9 +66,16 @@ export interface SharedKeyActivityDetail {
 
 /** Read-only share-recipient telemetry; payloads and credential material never cross this boundary. */
 export interface ShareActivityPort {
+  /**
+   * `familyTemplateKeyId` is the share template the children were issued from:
+   * the telemetry reads scope to the whole family through it (an `EXISTS`
+   * against `api_keys`, constant-wire) rather than through an id list, so the
+   * read is the same no matter how many keys the template has minted.
+   */
   getSharedKeySummaries(
     tenantId: string,
     children: readonly ApiKeyRecord[],
+    familyTemplateKeyId: string,
   ): Promise<readonly SharedKeySummary[]>;
   getSharedKeyDetail(tenantId: string, childKeyId: string): Promise<SharedKeyActivityDetail>;
 }
@@ -133,15 +140,25 @@ export function createShareUsagePort(deps: ShareUsagePortDeps): ShareActivityPor
   const { db, redis } = deps;
   const preferences = new CachedPreferencesReader(new DrizzlePreferencesReader(db));
   return {
-    async getSharedKeySummaries(tenantId, children) {
+    async getSharedKeySummaries(tenantId, children, familyTemplateKeyId) {
       if (children.length === 0) return [];
-      const childIds = children.map((child) => child.id);
       const todayStart = utcDayStart(new Date());
+      /**
+       * Family membership of the entity the totals/events row is attributed to.
+       * Primary predicate is the denormalized template column (so history
+       * survives key deletion); the `EXISTS` fallback covers rows written
+       * before the column existed.
+       */
+      const familyMembership = (entityId: typeof apiKeys.id | typeof telemetryUsageTotals.entityId) =>
+        sql`(${telemetryUsageTotals.familyTemplateKeyId} = ${familyTemplateKeyId} or (${telemetryUsageTotals.familyTemplateKeyId} is null and exists (select 1 from ${apiKeys} where ${apiKeys.id} = ${entityId} and (${apiKeys.id} = ${familyTemplateKeyId} or ${apiKeys.parentKeyId} = ${familyTemplateKeyId}))))`;
       const [todayEvents, lifetimeRows, hideClientIp] = await Promise.all([
         // Today's per-key totals as one GROUP BY instead of reading every
         // event of the family. `addEventUsage` needs per-event fields, so the
-        // groups are projected into the same shape the loop consumes.
-        querySqlEvents(db, { tenantId, apiKeyIds: childIds, since: todayStart, limit: MAX_SUMMARY_EVENTS }).then(
+        // groups are projected into the same shape the loop consumes. The
+        // family filter is the template key, not an id list: a family with
+        // tens of thousands of minted children must not expand them into bind
+        // parameters on every dashboard poll.
+        querySqlEvents(db, { tenantId, familyApiKeyId: familyTemplateKeyId, since: todayStart, limit: MAX_SUMMARY_EVENTS }).then(
           (page) => page.events,
         ),
         db
@@ -158,7 +175,7 @@ export function createShareUsagePort(deps: ShareUsagePortDeps): ShareActivityPor
             and(
               eq(telemetryUsageTotals.tenantId, tenantId),
               eq(telemetryUsageTotals.identityType, "api_key"),
-              inArray(telemetryUsageTotals.entityId, childIds),
+              familyMembership(telemetryUsageTotals.entityId),
             ),
           ),
         shouldMaskClientIp(preferences, tenantId),

package/src/console/system-prompt/contracts.ts

@@ -0,0 +1,102 @@
+// Tenant system-prompt injection contracts.
+//
+// Shared by the console API, the persistence store, and the dispatch-path
+// transform — all Elysia-free so the dashboard bundle can import the types.
+
+/**
+ * One scope's prompt configuration. `enabled` is the master switch for the
+ * scope; `mode` decides how the text meets existing system content.
+ */
+export interface PromptSetting {
+  readonly enabled: boolean;
+  readonly mode: PromptMode;
+  readonly text: string;
+}
+
+export const PROMPT_MODES = ["append", "override"] as const;
+export type PromptMode = (typeof PROMPT_MODES)[number];
+
+/** Per-provider entry: follow the tenant's global prompt, or carry a custom one. */
+export interface ProviderPromptEntry {
+  readonly followGlobal: boolean;
+  /** Present and used only when `followGlobal` is false. */
+  readonly setting?: PromptSetting;
+}
+
+/** The full per-tenant configuration, one row in `tenant_system_prompts`. */
+export interface TenantSystemPrompts {
+  /** `null` = never configured — distinct from an explicit disabled setting. */
+  readonly global: PromptSetting | null;
+  /** providerId → entry */
+  readonly providers: Readonly<Record<string, ProviderPromptEntry>>;
+  /** `${providerId}::${modelId}` → setting */
+  readonly models: Readonly<Record<string, PromptSetting>>;
+}
+
+/** Empty configuration: nothing configured anywhere. */
+export const EMPTY_TENANT_SYSTEM_PROMPTS: TenantSystemPrompts = {
+  global: null,
+  providers: {},
+  models: {},
+};
+
+/** Maximum stored text per scope (5 MB). Enforced at the console API. */
+export const SYSTEM_PROMPT_TEXT_CAP_BYTES = 5_000_000;
+
+/**
+ * Marker wrapping tenant text injected into a provider wire whose upstream
+ * validates the system prompt as a channel identity (the buddy family). The
+ * fixed identity prompt stays the opener; the tenant text rides after it
+ * inside the same turn, framed so the provider's own parser is not confused.
+ */
+export const SYSTEM_PROMPT_WRAPPER_PREFIX = "<cartethyia:system-prompt>";
+export const SYSTEM_PROMPT_WRAPPER_SUFFIX = "</cartethyia:system-prompt>";
+
+/** Maximum number of per-provider entries stored for one tenant. */
+export const SYSTEM_PROMPT_PROVIDER_LIMIT = 256;
+
+/** Maximum number of per-model entries stored for one tenant. */
+export const SYSTEM_PROMPT_MODEL_LIMIT = 512;
+
+/**
+ * Providers whose upstream validates the fixed system prompt as a channel
+ * identity. Their system turn must keep the fixed prompt as the opener, so
+ * tenant text is appended after it inside the same turn, wrapped in the
+ * gateway's prefix/suffix markers (see `SYSTEM_PROMPT_WRAPPER_PREFIX`).
+ * `override` mode is not honoured for these providers — it would strip the
+ * identity and the upstream would refuse the request.
+ */
+export const WRAPPED_INJECTION_PROVIDERS: ReadonlySet<string> = new Set([
+  "cb", // CodeBuddy International
+  "cbcn", // CodeBuddy CN
+  "workbuddy",
+]);
+
+/** Whether a provider's tenant text rides wrapped after the fixed identity prompt. */
+export function isWrappedInjectionProvider(providerId: string): boolean {
+  return WRAPPED_INJECTION_PROVIDERS.has(providerId);
+}
+
+/** Model-scope key for the `models` map. */
+export function systemPromptModelKey(providerId: string, modelId: string): string {
+  return `${providerId}::${modelId}`;
+}
+
+/** Parses a model-scope key; null when the key is malformed. */
+export function parseSystemPromptModelKey(key: string): { providerId: string; modelId: string } | null {
+  const index = key.indexOf("::");
+  if (index <= 0 || index === key.length - 2) return null;
+  return { providerId: key.slice(0, index), modelId: key.slice(index + 2) };
+}
+
+/** True when the value is a well-formed prompt setting (shape only, not size). */
+export function isPromptSetting(value: unknown): value is PromptSetting {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<PromptSetting>;
+  return (
+    typeof candidate.enabled === "boolean" &&
+    typeof candidate.mode === "string" &&
+    (PROMPT_MODES as readonly string[]).includes(candidate.mode) &&
+    typeof candidate.text === "string"
+  );
+}