cartethyia 2.6.7 → 2.7.1

package/src/console/providers/catalog/store.ts

@@ -1,1563 +1,1292 @@
-// Drizzle-backed provider, account, model, routing, and API-key repositories.
-import { and, asc, eq, inArray, isNull, or, sql, type SQL } from "drizzle-orm";
-import { ConsoleDomainError } from "../../shared/errors";
-import { parseCustomProviderId, isBundledProviderId } from "../../../providers/provider-contracts";
-import {
-  asRecord,
-  firstNonEmptyString as firstString,
-  tryParseJson as safeParseJson,
-} from "../../../shared/coerce";
-import type { ModelDefinition } from "../../../providers/provider-model-definition";
-import type { ProviderRegistry } from "../../../providers/provider-registry";
-import { BUNDLED_PROVIDER_MODULES } from "../../../providers/default-registry";
-import { modelsDevCatalog } from "../../../providers/discovery/models-dev-catalog";
-import { globalOrOwnedBy, ownedByOnly } from "../../../persistence/tenant-scope";
-import { nextSortIndex, reorderSortIndex } from "../../../persistence/sort-order";
-import type { CartethyiaDatabase } from "../../../persistence/db-handle";
-import { buddyTaskLedger, models, providerAccounts, providerOauthStates, providers, telemetryUsageTotals, tenantDisabledModels } from "../../../persistence/schema";
-import { breakdownTelemetry } from "../../../observability/event-query";
-import type { WireFamily } from "../../../protocol/canonical-model";
-import { listAccountHealthEvents, recoverAccount, deleteAccountHealthEvents, type AccountHealthEventRecord } from "../../../providers/operations/account-health-service";
-import { invalidateCredentialCache } from "../../../providers/operations/provider-credential-service";
-import { encryptCredential, hashSecret } from "../../../security/crypto";
-import type { TelemetryBatchBuffer } from "../../../observability/telemetry-buffer";
-import { bumpCatalogRevision, type BundledProviderCatalog } from "../../../providers/operations/provider-catalog-service";
-import type { AccountInflightReading, BuddyGrowthTaskLedgerEntry, ByokConnectionTestRequest, ByokConnectionTestResult, CreateProviderAccountBatchItemResult, CreateProviderAccountBatchResult, CreateProviderAccountRequest, CredentialMode, ModelCatalogEntry, ProbeAllAccountsResult, ProbeAllModelsResult, ProbeModelRequest, ProbeModelResult, ProviderAccountResponse, ProviderAccountTokenUsage, ProviderCatalogStore, ProviderRecord, SetModelEnabledRequest, UpdateModelMetadataRequest, UpdateProviderAccountRequest, ModelMetadataOverride } from "./contracts";
-import { isServiceKind, validateCompatibilityProfile } from "./contracts";
-import { ProviderProbingService, type ProbeOutboundResolver } from "../../../providers/discovery/probing-service";
-import {
-  applyModelMetadataOverride,
-  FALLBACK_CONTEXT_LIMIT,
-  FALLBACK_OUTPUT_LIMIT,
-  resolveManualModelMetadata,
-} from "../../../providers/provider-model-definition";
-import { isUniqueViolation } from "../../../persistence/boot";
-import { DEFAULT_ENDPOINT_BY_WIRE_FAMILY, endpointPathForProviderModel, mapProviderRow } from "./catalog-projections";
-import { pushStructuredConsoleLog } from "../../../observability/log-ring";
-import { decodeJwtPayload } from "../../../providers/authentication/oauth-flow-store";
-
-/** Real Drizzle-backed provider and model catalog repository. */
-
-/** Field names a pasted OAuth credential may carry its access token under. */
-const OAUTH_ACCESS_FIELDS = ["accessToken", "access_token", "access", "token"] as const;
-/** Field names a pasted OAuth credential may carry its refresh token under. */
-const OAUTH_REFRESH_FIELDS = ["refreshToken", "refresh_token", "refresh"] as const;
-
-/** Parses an expiry field that may be an ISO string, an epoch ms, or epoch seconds. */
-function parseExpiry(value: unknown): Date | undefined {
-  if (typeof value === "number" && Number.isFinite(value)) {
-    // Heuristic: a 10-digit value is epoch seconds, a 13-digit value is ms.
-    const ms = value < 1e12 ? value * 1000 : value;
-    const date = new Date(ms);
-    return Number.isFinite(date.getTime()) ? date : undefined;
-  }
-  if (typeof value === "string" && value.trim().length > 0) {
-    const asNumber = Number(value);
-    if (Number.isFinite(asNumber)) return parseExpiry(asNumber);
-    const date = new Date(value);
-    return Number.isFinite(date.getTime()) ? date : undefined;
-  }
-  return undefined;
-}
-/**
- * Reads the two claims a static token's own payload can answer: when it stops
- * working, and who issued it.
- *
- * The issuer is kept because a static JWT carries no other hint of its origin:
- * an operator who pasted one from the wrong surface has nothing in the console
- * to check it against, and several issuers accept the same token shape.
- */
-function parseJwtCredential(
-  raw: string,
-): { readonly expiresAt?: Date; readonly issuer?: string } | undefined {
-  const payload = decodeJwtPayload(raw.trim());
-  if (payload === undefined) return undefined;
-  const expiresAt = parseExpiry(payload["exp"]);
-  const iss = payload["iss"];
-  const issuer = typeof iss === "string" && iss.trim().length > 0 ? iss.trim() : undefined;
-  return {
-    ...(expiresAt === undefined ? {} : { expiresAt }),
-    ...(issuer === undefined ? {} : { issuer }),
-  };
-}
-
-/**
- * Splits a pasted OAuth credential into its access token, refresh token, and
- * expiry.
- *
- * The console accepts either a bare access token or the JSON export a client
- * produces (`{accessToken, refreshToken, expiresAt, …}`, possibly nested under
- * `data`). A bare token has no refresh token — the account can be dispatched
- * with it but cannot be refreshed, so the caller stores it as a static
- * API credential instead of sending the access token to a refresh endpoint.
- */
-/**
- * Middle segment of an auto-generated account label, from how the credential
- * was actually detected.
- *
- * Only the two kinds that arrive with no name of their own are named here. An
- * OAuth paste carries its own identity in `authState` (the account it was
- * exported from), so it keeps whatever the export or the operator supplied —
- * generating a name for it would overwrite an identity that was already there.
- * An unrecognized mode falls back to `key`, matching the mode it is stored as.
- */
-export function accountLabelKindSegment(credentialMode: CredentialMode): string {
-  return credentialMode === "jwt" ? "jwt" : "key";
-}
-
-/**
- * First unused `dcint-key-N` / `dcint-jwt-N` label for one provider.
- *
- * Polished tokens and plain JWTs are the credentials that arrive nameless: an
- * operator pastes several into one provider and every row came out as
- * "<providerId> account", so five accounts were five identical labels and the
- * list could not tell them apart — which account failed, or is cooling, was
- * unreadable.
- *
- * Numbering runs per kind, so the first JWT is `jwt-1` rather than inheriting
- * whatever number the api_key rows reached (`jwt-3` with no `jwt-1` reads as
- * two missing accounts). Counting is case-insensitive on the whole label, so a
- * hand-typed `DCINT-KEY-2` still reserves its number.
- *
- * Pure, so the numbering can be pinned without a database.
- */
-export function nextGeneratedAccountLabel(
-  providerId: string,
-  credentialMode: CredentialMode,
-  existingLabels: readonly string[],
-): string {
-  const kind = accountLabelKindSegment(credentialMode);
-  const prefix = `${providerId}-${kind}-`;
-  const taken = new Set(
-    existingLabels.map((label) => label.trim().toLowerCase()),
-  );
-  for (let n = 1; ; n += 1) {
-    const candidate = `${prefix}${n}`;
-    if (!taken.has(candidate.toLowerCase())) return candidate;
-  }
-}
-
-export function parsePastedOAuthCredential(raw: string): {
-  readonly accessToken: string;
-  readonly refreshToken: string;
-  readonly expiresAt: Date | undefined;
-  /**
-   * Non-secret account configuration the export carried — the profile the
-   * account is bound to, how it authenticates, the region it was minted in.
-   * Empty for a bare token, which carries none.
-   */
-  readonly authState: Readonly<Record<string, unknown>>;
-} {
-  let record: Record<string, unknown> | undefined;
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-      record = parsed as Record<string, unknown>;
-    }
-  } catch {
-    record = undefined;
-  }
-  if (record === undefined) {
-    // Bare token: it is the access token, and there is no refresh token.
-    const jwt = parseJwtCredential(raw);
-    return {
-      accessToken: raw,
-      refreshToken: raw,
-      expiresAt: jwt?.expiresAt,
-      authState: {},
-    };
-  }
-  // A nested `data` object is unwrapped the same way the dashboard's parser does.
-  const nested =
-    record["data"] !== null && typeof record["data"] === "object" && !Array.isArray(record["data"])
-      ? (record["data"] as Record<string, unknown>)
-      : undefined;
-  const accessToken =
-    firstString(record, OAUTH_ACCESS_FIELDS) ??
-    (nested ? firstString(nested, OAUTH_ACCESS_FIELDS) : undefined) ??
-    raw;
-  const refreshToken =
-    firstString(record, OAUTH_REFRESH_FIELDS) ??
-    (nested ? firstString(nested, OAUTH_REFRESH_FIELDS) : undefined) ??
-    accessToken;
-  const expiresAt =
-    parseExpiry(
-      record["expiresAt"] ??
-        record["expires_at"] ??
-        (nested ? (nested["expiresAt"] ?? nested["expires_at"]) : undefined) ??
-        record["expires"] ??
-        (nested ? nested["expires"] : undefined),
-    ) ?? parseJwtCredential(accessToken)?.expiresAt;
-  return { accessToken, refreshToken, expiresAt, authState: pastedAuthState(record, nested) };
-}
-
-/**
- * The account configuration a pasted export carries beside its tokens.
- *
- * Kiro refuses a generation request that omits the profile the account is bound
- * to, and exports from older installs carry that profile under a different key.
- * Reading neither is how an imported account probes with no
- * profile and is answered `400 profileArn is required`.
- */
-function pastedAuthState(
-  record: Record<string, unknown>,
-  nested: Record<string, unknown> | undefined,
-): Readonly<Record<string, unknown>> {
-  const sources = [record, nested, asRecord(record["providerSpecificData"]), asRecord(record["authState"]), asRecord(nested?.["authState"])];
-  const profileArn = firstStringFrom(sources, ["profileArn", "profile_arn"]);
-  const authMethod = firstStringFrom(sources, ["authMethod", "auth_method"]);
-  const region = firstStringFrom(sources, ["region"]);
-  return {
-    ...(profileArn === undefined ? {} : { profileArn }),
-    ...(authMethod === undefined ? {} : { authMethod }),
-    ...(region === undefined ? {} : { region }),
-  };
-}
-
-/**
- * Adds or removes the `image` input modality on a stored modalities blob.
- *
- * The blob is a JSON string whose shape varies by source (bundled seed,
- * discovery, manual add), so it is normalized rather than pattern-matched: an
- * unparseable blob is replaced with the minimal text shape rather than left to
- * corrupt capability preflight.
- */
-export function withImageModality(stored: string | null | undefined, image: boolean): string {
-  const parsed = asRecord(safeParseJson(stored));
-  const input = Array.isArray(parsed?.input)
-    ? (parsed.input as unknown[]).filter((m): m is string => typeof m === "string")
-    : ["text"];
-  const output = Array.isArray(parsed?.output)
-    ? (parsed.output as unknown[]).filter((m): m is string => typeof m === "string")
-    : ["text"];
-  const nextInput = image
-    ? Array.from(new Set([...input, "image"]))
-    : input.filter((m) => m !== "image");
-  return JSON.stringify({
-    ...(parsed ?? {}),
-    input: nextInput.length > 0 ? nextInput : ["text"],
-    output: output.length > 0 ? output : ["text"],
-  });
-}
-
-/** Normalizes a text column read as `unknown` back to a string or null. */
-function asStoredText(value: unknown): string | null {
-  return typeof value === "string" ? value : null;
-}
-
-function firstStringFrom(
-  sources: readonly (Record<string, unknown> | undefined)[],
-  fields: readonly string[],
-): string | undefined {
-  for (const source of sources) {
-    if (source === undefined) continue;
-    const value = firstString(source, fields);
-    if (value !== undefined) return value;
-  }
-  return undefined;
-}
-
-/**
- * The account's still-active per-model backoffs, or `undefined` when none are.
- *
- * Expired entries are dropped rather than returned: the sweep that clears them
- * runs on a timer, so between the deadline passing and the sweep a raw read
- * would report a cooldown that is not in force.
- */
-function liveModelCooldowns(
-  raw: unknown,
-): { modelCooldowns: Record<string, string> } | undefined {
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-  const now = Date.now();
-  const live: Record<string, string> = {};
-  for (const [modelId, value] of Object.entries(raw as Record<string, unknown>)) {
-    if (typeof value !== "string") continue;
-    const at = new Date(value).getTime();
-    if (Number.isFinite(at) && at > now) live[modelId] = value;
-  }
-  return Object.keys(live).length > 0 ? { modelCooldowns: live } : undefined;
-}
-
-
-/**
- * Projects one persisted `models` row into the console's catalog entry.
- *
- * `disabled` is resolved by the caller (from `tenant_disabled_models`), because
- * the bulk read has to look it up across every provider at once while the
- * single-provider read looks it up for one; the projection itself is identical
- * either way, so it lives here rather than being written twice.
- *
- * Exported so a test can pin the unsized-model substitution without a database:
- * which rows get the fallback, and that they are the same rows marked estimated.
- */
-export function mapModelRow(
-  row: typeof models.$inferSelect,
-  disabled: boolean,
-): ModelCatalogEntry {
-  const modalities =
-    row.modalities && typeof row.modalities === "object"
-      ? (row.modalities as { input?: unknown; output?: unknown })
-      : undefined;
-  const inputModalities = Array.isArray(modalities?.input) ? modalities.input : [];
-  const outputModalities = Array.isArray(modalities?.output) ? modalities.output : [];
-  // Nothing filed this model — not its own row, not the base catalog under this
-  // provider's id, not a majority across the catalog's other resellers. The
-  // fallback is substituted here rather than persisted: the stored `null` is the
-  // honest record of what upstream said, and substituting at the write would
-  // make a guess indistinguishable from a measurement on the next read. The
-  // marker rides along so the card can say which one it is showing.
-  const unfiled =
-    row.contextLimit === null &&
-    modelsDevCatalog.resolve(row.providerId, row.modelId) === undefined &&
-    modelsDevCatalog.majorityFor(row.modelId) === undefined;
-  return {
-    modelId: row.modelId,
-    route: row.endpointPath,
-    provider: row.providerId,
-    wireFamily: row.wireFamily,
-    serviceKind: row.serviceKind,
-    enabled: disabled ? false : row.enabled,
-    // A fetched model that published no context size read `n/a ctx · n/a out`
-    // while still being routable — a working model that looked unusable. These
-    // rows get the same ceilings a manual add is offered, flagged as estimated.
-    contextLimit: unfiled ? FALLBACK_CONTEXT_LIMIT : row.contextLimit,
-    outputLimit: unfiled ? FALLBACK_OUTPUT_LIMIT : row.outputLimit,
-    reasoning: row.reasoning,
-    toolCall: row.toolCall,
-    vision: inputModalities.includes("image"),
-    document: inputModalities.includes("document"),
-    audio: inputModalities.includes("audio"),
-    mediaGeneration: outputModalities.includes("image"),
-    cost: row.cost as ModelCatalogEntry["cost"],
-    source: row.source,
-    ...(unfiled ? { limitsEstimated: true } : {}),
-    // Three-valued on the wire as it is in the column: only a row that claims
-    // `true` is pro-only. Absence means nobody established the tier, and the
-    // surface must render that as unknown rather than as free.
-    ...(row.proOnly === true ? { proOnly: true } : {}),
-    // Same three-valued rule, from the provider's own directory. Qoder states
-    // `is_free` per row, so a plan change moves the pill without a code change.
-    ...(row.freeTier === true ? { freeTier: true } : {}),
-    sourceUpdatedAt: row.sourceUpdatedAt?.toISOString() ?? null,
-  } satisfies ModelCatalogEntry;
-}
-
-export class DrizzleProviderCatalogStore implements ProviderCatalogStore {
-  private readonly probing: ProviderProbingService;
-  private readonly bundledModelCatalog: ReadonlyMap<string, readonly ModelDefinition[]>;
-  private readonly providerRegistry: ProviderRegistry;
-
-  private readonly readAccountInflight:
-    | ((
-        providerId: string,
-        tenantId: string,
-      ) => Promise<readonly AccountInflightReading[]>)
-    | undefined;
-
-  constructor(
-    private readonly db: CartethyiaDatabase,
-    options: {
-      readonly telemetryBuffer: TelemetryBatchBuffer;
-      readonly bundledModelCatalog: BundledProviderCatalog;
-      readonly providerRegistry: ProviderRegistry;
-      readonly outboundFetchFor: ProbeOutboundResolver;
-      readonly snapshotInvalidator: { invalidate(): unknown };
-      readonly readAccountInflight?:
-        | ((
-            providerId: string,
-            tenantId: string,
-          ) => Promise<readonly AccountInflightReading[]>)
-        | undefined;
-    },
-  ) {
-    this.bundledModelCatalog = options.bundledModelCatalog.modelsByProvider;
-    this.providerRegistry = options.providerRegistry;
-    this.readAccountInflight = options.readAccountInflight;
-    this.probing = new ProviderProbingService({
-      db,
-      telemetryBuffer: options.telemetryBuffer,
-      defaultEndpoints: DEFAULT_ENDPOINT_BY_WIRE_FAMILY,
-      bundledModelCatalog: this.bundledModelCatalog,
-      outboundFetchFor: options.outboundFetchFor,
-      snapshotInvalidator: options.snapshotInvalidator,
-      providerRegistry: options.providerRegistry,
-    });
-  }
-  async list(tenantId: string): Promise<readonly ProviderRecord[]> {
-    const bundledIds = BUNDLED_PROVIDER_MODULES.map((provider) => provider.id);
-    const rows = await this.db
-      .select()
-      .from(providers)
-      .where(
-        and(
-          globalOrOwnedBy(providers.tenantId, tenantId),
-          or(inArray(providers.id, bundledIds), eq(providers.tenantId, tenantId)),
-        ),
-      )
-      .orderBy(asc(providers.id));
-    return rows.map((row) => mapProviderRow(row, this.providerRegistry));
-  }
-  async get(tenantId: string, providerId: string): Promise<ProviderRecord | undefined> {
-    const rows = await this.db
-      .select()
-      .from(providers)
-      .where(
-        and(
-          eq(providers.id, providerId),
-          globalOrOwnedBy(providers.tenantId, tenantId),
-        ),
-      )
-      .limit(1);
-    const row = rows[0];
-    return row ? mapProviderRow(row, this.providerRegistry) : undefined;
-  }
-  async create(record: ProviderRecord): Promise<void> {
-    if (isBundledProviderId(record.providerId))
-      throw new ConsoleDomainError(
-        "provider_is_builtin",
-        403,
-        "Built-in provider cannot be created",
-      );
-    parseCustomProviderId(record.providerId);
-    if (record.compatibilityProfile) validateCompatibilityProfile(record.compatibilityProfile);
-    await this.db.insert(providers).values({
-      id: record.providerId,
-      tenantId: record.tenantId ?? null,
-      enabled: record.enabled,
-      ...(record.wireFamilyDefault ? { wireFamilyDefault: record.wireFamilyDefault } : {}),
-      capabilityProfile: record.capabilityProfile ?? null,
-      baseUrl: record.baseUrl ?? null,
-      compatibilityProfile: record.compatibilityProfile ?? null,
-    });
-  }
-  async update(
-    tenantId: string,
-    providerId: string,
-    patch: Partial<ProviderRecord>,
-  ): Promise<ProviderRecord | undefined> {
-    if (isBundledProviderId(providerId))
-      throw new ConsoleDomainError(
-        "provider_is_builtin",
-        403,
-        "Built-in provider cannot be updated",
-      );
-    if (patch.compatibilityProfile) validateCompatibilityProfile(patch.compatibilityProfile);
-    const set: Partial<typeof providers.$inferInsert> = {};
-    if (patch.enabled !== undefined) set.enabled = patch.enabled;
-    if (patch.capabilityProfile !== undefined) set.capabilityProfile = patch.capabilityProfile;
-    if (patch.baseUrl !== undefined) set.baseUrl = patch.baseUrl;
-    if (patch.compatibilityProfile !== undefined)
-      set.compatibilityProfile = patch.compatibilityProfile;
-    const rows =
-      Object.keys(set).length > 0
-        ? await this.db
-            .update(providers)
-            .set(set)
-            .where(
-              and(
-                eq(providers.id, providerId),
-                ownedByOnly(providers.tenantId, tenantId),
-              ),
-            )
-            .returning()
-        : await this.db
-            .select()
-            .from(providers)
-            .where(
-              and(
-                eq(providers.id, providerId),
-                ownedByOnly(providers.tenantId, tenantId),
-              ),
-            );
-    const row = rows[0];
-    return row ? mapProviderRow(row, this.providerRegistry) : undefined;
-  }
-  async delete(tenantId: string, providerId: string): Promise<boolean> {
-    if (isBundledProviderId(providerId))
-      throw new ConsoleDomainError(
-        "provider_is_builtin",
-        403,
-        "Built-in provider cannot be deleted",
-      );
-    // Custom-provider rows own their models, accounts, disabled-model flags,
-    // and routing preferences: deleting the parent cascades all of them
-    // (models/provider_accounts/provider_oauth_states via provider FK,
-    // health_events via account FK, tenant_disabled_models and
-    // provider_routing_settings via provider FK) in one atomic DELETE.
-    const deleted = await this.db
-      .delete(providers)
-      .where(and(eq(providers.id, providerId), ownedByOnly(providers.tenantId, tenantId)))
-      .returning({ id: providers.id });
-    if (deleted.length === 0) return false;
-    this.providerRegistry.unregister(providerId);
-    // The provider left the registry, so the compiled catalog is now missing it
-    // — the snapshot's re-seed is gated on that revision, and a delete that did
-    // not bump it would leave the provider's model rows behind.
-    bumpCatalogRevision();
-    return true;
-  }
-  async updateGlobal(
-    providerId: string,
-    patch: Partial<ProviderRecord>,
-  ): Promise<ProviderRecord | undefined> {
-    const isBuiltin = isBundledProviderId(providerId);
-    if (isBuiltin && Object.keys(patch).some((field) => field !== "enabled")) {
-      throw new ConsoleDomainError(
-        "provider_is_builtin",
-        403,
-        "Built-in providers only support enable/disable",
-      );
-    }
-    if (patch.compatibilityProfile) validateCompatibilityProfile(patch.compatibilityProfile);
-    const set: Partial<typeof providers.$inferInsert> = {};
-    if (patch.enabled !== undefined) set.enabled = patch.enabled;
-    if (patch.capabilityProfile !== undefined) set.capabilityProfile = patch.capabilityProfile;
-    if (patch.baseUrl !== undefined) set.baseUrl = patch.baseUrl;
-    if (patch.compatibilityProfile !== undefined) {
-      set.compatibilityProfile = patch.compatibilityProfile;
-    }
-    const rows =
-      Object.keys(set).length > 0
-        ? await this.db
-            .update(providers)
-            .set(set)
-            .where(and(eq(providers.id, providerId), isNull(providers.tenantId)))
-            .returning()
-        : await this.db
-            .select()
-            .from(providers)
-            .where(and(eq(providers.id, providerId), isNull(providers.tenantId)));
-    const row = rows[0];
-    return row ? mapProviderRow(row, this.providerRegistry) : undefined;
-  }
-
-  async deleteGlobal(providerId: string): Promise<boolean> {
-    if (isBundledProviderId(providerId)) {
-      throw new ConsoleDomainError(
-        "provider_is_builtin",
-        403,
-        "Built-in provider cannot be deleted",
-      );
-    }
-    const rows = await this.db
-      .delete(providers)
-      .where(and(eq(providers.id, providerId), isNull(providers.tenantId)))
-      .returning({ id: providers.id });
-    return rows.length > 0;
-  }
-  async listModels(tenantId: string, providerId: string): Promise<readonly ModelCatalogEntry[]> {
-    const byProvider = await this.listModelsForTenant(tenantId, providerId);
-    return byProvider.get(providerId) ?? [];
-  }
-
-  /**
-   * Every enabled-and-disabled model row the tenant can see, grouped by
-   * provider. One pair of statements for the whole tenant instead of a pair per
-   * provider.
-   *
-   * The per-provider `listModels` shape costs two queries per call, so a caller
-   * that needs every provider's models — the flat catalog the picker renders —
-   * issued `2 * providers + 2` statements, growing with the bundled catalog.
-   * Grouping here makes it constant: one disabled-model read and one models
-   * join, regardless of provider count. `providerId` narrows it to a single
-   * provider for callers that already know which one they want.
-   */
-  async listModelsForTenant(
-    tenantId: string,
-    providerId?: string,
-  ): Promise<Map<string, readonly ModelCatalogEntry[]>> {
-    const disabled = await this.db
-      .select({
-        providerId: tenantDisabledModels.providerId,
-        modelId: tenantDisabledModels.modelId,
-        endpointPath: tenantDisabledModels.endpointPath,
-      })
-      .from(tenantDisabledModels)
-      .where(
-        providerId === undefined
-          ? eq(tenantDisabledModels.tenantId, tenantId)
-          : and(
-              eq(tenantDisabledModels.tenantId, tenantId),
-              eq(tenantDisabledModels.providerId, providerId),
-            ),
-      );
-    const disabledKeys = new Set(
-      disabled.map((d) => `${d.providerId}::${d.modelId}::${d.endpointPath}`),
-    );
-    const dbRows = await this.db
-      .select({ model: models })
-      .from(models)
-      .innerJoin(providers, eq(models.providerId, providers.id))
-      .where(
-        and(
-          ...(providerId === undefined ? [] : [eq(models.providerId, providerId)]),
-          globalOrOwnedBy(providers.tenantId, tenantId),
-        ),
-      );
-    const grouped = new Map<string, ModelCatalogEntry[]>();
-    for (const { model: row } of dbRows) {
-      const isDisabled = disabledKeys.has(
-        `${row.providerId}::${row.modelId}::${row.endpointPath}`,
-      );
-      const list = grouped.get(row.providerId) ?? [];
-      list.push(mapModelRow(row, isDisabled));
-      grouped.set(row.providerId, list);
-    }
-    return grouped;
-  }
-  async registerModels(
-    tenantId: string,
-    providerId: string,
-    modelIds: readonly string[],
-    wireFamily?: string,
-    metadata?: ModelMetadataOverride,
-  ): Promise<void> {
-    const owner = await this.db
-      .select({
-        id: providers.id,
-        baseUrl: providers.baseUrl,
-        compatibilityProfile: providers.compatibilityProfile,
-      })
-      .from(providers)
-      .where(and(eq(providers.id, providerId), globalOrOwnedBy(providers.tenantId, tenantId)))
-      .limit(1);
-    if (!owner[0]) {
-      throw new ConsoleDomainError("provider_not_found", 404, `Provider ${providerId} not found`);
-    }
-    const family = (wireFamily ?? "chat") as WireFamily;
-    // Static endpoint from the provider's own bundled catalog via the probing
-    // service (the same startup-built map this store is constructed with).
-    // Without this, bundled providers on versioned bases (cline) get the
-    // generic `/v1/…` default, which joins into an unreachable path and every
-    // probe/dispatch 404s.
-    const staticEndpoint = await this.probing.resolveStaticEndpoint(providerId, family);
-    const endpointPath = endpointPathForProviderModel(
-      family,
-      owner[0].compatibilityProfile,
-      staticEndpoint === undefined ? undefined : { [family]: staticEndpoint },
-    );
-    if (modelIds.length === 0) return;
-    // Single multi-row insert and upsert of the capability flags so a
-    // re-registration repairs a row whose `tool_call` (and `reasoning`) was
-    // seeded false — a manual add persists schema defaults, which capability
-    // preflight reads as "route cannot use tools" and silently strips `tools`
-    // from every request. `enabled` stays operator-owned; `source` is refreshed
-    // to `manual`.
-    await this.db
-      .insert(models)
-      .values(
-        modelIds.map((modelId) => ({
-          providerId,
-          modelId,
-          wireFamily: family,
-          endpointPath,
-          ...applyModelMetadataOverride(
-            resolveManualModelMetadata(providerId, modelId),
-            metadata,
-          ),
-          source: "manual",
-          sourceUpdatedAt: new Date(),
-          enabled: true,
-        })),
-      )
-      .onConflictDoUpdate({
-        target: [models.providerId, models.modelId, models.endpointPath],
-        set: {
-          wireFamily: sql`excluded.wire_family`,
-          contextLimit: sql`excluded.context_limit`,
-          outputLimit: sql`excluded.output_limit`,
-          modalities: sql`excluded.modalities`,
-          reasoning: sql`excluded.reasoning`,
-          toolCall: sql`excluded.tool_call`,
-          source: sql`'manual'`,
-          sourceUpdatedAt: sql`excluded.source_updated_at`,
-        },
-      });
-  }
-
-  /**
-   * One-shot connectivity probe and model discovery live in
-   * `services/provider-probing.ts` — the store only forwards so the domain
-   * `ProviderCatalogStore` interface is unchanged.
-   */
-  async probeModel(
-    tenantId: string,
-    providerId: string,
-    request: ProbeModelRequest,
-  ): Promise<ProbeModelResult> {
-    return this.probing.probeModel(tenantId, providerId, request);
-  }
-
-  /** Ad-hoc BYOK connectivity test; delegates to the shared probing service. */
-  async testByokConnection(
-    tenantId: string,
-    request: ByokConnectionTestRequest,
-  ): Promise<ByokConnectionTestResult> {
-    return this.probing.testByokConnection(tenantId, request);
-  }
-
-  /**
-   * Batched provider-wide probe: the first registered model runs sequentially
-   * (warms OAuth token / connection pools), the rest run concurrently bounded
-   * to 5. Registered model ids come from this store's own catalog read.
-   */
-  async probeAllModels(tenantId: string, providerId: string): Promise<ProbeAllModelsResult> {
-    const entries = await this.listModels(tenantId, providerId);
-    const requests = entries.map((entry) => ({
-      modelId: entry.modelId,
-      route: entry.route,
-      serviceKind: isServiceKind(entry.serviceKind) ? entry.serviceKind : ("llm" as const),
-    }));
-    const uniqueRequests = requests.filter(
-      (request, index, all) =>
-        all.findIndex(
-          (candidate) =>
-            candidate.modelId === request.modelId &&
-            candidate.route === request.route &&
-            candidate.serviceKind === request.serviceKind,
-        ) === index,
-    );
-    return this.probing.probeAllModels(tenantId, providerId, uniqueRequests);
-  }
-  async probeAllAccounts(
-    tenantId: string,
-    providerId: string,
-    request: ProbeModelRequest,
-): Promise<ProbeAllAccountsResult> {
-    return this.probing.probeAllAccounts(tenantId, providerId, request);
-  }
-  /** Toggles a persisted model's routing eligibility. */
-  async setModelEnabled(
-    tenantId: string,
-    providerId: string,
-    request: SetModelEnabledRequest,
-  ): Promise<boolean> {
-    // Tenant-owned (BYOK) model: toggle the shared row directly.
-    const owned = await this.db
-      .select({ id: models.id })
-      .from(models)
-      .innerJoin(providers, eq(models.providerId, providers.id))
-      .where(
-        and(
-          eq(models.providerId, providerId),
-          eq(models.modelId, request.modelId),
-          eq(models.endpointPath, request.route),
-          ownedByOnly(providers.tenantId, tenantId),
-        ),
-      )
-      .limit(1);
-    const ownedTarget = owned[0];
-    if (ownedTarget) {
-      await this.db
-        .update(models)
-        .set({ enabled: request.enabled })
-        .where(eq(models.id, ownedTarget.id));
-      return true;
-    }
-
-    // Global/built-in model: tenants cannot mutate the shared row, so record
-    // (or clear) a tenant-scoped disable in `tenantDisabledModels`.
-    const global = await this.db
-      .select({ id: models.id })
-      .from(models)
-      .innerJoin(providers, eq(models.providerId, providers.id))
-      .where(
-        and(
-          eq(models.providerId, providerId),
-          eq(models.modelId, request.modelId),
-          eq(models.endpointPath, request.route),
-          isNull(providers.tenantId),
-        ),
-      )
-      .limit(1);
-    if (global[0] === undefined) return false;
-    if (request.enabled) {
-      await this.db
-        .delete(tenantDisabledModels)
-        .where(
-          and(
-            eq(tenantDisabledModels.tenantId, tenantId),
-            eq(tenantDisabledModels.providerId, providerId),
-            eq(tenantDisabledModels.modelId, request.modelId),
-            eq(tenantDisabledModels.endpointPath, request.route),
-          ),
-        );
-      return true;
-    }
-    await this.db
-      .insert(tenantDisabledModels)
-      .values({
-        tenantId,
-        providerId,
-        modelId: request.modelId,
-        endpointPath: request.route,
-      })
-      .onConflictDoNothing({
-        target: [
-          tenantDisabledModels.tenantId,
-          tenantDisabledModels.providerId,
-          tenantDisabledModels.modelId,
-          tenantDisabledModels.endpointPath,
-        ],
-      });
-    return true;
-  }
-
-  /**
-   * Updates one model's limits and capability flags.
-   *
-   * Two row kinds are writable. A tenant-owned (BYOK) row is updated directly.
-   * A model belonging to a *global* provider row is also updated directly:
-   * bundled providers are seeded once with `tenant_id IS NULL` and `providers.id`
-   * is the primary key, so a bundled provider can only ever have that one row —
-   * there is no tenant-scoped row to edit instead. Auto-fetched rows
-   * (`discovered` / `auto_free`) live on exactly those providers, which is why
-   * the previous `ownedByOnly` filter answered `not_found` for every model the
-   * operator had just fetched and could not be edited at all.
-   *
-   * A global `builtin` row is rejected: it is re-seeded from the bundle on every
-   * boot, so an edit there would be silently reverted, and `deleteModel` refuses
-   * it for the same reason.
-   *
-   * Absent override fields leave the stored value untouched — an edit that only
-   * sets the context ceiling must not reset the capability flags.
-   */
-  async updateModelMetadata(
-    tenantId: string,
-    providerId: string,
-    request: UpdateModelMetadataRequest,
-  ): Promise<boolean> {
-    const findRow = (ownership: SQL) =>
-      this.db
-        .select({ id: models.id, modalities: models.modalities, source: models.source })
-        .from(models)
-        .innerJoin(providers, eq(models.providerId, providers.id))
-        .where(
-          and(
-            eq(models.providerId, providerId),
-            eq(models.modelId, request.modelId),
-            eq(models.endpointPath, request.route),
-            ownership,
-          ),
-        )
-        .limit(1);
-    const owned = await findRow(ownedByOnly(providers.tenantId, tenantId));
-    let row = owned[0];
-    if (row === undefined) {
-      const global = await findRow(isNull(providers.tenantId));
-      const candidate = global[0];
-      if (candidate === undefined) return false;
-      if (candidate.source === "builtin") {
-        throw new ConsoleDomainError(
-          "builtin_model_immutable",
-          403,
-          `Built-in model ${providerId}/${request.modelId} cannot be edited — the bundle re-seeds it on every boot`,
-        );
-      }
-      row = candidate;
-    }
-
-    const override = request.metadata;
-    const set: Record<string, unknown> = { sourceUpdatedAt: new Date() };
-    if (override?.contextLimit !== undefined) set.contextLimit = override.contextLimit;
-    if (override?.outputLimit !== undefined) set.outputLimit = override.outputLimit;
-    // Passthrough grants every capability and cannot be partly revoked by a
-    // per-flag field: the point of the flag is that the operator does not know
-    // which capabilities the model has, so an explicit `false` alongside it is
-    // either stale or a mistake.
-    if (override?.passthrough === true) {
-      set.reasoning = true;
-      set.toolCall = true;
-      set.modalities = withImageModality(asStoredText(row.modalities), true);
-    } else {
-      if (override?.reasoning !== undefined) set.reasoning = override.reasoning;
-      if (override?.toolCall !== undefined) set.toolCall = override.toolCall;
-      if (override?.image !== undefined)
-        set.modalities = withImageModality(asStoredText(row.modalities), override.image);
-    }
-    await this.db.update(models).set(set).where(eq(models.id, row.id));
-    return true;
-  }
-
-  async deleteModel(
-    tenantId: string,
-    providerId: string,
-    request: SetModelEnabledRequest,
-  ): Promise<boolean> {
-    const owned = await this.db
-      .select({ id: models.id })
-      .from(models)
-      .innerJoin(providers, eq(models.providerId, providers.id))
-      .where(
-        and(
-          eq(models.providerId, providerId),
-          eq(models.modelId, request.modelId),
-          eq(models.endpointPath, request.route),
-          ownedByOnly(providers.tenantId, tenantId),
-        ),
-      )
-      .limit(1);
-    const target = owned[0];
-    if (target) {
-      const rows = await this.db
-        .delete(models)
-        .where(eq(models.id, target.id))
-        .returning({ id: models.id });
-      return rows.length > 0;
-    }
-    const global = await this.db
-      .select({ id: models.id, source: models.source })
-      .from(models)
-      .innerJoin(providers, eq(models.providerId, providers.id))
-      .where(
-        and(
-          eq(models.providerId, providerId),
-          eq(models.modelId, request.modelId),
-          eq(models.endpointPath, request.route),
-          isNull(providers.tenantId),
-        ),
-      )
-      .limit(1);
-    if (!global[0]) return false;
-    // Built-in models are immutable catalog: tenants can only disable them
-    // (via tenantDisabledModels), never delete the shared row.
-    if (global[0].source === "builtin") {
-      throw new ConsoleDomainError(
-        "builtin_model_immutable",
-        403,
-        `Built-in model ${providerId}/${request.modelId} cannot be deleted — disable it instead`,
-      );
-    }
-    const rows = await this.db
-      .delete(models)
-      .where(eq(models.id, global[0].id))
-      .returning({ id: models.id });
-    await this.db
-      .delete(tenantDisabledModels)
-      .where(
-        and(
-          eq(tenantDisabledModels.tenantId, tenantId),
-          eq(tenantDisabledModels.providerId, providerId),
-          eq(tenantDisabledModels.modelId, request.modelId),
-          eq(tenantDisabledModels.endpointPath, request.route),
-        ),
-      );
-    return rows.length > 0;
-  }
-
-  private async accountsWithUsage(
-    tenantId: string,
-    rows: readonly (typeof providerAccounts.$inferSelect)[],
-  ): Promise<readonly ProviderAccountResponse[]> {
-    if (rows.length === 0) return [];
-    const todayStart = new Date();
-    todayStart.setUTCHours(0, 0, 0, 0);
-    const accountIds = rows.map((row) => row.id);
-    // Today's per-account usage is one GROUP BY, not a read of every event
-    // since midnight. `breakdownTelemetry("account")` is capped at 100 groups;
-    // a page of accounts never exceeds it, and the lookup below is by id, so a
-    // group that fell outside the cap simply reads as "no usage today" — the
-    // same value an account with no traffic gets.
-    const todayGroups = await breakdownTelemetry(this.db, tenantId, "account", todayStart);
-    const todayByAccount = new Map(
-      todayGroups.map((group) => [
-        group.key,
-        {
-          requests: group.requests,
-          errors: group.errors,
-          inputTokens: group.inputTokens,
-          outputTokens: group.outputTokens,
-        },
-      ]),
-    );
-    const [lifetimeRows] = await Promise.all([
-      this.db
-        .select()
-        .from(telemetryUsageTotals)
-        .where(
-          and(
-            eq(telemetryUsageTotals.tenantId, tenantId),
-            eq(telemetryUsageTotals.identityType, "account"),
-            inArray(telemetryUsageTotals.entityId, accountIds),
-          ),
-        ),
-    ]);
-    const lifetimeByAccount = new Map(lifetimeRows.map((row) => [row.entityId, row]));
-    const mapUsage = (row: {
-      readonly requests: number | string | null;
-      readonly errors: number | string | null;
-      readonly inputTokens: number | string | null;
-      readonly outputTokens: number | string | null;
-    } | undefined): ProviderAccountTokenUsage => {
-      const inputTokens = Number(row?.inputTokens ?? 0);
-      const outputTokens = Number(row?.outputTokens ?? 0);
-      return {
-        requests: Number(row?.requests ?? 0),
-        errors: Number(row?.errors ?? 0),
-        inputTokens,
-        outputTokens,
-        totalTokens: inputTokens + outputTokens,
-      };
-    };
-    const first = rows[0];
-    const inflightByAccount = await this.accountInflightFor(tenantId, first?.providerId);
-    return rows.map((row) => {
-      const inflight = inflightByAccount.get(row.id);
-      return this.mapAccount(row, {
-        today: mapUsage(todayByAccount.get(row.id)),
-        allTime: mapUsage(lifetimeByAccount.get(row.id)),
-        ...(inflight === undefined ? {} : { inflight }),
-      });
-    });
-  }
-
-  private async accountInflightFor(
-    tenantId: string,
-    providerId: string | undefined,
-  ): Promise<Map<string, number>> {
-    const readings = new Map<string, number>();
-    if (!this.readAccountInflight || !providerId) return readings;
-    const rows = await this.readAccountInflight(providerId, tenantId);
-    for (const row of rows) {
-      if (typeof row.accountId !== "string" || !Number.isFinite(row.inflight)) continue;
-      readings.set(row.accountId, Math.max(0, Math.floor(row.inflight)));
-    }
-    return readings;
-  }
-
-  /**
-   * Next free list position for a new account in this provider's list.
-   *
-   * Scoped to (provider, tenant) because the list is per provider: a tenant
-   * with accounts under two providers must not have the second provider's
-   * first account land at a high index.
-   */
-  /**
-   * Labels already in use for one provider, for numbering a generated name.
-   *
-   * Scoped to this provider and tenant: `dcint-key-1` and `other-key-1` belong
-   * to different providers and must not collide with each other.
-   */
-  private async generateAccountLabel(
-    db: CartethyiaDatabase | Parameters<Parameters<CartethyiaDatabase["transaction"]>[0]>[0],
-    providerId: string,
-    tenantId: string,
-    credentialMode: CredentialMode,
-  ): Promise<string> {
-    const rows = await db
-      .select({ label: providerAccounts.label })
-      .from(providerAccounts)
-      .where(
-        and(
-          eq(providerAccounts.providerId, providerId),
-          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-        ),
-      );
-    return nextGeneratedAccountLabel(
-      providerId,
-      credentialMode,
-      rows.map((row) => row.label).filter((label): label is string => typeof label === "string"),
-    );
-  }
-
-  private async nextAccountSortIndex(
-    db: CartethyiaDatabase | Parameters<Parameters<CartethyiaDatabase["transaction"]>[0]>[0],
-    providerId: string,
-    tenantId: string,
-  ): Promise<number> {
-    return nextSortIndex(
-      db,
-      { table: providerAccounts, idColumn: providerAccounts.id, sortIndexColumn: providerAccounts.sortIndex },
-      and(
-        eq(providerAccounts.providerId, providerId),
-        globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-      ),
-    );
-  }
-
-  /** Rewrites one provider's account order; `accountIds` is the full order. */
-  async reorderAccounts(
-    tenantId: string,
-    providerId: string,
-    accountIds: readonly string[],
-  ): Promise<void> {
-    await reorderSortIndex(
-      this.db,
-      { table: providerAccounts, idColumn: providerAccounts.id, sortIndexColumn: providerAccounts.sortIndex },
-      and(
-        eq(providerAccounts.providerId, providerId),
-        globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-      ),
-      accountIds,
-    );
-  }
-
-  async listAccounts(
-    tenantId: string,
-    providerId: string,
-  ): Promise<readonly ProviderAccountResponse[]> {
-    const rows = await this.db
-      .select()
-      .from(providerAccounts)
-      .where(
-        and(
-          eq(providerAccounts.providerId, providerId),
-          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-        ),
-      )
-      // Stable list position, not `created_at`: two accounts created in the
-      // same millisecond could swap between loads. `id` breaks a tie so the
-      // order is total even before a reorder assigns distinct indices.
-      .orderBy(asc(providerAccounts.sortIndex), asc(providerAccounts.createdAt), asc(providerAccounts.id));
-    return this.accountsWithUsage(tenantId, rows);
-  }
-
-  async listAllAccounts(tenantId: string): Promise<readonly ProviderAccountResponse[]> {
-    const rows = await this.db
-      .select()
-      .from(providerAccounts)
-      .where(globalOrOwnedBy(providerAccounts.tenantId, tenantId))
-      .orderBy(asc(providerAccounts.sortIndex), asc(providerAccounts.createdAt), asc(providerAccounts.id));
-    return this.accountsWithUsage(tenantId, rows);
-  }
-
-  async createAccount(
-    tenantId: string,
-    providerId: string,
-    request: CreateProviderAccountRequest,
-    existingTx?: Parameters<Parameters<CartethyiaDatabase["transaction"]>[0]>[0],
-    includeUsage = true,
-    sortIndexOverride?: number,
-  ): Promise<ProviderAccountResponse> {
-    // Callers inside an existing transaction pass it in so the account lands in
-    // that unit of work (the batch path); otherwise this opens its own.
-    const run = async (
-      tx: Parameters<Parameters<CartethyiaDatabase["transaction"]>[0]>[0],
-    ): Promise<ProviderAccountResponse> => {
-    let effectiveSecret = request.secret;
-        let effectiveCredentialKind = request.credentialKind;
-        const requestedCredentialMode: CredentialMode = request.credentialMode ?? "auto";
-        let effectiveCredentialMode: CredentialMode = requestedCredentialMode;
-        let tokenExpiresAt: Date | undefined;
-        let jwtIssuer: string | undefined;
-        let oauthRefreshCiphertext: Buffer | undefined;
-        let oauthExpiresAt: Date | undefined;
-        let oauthHasRefreshToken = false;
-        let pastedAuthState: Readonly<Record<string, unknown>> = {};
-
-        if (
-          (request.credentialKind === "oauth" || request.credentialKind === "api_key") &&
-          request.secret.trim().length > 0
-        ) {
-          const trimmed = request.secret.trim();
-          const parts = parsePastedOAuthCredential(trimmed);
-          pastedAuthState = parts.authState;
-          const hasRefreshToken = parts.refreshToken !== parts.accessToken;
-          const parsedJwt =
-            requestedCredentialMode === "api_key"
-              ? undefined
-              : parseJwtCredential(parts.accessToken);
-          if (requestedCredentialMode === "jwt" && parsedJwt === undefined) {
-            throw new ConsoleDomainError(
-              "invalid_request",
-              400,
-              "credentialMode jwt requires a valid three-part JWT",
-            );
-          }
-          if (requestedCredentialMode === "api_key") {
-            effectiveSecret = parts.accessToken;
-            effectiveCredentialKind = "api_key";
-            effectiveCredentialMode = "api_key";
-          } else if (
-            parsedJwt !== undefined &&
-            (requestedCredentialMode === "jwt" || !hasRefreshToken)
-          ) {
-            effectiveSecret = parts.accessToken;
-            effectiveCredentialKind = "api_key";
-            effectiveCredentialMode = "jwt";
-            tokenExpiresAt = parsedJwt.expiresAt;
-            // Kept alongside the expiry: the console shows who issued a static
-            // token, and the secret itself is never readable after this point.
-            jwtIssuer = parsedJwt.issuer;
-          } else if (request.credentialKind === "oauth" || hasRefreshToken) {
-            effectiveSecret = parts.accessToken;
-            effectiveCredentialKind = hasRefreshToken ? "oauth" : "api_key";
-            effectiveCredentialMode = hasRefreshToken ? "auto" : "api_key";
-            if (hasRefreshToken) {
-              oauthRefreshCiphertext = encryptCredential(parts.refreshToken);
-              oauthHasRefreshToken = true;
-            }
-            oauthExpiresAt = parts.expiresAt;
-          } else {
-            effectiveCredentialMode = "api_key";
-          }
-        }
-
-        // Append to the end of this provider's list rather than relying on
-        // creation time, so a new account never displaces existing positions.
-        const credentialFingerprint =
-          effectiveCredentialKind === "none" || effectiveSecret.length === 0
-            ? undefined
-            : hashSecret(effectiveSecret);
-        const accountAuthState = {
-          ...pastedAuthState,
-          ...(request.authState ?? {}),
-          credentialMode: effectiveCredentialMode,
-          ...(tokenExpiresAt === undefined ? {} : { tokenExpiresAt: tokenExpiresAt.toISOString() }),
-          ...(jwtIssuer === undefined ? {} : { jwtIssuer }),
-        };
-        const nextSortIndex =
-          sortIndexOverride ?? (await this.nextAccountSortIndex(tx, providerId, tenantId));
-        // Read existing labels only when one has to be generated: a named
-        // account costs no extra query, and this is the path a large batch
-        // paste walks once per row.
-        const label =
-          request.label ??
-          (await this.generateAccountLabel(tx, providerId, tenantId, effectiveCredentialMode));
-        const rows = await tx
-          .insert(providerAccounts)
-          .values({
-            providerId,
-            tenantId,
-            sortIndex: nextSortIndex,
-            label,
-            credentialCiphertext: encryptCredential(effectiveSecret),
-            ...(credentialFingerprint ? { credentialFingerprint } : {}),
-            credentialKind: effectiveCredentialKind,
-            status: "active",
-            authState: accountAuthState,
-            // An OAuth account pasted without a refresh token is a *static*
-            // token: the pasted value is a bearer token used exactly as issued
-            // and there is no refresh grant to run. Flag it as static so the
-            // console reads it as an informational "static token" rather than
-            // "re-login required" — the token is still valid and dispatchable —
-            // and so the refresh sweep skips it instead of retrying a refresh
-            // that can never succeed.
-            ...(effectiveCredentialKind === "oauth" && !oauthHasRefreshToken || effectiveCredentialMode === "jwt"
-              ? { staticToken: true }
-              : {}),
-          })
-          .returning();
-        const row = rows[0];
-        if (!row) throw new Error("failed to create provider account");
-
-        if (effectiveCredentialKind === "oauth") {
-          await tx.insert(providerOauthStates).values({
-            providerAccountId: row.id,
-            ...(oauthRefreshCiphertext ? { refreshCiphertext: oauthRefreshCiphertext } : {}),
-            expiresAt: oauthExpiresAt ?? null,
-          });
-        }
-        if (request.credentialKind === "oauth" && !oauthHasRefreshToken) {
-          pushStructuredConsoleLog(
-            "info",
-            "OAuth access token stored as a static API credential; it will not be refreshed",
-            {
-              event: "token_refresh",
-              providerId,
-              accountId: row.id,
-              errorCode: "static_token",
-            },
-          );
-        }
-
-        if (!includeUsage) {
-          const emptyUsage = { requests: 0, errors: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-          return this.mapAccount(row, { today: emptyUsage, allTime: emptyUsage });
-        }
-        const [account] = await this.accountsWithUsage(tenantId, [row]);
-        if (!account) throw new Error("created provider account could not be mapped");
-        return account;
-    };
-
-    try {
-      if (existingTx !== undefined) {
-        return await run(existingTx);
-      }
-      return await this.db.transaction(run);
-    } catch (error) {
-      if (isUniqueViolation(error)) {
-        throw new ConsoleDomainError(
-          "provider_account_duplicate",
-          409,
-          "A provider account with this credential already exists",
-        );
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Creates many accounts in one round-trip.
-   *
-   * The whole batch shares one transaction, so a paste of 40 credentials costs
-   * one connection checkout rather than 40. Each item is created through the
-   * same `createAccount` path the single route uses — there is no second
-   * implementation of credential detection to drift.
-   *
-   * Items are created sequentially inside that transaction: the unique
-   * credential fingerprint makes two identical pastes collide, and a nested
-   * transaction per item keeps that collision from aborting the whole batch.
-   * Outcomes are reported per index, so a partial paste still lands the
-   * accounts that were fine — an operator fixing one bad line should not have
-   * to re-import 39.
-   */
-  async createAccountBatch(
-    tenantId: string,
-    providerId: string,
-    requests: readonly CreateProviderAccountRequest[],
-  ): Promise<CreateProviderAccountBatchResult> {
-    if (requests.length === 0) {
-      return { created: 0, failed: 0, results: [] };
-    }
-    const results: CreateProviderAccountBatchItemResult[] = [];
-    let created = 0;
-    let failed = 0;
-
-    await this.db.transaction(async (tx) => {
-      let nextSortIndex = await this.nextAccountSortIndex(tx, providerId, tenantId);
-      for (const [index, request] of requests.entries()) {
-        try {
-          // A nested transaction acts as a savepoint: a duplicate-fingerprint
-          // violation rolls back only this item, not the accounts before it.
-          const account = await tx.transaction(async (inner) =>
-            this.createAccount(tenantId, providerId, request, inner, false, nextSortIndex),
-          );
-          created += 1;
-          nextSortIndex += 1;
-          results.push({ index, ok: true, ...(account ? { account } : {}) });
-        } catch (error) {
-          failed += 1;
-          results.push({
-            index,
-            ok: false,
-            error: error instanceof Error ? error.message : String(error),
-            code: error instanceof ConsoleDomainError ? error.code : "create_failed",
-          });
-        }
-      }
-    });
-
-    return { created, failed, results };
-  }
-
-  async updateAccount(
-    tenantId: string,
-    providerId: string,
-    accountId: string,
-    patch: UpdateProviderAccountRequest,
-  ): Promise<ProviderAccountResponse | undefined> {
-    const set: Partial<typeof providerAccounts.$inferInsert> = {};
-    if (patch.label !== undefined) set.label = patch.label;
-    if (patch.secret !== undefined) {
-      set.credentialCiphertext = encryptCredential(patch.secret);
-      set.credentialFingerprint =
-        patch.secret.length === 0 ? null : hashSecret(patch.secret);
-    }
-    if (patch.status !== undefined) set.status = patch.status;
-    // Toggling the static-token flag: turning it on declares the credential is
-    // used as issued and never refreshed, so any stale re-auth flag is cleared —
-    // the operator has said the account is fine, and the pill must stop reading
-    // "Re-login required". Turning it off returns the account to normal OAuth
-    // refresh handling; the sweep picks it up again on its next pass.
-    if (patch.staticToken !== undefined) {
-      set.staticToken = patch.staticToken;
-      if (patch.staticToken) {
-        set.lastError = null;
-        set.lastErrorCategory = null;
-        set.lastErrorAt = null;
-      }
-    }
-    // Status toggles are not recovery: preserve the health machine's evidence
-    // until the operator uses Recover or replaces the rejected credential.
-    const clearsFailureState = patch.secret !== undefined && patch.secret.length > 0;
-    if (clearsFailureState) {
-      set.consecutiveFailures = 0;
-      set.cooldownUntil = null;
-      set.modelCooldowns = {};
-      set.lastError = null;
-      set.lastErrorCategory = null;
-      set.lastErrorAt = null;
-    }
-    const where = and(
-      eq(providerAccounts.id, accountId),
-      eq(providerAccounts.providerId, providerId),
-      globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-    );
-    try {
-      const rows =
-        Object.keys(set).length > 0
-          ? await this.db.update(providerAccounts).set(set).where(where).returning()
-          : await this.db.select().from(providerAccounts).where(where);
-      const row = rows[0];
-      if (!row) return undefined;
-      // Secret/status mutation: drop any cached credential so the next
-      // attempt decrypts the new ciphertext (or refuses a disabled account).
-      if (patch.secret !== undefined || patch.status !== undefined) {
-        invalidateCredentialCache(accountId);
-      }
-      const [account] = await this.accountsWithUsage(tenantId, [row]);
-      return account;
-    } catch (error) {
-      if (isUniqueViolation(error)) {
-        throw new ConsoleDomainError(
-          "provider_account_duplicate",
-          409,
-          "A provider account with this credential already exists",
-        );
-      }
-      throw error;
-    }
-  }
-
-  private mapAccount(
-    row: typeof providerAccounts.$inferSelect,
-    usage: {
-      readonly today: ProviderAccountTokenUsage;
-      readonly allTime: ProviderAccountTokenUsage;
-      readonly inflight?: number | undefined;
-    },
-  ): ProviderAccountResponse {
-    const authState =
-      row.authState !== null && typeof row.authState === "object" && !Array.isArray(row.authState)
-        ? (row.authState as Record<string, unknown>)
-        : undefined;
-    const rawCredentialMode = authState?.["credentialMode"];
-    const credentialMode: CredentialMode | undefined =
-      rawCredentialMode === "auto" || rawCredentialMode === "jwt" || rawCredentialMode === "api_key"
-        ? rawCredentialMode
-        : undefined;
-    const tokenExpiresAt =
-      typeof authState?.["tokenExpiresAt"] === "string" ? authState["tokenExpiresAt"] : undefined;
-    const jwtIssuer =
-      typeof authState?.["jwtIssuer"] === "string" ? authState["jwtIssuer"] : undefined;
-    return {
-      id: row.id,
-      providerId: row.providerId,
-      tenantId: row.tenantId,
-      label: row.label,
-      credentialKind: row.credentialKind,
-      ...(credentialMode === undefined ? {} : { credentialMode }),
-      ...(tokenExpiresAt === undefined ? {} : { tokenExpiresAt }),
-      ...(jwtIssuer === undefined ? {} : { jwtIssuer }),
-      status: row.status,
-      ...(usage.inflight === undefined ? {} : { inflight: usage.inflight }),
-      usageToday: usage.today,
-      usageAllTime: usage.allTime,
-      consecutiveFailures: row.consecutiveFailures,
-      ...(row.lastSuccessAt ? { lastSuccessAt: row.lastSuccessAt.toISOString() } : {}),
-      ...(row.lastError ? { lastError: row.lastError } : {}),
-      ...(row.lastErrorCategory ? { lastErrorCategory: row.lastErrorCategory } : {}),
-      ...(row.lastErrorAt ? { lastErrorAt: row.lastErrorAt.toISOString() } : {}),
-      ...(row.cooldownUntil ? { cooldownUntil: row.cooldownUntil.toISOString() } : {}),
-      ...(liveModelCooldowns(row.modelCooldowns) ?? {}),
-      ...(row.lastRecoveredAt ? { lastRecoveredAt: row.lastRecoveredAt.toISOString() } : {}),
-      createdAt: row.createdAt.toISOString(),
-      sortIndex: row.sortIndex,
-      ...(row.staticToken ? { staticToken: true } : {}),
-    };
-  }
-
-  async listAccountHealthEvents(
-    tenantId: string,
-    providerId: string,
-    accountId: string,
-  ): Promise<readonly AccountHealthEventRecord[]> {
-    const owned = await this.db
-      .select({ id: providerAccounts.id })
-      .from(providerAccounts)
-      .where(
-        and(
-          eq(providerAccounts.id, accountId),
-          eq(providerAccounts.providerId, providerId),
-          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-        ),
-      )
-      .limit(1);
-    if (owned.length === 0) return [];
-    return listAccountHealthEvents(this.db, accountId);
-  }
-
-  /** Deletes one account's stored health & error rows, for the modal's purge. */
-  async purgeAccountHealthEvents(
-    tenantId: string,
-    providerId: string,
-    accountId: string,
-  ): Promise<number> {
-    const owned = await this.db
-      .select({ id: providerAccounts.id })
-      .from(providerAccounts)
-      .where(
-        and(
-          eq(providerAccounts.id, accountId),
-          eq(providerAccounts.providerId, providerId),
-          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-        ),
-      )
-      .limit(1);
-    if (owned.length === 0) return 0;
-    return deleteAccountHealthEvents(this.db, accountId);
-  }
-  async listBuddyGrowthTasks(
-    tenantId: string,
-    providerId: string,
-    accountId: string,
-    dayKey: string,
-  ): Promise<readonly BuddyGrowthTaskLedgerEntry[]> {
-    const owned = await this.db
-      .select({ id: providerAccounts.id })
-      .from(providerAccounts)
-      .where(
-        and(
-          eq(providerAccounts.id, accountId),
-          eq(providerAccounts.providerId, providerId),
-          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-        ),
-      )
-      .limit(1);
-    if (owned.length === 0) return [];
-    const rows = await this.db
-      .select({
-        accountId: buddyTaskLedger.accountId,
-        task: buddyTaskLedger.task,
-        claimedAt: buddyTaskLedger.claimedAt,
-      })
-      .from(buddyTaskLedger)
-      .where(
-        and(
-          eq(buddyTaskLedger.accountId, accountId),
-          eq(buddyTaskLedger.dayKey, dayKey),
-        ),
-      );
-    return rows.map((row) => ({
-      accountId: row.accountId,
-      task: row.task,
-      claimedAt: row.claimedAt.toISOString(),
-    }));
-  }
-
-  async recoverAccount(
-    tenantId: string,
-    providerId: string,
-    accountId: string,
-  ): Promise<boolean> {
-    const owned = await this.db
-      .select({ id: providerAccounts.id })
-      .from(providerAccounts)
-      .where(
-        and(
-          eq(providerAccounts.id, accountId),
-          eq(providerAccounts.providerId, providerId),
-          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
-        ),
-      )
-      .limit(1);
-    if (owned.length === 0) return false;
-    return recoverAccount(this.db, accountId, "manual_operator_recovery");
-  }
-
-
-  async syncModels(tenantId: string, providerId: string): Promise<{ synced: number }> {
-    return this.probing.syncModels(tenantId, providerId);
-  }
-}
+// Drizzle-backed provider, account, model, routing, and API-key repositories.
+import { and, asc, eq, inArray, isNull, or, sql, type SQL } from "drizzle-orm";
+import { ConsoleDomainError } from "../../shared/errors";
+import { parseCustomProviderId, isBundledProviderId } from "../../../providers/provider-contracts";
+import type { ModelDefinition } from "../../../providers/provider-model-definition";
+import type { ProviderRegistry } from "../../../providers/provider-registry";
+import { BUNDLED_PROVIDER_MODULES } from "../../../providers/default-registry";
+import { globalOrOwnedBy, ownedByOnly } from "../../../persistence/tenant-scope";
+import { nextSortIndex, reorderSortIndex } from "../../../persistence/sort-order";
+import type { CartethyiaDatabase } from "../../../persistence/db-handle";
+import { buddyTaskLedger, models, providerAccounts, providerOauthStates, providers, telemetryUsageTotals, tenantDisabledModels } from "../../../persistence/schema";
+import { breakdownTelemetry } from "../../../observability/event-query";
+import type { WireFamily } from "../../../protocol/canonical-model";
+import { listAccountHealthEvents, recoverAccount, deleteAccountHealthEvents, type AccountHealthEventRecord } from "../../../providers/operations/account-health-service";
+import { invalidateCredentialCache } from "../../../providers/operations/provider-credential-service";
+import { encryptCredential, hashSecret } from "../../../security/crypto";
+import type { TelemetryBatchBuffer } from "../../../observability/telemetry-buffer";
+import { bumpCatalogRevision, type BundledProviderCatalog } from "../../../providers/operations/provider-catalog-service";
+import type { AccountInflightReading, BuddyGrowthTaskLedgerEntry, ByokConnectionTestRequest, ByokConnectionTestResult, CreateProviderAccountBatchItemResult, CreateProviderAccountBatchResult, CreateProviderAccountRequest, CredentialMode, ModelCatalogEntry, ProbeAllAccountsResult, ProbeAllModelsResult, ProbeModelRequest, ProbeModelResult, ProviderAccountResponse, ProviderAccountTokenUsage, ProviderCatalogStore, ProviderRecord, SetModelEnabledRequest, UpdateModelMetadataRequest, UpdateProviderAccountRequest, ModelMetadataOverride } from "./contracts";
+import { isServiceKind, validateCompatibilityProfile } from "./contracts";
+import { ProviderProbingService, type ProbeOutboundResolver } from "../../../providers/discovery/probing-service";
+import {
+  applyModelMetadataOverride,
+  resolveManualModelMetadata,
+} from "../../../providers/provider-model-definition";
+import { isUniqueViolation } from "../../../persistence/boot";
+import { DEFAULT_ENDPOINT_BY_WIRE_FAMILY, endpointPathForProviderModel, mapProviderRow } from "./catalog-projections";
+import { pushStructuredConsoleLog } from "../../../observability/log-ring";
+
+/** Real Drizzle-backed provider and model catalog repository. */
+
+import {
+  asStoredText,
+  liveModelCooldowns,
+  mapModelRow,
+  nextGeneratedAccountLabel,
+  parseJwtCredential,
+  parsePastedOAuthCredential,
+  withImageModality,
+} from "./store-helpers";
+
+export {
+  accountLabelKindSegment,
+  mapModelRow,
+  nextGeneratedAccountLabel,
+  withImageModality,
+} from "./store-helpers";
+
+export class DrizzleProviderCatalogStore implements ProviderCatalogStore {
+  private readonly probing: ProviderProbingService;
+  private readonly bundledModelCatalog: ReadonlyMap<string, readonly ModelDefinition[]>;
+  private readonly providerRegistry: ProviderRegistry;
+
+  private readonly readAccountInflight:
+    | ((
+        providerId: string,
+        tenantId: string,
+      ) => Promise<readonly AccountInflightReading[]>)
+    | undefined;
+
+  constructor(
+    private readonly db: CartethyiaDatabase,
+    options: {
+      readonly telemetryBuffer: TelemetryBatchBuffer;
+      readonly bundledModelCatalog: BundledProviderCatalog;
+      readonly providerRegistry: ProviderRegistry;
+      readonly outboundFetchFor: ProbeOutboundResolver;
+      readonly snapshotInvalidator: { invalidate(): unknown };
+      readonly readAccountInflight?:
+        | ((
+            providerId: string,
+            tenantId: string,
+          ) => Promise<readonly AccountInflightReading[]>)
+        | undefined;
+    },
+  ) {
+    this.bundledModelCatalog = options.bundledModelCatalog.modelsByProvider;
+    this.providerRegistry = options.providerRegistry;
+    this.readAccountInflight = options.readAccountInflight;
+    this.probing = new ProviderProbingService({
+      db,
+      telemetryBuffer: options.telemetryBuffer,
+      defaultEndpoints: DEFAULT_ENDPOINT_BY_WIRE_FAMILY,
+      bundledModelCatalog: this.bundledModelCatalog,
+      outboundFetchFor: options.outboundFetchFor,
+      snapshotInvalidator: options.snapshotInvalidator,
+      providerRegistry: options.providerRegistry,
+    });
+  }
+  async list(tenantId: string): Promise<readonly ProviderRecord[]> {
+    const bundledIds = BUNDLED_PROVIDER_MODULES.map((provider) => provider.id);
+    const rows = await this.db
+      .select()
+      .from(providers)
+      .where(
+        and(
+          globalOrOwnedBy(providers.tenantId, tenantId),
+          or(inArray(providers.id, bundledIds), eq(providers.tenantId, tenantId)),
+        ),
+      )
+      .orderBy(asc(providers.id));
+    return rows.map((row) => mapProviderRow(row, this.providerRegistry));
+  }
+  async get(tenantId: string, providerId: string): Promise<ProviderRecord | undefined> {
+    const rows = await this.db
+      .select()
+      .from(providers)
+      .where(
+        and(
+          eq(providers.id, providerId),
+          globalOrOwnedBy(providers.tenantId, tenantId),
+        ),
+      )
+      .limit(1);
+    const row = rows[0];
+    return row ? mapProviderRow(row, this.providerRegistry) : undefined;
+  }
+  async create(record: ProviderRecord): Promise<void> {
+    if (isBundledProviderId(record.providerId))
+      throw new ConsoleDomainError(
+        "provider_is_builtin",
+        403,
+        "Built-in provider cannot be created",
+      );
+    parseCustomProviderId(record.providerId);
+    if (record.compatibilityProfile) validateCompatibilityProfile(record.compatibilityProfile);
+    await this.db.insert(providers).values({
+      id: record.providerId,
+      tenantId: record.tenantId ?? null,
+      enabled: record.enabled,
+      ...(record.wireFamilyDefault ? { wireFamilyDefault: record.wireFamilyDefault } : {}),
+      capabilityProfile: record.capabilityProfile ?? null,
+      baseUrl: record.baseUrl ?? null,
+      compatibilityProfile: record.compatibilityProfile ?? null,
+    });
+  }
+  async update(
+    tenantId: string,
+    providerId: string,
+    patch: Partial<ProviderRecord>,
+  ): Promise<ProviderRecord | undefined> {
+    if (isBundledProviderId(providerId))
+      throw new ConsoleDomainError(
+        "provider_is_builtin",
+        403,
+        "Built-in provider cannot be updated",
+      );
+    if (patch.compatibilityProfile) validateCompatibilityProfile(patch.compatibilityProfile);
+    const set: Partial<typeof providers.$inferInsert> = {};
+    if (patch.enabled !== undefined) set.enabled = patch.enabled;
+    if (patch.capabilityProfile !== undefined) set.capabilityProfile = patch.capabilityProfile;
+    if (patch.baseUrl !== undefined) set.baseUrl = patch.baseUrl;
+    if (patch.compatibilityProfile !== undefined)
+      set.compatibilityProfile = patch.compatibilityProfile;
+    const rows =
+      Object.keys(set).length > 0
+        ? await this.db
+            .update(providers)
+            .set(set)
+            .where(
+              and(
+                eq(providers.id, providerId),
+                ownedByOnly(providers.tenantId, tenantId),
+              ),
+            )
+            .returning()
+        : await this.db
+            .select()
+            .from(providers)
+            .where(
+              and(
+                eq(providers.id, providerId),
+                ownedByOnly(providers.tenantId, tenantId),
+              ),
+            );
+    const row = rows[0];
+    return row ? mapProviderRow(row, this.providerRegistry) : undefined;
+  }
+  async delete(tenantId: string, providerId: string): Promise<boolean> {
+    if (isBundledProviderId(providerId))
+      throw new ConsoleDomainError(
+        "provider_is_builtin",
+        403,
+        "Built-in provider cannot be deleted",
+      );
+    // Custom-provider rows own their models, accounts, disabled-model flags,
+    // and routing preferences: deleting the parent cascades all of them
+    // (models/provider_accounts/provider_oauth_states via provider FK,
+    // health_events via account FK, tenant_disabled_models and
+    // provider_routing_settings via provider FK) in one atomic DELETE.
+    const deleted = await this.db
+      .delete(providers)
+      .where(and(eq(providers.id, providerId), ownedByOnly(providers.tenantId, tenantId)))
+      .returning({ id: providers.id });
+    if (deleted.length === 0) return false;
+    this.providerRegistry.unregister(providerId);
+    // The provider left the registry, so the compiled catalog is now missing it
+    // — the snapshot's re-seed is gated on that revision, and a delete that did
+    // not bump it would leave the provider's model rows behind.
+    bumpCatalogRevision();
+    return true;
+  }
+  async updateGlobal(
+    providerId: string,
+    patch: Partial<ProviderRecord>,
+  ): Promise<ProviderRecord | undefined> {
+    const isBuiltin = isBundledProviderId(providerId);
+    if (isBuiltin && Object.keys(patch).some((field) => field !== "enabled")) {
+      throw new ConsoleDomainError(
+        "provider_is_builtin",
+        403,
+        "Built-in providers only support enable/disable",
+      );
+    }
+    if (patch.compatibilityProfile) validateCompatibilityProfile(patch.compatibilityProfile);
+    const set: Partial<typeof providers.$inferInsert> = {};
+    if (patch.enabled !== undefined) set.enabled = patch.enabled;
+    if (patch.capabilityProfile !== undefined) set.capabilityProfile = patch.capabilityProfile;
+    if (patch.baseUrl !== undefined) set.baseUrl = patch.baseUrl;
+    if (patch.compatibilityProfile !== undefined) {
+      set.compatibilityProfile = patch.compatibilityProfile;
+    }
+    const rows =
+      Object.keys(set).length > 0
+        ? await this.db
+            .update(providers)
+            .set(set)
+            .where(and(eq(providers.id, providerId), isNull(providers.tenantId)))
+            .returning()
+        : await this.db
+            .select()
+            .from(providers)
+            .where(and(eq(providers.id, providerId), isNull(providers.tenantId)));
+    const row = rows[0];
+    return row ? mapProviderRow(row, this.providerRegistry) : undefined;
+  }
+
+  async deleteGlobal(providerId: string): Promise<boolean> {
+    if (isBundledProviderId(providerId)) {
+      throw new ConsoleDomainError(
+        "provider_is_builtin",
+        403,
+        "Built-in provider cannot be deleted",
+      );
+    }
+    const rows = await this.db
+      .delete(providers)
+      .where(and(eq(providers.id, providerId), isNull(providers.tenantId)))
+      .returning({ id: providers.id });
+    return rows.length > 0;
+  }
+  async listModels(tenantId: string, providerId: string): Promise<readonly ModelCatalogEntry[]> {
+    const byProvider = await this.listModelsForTenant(tenantId, providerId);
+    return byProvider.get(providerId) ?? [];
+  }
+
+  /**
+   * Every enabled-and-disabled model row the tenant can see, grouped by
+   * provider. One pair of statements for the whole tenant instead of a pair per
+   * provider.
+   *
+   * The per-provider `listModels` shape costs two queries per call, so a caller
+   * that needs every provider's models — the flat catalog the picker renders —
+   * issued `2 * providers + 2` statements, growing with the bundled catalog.
+   * Grouping here makes it constant: one disabled-model read and one models
+   * join, regardless of provider count. `providerId` narrows it to a single
+   * provider for callers that already know which one they want.
+   */
+  async listModelsForTenant(
+    tenantId: string,
+    providerId?: string,
+  ): Promise<Map<string, readonly ModelCatalogEntry[]>> {
+    const disabled = await this.db
+      .select({
+        providerId: tenantDisabledModels.providerId,
+        modelId: tenantDisabledModels.modelId,
+        endpointPath: tenantDisabledModels.endpointPath,
+      })
+      .from(tenantDisabledModels)
+      .where(
+        providerId === undefined
+          ? eq(tenantDisabledModels.tenantId, tenantId)
+          : and(
+              eq(tenantDisabledModels.tenantId, tenantId),
+              eq(tenantDisabledModels.providerId, providerId),
+            ),
+      );
+    const disabledKeys = new Set(
+      disabled.map((d) => `${d.providerId}::${d.modelId}::${d.endpointPath}`),
+    );
+    const dbRows = await this.db
+      .select({ model: models })
+      .from(models)
+      .innerJoin(providers, eq(models.providerId, providers.id))
+      .where(
+        and(
+          ...(providerId === undefined ? [] : [eq(models.providerId, providerId)]),
+          globalOrOwnedBy(providers.tenantId, tenantId),
+        ),
+      );
+    const grouped = new Map<string, ModelCatalogEntry[]>();
+    for (const { model: row } of dbRows) {
+      const isDisabled = disabledKeys.has(
+        `${row.providerId}::${row.modelId}::${row.endpointPath}`,
+      );
+      const list = grouped.get(row.providerId) ?? [];
+      list.push(mapModelRow(row, isDisabled));
+      grouped.set(row.providerId, list);
+    }
+    return grouped;
+  }
+  async registerModels(
+    tenantId: string,
+    providerId: string,
+    modelIds: readonly string[],
+    wireFamily?: string,
+    metadata?: ModelMetadataOverride,
+  ): Promise<void> {
+    const owner = await this.db
+      .select({
+        id: providers.id,
+        baseUrl: providers.baseUrl,
+        compatibilityProfile: providers.compatibilityProfile,
+      })
+      .from(providers)
+      .where(and(eq(providers.id, providerId), globalOrOwnedBy(providers.tenantId, tenantId)))
+      .limit(1);
+    if (!owner[0]) {
+      throw new ConsoleDomainError("provider_not_found", 404, `Provider ${providerId} not found`);
+    }
+    const family = (wireFamily ?? "chat") as WireFamily;
+    // Static endpoint from the provider's own bundled catalog via the probing
+    // service (the same startup-built map this store is constructed with).
+    // Without this, bundled providers on versioned bases (cline) get the
+    // generic `/v1/…` default, which joins into an unreachable path and every
+    // probe/dispatch 404s.
+    const staticEndpoint = await this.probing.resolveStaticEndpoint(providerId, family);
+    const endpointPath = endpointPathForProviderModel(
+      family,
+      owner[0].compatibilityProfile,
+      staticEndpoint === undefined ? undefined : { [family]: staticEndpoint },
+    );
+    if (modelIds.length === 0) return;
+    // Single multi-row insert and upsert of the capability flags so a
+    // re-registration repairs a row whose `tool_call` (and `reasoning`) was
+    // seeded false — a manual add persists schema defaults, which capability
+    // preflight reads as "route cannot use tools" and silently strips `tools`
+    // from every request. `enabled` stays operator-owned; `source` is refreshed
+    // to `manual`.
+    await this.db
+      .insert(models)
+      .values(
+        modelIds.map((modelId) => ({
+          providerId,
+          modelId,
+          wireFamily: family,
+          endpointPath,
+          ...applyModelMetadataOverride(
+            resolveManualModelMetadata(providerId, modelId),
+            metadata,
+          ),
+          source: "manual",
+          sourceUpdatedAt: new Date(),
+          enabled: true,
+        })),
+      )
+      .onConflictDoUpdate({
+        target: [models.providerId, models.modelId, models.endpointPath],
+        set: {
+          wireFamily: sql`excluded.wire_family`,
+          contextLimit: sql`excluded.context_limit`,
+          outputLimit: sql`excluded.output_limit`,
+          modalities: sql`excluded.modalities`,
+          reasoning: sql`excluded.reasoning`,
+          toolCall: sql`excluded.tool_call`,
+          source: sql`'manual'`,
+          sourceUpdatedAt: sql`excluded.source_updated_at`,
+        },
+      });
+  }
+
+  /**
+   * One-shot connectivity probe and model discovery live in
+   * `services/provider-probing.ts` — the store only forwards so the domain
+   * `ProviderCatalogStore` interface is unchanged.
+   */
+  async probeModel(
+    tenantId: string,
+    providerId: string,
+    request: ProbeModelRequest,
+  ): Promise<ProbeModelResult> {
+    return this.probing.probeModel(tenantId, providerId, request);
+  }
+
+  /** Ad-hoc BYOK connectivity test; delegates to the shared probing service. */
+  async testByokConnection(
+    tenantId: string,
+    request: ByokConnectionTestRequest,
+  ): Promise<ByokConnectionTestResult> {
+    return this.probing.testByokConnection(tenantId, request);
+  }
+
+  /**
+   * Batched provider-wide probe: the first registered model runs sequentially
+   * (warms OAuth token / connection pools), the rest run concurrently bounded
+   * to 5. Registered model ids come from this store's own catalog read.
+   */
+  async probeAllModels(tenantId: string, providerId: string): Promise<ProbeAllModelsResult> {
+    const entries = await this.listModels(tenantId, providerId);
+    const requests = entries.map((entry) => ({
+      modelId: entry.modelId,
+      route: entry.route,
+      serviceKind: isServiceKind(entry.serviceKind) ? entry.serviceKind : ("llm" as const),
+    }));
+    const uniqueRequests = requests.filter(
+      (request, index, all) =>
+        all.findIndex(
+          (candidate) =>
+            candidate.modelId === request.modelId &&
+            candidate.route === request.route &&
+            candidate.serviceKind === request.serviceKind,
+        ) === index,
+    );
+    return this.probing.probeAllModels(tenantId, providerId, uniqueRequests);
+  }
+  async probeAllAccounts(
+    tenantId: string,
+    providerId: string,
+    request: ProbeModelRequest,
+): Promise<ProbeAllAccountsResult> {
+    return this.probing.probeAllAccounts(tenantId, providerId, request);
+  }
+  /** Toggles a persisted model's routing eligibility. */
+  async setModelEnabled(
+    tenantId: string,
+    providerId: string,
+    request: SetModelEnabledRequest,
+  ): Promise<boolean> {
+    // Tenant-owned (BYOK) model: toggle the shared row directly.
+    const owned = await this.db
+      .select({ id: models.id })
+      .from(models)
+      .innerJoin(providers, eq(models.providerId, providers.id))
+      .where(
+        and(
+          eq(models.providerId, providerId),
+          eq(models.modelId, request.modelId),
+          eq(models.endpointPath, request.route),
+          ownedByOnly(providers.tenantId, tenantId),
+        ),
+      )
+      .limit(1);
+    const ownedTarget = owned[0];
+    if (ownedTarget) {
+      await this.db
+        .update(models)
+        .set({ enabled: request.enabled })
+        .where(eq(models.id, ownedTarget.id));
+      return true;
+    }
+
+    // Global/built-in model: tenants cannot mutate the shared row, so record
+    // (or clear) a tenant-scoped disable in `tenantDisabledModels`.
+    const global = await this.db
+      .select({ id: models.id })
+      .from(models)
+      .innerJoin(providers, eq(models.providerId, providers.id))
+      .where(
+        and(
+          eq(models.providerId, providerId),
+          eq(models.modelId, request.modelId),
+          eq(models.endpointPath, request.route),
+          isNull(providers.tenantId),
+        ),
+      )
+      .limit(1);
+    if (global[0] === undefined) return false;
+    if (request.enabled) {
+      await this.db
+        .delete(tenantDisabledModels)
+        .where(
+          and(
+            eq(tenantDisabledModels.tenantId, tenantId),
+            eq(tenantDisabledModels.providerId, providerId),
+            eq(tenantDisabledModels.modelId, request.modelId),
+            eq(tenantDisabledModels.endpointPath, request.route),
+          ),
+        );
+      return true;
+    }
+    await this.db
+      .insert(tenantDisabledModels)
+      .values({
+        tenantId,
+        providerId,
+        modelId: request.modelId,
+        endpointPath: request.route,
+      })
+      .onConflictDoNothing({
+        target: [
+          tenantDisabledModels.tenantId,
+          tenantDisabledModels.providerId,
+          tenantDisabledModels.modelId,
+          tenantDisabledModels.endpointPath,
+        ],
+      });
+    return true;
+  }
+
+  /**
+   * Updates one model's limits and capability flags.
+   *
+   * Two row kinds are writable. A tenant-owned (BYOK) row is updated directly.
+   * A model belonging to a *global* provider row is also updated directly:
+   * bundled providers are seeded once with `tenant_id IS NULL` and `providers.id`
+   * is the primary key, so a bundled provider can only ever have that one row —
+   * there is no tenant-scoped row to edit instead. Auto-fetched rows
+   * (`discovered` / `auto_free`) live on exactly those providers, which is why
+   * the previous `ownedByOnly` filter answered `not_found` for every model the
+   * operator had just fetched and could not be edited at all.
+   *
+   * A global `builtin` row is rejected: it is re-seeded from the bundle on every
+   * boot, so an edit there would be silently reverted, and `deleteModel` refuses
+   * it for the same reason.
+   *
+   * Absent override fields leave the stored value untouched — an edit that only
+   * sets the context ceiling must not reset the capability flags.
+   */
+  async updateModelMetadata(
+    tenantId: string,
+    providerId: string,
+    request: UpdateModelMetadataRequest,
+  ): Promise<boolean> {
+    const findRow = (ownership: SQL) =>
+      this.db
+        .select({ id: models.id, modalities: models.modalities, source: models.source })
+        .from(models)
+        .innerJoin(providers, eq(models.providerId, providers.id))
+        .where(
+          and(
+            eq(models.providerId, providerId),
+            eq(models.modelId, request.modelId),
+            eq(models.endpointPath, request.route),
+            ownership,
+          ),
+        )
+        .limit(1);
+    const owned = await findRow(ownedByOnly(providers.tenantId, tenantId));
+    let row = owned[0];
+    if (row === undefined) {
+      const global = await findRow(isNull(providers.tenantId));
+      const candidate = global[0];
+      if (candidate === undefined) return false;
+      if (candidate.source === "builtin") {
+        throw new ConsoleDomainError(
+          "builtin_model_immutable",
+          403,
+          `Built-in model ${providerId}/${request.modelId} cannot be edited — the bundle re-seeds it on every boot`,
+        );
+      }
+      row = candidate;
+    }
+
+    const override = request.metadata;
+    const set: Record<string, unknown> = { sourceUpdatedAt: new Date() };
+    if (override?.contextLimit !== undefined) set.contextLimit = override.contextLimit;
+    if (override?.outputLimit !== undefined) set.outputLimit = override.outputLimit;
+    // Passthrough grants every capability and cannot be partly revoked by a
+    // per-flag field: the point of the flag is that the operator does not know
+    // which capabilities the model has, so an explicit `false` alongside it is
+    // either stale or a mistake.
+    if (override?.passthrough === true) {
+      set.reasoning = true;
+      set.toolCall = true;
+      set.modalities = withImageModality(asStoredText(row.modalities), true);
+    } else {
+      if (override?.reasoning !== undefined) set.reasoning = override.reasoning;
+      if (override?.toolCall !== undefined) set.toolCall = override.toolCall;
+      if (override?.image !== undefined)
+        set.modalities = withImageModality(asStoredText(row.modalities), override.image);
+    }
+    await this.db.update(models).set(set).where(eq(models.id, row.id));
+    return true;
+  }
+
+  async deleteModel(
+    tenantId: string,
+    providerId: string,
+    request: SetModelEnabledRequest,
+  ): Promise<boolean> {
+    const owned = await this.db
+      .select({ id: models.id })
+      .from(models)
+      .innerJoin(providers, eq(models.providerId, providers.id))
+      .where(
+        and(
+          eq(models.providerId, providerId),
+          eq(models.modelId, request.modelId),
+          eq(models.endpointPath, request.route),
+          ownedByOnly(providers.tenantId, tenantId),
+        ),
+      )
+      .limit(1);
+    const target = owned[0];
+    if (target) {
+      const rows = await this.db
+        .delete(models)
+        .where(eq(models.id, target.id))
+        .returning({ id: models.id });
+      return rows.length > 0;
+    }
+    const global = await this.db
+      .select({ id: models.id, source: models.source })
+      .from(models)
+      .innerJoin(providers, eq(models.providerId, providers.id))
+      .where(
+        and(
+          eq(models.providerId, providerId),
+          eq(models.modelId, request.modelId),
+          eq(models.endpointPath, request.route),
+          isNull(providers.tenantId),
+        ),
+      )
+      .limit(1);
+    if (!global[0]) return false;
+    // Built-in models are immutable catalog: tenants can only disable them
+    // (via tenantDisabledModels), never delete the shared row.
+    if (global[0].source === "builtin") {
+      throw new ConsoleDomainError(
+        "builtin_model_immutable",
+        403,
+        `Built-in model ${providerId}/${request.modelId} cannot be deleted — disable it instead`,
+      );
+    }
+    const rows = await this.db
+      .delete(models)
+      .where(eq(models.id, global[0].id))
+      .returning({ id: models.id });
+    await this.db
+      .delete(tenantDisabledModels)
+      .where(
+        and(
+          eq(tenantDisabledModels.tenantId, tenantId),
+          eq(tenantDisabledModels.providerId, providerId),
+          eq(tenantDisabledModels.modelId, request.modelId),
+          eq(tenantDisabledModels.endpointPath, request.route),
+        ),
+      );
+    return rows.length > 0;
+  }
+
+  private async accountsWithUsage(
+    tenantId: string,
+    rows: readonly (typeof providerAccounts.$inferSelect)[],
+  ): Promise<readonly ProviderAccountResponse[]> {
+    if (rows.length === 0) return [];
+    const todayStart = new Date();
+    todayStart.setUTCHours(0, 0, 0, 0);
+    const accountIds = rows.map((row) => row.id);
+    // Today's per-account usage is one GROUP BY, not a read of every event
+    // since midnight. `breakdownTelemetry("account")` is capped at 100 groups;
+    // a page of accounts never exceeds it, and the lookup below is by id, so a
+    // group that fell outside the cap simply reads as "no usage today" — the
+    // same value an account with no traffic gets.
+    const todayGroups = await breakdownTelemetry(this.db, tenantId, "account", todayStart);
+    const todayByAccount = new Map(
+      todayGroups.map((group) => [
+        group.key,
+        {
+          requests: group.requests,
+          errors: group.errors,
+          inputTokens: group.inputTokens,
+          outputTokens: group.outputTokens,
+        },
+      ]),
+    );
+    const [lifetimeRows] = await Promise.all([
+      this.db
+        .select()
+        .from(telemetryUsageTotals)
+        .where(
+          and(
+            eq(telemetryUsageTotals.tenantId, tenantId),
+            eq(telemetryUsageTotals.identityType, "account"),
+            inArray(telemetryUsageTotals.entityId, accountIds),
+          ),
+        ),
+    ]);
+    const lifetimeByAccount = new Map(lifetimeRows.map((row) => [row.entityId, row]));
+    const mapUsage = (row: {
+      readonly requests: number | string | null;
+      readonly errors: number | string | null;
+      readonly inputTokens: number | string | null;
+      readonly outputTokens: number | string | null;
+    } | undefined): ProviderAccountTokenUsage => {
+      const inputTokens = Number(row?.inputTokens ?? 0);
+      const outputTokens = Number(row?.outputTokens ?? 0);
+      return {
+        requests: Number(row?.requests ?? 0),
+        errors: Number(row?.errors ?? 0),
+        inputTokens,
+        outputTokens,
+        totalTokens: inputTokens + outputTokens,
+      };
+    };
+    const first = rows[0];
+    const inflightByAccount = await this.accountInflightFor(tenantId, first?.providerId);
+    return rows.map((row) => {
+      const inflight = inflightByAccount.get(row.id);
+      return this.mapAccount(row, {
+        today: mapUsage(todayByAccount.get(row.id)),
+        allTime: mapUsage(lifetimeByAccount.get(row.id)),
+        ...(inflight === undefined ? {} : { inflight }),
+      });
+    });
+  }
+
+  private async accountInflightFor(
+    tenantId: string,
+    providerId: string | undefined,
+  ): Promise<Map<string, number>> {
+    const readings = new Map<string, number>();
+    if (!this.readAccountInflight || !providerId) return readings;
+    const rows = await this.readAccountInflight(providerId, tenantId);
+    for (const row of rows) {
+      if (typeof row.accountId !== "string" || !Number.isFinite(row.inflight)) continue;
+      readings.set(row.accountId, Math.max(0, Math.floor(row.inflight)));
+    }
+    return readings;
+  }
+
+  /**
+   * Next free list position for a new account in this provider's list.
+   *
+   * Scoped to (provider, tenant) because the list is per provider: a tenant
+   * with accounts under two providers must not have the second provider's
+   * first account land at a high index.
+   */
+  /**
+   * Labels already in use for one provider, for numbering a generated name.
+   *
+   * Scoped to this provider and tenant: `dcint-key-1` and `other-key-1` belong
+   * to different providers and must not collide with each other.
+   */
+  private async generateAccountLabel(
+    db: CartethyiaDatabase | Parameters<Parameters<CartethyiaDatabase["transaction"]>[0]>[0],
+    providerId: string,
+    tenantId: string,
+    credentialMode: CredentialMode,
+  ): Promise<string> {
+    const rows = await db
+      .select({ label: providerAccounts.label })
+      .from(providerAccounts)
+      .where(
+        and(
+          eq(providerAccounts.providerId, providerId),
+          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+        ),
+      );
+    return nextGeneratedAccountLabel(
+      providerId,
+      credentialMode,
+      rows.map((row) => row.label).filter((label): label is string => typeof label === "string"),
+    );
+  }
+
+  private async nextAccountSortIndex(
+    db: CartethyiaDatabase | Parameters<Parameters<CartethyiaDatabase["transaction"]>[0]>[0],
+    providerId: string,
+    tenantId: string,
+  ): Promise<number> {
+    return nextSortIndex(
+      db,
+      { table: providerAccounts, idColumn: providerAccounts.id, sortIndexColumn: providerAccounts.sortIndex },
+      and(
+        eq(providerAccounts.providerId, providerId),
+        globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+      ),
+    );
+  }
+
+  /** Rewrites one provider's account order; `accountIds` is the full order. */
+  async reorderAccounts(
+    tenantId: string,
+    providerId: string,
+    accountIds: readonly string[],
+  ): Promise<void> {
+    await reorderSortIndex(
+      this.db,
+      { table: providerAccounts, idColumn: providerAccounts.id, sortIndexColumn: providerAccounts.sortIndex },
+      and(
+        eq(providerAccounts.providerId, providerId),
+        globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+      ),
+      accountIds,
+    );
+  }
+
+  async listAccountAuthStates(
+    tenantId: string,
+    providerId: string,
+    accountIds: readonly string[],
+  ): Promise<Readonly<Record<string, Readonly<Record<string, unknown>>>>> {
+    if (accountIds.length === 0) return {};
+    const rows = await this.db
+      .select({ id: providerAccounts.id, authState: providerAccounts.authState })
+      .from(providerAccounts)
+      .where(
+        and(
+          eq(providerAccounts.providerId, providerId),
+          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+          inArray(providerAccounts.id, accountIds),
+        ),
+      );
+    const out: Record<string, Readonly<Record<string, unknown>>> = {};
+    for (const row of rows) {
+      if (row.authState !== null && typeof row.authState === "object" && !Array.isArray(row.authState)) {
+        out[row.id] = row.authState as Record<string, unknown>;
+      }
+    }
+    return out;
+  }
+
+  async listAccounts(
+    tenantId: string,
+    providerId: string,
+  ): Promise<readonly ProviderAccountResponse[]> {
+    const rows = await this.db
+      .select()
+      .from(providerAccounts)
+      .where(
+        and(
+          eq(providerAccounts.providerId, providerId),
+          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+        ),
+      )
+      // Stable list position, not `created_at`: two accounts created in the
+      // same millisecond could swap between loads. `id` breaks a tie so the
+      // order is total even before a reorder assigns distinct indices.
+      .orderBy(asc(providerAccounts.sortIndex), asc(providerAccounts.createdAt), asc(providerAccounts.id));
+    return this.accountsWithUsage(tenantId, rows);
+  }
+
+  async listAllAccounts(tenantId: string): Promise<readonly ProviderAccountResponse[]> {
+    const rows = await this.db
+      .select()
+      .from(providerAccounts)
+      .where(globalOrOwnedBy(providerAccounts.tenantId, tenantId))
+      .orderBy(asc(providerAccounts.sortIndex), asc(providerAccounts.createdAt), asc(providerAccounts.id));
+    return this.accountsWithUsage(tenantId, rows);
+  }
+
+  async createAccount(
+    tenantId: string,
+    providerId: string,
+    request: CreateProviderAccountRequest,
+    existingTx?: Parameters<Parameters<CartethyiaDatabase["transaction"]>[0]>[0],
+    includeUsage = true,
+    sortIndexOverride?: number,
+  ): Promise<ProviderAccountResponse> {
+    // Callers inside an existing transaction pass it in so the account lands in
+    // that unit of work (the batch path); otherwise this opens its own.
+    const run = async (
+      tx: Parameters<Parameters<CartethyiaDatabase["transaction"]>[0]>[0],
+    ): Promise<ProviderAccountResponse> => {
+    let effectiveSecret = request.secret;
+        let effectiveCredentialKind = request.credentialKind;
+        const requestedCredentialMode: CredentialMode = request.credentialMode ?? "auto";
+        let effectiveCredentialMode: CredentialMode = requestedCredentialMode;
+        let tokenExpiresAt: Date | undefined;
+        let jwtIssuer: string | undefined;
+        let oauthRefreshCiphertext: Buffer | undefined;
+        let oauthExpiresAt: Date | undefined;
+        let oauthHasRefreshToken = false;
+        let pastedAuthState: Readonly<Record<string, unknown>> = {};
+
+        if (
+          (request.credentialKind === "oauth" || request.credentialKind === "api_key") &&
+          request.secret.trim().length > 0
+        ) {
+          const trimmed = request.secret.trim();
+          const parts = parsePastedOAuthCredential(trimmed);
+          pastedAuthState = parts.authState;
+          const hasRefreshToken = parts.refreshToken !== parts.accessToken;
+          const parsedJwt =
+            requestedCredentialMode === "api_key"
+              ? undefined
+              : parseJwtCredential(parts.accessToken);
+          if (requestedCredentialMode === "jwt" && parsedJwt === undefined) {
+            throw new ConsoleDomainError(
+              "invalid_request",
+              400,
+              "credentialMode jwt requires a valid three-part JWT",
+            );
+          }
+          if (requestedCredentialMode === "api_key") {
+            effectiveSecret = parts.accessToken;
+            effectiveCredentialKind = "api_key";
+            effectiveCredentialMode = "api_key";
+          } else if (
+            parsedJwt !== undefined &&
+            (requestedCredentialMode === "jwt" || !hasRefreshToken)
+          ) {
+            effectiveSecret = parts.accessToken;
+            effectiveCredentialKind = "api_key";
+            effectiveCredentialMode = "jwt";
+            tokenExpiresAt = parsedJwt.expiresAt;
+            // Kept alongside the expiry: the console shows who issued a static
+            // token, and the secret itself is never readable after this point.
+            jwtIssuer = parsedJwt.issuer;
+          } else if (request.credentialKind === "oauth" || hasRefreshToken) {
+            effectiveSecret = parts.accessToken;
+            effectiveCredentialKind = hasRefreshToken ? "oauth" : "api_key";
+            effectiveCredentialMode = hasRefreshToken ? "auto" : "api_key";
+            if (hasRefreshToken) {
+              oauthRefreshCiphertext = encryptCredential(parts.refreshToken);
+              oauthHasRefreshToken = true;
+            }
+            oauthExpiresAt = parts.expiresAt;
+          } else {
+            effectiveCredentialMode = "api_key";
+          }
+        }
+
+        // Append to the end of this provider's list rather than relying on
+        // creation time, so a new account never displaces existing positions.
+        const credentialFingerprint =
+          effectiveCredentialKind === "none" || effectiveSecret.length === 0
+            ? undefined
+            : hashSecret(effectiveSecret);
+        const accountAuthState = {
+          ...pastedAuthState,
+          ...(request.authState ?? {}),
+          credentialMode: effectiveCredentialMode,
+          ...(tokenExpiresAt === undefined ? {} : { tokenExpiresAt: tokenExpiresAt.toISOString() }),
+          ...(jwtIssuer === undefined ? {} : { jwtIssuer }),
+        };
+        const nextSortIndex =
+          sortIndexOverride ?? (await this.nextAccountSortIndex(tx, providerId, tenantId));
+        // Read existing labels only when one has to be generated: a named
+        // account costs no extra query, and this is the path a large batch
+        // paste walks once per row.
+        const label =
+          request.label ??
+          (await this.generateAccountLabel(tx, providerId, tenantId, effectiveCredentialMode));
+        const rows = await tx
+          .insert(providerAccounts)
+          .values({
+            providerId,
+            tenantId,
+            sortIndex: nextSortIndex,
+            label,
+            credentialCiphertext: encryptCredential(effectiveSecret),
+            ...(credentialFingerprint ? { credentialFingerprint } : {}),
+            credentialKind: effectiveCredentialKind,
+            status: "active",
+            authState: accountAuthState,
+            // An OAuth account pasted without a refresh token is a *static*
+            // token: the pasted value is a bearer token used exactly as issued
+            // and there is no refresh grant to run. Flag it as static so the
+            // console reads it as an informational "static token" rather than
+            // "re-login required" — the token is still valid and dispatchable —
+            // and so the refresh sweep skips it instead of retrying a refresh
+            // that can never succeed.
+            ...(effectiveCredentialKind === "oauth" && !oauthHasRefreshToken || effectiveCredentialMode === "jwt"
+              ? { staticToken: true }
+              : {}),
+          })
+          .returning();
+        const row = rows[0];
+        if (!row) throw new Error("failed to create provider account");
+
+        if (effectiveCredentialKind === "oauth") {
+          await tx.insert(providerOauthStates).values({
+            providerAccountId: row.id,
+            ...(oauthRefreshCiphertext ? { refreshCiphertext: oauthRefreshCiphertext } : {}),
+            expiresAt: oauthExpiresAt ?? null,
+          });
+        }
+        if (request.credentialKind === "oauth" && !oauthHasRefreshToken) {
+          pushStructuredConsoleLog(
+            "info",
+            "OAuth access token stored as a static API credential; it will not be refreshed",
+            {
+              event: "token_refresh",
+              providerId,
+              accountId: row.id,
+              errorCode: "static_token",
+            },
+          );
+        }
+
+        if (!includeUsage) {
+          const emptyUsage = { requests: 0, errors: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+          return this.mapAccount(row, { today: emptyUsage, allTime: emptyUsage });
+        }
+        const [account] = await this.accountsWithUsage(tenantId, [row]);
+        if (!account) throw new Error("created provider account could not be mapped");
+        return account;
+    };
+
+    try {
+      if (existingTx !== undefined) {
+        return await run(existingTx);
+      }
+      return await this.db.transaction(run);
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new ConsoleDomainError(
+          "provider_account_duplicate",
+          409,
+          "A provider account with this credential already exists",
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Creates many accounts in one round-trip.
+   *
+   * The whole batch shares one transaction, so a paste of 40 credentials costs
+   * one connection checkout rather than 40. Each item is created through the
+   * same `createAccount` path the single route uses — there is no second
+   * implementation of credential detection to drift.
+   *
+   * Items are created sequentially inside that transaction: the unique
+   * credential fingerprint makes two identical pastes collide, and a nested
+   * transaction per item keeps that collision from aborting the whole batch.
+   * Outcomes are reported per index, so a partial paste still lands the
+   * accounts that were fine — an operator fixing one bad line should not have
+   * to re-import 39.
+   */
+  async createAccountBatch(
+    tenantId: string,
+    providerId: string,
+    requests: readonly CreateProviderAccountRequest[],
+  ): Promise<CreateProviderAccountBatchResult> {
+    if (requests.length === 0) {
+      return { created: 0, failed: 0, results: [] };
+    }
+    const results: CreateProviderAccountBatchItemResult[] = [];
+    let created = 0;
+    let failed = 0;
+
+    await this.db.transaction(async (tx) => {
+      let nextSortIndex = await this.nextAccountSortIndex(tx, providerId, tenantId);
+      for (const [index, request] of requests.entries()) {
+        try {
+          // A nested transaction acts as a savepoint: a duplicate-fingerprint
+          // violation rolls back only this item, not the accounts before it.
+          const account = await tx.transaction(async (inner) =>
+            this.createAccount(tenantId, providerId, request, inner, false, nextSortIndex),
+          );
+          created += 1;
+          nextSortIndex += 1;
+          results.push({ index, ok: true, ...(account ? { account } : {}) });
+        } catch (error) {
+          failed += 1;
+          results.push({
+            index,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+            code: error instanceof ConsoleDomainError ? error.code : "create_failed",
+          });
+        }
+      }
+    });
+
+    return { created, failed, results };
+  }
+
+  async updateAccount(
+    tenantId: string,
+    providerId: string,
+    accountId: string,
+    patch: UpdateProviderAccountRequest,
+  ): Promise<ProviderAccountResponse | undefined> {
+    const set: Partial<typeof providerAccounts.$inferInsert> = {};
+    if (patch.label !== undefined) set.label = patch.label;
+    if (patch.secret !== undefined) {
+      set.credentialCiphertext = encryptCredential(patch.secret);
+      set.credentialFingerprint =
+        patch.secret.length === 0 ? null : hashSecret(patch.secret);
+    }
+    if (patch.status !== undefined) set.status = patch.status;
+    // Toggling the static-token flag: turning it on declares the credential is
+    // used as issued and never refreshed, so any stale re-auth flag is cleared —
+    // the operator has said the account is fine, and the pill must stop reading
+    // "Re-login required". Turning it off returns the account to normal OAuth
+    // refresh handling; the sweep picks it up again on its next pass.
+    if (patch.staticToken !== undefined) {
+      set.staticToken = patch.staticToken;
+      if (patch.staticToken) {
+        set.lastError = null;
+        set.lastErrorCategory = null;
+        set.lastErrorAt = null;
+      }
+    }
+    // Status toggles are not recovery: preserve the health machine's evidence
+    // until the operator uses Recover or replaces the rejected credential.
+    const clearsFailureState = patch.secret !== undefined && patch.secret.length > 0;
+    if (clearsFailureState) {
+      set.consecutiveFailures = 0;
+      set.cooldownUntil = null;
+      set.modelCooldowns = {};
+      set.lastError = null;
+      set.lastErrorCategory = null;
+      set.lastErrorAt = null;
+    }
+    const where = and(
+      eq(providerAccounts.id, accountId),
+      eq(providerAccounts.providerId, providerId),
+      globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+    );
+    try {
+      const rows =
+        Object.keys(set).length > 0
+          ? await this.db.update(providerAccounts).set(set).where(where).returning()
+          : await this.db.select().from(providerAccounts).where(where);
+      const row = rows[0];
+      if (!row) return undefined;
+      // Secret/status mutation: drop any cached credential so the next
+      // attempt decrypts the new ciphertext (or refuses a disabled account).
+      if (patch.secret !== undefined || patch.status !== undefined) {
+        invalidateCredentialCache(accountId);
+      }
+      const [account] = await this.accountsWithUsage(tenantId, [row]);
+      return account;
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new ConsoleDomainError(
+          "provider_account_duplicate",
+          409,
+          "A provider account with this credential already exists",
+        );
+      }
+      throw error;
+    }
+  }
+
+  private mapAccount(
+    row: typeof providerAccounts.$inferSelect,
+    usage: {
+      readonly today: ProviderAccountTokenUsage;
+      readonly allTime: ProviderAccountTokenUsage;
+      readonly inflight?: number | undefined;
+    },
+  ): ProviderAccountResponse {
+    const authState =
+      row.authState !== null && typeof row.authState === "object" && !Array.isArray(row.authState)
+        ? (row.authState as Record<string, unknown>)
+        : undefined;
+    const rawCredentialMode = authState?.["credentialMode"];
+    const credentialMode: CredentialMode | undefined =
+      rawCredentialMode === "auto" || rawCredentialMode === "jwt" || rawCredentialMode === "api_key"
+        ? rawCredentialMode
+        : undefined;
+    const tokenExpiresAt =
+      typeof authState?.["tokenExpiresAt"] === "string" ? authState["tokenExpiresAt"] : undefined;
+    const jwtIssuer =
+      typeof authState?.["jwtIssuer"] === "string" ? authState["jwtIssuer"] : undefined;
+    return {
+      id: row.id,
+      providerId: row.providerId,
+      tenantId: row.tenantId,
+      label: row.label,
+      credentialKind: row.credentialKind,
+      ...(credentialMode === undefined ? {} : { credentialMode }),
+      ...(tokenExpiresAt === undefined ? {} : { tokenExpiresAt }),
+      ...(jwtIssuer === undefined ? {} : { jwtIssuer }),
+      status: row.status,
+      ...(usage.inflight === undefined ? {} : { inflight: usage.inflight }),
+      usageToday: usage.today,
+      usageAllTime: usage.allTime,
+      consecutiveFailures: row.consecutiveFailures,
+      ...(row.lastSuccessAt ? { lastSuccessAt: row.lastSuccessAt.toISOString() } : {}),
+      ...(row.lastError ? { lastError: row.lastError } : {}),
+      ...(row.lastErrorCategory ? { lastErrorCategory: row.lastErrorCategory } : {}),
+      ...(row.lastErrorAt ? { lastErrorAt: row.lastErrorAt.toISOString() } : {}),
+      ...(row.cooldownUntil ? { cooldownUntil: row.cooldownUntil.toISOString() } : {}),
+      ...(liveModelCooldowns(row.modelCooldowns) ?? {}),
+      ...(row.lastRecoveredAt ? { lastRecoveredAt: row.lastRecoveredAt.toISOString() } : {}),
+      createdAt: row.createdAt.toISOString(),
+      sortIndex: row.sortIndex,
+      ...(row.staticToken ? { staticToken: true } : {}),
+    };
+  }
+
+  async listAccountHealthEvents(
+    tenantId: string,
+    providerId: string,
+    accountId: string,
+  ): Promise<readonly AccountHealthEventRecord[]> {
+    const owned = await this.db
+      .select({ id: providerAccounts.id })
+      .from(providerAccounts)
+      .where(
+        and(
+          eq(providerAccounts.id, accountId),
+          eq(providerAccounts.providerId, providerId),
+          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+        ),
+      )
+      .limit(1);
+    if (owned.length === 0) return [];
+    return listAccountHealthEvents(this.db, accountId);
+  }
+
+  /** Deletes one account's stored health & error rows, for the modal's purge. */
+  async purgeAccountHealthEvents(
+    tenantId: string,
+    providerId: string,
+    accountId: string,
+  ): Promise<number> {
+    const owned = await this.db
+      .select({ id: providerAccounts.id })
+      .from(providerAccounts)
+      .where(
+        and(
+          eq(providerAccounts.id, accountId),
+          eq(providerAccounts.providerId, providerId),
+          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+        ),
+      )
+      .limit(1);
+    if (owned.length === 0) return 0;
+    return deleteAccountHealthEvents(this.db, accountId);
+  }
+  async listBuddyGrowthTasks(
+    tenantId: string,
+    providerId: string,
+    accountId: string,
+    dayKey: string,
+  ): Promise<readonly BuddyGrowthTaskLedgerEntry[]> {
+    const owned = await this.db
+      .select({ id: providerAccounts.id })
+      .from(providerAccounts)
+      .where(
+        and(
+          eq(providerAccounts.id, accountId),
+          eq(providerAccounts.providerId, providerId),
+          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+        ),
+      )
+      .limit(1);
+    if (owned.length === 0) return [];
+    const rows = await this.db
+      .select({
+        accountId: buddyTaskLedger.accountId,
+        task: buddyTaskLedger.task,
+        claimedAt: buddyTaskLedger.claimedAt,
+      })
+      .from(buddyTaskLedger)
+      .where(
+        and(
+          eq(buddyTaskLedger.accountId, accountId),
+          eq(buddyTaskLedger.dayKey, dayKey),
+        ),
+      );
+    return rows.map((row) => ({
+      accountId: row.accountId,
+      task: row.task,
+      claimedAt: row.claimedAt.toISOString(),
+    }));
+  }
+
+  async recoverAccount(
+    tenantId: string,
+    providerId: string,
+    accountId: string,
+  ): Promise<boolean> {
+    const owned = await this.db
+      .select({ id: providerAccounts.id })
+      .from(providerAccounts)
+      .where(
+        and(
+          eq(providerAccounts.id, accountId),
+          eq(providerAccounts.providerId, providerId),
+          globalOrOwnedBy(providerAccounts.tenantId, tenantId),
+        ),
+      )
+      .limit(1);
+    if (owned.length === 0) return false;
+    return recoverAccount(this.db, accountId, "manual_operator_recovery");
+  }
+
+
+  async syncModels(tenantId: string, providerId: string): Promise<{ synced: number }> {
+    return this.probing.syncModels(tenantId, providerId);
+  }
+}