cartethyia 2.7.2 → 2.7.3

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

@@ -0,0 +1,165 @@
+// Console API for tenant system-prompt injection.
+//
+// GET    /system-prompt → the stored configuration
+// PUT    /system-prompt → replace the configuration wholesale
+// DELETE /system-prompt → clear it entirely
+//
+// The PUT replaces the row: the modal edits the whole three-scope shape at
+// once, so a PATCH surface would add states the UI never produces. Text is
+// capped at 5 MB per scope and the provider/model maps are bounded, matching
+// the store's own defensive limits.
+import { Elysia, t } from "elysia";
+import type { ConsoleAccessResolver } from "../auth/access";
+import { ConsoleDomainError, consoleErrorHandler, requireTenantScope } from "../shared/errors";
+import type { AuditSink } from "../audit/contracts";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import {
+  clearTenantSystemPrompts,
+  readTenantSystemPrompts,
+  writeTenantSystemPrompts,
+} from "../../persistence/system-prompt-store";
+import {
+  EMPTY_TENANT_SYSTEM_PROMPTS,
+  PROMPT_MODES,
+  SYSTEM_PROMPT_MODEL_LIMIT,
+  SYSTEM_PROMPT_PROVIDER_LIMIT,
+  SYSTEM_PROMPT_TEXT_CAP_BYTES,
+  isPromptSetting,
+  parseSystemPromptModelKey,
+  type PromptSetting,
+  type ProviderPromptEntry,
+  type TenantSystemPrompts,
+} from "./contracts";
+
+/** Route-group context injected by the composition root. */
+export interface SystemPromptRoutesConfig {
+  readonly db: CartethyiaDatabase;
+  readonly accessResolver: ConsoleAccessResolver;
+  readonly auditSink?: AuditSink;
+}
+
+/** Validates one scope setting, including the 5 MB text cap. */
+function validateSetting(value: unknown, scopeLabel: string): PromptSetting {
+  if (!isPromptSetting(value)) {
+    throw new ConsoleDomainError("invalid_request", 400, `${scopeLabel} is not a valid prompt setting`);
+  }
+  const bytes = Buffer.byteLength(value.text, "utf8");
+  if (bytes > SYSTEM_PROMPT_TEXT_CAP_BYTES) {
+    throw new ConsoleDomainError("payload_too_large", 413, `${scopeLabel} exceeds the 5 MB limit`);
+  }
+  if (!(PROMPT_MODES as readonly string[]).includes(value.mode)) {
+    throw new ConsoleDomainError("invalid_request", 400, `${scopeLabel} has an invalid mode`);
+  }
+  return value;
+}
+
+/** Validates the full PUT body into the stored shape. */
+function validateBody(value: unknown): TenantSystemPrompts {
+  if (typeof value !== "object" || value === null) {
+    throw new ConsoleDomainError("invalid_request", 400, "Body must be an object");
+  }
+  const body = value as {
+    global?: unknown;
+    providers?: unknown;
+    models?: unknown;
+  };
+
+  const global =
+    body.global === null || body.global === undefined
+      ? null
+      : validateSetting(body.global, "global");
+
+  if (body.providers !== undefined && typeof body.providers !== "object") {
+    throw new ConsoleDomainError("invalid_request", 400, "providers must be an object");
+  }
+  const rawProviders = (body.providers ?? {}) as Record<string, unknown>;
+  const providerIds = Object.keys(rawProviders);
+  if (providerIds.length > SYSTEM_PROMPT_PROVIDER_LIMIT) {
+    throw new ConsoleDomainError(
+      "invalid_request",
+      400,
+      `providers exceeds the ${SYSTEM_PROMPT_PROVIDER_LIMIT} entry limit`,
+    );
+  }
+  const providers: Record<string, ProviderPromptEntry> = {};
+  for (const providerId of providerIds) {
+    const entry = rawProviders[providerId];
+    if (typeof entry !== "object" || entry === null) {
+      throw new ConsoleDomainError("invalid_request", 400, `provider ${providerId} entry must be an object`);
+    }
+    const candidate = entry as Partial<ProviderPromptEntry>;
+    if (typeof candidate.followGlobal !== "boolean") {
+      throw new ConsoleDomainError("invalid_request", 400, `provider ${providerId} needs followGlobal`);
+    }
+    if (candidate.followGlobal) {
+      providers[providerId] = { followGlobal: true };
+    } else {
+      providers[providerId] = {
+        followGlobal: false,
+        setting: validateSetting(candidate.setting, `provider ${providerId}`),
+      };
+    }
+  }
+
+  if (body.models !== undefined && typeof body.models !== "object") {
+    throw new ConsoleDomainError("invalid_request", 400, "models must be an object");
+  }
+  const rawModels = (body.models ?? {}) as Record<string, unknown>;
+  const modelKeys = Object.keys(rawModels);
+  if (modelKeys.length > SYSTEM_PROMPT_MODEL_LIMIT) {
+    throw new ConsoleDomainError(
+      "invalid_request",
+      400,
+      `models exceeds the ${SYSTEM_PROMPT_MODEL_LIMIT} entry limit`,
+    );
+  }
+  const models: Record<string, PromptSetting> = {};
+  for (const key of modelKeys) {
+    if (parseSystemPromptModelKey(key) === null) {
+      throw new ConsoleDomainError("invalid_request", 400, `model key ${key} is malformed`);
+    }
+    models[key] = validateSetting(rawModels[key], `model ${key}`);
+  }
+
+  return { global, providers, models };
+}
+
+/**
+ * The return type is inferred rather than annotated as `Elysia`: `.error()`
+ * widens the instance type with its handler's response envelope, so the
+ * annotated base type no longer matches the chained result (same reason the
+ * remote-support routes leave it inferred).
+ */
+export function createSystemPromptRoutes(config: SystemPromptRoutesConfig) {
+  return new Elysia()
+    .error(consoleErrorHandler("System prompt settings failed"))
+    .get("/system-prompt", async ({ request }) => {
+      const access = requireTenantScope(config.accessResolver(request), "dashboard:read");
+      return await readTenantSystemPrompts(config.db, access.tenantId);
+    })
+    .put(
+      "/system-prompt",
+      { body: t.Any() },
+      async ({ request, body }) => {
+        const access = requireTenantScope(config.accessResolver(request), "dashboard:write");
+        const next = validateBody(body);
+        await writeTenantSystemPrompts(config.db, access.tenantId, next);
+        await config.auditSink?.record({
+          access,
+          action: "system_prompt.update",
+          target: "tenant_system_prompts",
+          detail: {
+            global: next.global !== null,
+            providers: Object.keys(next.providers).length,
+            models: Object.keys(next.models).length,
+          },
+        });
+        return next;
+      },
+    )
+    .delete("/system-prompt", async ({ request }) => {
+      const access = requireTenantScope(config.accessResolver(request), "dashboard:write");
+      await clearTenantSystemPrompts(config.db, access.tenantId);
+      return EMPTY_TENANT_SYSTEM_PROMPTS;
+    });
+}

package/src/main.ts

@@ -169,6 +169,17 @@ if (boot) {
     globalThis.__cartethyiaSignalsRegistered = true;
     process.on("SIGINT", () => shutdown("SIGINT"));
     process.on("SIGTERM", () => shutdown("SIGTERM"));
+    // A rejected promise nothing awaited (a sweep, a cache warm, a read whose
+    // parameters a bug elsewhere ballooned) must not kill the listener: the
+    // default is fatal exit, which turned one query fault into a systemd
+    // restart loop. Logged and absorbed — the failure stays visible, the
+    // process stays up.
+    process.on("unhandledRejection", (reason) => {
+      log.error(
+        "[process] unhandled rejection (kept alive)",
+        reason instanceof Error ? reason : new Error(String(reason)),
+      );
+    });
     // An in-place update signals SIGUSR2 before swapping the image so the old
     // process drains with the `update` reason and its callers are told the
     // replacement is seconds away instead of seeing a generic shutdown. Not

package/src/observability/event-query.ts

@@ -17,9 +17,9 @@
  *   latency arrays are never returned to JavaScript;
  * - `isGatewayError()` semantics live in one shared SQL predicate.
  */
-import { and, desc, eq, gte, inArray, isNotNull, sql } from "drizzle-orm";
+import { and, desc, eq, gte, inArray, isNotNull, or, sql, type SQL } from "drizzle-orm";
 import type { CartethyiaDatabase } from "../persistence/db-handle";
-import { telemetryEvents } from "../persistence/schema";
+import { apiKeys, telemetryEvents } from "../persistence/schema";
 import type { TelemetryEventRecord } from "./event-log";
 import { gatewayErrorSql } from "./telemetry-status";
 
@@ -52,6 +52,17 @@ export interface EventListQuery {
   readonly until?: Date;
   readonly apiKeyIds?: readonly string[];
   readonly accountIds?: readonly string[];
+  /**
+   * The share-template key whose family (the template itself plus every child
+   * key it issued) scopes the read. Rendered as an `EXISTS` subquery against
+   * `api_keys` rather than an id list: a family is minted by the tenant and
+   * can grow to whatever size the tenant drives it to, so enumerating its ids
+   * in JavaScript to feed a bind list would scale the query's wire size with
+   * the family instead of with the result. The subquery keeps the same
+   * membership semantics — template id or any child of it — for any family
+   * size.
+   */
+  readonly familyApiKeyId?: string;
   readonly requestId?: string;
   /** Several request ids at once — the backup restore's "already present" check. */
   readonly requestIds?: readonly string[];
@@ -231,6 +242,94 @@ function scoped(tenantId: string, since?: Date) {
   return since === undefined ? tenant : and(tenant, gte(telemetryEvents.createdAt, since));
 }
 
+/**
+ * Thrown when a membership filter outruns the guard below. This is a handled
+ * query error, not a protocol fault: callers surface it as a request failure
+ * instead of crashing the process with a PostgreSQL wire error that systemd
+ * would only restart into.
+ */
+export class TelemetryQueryInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TelemetryQueryInputError";
+  }
+}
+
+/**
+ * The deduplicated id count a list membership filter accepts before refusing.
+ *
+ * `idMembershipFilter` binds the whole set as one array parameter, so even a
+ * six-figure set is wire-safe; this guard is not a protocol necessity but a
+ * runaway-collector tripwire — a bug elsewhere (an unbounded accumulator, a
+ * vanished scope) must fail as a query error instead of materializing an
+ * unbounded parameter. Families larger than this must use the `familyApiKeyId`
+ * filter, which never materializes ids.
+ */
+const MAX_MEMBERSHIP_IDS = 200_000;
+
+/**
+ * The chunk size for the SQLite rendering of a list membership filter.
+ *
+ * SQLite has no array parameters, so the set has to come back as individual
+ * placeholders; 500 per chunk sits far below every build's
+ * SQLITE_MAX_VARIABLE_NUMBER while keeping the OR of chunks — semantically
+ * the identical membership test — to a handful of clauses for realistic sets.
+ */
+const SQLITE_IDS_PER_CHUNK = 500;
+
+/**
+ * Membership of `column` in a caller-supplied id set, safe at any set size.
+ *
+ * Expanding the members into one bind placeholder each breaks the wire twice
+ * over: PostgreSQL caps a Bind message at 65,535 parameters, and node-postgres
+ * miscounts long placeholder lists anyway (`08P01 bind message has N parameter
+ * formats but 0 parameters` — the shape that crash-looped the dev deployment,
+ * whose share family carried ~90k minted child keys). Instead the set is
+ * deduplicated and handed to the server as a single array parameter
+ * (`= ANY(…::uuid[])`), or, on SQLite, to chunks of individual placeholders;
+ * membership semantics are unchanged in both renderings.
+ */
+function idMembershipFilter(
+  db: CartethyiaDatabase,
+  column: typeof telemetryEvents.apiKeyId | typeof telemetryEvents.accountId | typeof telemetryEvents.requestId,
+  values: readonly string[],
+  cast: "uuid[]" | "text[]",
+): SQL {
+  const unique = [...new Set(values)];
+  if (unique.length > MAX_MEMBERSHIP_IDS) {
+    throw new TelemetryQueryInputError(
+      `telemetry filter exceeds ${MAX_MEMBERSHIP_IDS} distinct ids (got ${unique.length}); scope the read by family or tenant instead`,
+    );
+  }
+  if (unique.length === 0) return sql`false`;
+  if (isPostgres(db)) {
+    return sql`${column} = ANY(${unique}::${sql.raw(cast)})`;
+  }
+  if (unique.length <= SQLITE_IDS_PER_CHUNK) return inArray(column, unique);
+  const chunks: SQL[] = [];
+  for (let start = 0; start < unique.length; start += SQLITE_IDS_PER_CHUNK) {
+    chunks.push(inArray(column, unique.slice(start, start + SQLITE_IDS_PER_CHUNK)));
+  }
+  return or(...chunks) as SQL;
+}
+
+/**
+ * Membership of `api_key_id` in the family of one share template — the
+ * template itself plus every key it issued.
+ *
+ * The primary predicate is the denormalized `family_template_key_id` column:
+ * an event is in the family when it was stamped with the template at write
+ * time. That makes the read independent of the key row surviving — a revoked
+ * or removed key keeps its history. Events written before the column existed
+ * (or whose key was hard-deleted before the backfill) fall back to an
+ * `EXISTS` against `api_keys`, so the migration window is still counted when
+ * the key row is present. The tenant predicate is carried by every read
+ * already, so a child in another tenant still cannot match.
+ */
+function familyKeyCondition(templateKeyId: string): SQL {
+  return sql`(${telemetryEvents.familyTemplateKeyId} = ${templateKeyId} or (${telemetryEvents.familyTemplateKeyId} is null and exists (select 1 from ${apiKeys} where ${apiKeys.id} = ${telemetryEvents.apiKeyId} and (${apiKeys.id} = ${templateKeyId} or ${apiKeys.parentKeyId} = ${templateKeyId}))))`;
+}
+
 /**
  * Bounded detail/list read — the only place rows are materialized.
  *
@@ -249,16 +348,19 @@ export async function queryTelemetryEvents(
     conditions.push(sql`${telemetryEvents.createdAt} < ${query.until}`);
   }
   if (query.apiKeyIds !== undefined) {
-    conditions.push(inArray(telemetryEvents.apiKeyId, [...query.apiKeyIds]));
+    conditions.push(idMembershipFilter(db, telemetryEvents.apiKeyId, query.apiKeyIds, "uuid[]"));
+  }
+  if (query.familyApiKeyId !== undefined) {
+    conditions.push(familyKeyCondition(query.familyApiKeyId));
   }
   if (query.accountIds !== undefined) {
-    conditions.push(inArray(telemetryEvents.accountId, [...query.accountIds]));
+    conditions.push(idMembershipFilter(db, telemetryEvents.accountId, query.accountIds, "uuid[]"));
   }
   if (query.requestId !== undefined) {
     conditions.push(eq(telemetryEvents.requestId, query.requestId));
   }
   if (query.requestIds !== undefined) {
-    conditions.push(inArray(telemetryEvents.requestId, [...query.requestIds]));
+    conditions.push(idMembershipFilter(db, telemetryEvents.requestId, query.requestIds, "text[]"));
   }
   if (query.id !== undefined) {
     conditions.push(eq(telemetryEvents.id, query.id));
@@ -638,14 +740,23 @@ export async function healthTelemetry(
 export async function sumTelemetryTokens(
   db: CartethyiaDatabase,
   tenantId: string,
-  filters: { readonly apiKeyIds?: readonly string[]; readonly since: Date; readonly until?: Date },
+  filters: {
+    readonly apiKeyIds?: readonly string[];
+    /** The share-template family filter; see {@link EventListQuery.familyApiKeyId}. */
+    readonly familyKeyId?: string;
+    readonly since: Date;
+    readonly until?: Date;
+  },
 ): Promise<number> {
   const conditions = [scoped(tenantId, filters.since)];
   if (filters.until !== undefined) {
     conditions.push(sql`${telemetryEvents.createdAt} < ${filters.until}`);
   }
   if (filters.apiKeyIds !== undefined && filters.apiKeyIds.length > 0) {
-    conditions.push(inArray(telemetryEvents.apiKeyId, [...filters.apiKeyIds]));
+    conditions.push(idMembershipFilter(db, telemetryEvents.apiKeyId, filters.apiKeyIds, "uuid[]"));
+  }
+  if (filters.familyKeyId !== undefined) {
+    conditions.push(familyKeyCondition(filters.familyKeyId));
   }
   const [row] = await db
     .select({

package/src/persistence/db-pg.ts

@@ -108,6 +108,44 @@ export function poolMaxFromEnv(): number {
   return value;
 }
 
+/** Target number of idle connections the pool shrinks to (default 2). */
+export function poolIdleFloorFromEnv(): number {
+  const raw = process.env.DATABASE_POOL_IDLE_FLOOR ?? "2";
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`DATABASE_POOL_IDLE_FLOOR must be a non-negative integer (got "${raw}")`);
+  }
+  return value;
+}
+
+/**
+ * Periodically closes idle clients above the floor so a low-traffic process
+ * does not hold `DATABASE_POOL_MAX` backends open for nothing. node-postgres
+ * only closes an idle client after `idleTimeoutMillis` (60s here); this gives
+ * the pool a faster, explicit shrink path while still keeping the floor warm.
+ */
+export function startPoolShrinker(pool: Pool, floor: number): () => void {
+  const interval = setInterval(() => {
+    try {
+      const idle = pool.idleCount;
+      const excess = idle - floor;
+      if (excess <= 0) return;
+      // Close the excess idle clients in order; `release(true)` destroys the
+      // client instead of returning it to the pool.
+      for (let index = 0; index < excess; index += 1) {
+        pool
+          .connect()
+          .then((client) => client.release(true))
+          .catch(() => undefined);
+      }
+    } catch {
+      // The pool is best-effort; a failed shrink must never crash a request.
+    }
+  }, 30_000);
+  interval.unref();
+  return () => clearInterval(interval);
+}
+
 declare global {
   // eslint-disable-next-line no-var -- globalThis augmentation requires `var`
   var __cartethyiaPool: Pool | undefined;
@@ -147,6 +185,10 @@ export function getPool(): Pool {
   pool.on("error", (err) => {
     log.error("[postgres] pool error (idle client)", err);
   });
+  // Idle-floor shrinker: keeps the pool warm at the floor instead of parking
+  // a full `max` worth of backends. Tied to the pool's lifetime, so a hot
+  // reload that replaces the pool re-registers it.
+  startPoolShrinker(pool, poolIdleFloorFromEnv());
   globalThis.__cartethyiaPool = pool;
   return pool;
 }

package/src/persistence/schema.ts

@@ -183,6 +183,31 @@ export const providers = pgTable(
 // tenant-owned/BYOK. The concurrency ceiling lives in provider routing
 // (`provider_routing_settings.max_inflight`) and network pools
 // (`network_pools.max_inflight`); there is no per-account override.
+/**
+ * A Qoder native machine identity (UMID) bound to one account.
+ *
+ * The device identity is a deterministic function of a seed file
+ * (`~/.config/.locale_cfg`): the `runtime-info` bridge reads that seed and
+ * derives `machineToken`/`machineType`/`machineCode`. The server gates the
+ * daily 100-credit campaign on a *genuine, non-VM* device identity, so each
+ * account gets its own minted seed (a distinct "device").
+ *
+ * `seed` is the exact seed-file content the identity was minted from, stored
+ * so the same device identity can be replayed (restore seed → bridge → same
+ * token). It is not a credential, but it is the per-account device material
+ * and must never be shared between accounts. `machineToken` is the unique
+ * device key: two accounts sharing a token are the same device to the server.
+ */
+export interface NativeIdentityRecord {
+  readonly machineToken: string;
+  readonly machineType: string;
+  readonly machineCode: string;
+  /** The seed-file content this identity was minted from, if captured. */
+  readonly seed?: string;
+  /** How this identity was produced: the genuine SG bridge or the fallback. */
+  readonly source?: "runtime-info" | "generated";
+}
+
 export const providerAccounts = pgTable("provider_accounts", {
   id: uuid("id").primaryKey().defaultRandom(),
   providerId: text("provider_id")
@@ -270,6 +295,18 @@ export const providerAccounts = pgTable("provider_accounts", {
    */
   quotaPlan: text("quota_plan"),
 
+  /**
+   * Qoder native machine identity bound to this account, as one JSON object
+   * (see {@link NativeIdentityRecord}). `null` means the account has no bound
+   * identity: the check-in mints one on first use.
+   *
+   * Deliberately a dedicated column, not a key inside `auth_state`: the
+   * device token is queryable ("which device is taken by whom") and enforced
+   * unique by the partial index below, and it must survive backup/restore
+   * like any other non-secret column.
+   */
+  nativeIdentity: jsonb("native_identity").$type<NativeIdentityRecord | null>(),
+
   },
   (table) => [
     uniqueIndex("provider_accounts_identity_uidx").on(
@@ -290,6 +327,17 @@ export const providerAccounts = pgTable("provider_accounts", {
     // predicate that does not constrain `provider_id`. This one matches the
     // hot listing path.
     index("provider_accounts_tenant_id_idx").on(table.tenantId),
+    // One Qoder device identity per account: the partial unique index on the
+    // extracted `machineToken` guarantees two accounts never share a device,
+    // which is what makes the daily 100-credit grant reusable per account
+    // instead of colliding on a device identity. `NULL` rows (unbound
+    // accounts) are excluded so the uniqueness only applies to bound
+    // identities. The Postgres migration spells the expression
+    // `(native_identity ->> 'machineToken')`; the SQLite migration spells it
+    // `json_extract(native_identity, '$.machineToken')`.
+    uniqueIndex("provider_accounts_native_identity_token_uidx")
+      .on(sql`(${table.nativeIdentity} ->> 'machineToken')`)
+      .where(sql`${table.nativeIdentity} IS NOT NULL`),
   ],
 );
 
@@ -766,6 +814,13 @@ export const apiKeys = pgTable(
       .notNull()
       .default(0),
     maxConcurrentRequests: integer("max_concurrent_requests"),
+    /**
+     * Slot cap for a share template: the maximum number of concurrently
+     * active child keys it may mint. `null` = unlimited (legacy behavior).
+     * Enforced at mint time in `issueSharedApiKey`; the console exposes it as
+     * the template's "slots".
+     */
+    maxChildren: integer("max_children"),
     /**
      * `whitelist` = only the names in `modelList` may be used (empty = all);
      * `blacklist` = the names in `modelList` are refused (empty = none). One
@@ -1126,6 +1181,26 @@ export const consoleSettings = pgTable("console_settings", {
   updatedAt: updatedAtColumn(),
 });
 
+// Tenant-scoped system prompt injection (append/override). One row per
+// tenant; `global` NULL means never configured, distinct from an explicit
+// disabled setting. Providers/models are JSON object maps keyed by
+// providerId and `providerId::modelId` respectively — see
+// `src/console/system-prompt/contracts.ts` for the value shapes and the
+// resolution rules implemented by the dispatch-path transform.
+export const tenantSystemPrompts = pgTable("tenant_system_prompts", {
+  tenantId: tenantRefPrimaryKey(),
+  global: jsonb("global").$type<import("../console/system-prompt/contracts").PromptSetting | null>(),
+  providers: jsonb("providers")
+    .notNull()
+    .default({})
+    .$type<Record<string, import("../console/system-prompt/contracts").ProviderPromptEntry>>(),
+  models: jsonb("models")
+    .notNull()
+    .default({})
+    .$type<Record<string, import("../console/system-prompt/contracts").PromptSetting>>(),
+  updatedAt: updatedAtColumn(),
+});
+
 // InferHub `config_read` key. One row for the whole deployment.
 //
 // Deliberately NOT `provider_accounts.auth_state`: that field is documented as
@@ -1229,6 +1304,14 @@ export const telemetryEvents = pgTable(
     networkPoolId: uuid("network_pool_id"),
     endpoint: text("endpoint"),
     apiKeyId: uuid("api_key_id"),
+    /**
+     * The share-template key this event belongs to (the template itself, or
+     * the parent of the child key that carried the request). Denormalized at
+     * write time so family rollups survive the key row being deleted — an
+     * `EXISTS` join against `api_keys` tied history to key lifetime. NULL for
+     * requests that ran under no share template.
+     */
+    familyTemplateKeyId: uuid("family_template_key_id"),
     userAgent: text("user_agent"),
     clientIp: text("client_ip"),
     latencyMs: integer("latency_ms"),
@@ -1317,6 +1400,14 @@ export const telemetryEvents = pgTable(
       desc(table.createdAt),
       desc(table.id),
     ),
+    // Share-family rollup: equality on the denormalized template, keyset
+    // range+order. Backs both the family totals and the hourly chart reads.
+    index("telemetry_events_tenant_family_created_id_idx").on(
+      table.tenantId,
+      table.familyTemplateKeyId,
+      desc(table.createdAt),
+      desc(table.id),
+    ),
     index("telemetry_events_request_id_idx").on(table.requestId),
     index("telemetry_events_tenant_account_created_idx").on(
       table.tenantId,
@@ -1373,6 +1464,13 @@ export const telemetryUsageTotals = pgTable(
     tenantId: tenantRefRequired(),
     identityType: text("identity_type").$type<TelemetryUsageIdentityType>().notNull(),
     entityId: uuid("entity_id").notNull(),
+    /**
+     * For `api_key` identities, the share-template key this key belongs to
+     * (the template itself, or the parent of a minted child). Denormalized so
+     * family reads do not depend on the key row surviving; NULL for `account`
+     * identities and for keys outside a share family.
+     */
+    familyTemplateKeyId: uuid("family_template_key_id"),
     requests: bigint("requests", { mode: "number" }).notNull().default(0),
     errors: bigint("errors", { mode: "number" }).notNull().default(0),
     inputTokens: bigint("input_tokens", { mode: "number" }).notNull().default(0),
@@ -1389,6 +1487,10 @@ export const telemetryUsageTotals = pgTable(
       "telemetry_usage_totals_identity_type_check",
       sql`${table.identityType} IN ('account', 'api_key')`,
     ),
+    index("telemetry_usage_totals_tenant_family_idx").on(
+      table.tenantId,
+      table.familyTemplateKeyId,
+    ),
   ],
 );