cartethyia 2.7.3 → 2.7.5

package/src/persistence/schema.ts

@@ -2,11 +2,25 @@
 import { desc, sql } from "drizzle-orm";
 import {
   bigint, boolean, check, customType, index, integer, jsonb, numeric, pgEnum, pgTable,
-  primaryKey, text, timestamp, uniqueIndex, uuid, type AnyPgColumn,
+  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),
@@ -188,15 +202,16 @@ export const providers = pgTable(
  *
  * 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").
+ * derives `machineToken`/`machineType`/`machineCode`. The daily 100-credit
+ * campaign does not gate grants on this identity. A persisted seed allows the
+ * vendor bridge to replay the same native identity where another Qoder surface
+ * requires it.
  *
  * `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.
+ * token). It is not a credential, but it is per-account device material and
+ * should not be shared between accounts. Campaign grant eligibility is
+ * independent of `machineToken`.
  */
 export interface NativeIdentityRecord {
   readonly machineToken: string;
@@ -294,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
@@ -341,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
@@ -380,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
@@ -422,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"),
     /**
@@ -434,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(
@@ -475,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(),
@@ -569,6 +599,47 @@ export const networkPools = pgTable("network_pools", {
   ],
 );
 
+/**
+ * A pool's account-equivalent routing entity for ip-scoped, credential-less
+ * providers (OpenCode Free today).
+ *
+ * These providers own no `provider_accounts` rows — the rate limit belongs to
+ * the egress address, not to a credential. Materializing one row per (pool,
+ * ip-scoped provider) lets the account health machine, routing eligibility, and
+ * the provider-detail accounts UI treat each egress like an account: the row
+ * carries the same health state machine and cooldown columns, so a spent egress
+ * is excluded from the plan the same way a cooling account is, and the operator
+ * sees it in the provider's Accounts card with a "Pool" badge.
+ *
+ * The row is an *account-equivalent*, not an account: it resolves no credential
+ * (`credential_kind` is fixed to `none`-style egress), is skipped by the quota
+ * refresh and identity sweeps (they filter on real credential kinds), and is
+ * owned by its pool — deleting the pool cascades the row.
+ */
+export const providerPoolAccounts = pgTable(
+  "provider_pool_accounts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    tenantId: tenantRefRequired(),
+    networkPoolId: uuid("network_pool_id")
+      .notNull()
+      .references(() => networkPools.id, { onDelete: "cascade" }),
+    providerId: text("provider_id").notNull(),
+    label: text("label").notNull(),
+    ...healthColumns(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    unique("provider_pool_accounts_pool_provider_uidx").on(
+      table.networkPoolId,
+      table.providerId,
+      table.tenantId,
+    ),
+    index("provider_pool_accounts_tenant_status_idx").on(table.tenantId, table.status),
+    index("provider_pool_accounts_provider_status_idx").on(table.providerId, table.status),
+  ],
+);
 
 // Account and network-pool health events share one table. The entity kind
 // selects exactly one owner FK, and the CHECK constraint below preserves
@@ -609,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`.
@@ -762,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];
 
@@ -776,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
@@ -814,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).
@@ -845,6 +936,21 @@ export const apiKeys = pgTable(
     createdAt: createdAtColumn(),
     enabled: boolean("enabled").notNull().default(true),
     revokedAt: timestamp("revoked_at", { withTimezone: true }),
+    /**
+     * Ban state. A ban is distinct from a revoke: it records the operator's
+     * reason (`banReason`) so the console can show it, and it is fully
+     * reversible — unban clears both columns, leaving no metadata behind.
+     * Banned keys are rejected by the auth path exactly like revoked keys.
+     */
+    bannedAt: timestamp("banned_at", { withTimezone: true }),
+    banReason: text("ban_reason"),
+    /**
+     * When the ban lifts on its own, if it is not permanent. `null` means the
+     * ban does not lapse (until an operator unbans it). The auth path treats a
+     * key as banned only while `banned_at` is set and `banned_until` is either
+     * null or in the future — so a timed ban expires without SQL.
+     */
+    bannedUntil: timestamp("banned_until", { withTimezone: true }),
     /**
      * The tenant's mandatory gateway key. Seeded at first boot whether or not
      * `CARTETHYIA_API_KEY` was configured, and the one key the console refuses
@@ -925,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
@@ -934,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",
   {
@@ -981,7 +1085,6 @@ export const shareLinks = pgTable(
   ],
 );
 
-
 /**
  * Console dashboard users — distinct from API-key tenants.
  */
@@ -1054,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(
@@ -1077,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 {
@@ -1173,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", {
@@ -1183,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(),
 });
 
@@ -1217,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
@@ -1247,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(
@@ -1265,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
@@ -1414,6 +1532,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
@@ -1455,7 +1589,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(
@@ -1494,7 +1628,6 @@ export const telemetryUsageTotals = pgTable(
   ],
 );
 
-
 export const telemetryPayloads = pgTable(
   "telemetry_payloads",
   {
@@ -1537,8 +1670,6 @@ export const telemetryPayloads = pgTable(
   ],
 );
 
-
-
 // Daily check-in ledger: one row per (account, calendar day) once the sweep has
 // attempted that account's claim.
 //
@@ -1551,7 +1682,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) => [
@@ -1559,7 +1692,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;