cartethyia 2.7.4 → 2.7.6

package/src/observability/telemetry-reconciliation.ts

@@ -66,13 +66,13 @@ const MAX_FILES_PER_RUN = 64;
  */
 const HOURS_TO_SKIP = 2;
 
-export interface ReconcileOptions {
+interface ReconcileOptions {
   /** Report only: count the gap without writing anything. */
   readonly verify?: boolean;
   readonly now?: Date;
 }
 
-export interface ReconcileReport {
+interface ReconcileReport {
   readonly ran: boolean;
   /** Why the run did nothing, when it did nothing. */
   readonly skippedReason?: "lease_held" | "no_files" | "uptodate";
@@ -393,7 +393,7 @@ async function insertChunk(
       .set({
         fileName,
         byteOffset,
-        filesCompleted: sql`${telemetryReconciliationState.filesCompleted} + 0`,
+        filesCompleted: sql`${telemetryReconciliationState.filesCompleted} + 1`,
         eventsExamined: sql`${telemetryReconciliationState.eventsExamined} + ${events.length}`,
         eventsInserted: sql`${telemetryReconciliationState.eventsInserted} + ${rows.length}`,
         conflicts: sql`${telemetryReconciliationState.conflicts} + ${events.length - rows.length}`,

package/src/observability/token-speed.ts

@@ -31,7 +31,7 @@
  * but those spans measure local response processing, not decode. Only a
  * client-visible stream window counts as decode time.
  */
-export interface TokenSpeedInput {
+interface TokenSpeedInput {
   /** Completion/output tokens reported for the request. */
   readonly outputTokens?: number | undefined;
   /** End-to-end gateway latency in milliseconds. */

package/src/persistence/connection-url.ts

@@ -23,7 +23,7 @@ export interface ConnectionUrlCandidate {
 }
 
 /** How one backing service's connection string is resolved. */
-export interface ConnectionUrlSpec {
+interface ConnectionUrlSpec {
   /** Accepted URL schemes, e.g. `postgres:` / `postgresql:`. */
   readonly schemes: readonly string[];
   /** URL variables, in resolution order. */

package/src/persistence/db-handle.ts

@@ -17,7 +17,7 @@ export const fullSchema = schema;
 export type CartethyiaDatabase = NodePgDatabase<typeof fullSchema>;
 
 /** Raw rows from a parameter query, without driver-specific decoration. */
-export interface QueryRows {
+interface QueryRows {
   readonly rows: unknown[];
 }
 

package/src/persistence/db-pg.ts

@@ -81,7 +81,7 @@ function databaseUrlFromLibpqEnv(): string | undefined {
   return `postgres://${credentials}${authorityHost}:${port}${path}`;
 }
 
-export function requireDatabaseUrl(): string {
+function requireDatabaseUrl(): string {
   return requireConnectionUrl({
     schemes: ["postgres:", "postgresql:"],
     candidates: databaseUrlCandidates(),
@@ -124,7 +124,7 @@ export function poolIdleFloorFromEnv(): number {
  * 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 {
+function startPoolShrinker(pool: Pool, floor: number): () => void {
   const interval = setInterval(() => {
     try {
       const idle = pool.idleCount;

package/src/persistence/db-sqlite.ts

@@ -326,7 +326,7 @@ const AUTH_KEY_COLUMNS = [
   "id", "tenant_id", "key_hash", "key_mode", "parent_key_id", "issued_client_ip",
   "issued_client_ip_key", "label", "scopes", "requests_per_minute", "daily_token_limit",
   "monthly_token_limit", "lifetime_token_budget", "lifetime_tokens_consumed",
-  "max_concurrent_requests", "model_access_mode", "model_list", "client_router_denylist",
+  "max_concurrent_requests", "concurrency_scope", "model_access_mode", "model_list", "client_router_denylist",
   "model_prefix", "created_at", "enabled", "revoked_at", "banned_at", "ban_reason", "banned_until",
   "key_prefix", "key_encrypted",
   "notes_title", "notes_subtitle", "notes_body", "is_default", "sort_index",
@@ -341,7 +341,7 @@ export interface SqliteAuthStatements {
   readonly childrenConsumed: { get: (parentId: string) => { total: number } | null };
 }
 
-export function prepareAuthStatements(sqlite: Database): SqliteAuthStatements {
+function prepareAuthStatements(sqlite: Database): SqliteAuthStatements {
   // A key is active while not revoked and not under an active ban: a ban is
   // active when `banned_at` is set and `banned_until` is null (permanent) or
   // still in the future. SQLite stores timestamps as ISO text, so the
@@ -507,7 +507,7 @@ function applyFilePragmas(db: Database): void {
 }
 
 /** The SQLite set lives beside the PostgreSQL one, never inside it. */
-export function resolveSqliteMigrationsFolder(): string {
+function resolveSqliteMigrationsFolder(): string {
   return resolvePackagePath("migrations", "lite-sqlite3");
 }
 

package/src/persistence/dialect.ts

@@ -143,7 +143,11 @@ export function affectedRows(result: unknown): number {
  * `.for()`, but a transaction there is already the write lock, so the query
  * runs as-is. The two builders disagree on `.for()`, so the call is typed at
  * the boundary instead of pushed into every store.
+ *
+ * The dialect is read from the query itself, not the process environment: a
+ * test may build a SQLite handle while the suite runs in full mode, and a
+ * PostgreSQL query always carries `.for` while a SQLite one never does.
  */
 export function lockRows<T>(query: T & { for?(mode: string): PromiseLike<unknown> }): PromiseLike<T extends PromiseLike<infer R> ? R : never> {
-  return (sqliteDialect() ? query : query.for!("update")) as PromiseLike<T extends PromiseLike<infer R> ? R : never>;
+  return (typeof query.for === "function" ? query.for!("update") : query) as PromiseLike<T extends PromiseLike<infer R> ? R : never>;
 }

package/src/persistence/readiness.ts

@@ -45,7 +45,7 @@ function sameMemoKey(left: ReadinessMemoKey, right: ReadinessMemoKey): boolean {
  * Returns typed ready/not_ready response.
  */
 
-export type ReadinessStatus = "ready" | "not_ready";
+type ReadinessStatus = "ready" | "not_ready";
 
 export interface ReadinessCheckResult {
   readonly status: ReadinessStatus;

package/src/persistence/redis.ts

@@ -92,7 +92,7 @@ export function resolveRedisBackend(client: RedisClient | undefined): RedisBacke
   return client === undefined ? "memory" : "redis";
 }
 
-export interface CloseRedisOptions {
+interface CloseRedisOptions {
   /** Bounded wait for `QUIT` before falling back to `disconnect()`. Defaults to 2s. */
   readonly quitTimeoutMs?: number;
 }

package/src/persistence/schema.ts

@@ -4,9 +4,23 @@ import {
   bigint, boolean, check, customType, index, integer, jsonb, numeric, pgEnum, pgTable,
   primaryKey, text, timestamp, unique, uniqueIndex, uuid, type AnyPgColumn,
 } from "drizzle-orm/pg-core";
+import type { ProviderQuotaResult } from "../providers/quota/quota-contracts";
 
-export const TENANT_STATUSES = ["active", "suspended", "deleted"] as const;
-export type TenantStatus = (typeof TENANT_STATUSES)[number];
+/**
+ * The persisted copy of one account's last successful quota read.
+ *
+ * Survives process restarts, which the in-process quota cache does not — so a
+ * cold page open can render the last known balance immediately while the sweep
+ * refreshes it. Stored only on success; a failed fetch leaves the previous
+ * snapshot in place.
+ */
+export interface ProviderQuotaResultSnapshot {
+  readonly quota: ProviderQuotaResult;
+  readonly fetchedAt: string;
+}
+
+const TENANT_STATUSES = ["active", "suspended", "deleted"] as const;
+type TenantStatus = (typeof TENANT_STATUSES)[number];
 
 export const tenants = pgTable(
   "tenants",
@@ -26,35 +40,35 @@ export const tenants = pgTable(
 
 // Canonical tenant/timestamp column definitions shared by every table.
 
-export function tenantRefNullable() {
+function tenantRefNullable() {
   return uuid("tenant_id").references(() => tenants.id, { onDelete: "cascade" });
 }
 
-export function tenantRefRequired() {
+function tenantRefRequired() {
   return uuid("tenant_id")
     .notNull()
     .references(() => tenants.id, { onDelete: "cascade" });
 }
 
-export function tenantRefPrimaryKey() {
+function tenantRefPrimaryKey() {
   return uuid("tenant_id")
     .primaryKey()
     .references(() => tenants.id, { onDelete: "cascade" });
 }
 
-export function tenantCascadeSetNull() {
+function tenantCascadeSetNull() {
   return uuid("tenant_id").references(() => tenants.id, { onDelete: "set null" });
 }
 
-export function createdAtColumn() {
+function createdAtColumn() {
   return timestamp("created_at", { withTimezone: true }).notNull().defaultNow();
 }
 
-export function updatedAtColumn() {
+function updatedAtColumn() {
   return timestamp("updated_at", { withTimezone: true }).notNull().defaultNow();
 }
 
-export function timestampColumns() {
+function timestampColumns() {
   return { createdAt: createdAtColumn(), updatedAt: updatedAtColumn() };
 }
 
@@ -90,7 +104,7 @@ export const healthStatus = pgEnum("health_status", ["active", "cooldown", "disa
  * One definition, because the two tables are driven by the same transitions and
  * a column added to one of them by hand is how they drift.
  */
-export function healthColumns() {
+function healthColumns() {
   return {
     status: healthStatus("status").notNull().default("active"),
     consecutiveFailures: integer("consecutive_failures").notNull().default(0),
@@ -295,6 +309,18 @@ export const providerAccounts = pgTable("provider_accounts", {
    * to an account that may well be refused.
    */
   quotaPlan: text("quota_plan"),
+  /**
+   * The last successful quota read for this account, as a JSON snapshot.
+   *
+   * Persisted rather than left only in the quota cache: that cache is a short
+   * in-process TTL and empty on a cold start, so right after a restart the
+   * console would show no balance for every account until the sweep re-read
+   * them. The row survives the restart, so a cold page open renders the last
+   * known numbers immediately (and the sweep refreshes them). Only a
+   * *successful* read is stored — a failed fetch leaves the previous snapshot
+   * in place, mirroring the plan column's behaviour.
+   */
+  quotaSnapshot: jsonb("quota_snapshot").$type<ProviderQuotaResultSnapshot | null>(),
 
   /**
    * Qoder native machine identity bound to this account, as one JSON object
@@ -342,7 +368,6 @@ export const providerAccounts = pgTable("provider_accounts", {
   ],
 );
 
-
 //  OAuth refresh token + cross-process lease, normalized out of
 // `provider_accounts` into its own 1:0/1 table. The vast majority of
 // provider accounts are `credentialKind: "api_key"`, for which these four
@@ -381,7 +406,6 @@ export const providerOauthStates = pgTable("provider_oauth_states", {
   leaseExpiresAt: timestamp("lease_expires_at", { withTimezone: true }),
 });
 
-
 // One row per (provider_id, model_id, route), with `endpoint_path`
 // identifying the route — the same model through two providers, or through
 // two routes of one provider, is two rows. `enabled` is a hard routing
@@ -423,7 +447,7 @@ export const models = pgTable(
      * that predicts access — `credits` and `vendor` were both measured against
      * real dispatches and neither correlates. Only the refusal itself is a
      * signal, so the answer has to be recorded. See
-     * `.skills/cartethyia-reverse-engineering/references/codebuddy-dispatch-headers.md`.
+     * `documentation/research/codebuddy/2026-10-19-codebuddy-chat-dispatch-headers.md`.
      */
     proOnly: boolean("pro_only"),
     /**
@@ -435,6 +459,12 @@ export const models = pgTable(
      * provider did not state it, which is not the same as billed.
      */
     freeTier: boolean("free_tier"),
+    /**
+     * Explicit wire dialect for this row (nullable). Absent = resolver
+     * fallback (heuristic + family default). See
+     * `src/protocol/translation/dialect/`.
+     */
+    dialect: text("dialect"),
   },
   (table) => [
     uniqueIndex("models_provider_model_route_uidx").on(
@@ -476,7 +506,6 @@ export const tenantDisabledModels = pgTable(
   ],
 );
 
-
 // Tenant-owned HTTP/HTTPS/SOCKS5 pools share the provider-account health state machine.
 export const networkPools = pgTable("network_pools", {
   id: uuid("id").primaryKey().defaultRandom(),
@@ -611,8 +640,6 @@ export const providerPoolAccounts = pgTable(
     index("provider_pool_accounts_provider_status_idx").on(table.providerId, table.status),
   ],
 );
-export type ProviderPoolAccount = typeof providerPoolAccounts.$inferSelect;
-
 
 // Account and network-pool health events share one table. The entity kind
 // selects exactly one owner FK, and the CHECK constraint below preserves
@@ -653,7 +680,6 @@ export const healthEvents = pgTable(
   ],
 );
 
-
 // Model aliasing & combos. Aliases resolve a client-facing name to a
 // real model; combos back a client-facing name with >=1 real models,
 // auto-selected via `fallback` or `round_robin`.
@@ -806,7 +832,6 @@ export const poolRoutingSettings = pgTable("pool_routing_settings", {
   rotateCount: integer("rotate_count").notNull().default(1),
 });
 
-
 export const API_KEY_MODES = ["personal", "share"] as const;
 export type ApiKeyMode = (typeof API_KEY_MODES)[number];
 
@@ -820,6 +845,10 @@ export type ApiKeyMode = (typeof API_KEY_MODES)[number];
 export const API_KEY_MODEL_ACCESS_MODES = ["whitelist", "blacklist"] as const;
 export type ApiKeyModelAccessMode = (typeof API_KEY_MODEL_ACCESS_MODES)[number];
 
+/** Share-template concurrency scope — see `apiKeys.concurrencyScope`. */
+export const API_KEY_CONCURRENCY_SCOPES = ["family", "per_key"] as const;
+export type ApiKeyConcurrencyScope = (typeof API_KEY_CONCURRENCY_SCOPES)[number];
+
 /**
  * Inbound `/v1/*` keys never store plaintext secrets. Personal keys carry an
  * authentication hash; share templates carry policy and child keys point back
@@ -858,6 +887,24 @@ export const apiKeys = pgTable(
       .notNull()
       .default(0),
     maxConcurrentRequests: integer("max_concurrent_requests"),
+    /**
+     * How `maxConcurrentRequests` applies to a share family:
+     *
+     * - `family` (default) — one cap across the whole family: every recipient
+     *   key shares the same admission counter and budget, so 20 means 20
+     *   concurrent requests across all children of the template.
+     * - `per_key` — each recipient key gets its own independent concurrent
+     *   window and cap. The cap is copied from the template to each child at
+     *   issue time (children carry their own `maxConcurrentRequests`), and a
+     *   child's admission identity is its own id, not the parent's.
+     *
+     * Only meaningful for `share` keys; personal keys always use their own
+     * per-key cap.
+     */
+    concurrencyScope: text("concurrency_scope")
+      .$type<ApiKeyConcurrencyScope>()
+      .notNull()
+      .default("family"),
     /**
      * Slot cap for a share template: the maximum number of concurrently
      * active child keys it may mint. `null` = unlimited (legacy behavior).
@@ -984,7 +1031,6 @@ export const sharePopups = pgTable(
   ],
 );
 
-
 // Public bearer links for enrolling one shared key per resolved client IP, and
 // for handing a personal key to its owner. The hash is the lookup key; the
 // token is additionally retained encrypted so the owner's console can show the
@@ -993,12 +1039,11 @@ export const sharePopups = pgTable(
  * Share-link kinds, as a runtime tuple. Route schemas and DTOs project this
  * list rather than restating it.
  */
-export const SHARE_LINK_KINDS = ["enroll", "handoff"] as const;
+const SHARE_LINK_KINDS = ["enroll", "handoff"] as const;
 
 /** One share-link kind. */
 export type ShareLinkKind = (typeof SHARE_LINK_KINDS)[number];
 
-
 export const shareLinks = pgTable(
   "share_links",
   {
@@ -1040,7 +1085,6 @@ export const shareLinks = pgTable(
   ],
 );
 
-
 /**
  * Console dashboard users — distinct from API-key tenants.
  */
@@ -1113,7 +1157,6 @@ export const consoleLockouts = pgTable(
   ],
 );
 
-
 // Configuration-change audit has its own retention lifecycle; it is separate
 // from metadata telemetry and short-lived optional payload capture.
 export const adminAuditLog = pgTable(
@@ -1136,7 +1179,6 @@ export const adminAuditLog = pgTable(
   ],
 );
 
-
 // Runtime preferences are stored in one validated JSONB bag. The filter
 // master toggle remains a typed column because it is read on the proxy path.
 export interface ConsoleSettingsPreferences {
@@ -1232,6 +1274,14 @@ export interface ConsoleSettingsPreferences {
    * the safer direction and the more common need.
    */
   imageClampMaxBytes?: number | null;
+  /**
+   * Ordered list of vision model ids (`provider/model`) used to describe
+   * images when the selected model is not image-capable. The first healthy
+   * model wins; if it fails (cooldown/quota/upstream error), the handoff
+   * falls through to the next entry. Empty/absent = legacy `[image]`
+   * placeholder behavior.
+   */
+  visionHandoffModels?: readonly string[];
 }
 
 export const consoleSettings = pgTable("console_settings", {
@@ -1242,21 +1292,33 @@ export const consoleSettings = pgTable("console_settings", {
 
 // 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.
+// disabled setting. Providers/models/combos/aliases are JSON object maps
+// keyed by providerId, `providerId::modelId`, combo name, and alias name
+// 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>(),
+  global: jsonb("global").$type<import("../console/system-prompt/contracts").ScopePromptRef | null>(),
+  presets: jsonb("presets")
+    .notNull()
+    .default({})
+    .$type<Record<string, import("../console/system-prompt/contracts").SystemPromptPreset>>(),
   providers: jsonb("providers")
     .notNull()
     .default({})
-    .$type<Record<string, import("../console/system-prompt/contracts").ProviderPromptEntry>>(),
+    .$type<Record<string, import("../console/system-prompt/contracts").ScopePromptRef>>(),
   models: jsonb("models")
     .notNull()
     .default({})
-    .$type<Record<string, import("../console/system-prompt/contracts").PromptSetting>>(),
+    .$type<Record<string, import("../console/system-prompt/contracts").ScopePromptRef>>(),
+  combos: jsonb("combos")
+    .notNull()
+    .default({})
+    .$type<Record<string, import("../console/system-prompt/contracts").ScopePromptRef>>(),
+  aliases: jsonb("aliases")
+    .notNull()
+    .default({})
+    .$type<Record<string, import("../console/system-prompt/contracts").ScopePromptRef>>(),
   updatedAt: updatedAtColumn(),
 });
 
@@ -1276,7 +1338,6 @@ export const inferhubConfigKeys = pgTable("inferhub_config_keys", {
   updatedAt: updatedAtColumn(),
 });
 
-
 // CLI Tools (CLI tool configuration): per-tenant mapping table that lets a coding-agent
 // slot (e.g. Claude Code's "opus" slot) target a specific Cartethyia model. Rows
 // are opaque strings — validation happens at the API boundary against the
@@ -1306,7 +1367,6 @@ export const cliToolMappings = pgTable(
   ],
 );
 
-
 // Per-(tenant, tool, api_key) settings: whether mappings are active and which
 // mode the tool is configured for. Primary key is the composite of all three.
 export const cliToolSettings = pgTable(
@@ -1324,7 +1384,6 @@ export const cliToolSettings = pgTable(
   (table) => [primaryKey({ columns: [table.tenantId, table.toolId, table.apiKeyId] })],
 );
 
-
 // Metadata-only request telemetry. Retention is configured independently of
 // payload capture (`CARTETHYIA_TELEMETRY_RETENTION_DAYS`, default 30 days).
 // No prompt text, raw body, API key, encrypted-reasoning payload, or generic
@@ -1424,6 +1483,14 @@ export const telemetryEvents = pgTable(
      * tell "not configured" from "broken".
      */
     payloadCaptureState: text("payload_capture_state"),
+    /**
+     * Set for a completed request whose output is far smaller than what the
+     * model can produce AND which the model ended with an ordinary `stop`
+     * (a "degenerate stop"). Introduced to measure how often a model
+     * truncates itself on a cached prefix — the pattern that surfaced as
+     * short, cut-off chat replies. NULL/unset for everything else.
+     */
+    degenerateStop: boolean("degenerate_stop"),
   },
   (table) => [
     index("telemetry_events_created_at_idx").on(table.createdAt),
@@ -1473,6 +1540,22 @@ export const telemetryEvents = pgTable(
       table.accountId,
       table.createdAt,
     ),
+    // Provider usage matrix + `breakdownTelemetry("provider")`: equality on
+    // `provider_id`, range+aggregate on `created_at`. Was served by the
+    // tenant-range index, which scanned every event in the window for one
+    // provider's card.
+    index("telemetry_events_tenant_provider_created_idx").on(
+      table.tenantId,
+      table.providerId,
+      table.createdAt,
+    ),
+    // `breakdownTelemetry("model")` (top-model lists): equality on
+    // `requested_model`, range+aggregate on `created_at`.
+    index("telemetry_events_tenant_model_created_idx").on(
+      table.tenantId,
+      table.requestedModel,
+      table.createdAt,
+    ),
     /**
      * Serves the public share page's per-key aggregate (`share-usage.ts`):
      * equality on `api_key_id`, range and aggregate on `created_at`. Without
@@ -1514,7 +1597,7 @@ export const telemetryReconciliationState = pgTable(
 );
 
 /** Durable aggregates retained after metadata telemetry expires. */
-export const TELEMETRY_USAGE_IDENTITY_TYPES = ["account", "api_key"] as const;
+const TELEMETRY_USAGE_IDENTITY_TYPES = ["account", "api_key"] as const;
 export type TelemetryUsageIdentityType = (typeof TELEMETRY_USAGE_IDENTITY_TYPES)[number];
 
 export const telemetryUsageTotals = pgTable(
@@ -1553,7 +1636,6 @@ export const telemetryUsageTotals = pgTable(
   ],
 );
 
-
 export const telemetryPayloads = pgTable(
   "telemetry_payloads",
   {
@@ -1596,8 +1678,6 @@ export const telemetryPayloads = pgTable(
   ],
 );
 
-
-
 // Daily check-in ledger: one row per (account, calendar day) once the sweep has
 // attempted that account's claim.
 //
@@ -1610,7 +1690,9 @@ export const dailyCheckinLedger = pgTable(
   "daily_checkin_ledger",
   {
     dayKey: text("day_key").notNull(),
-    accountId: uuid("account_id").notNull(),
+    accountId: uuid("account_id")
+      .notNull()
+      .references(() => providerAccounts.id, { onDelete: "cascade" }),
     claimedAt: timestamp("claimed_at", { withTimezone: true }).notNull().defaultNow(),
   },
   (table) => [
@@ -1618,7 +1700,6 @@ export const dailyCheckinLedger = pgTable(
   ],
 );
 
-
 /**
  * Per-day, per-model credit deductions the buddy billing meter reported.
  *

package/src/persistence/shared-cache.ts

@@ -33,7 +33,7 @@ const INVALIDATION_CHANNEL = "cartethyia:cache:invalidate";
  * collide, and so a `FLUSHDB`-free deploy can drop one namespace without
  * touching another.
  */
-export type SharedCacheNamespace = "auth" | "preferences" | "credential" | "routing" | "public-models";
+type SharedCacheNamespace = "auth" | "preferences" | "credential" | "routing" | "public-models";
 
 const NAMESPACE_PREFIX: Readonly<Record<SharedCacheNamespace, string>> = {
   auth: "cartethyia:cache:auth:",
@@ -50,7 +50,7 @@ const NAMESPACE_PREFIX: Readonly<Record<SharedCacheNamespace, string>> = {
 };
 
 /** One notice that peers must drop an entry. */
-export interface InvalidationNotice {
+interface InvalidationNotice {
   readonly namespace: SharedCacheNamespace;
   /** Omitted means "all keys in the namespace". */
   readonly key?: string;

package/src/persistence/sort-order.ts

@@ -27,7 +27,7 @@ export type SortOrderDb =
  * `idColumn`/`sortIndexColumn`, and every caller passes its own schema-typed
  * table plus the two columns.
  */
-export interface SortOrderTable {
+interface SortOrderTable {
   readonly table: PgTable;
   readonly idColumn: AnyColumn;
   readonly sortIndexColumn: AnyColumn;

package/src/persistence/stores/api-key-store.ts

@@ -1,11 +1,11 @@
 // Persisted API-key store: the console API-key domain and gateway authentication both consume this boundary.
 
-import { and, asc, count, desc, eq, inArray, isNotNull, isNull, lte, or, sql, type SQL } from "drizzle-orm";
+import { and, asc, count, desc, eq, gt, inArray, isNotNull, isNull, lte, or, sql, type SQL } from "drizzle-orm";
 import { nextSortIndex, reorderSortIndex, type SortOrderDb } from "../sort-order";
 import { getDbHandle } from "../boot";
 import type { CartethyiaDatabase } from "../db-handle";
 import { lockRows } from "../dialect";
-import { apiKeys, shareLinks, sharePopups, telemetryUsageTotals, type ApiKeyMode, type ApiKeyModelAccessMode } from "../schema";
+import { apiKeys, shareLinks, sharePopups, telemetryUsageTotals, type ApiKeyMode, type ApiKeyModelAccessMode, type ApiKeyConcurrencyScope } from "../schema";
 import type { AccessScope } from "../../security/access-control";
 
 /** Sortable columns for the paged share-child listing (api_keys columns only). */
@@ -78,6 +78,7 @@ export interface ApiKeyRecord {
   readonly monthlyTokenLimit?: number;
   readonly lifetimeTokenBudget?: number;
   readonly maxConcurrentRequests?: number;
+  readonly concurrencyScope?: ApiKeyConcurrencyScope;
   /** Share-template recipient slot cap; undefined = unlimited. */
   readonly maxChildren?: number;
   readonly modelPrefix?: string;
@@ -252,6 +253,8 @@ async function writeSharePopup(
 /** Explicit persistence boundary. Production must provide this; there is no fallback store. */
 export interface ApiKeyStore {
   list(tenantId: string): Promise<readonly ApiKeyRecord[]>;
+  /** Active, non-revoked bans for one tenant, including share children. */
+  listActiveBanned(tenantId: string): Promise<readonly ApiKeyRecord[]>;
   get(tenantId: string, keyId: string): Promise<ApiKeyRecord | undefined>;
   listChildren(tenantId: string, parentKeyId: string): Promise<readonly ApiKeyRecord[]>;
   revokeChildrenByScope(
@@ -344,6 +347,9 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       ...(row.maxConcurrentRequests === null
         ? {}
         : { maxConcurrentRequests: row.maxConcurrentRequests }),
+      ...(row.concurrencyScope
+        ? { concurrencyScope: row.concurrencyScope as ApiKeyConcurrencyScope }
+        : {}),
       ...(row.maxChildren === null ? {} : { maxChildren: row.maxChildren }),
       ...(row.modelPrefix === null ? {} : { modelPrefix: row.modelPrefix }),
       modelAccessMode: row.modelAccessMode,
@@ -378,6 +384,22 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       .limit(1000);
     return this.withPopups(this.db, rows);
   }
+  async listActiveBanned(tenantId: string): Promise<readonly ApiKeyRecord[]> {
+    const now = new Date();
+    const rows = await this.db
+      .select()
+      .from(apiKeys)
+      .where(
+        and(
+          eq(apiKeys.tenantId, tenantId),
+          isNotNull(apiKeys.bannedAt),
+          isNull(apiKeys.revokedAt),
+          or(isNull(apiKeys.bannedUntil), gt(apiKeys.bannedUntil, now)),
+        ),
+      )
+      .orderBy(desc(apiKeys.bannedAt), apiKeys.id);
+    return rows.map((row) => this.map(row));
+  }
 
   /** Rewrites the list order for one tenant; `keyIds` is the full order. */
   async reorder(tenantId: string, keyIds: readonly string[]): Promise<void> {
@@ -547,6 +569,7 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       monthlyTokenLimit: record.monthlyTokenLimit ?? null,
       lifetimeTokenBudget: record.lifetimeTokenBudget ?? null,
       maxConcurrentRequests: record.maxConcurrentRequests ?? null,
+      concurrencyScope: record.concurrencyScope ?? "family",
       maxChildren: record.maxChildren ?? null,
       modelPrefix: record.modelPrefix ?? null,
       modelAccessMode: record.modelAccessMode ?? "whitelist",
@@ -615,6 +638,9 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
           ...(patch.maxConcurrentRequests !== undefined
             ? { maxConcurrentRequests: patch.maxConcurrentRequests }
             : {}),
+          ...(patch.concurrencyScope !== undefined
+            ? { concurrencyScope: patch.concurrencyScope }
+            : {}),
           ...(patch.maxChildren !== undefined ? { maxChildren: patch.maxChildren } : {}),
           ...(patch.modelPrefix !== undefined ? { modelPrefix: patch.modelPrefix } : {}),
           ...(patch.modelAccessMode !== undefined ? { modelAccessMode: patch.modelAccessMode } : {}),
@@ -802,6 +828,7 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       lifetimeTokenBudget: integer("lifetime_token_budget"),
       lifetimeTokensConsumed: integer("lifetime_tokens_consumed") ?? 0,
       maxConcurrentRequests: integer("max_concurrent_requests"),
+      concurrencyScope: (text("concurrency_scope") ?? "family") as ApiKeyConcurrencyScope,
       modelAccessMode: (text("model_access_mode") ?? "whitelist") as ApiKeyModelAccessMode,
       modelList: json("model_list"),
       clientRouterDenylist: json("client_router_denylist"),