cartethyia 2.5.9 → 2.6.0

package/src/console/backup/store.ts

@@ -32,7 +32,8 @@
 import { and, eq, sql } from "drizzle-orm";
 import { gzipSync, gunzipSync } from "node:zlib";
 import { differsFrom } from "../../persistence/dialect";
-import { readTelemetryEvents, TELEMETRY_EVENT_DIR } from "../../observability/event-log";
+import { TELEMETRY_EVENT_DIR } from "../../observability/event-log";
+import { queryTelemetryEvents as querySqlEvents } from "../../observability/event-query";
 import { appendFile, mkdir } from "node:fs/promises";
 import { getTableColumns, type Column, type SQL, type Table } from "drizzle-orm";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
@@ -294,7 +295,7 @@ export async function exportBackup(
   const reads = tables.map(async (table) =>
     [
       table,
-      table === telemetryEvents ? await exportEventFile(tenantId) : await exportTable(db, table, tenantId),
+      table === telemetryEvents ? await exportEventFile(db, tenantId) : await exportTable(db, table, tenantId),
     ] as const,
   );
   // Preserve the caller's `tables` order when writing into the output maps so
@@ -373,10 +374,12 @@ export function decompressBackup(bytes: Uint8Array): string {
  * backup contract still names. The table is no longer written, so reading it
  * would export nothing.
  */
-async function exportEventFile(tenantId: string): Promise<readonly BackupRow[]> {
-  const events = await readTelemetryEvents();
-  return events
-    .filter((event) => event.tenantId === tenantId)
+async function exportEventFile(db: CartethyiaDatabase, tenantId: string): Promise<readonly BackupRow[]> {
+  // The SQL table is the durable record now, and it is tenant-scoped and
+  // retained by the same rule as the raw files — so the export reads it
+  // instead of scanning every raw file and filtering by tenant afterwards.
+  const page = await querySqlEvents(db, { tenantId, limit: MAX_ROWS_PER_TABLE });
+  return page.events
     .slice(0, MAX_ROWS_PER_TABLE)
     .map((event) => {
       const row: BackupRow = {};
@@ -465,13 +468,15 @@ function createdAtIso(value: unknown): string {
  * so the two sides are comparable regardless of how the driver types them.
  */
 /** Natural keys already present in the event file, so a re-import skips them. */
-async function existingEventFileKeys(rows: readonly BackupRow[]): Promise<Set<string>> {
+async function existingEventFileKeys(db: CartethyiaDatabase, tenantId: string, rows: readonly BackupRow[]): Promise<Set<string>> {
   const wanted = new Set(rows.map((row) => row.request_id).filter((id): id is string => typeof id === "string"));
   if (wanted.size === 0) return new Set();
-  const events = await readTelemetryEvents();
+  // One indexed query for the ids being restored, instead of reading every
+  // raw file to test membership. `id = request_id`, so the unique index serves
+  // this directly.
+  const page = await querySqlEvents(db, { tenantId, requestIds: [...wanted] });
   return new Set(
-    events
-      .filter((event) => wanted.has(event.requestId))
+    page.events
       .map((event) => `${event.tenantId ?? ""}\u0000${event.requestId}\u0000${event.createdAt}`),
   );
 }
@@ -832,7 +837,7 @@ export async function applyRestore(
       const entry = validation.tables.get(table);
       if (entry === undefined) continue;
       if (table === telemetryEvents) {
-        const existing = await existingEventFileKeys(entry.rows);
+        const existing = await existingEventFileKeys(db, tenantId, entry.rows);
         const fresh = entry.rows.filter((row) => !existing.has(telemetryKey(row)));
         await appendRestoredEvents(fresh);
         restored[tableName(table)] = fresh.length;

package/src/console/backup/validate.ts

@@ -13,6 +13,7 @@
  */
 import type { Table } from "drizzle-orm";
 import { getTableColumns } from "drizzle-orm";
+import { isRecord as isPlainObject } from "../../protocol/codecs";
 import { decryptCredentialToString } from "../../security/crypto";
 import {
   BACKUP_APP,
@@ -100,10 +101,6 @@ function normalizeLegacyCiphertext(table: Table, row: Record<string, unknown>):
   return normalized;
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** Column name → its Drizzle data type, so validation knows what may nest. */
 function columnTypes(table: Table): ReadonlyMap<string, string> {
   const out = new Map<string, string>();

package/src/console/cli-tools/fs-ops.ts

@@ -11,8 +11,24 @@ import { homedir, platform } from "node:os";
 import { join } from "node:path";
 import { mkdir, rm } from "node:fs/promises";
 
-/** Home directory — shared contract used by all injectors. */
-export { homedir as homeDir };
+/**
+ * Home directory — shared contract used by all injectors.
+ *
+ * Reads the environment on every call rather than exporting `os.homedir()`,
+ * whose value is cached at first use. That cache silently broke the redirect
+ * this module documents: a test that pointed `HOME` at a temp dir had its
+ * first path resolved correctly and every later one resolved to the home that
+ * was live when the process started — and on Linux that is the only value
+ * `os.homedir()` ever returns, so injectors wrote to the real home while the
+ * assertions read a temp dir that `afterEach` had already deleted.
+ *
+ * Production behaviour is unchanged: `HOME`/`USERPROFILE` are still what
+ * decide the directory, so an operator's environment is honoured as before.
+ */
+export function homeDir(): string {
+  const fromEnv = process.env.HOME ?? process.env.USERPROFILE;
+  return fromEnv && fromEnv.length > 0 ? fromEnv : homedir();
+}
 export { join };
 
 const IS_WIN: boolean = platform() === "win32";

package/src/console/data-management/contracts.ts

@@ -19,7 +19,7 @@
 /** One measured category of on-disk data. */
 export interface DiskUsageBucket {
   /** Stable id, so the dashboard can key rows without matching on copy. */
-  readonly id: "telemetry_events" | "telemetry_index" | "payload_frames";
+  readonly id: "telemetry_events" | "payload_frames";
   readonly label: string;
   readonly bytes: number;
   readonly files: number;
@@ -37,13 +37,6 @@ export interface DiskUsageResponse {
   readonly retentionDays: number;
   /** Payload frames live this long by default before they are reclaimable. */
   readonly payloadRetentionMs: number;
-  /**
-   * The longest retention a tenant may have chosen. A frame is only counted as
-   * reclaimable once it is older than *this*, because a tenant who raised the
-   * window has frames the default would call dead while their rows still
-   * address them.
-   */
-  readonly payloadRetentionMaxMs: number;
   /**
    * Stored health & error rows, for the purge row's label. Absent when the
    * composition does not wire the health-event store (a reduced console),

package/src/console/data-management/operations.ts

@@ -1,6 +1,7 @@
 import { readdir, stat, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { payloadDirectory, prunePayloadFrames } from "../../observability/payload-store";
+import { payloadPruneBound } from "../../observability/payload-capture";
 import type {
   DiskUsageBucket,
   DiskUsageResponse,
@@ -9,6 +10,7 @@ import type {
   ReclaimResponse,
 } from "./contracts";
 import { PurgeNotWiredError, ReclaimNotAllowedError } from "./contracts";
+import { hourStamp } from "../../shared/time";
 
 /**
  * Reads and reclaims the on-disk telemetry and payload directories, and
@@ -33,14 +35,16 @@ import { PurgeNotWiredError, ReclaimNotAllowedError } from "./contracts";
 export interface DataManagementConfig {
   readonly telemetryDir: string;
   readonly retentionDays: number;
-  readonly payloadRetentionMs: number;
   /**
-   * The longest payload retention a tenant may have chosen, and therefore the
-   * only cutoff a frame file can be judged dead against without reading it.
-   * Defaults to `payloadRetentionMs` for callers that predate per-tenant
-   * retention, which is then the true ceiling in that deployment.
+   * How long a payload frame lives, for one tenant.
+   *
+   * A function of the tenant, not a number: the Request detail window in
+   * Settings is per tenant, and a single deployment-level number made this
+   * panel report the deployment default while the gateway applied the tenant's
+   * own window. The same panel then offered to reclaim frames the gateway
+   * still considered live, and left alone ones it had already expired.
    */
-  readonly payloadRetentionMaxMs?: number;
+  readonly payloadRetentionMs: (tenantId: string | null) => Promise<number>;
   /**
    * The health & error log store, backing the console's only row-level purge.
    * Absent (a reduced console composition) means the purge is not offered
@@ -78,13 +82,37 @@ async function scan(
   return { bytes, files };
 }
 
-const isIndex = (name: string): boolean => name.endsWith(".index.json");
-const isHourly = (name: string): boolean => name.endsWith(".events.jsonl");
+const isEventLog = (name: string): boolean =>
+  name.endsWith(".jsonl") && !name.endsWith(".compacted.jsonl");
 const isFrame = (name: string): boolean =>
   name.endsWith(".jsonl");
 
+/**
+ * A duration in minutes as the operator's own units, not raw milliseconds.
+ *
+ * An hour is "1 hour" rather than "60 min" because that is how the window was
+ * chosen — the dropdown they picked it from says "1 hour", and a note that
+ * renders the same choice as "60 min" makes the two screens disagree about
+ * what was set.
+ */
+function formatMinutes(ms: number): string {
+  const minutes = Math.round(ms / 60_000);
+  if (minutes % 1440 === 0) {
+    const days = minutes / 1440;
+    return `${days} day${days === 1 ? "" : "s"}`;
+  }
+  if (minutes % 60 === 0) {
+    const hours = minutes / 60;
+    return `${hours} hour${hours === 1 ? "" : "s"}`;
+  }
+  return `${minutes} min`;
+}
+
 /** The UTC day a telemetry file name starts with, compared to a cutoff. */
-function dayBefore(name: string, cutoff: number): boolean {
+function eventBefore(name: string, cutoff: number): boolean {
+  if (!name.endsWith(".events.jsonl")) {
+    return name.slice(0, 13) < hourStamp(new Date(cutoff));
+  }
   const at = Date.parse(`${name.slice(0, 10)}T00:00:00Z`);
   return Number.isFinite(at) && at < cutoff;
 }
@@ -92,55 +120,47 @@ function dayBefore(name: string, cutoff: number): boolean {
 export function createDataManagementOperations(config: DataManagementConfig) {
   const payloadDir = (): string => payloadDirectory();
   /**
-   * The only cutoff a frame file can be judged dead against without parsing it.
+   * Disk usage for one tenant.
    *
-   * A file's mtime says when it was last written, not what its frames' tenants
-   * chose — so a file written an hour ago can hold a frame with a week to live.
-   * The ceiling is therefore the bound, and the default retention is only used
-   * when no ceiling was configured.
+   * `tenantId` is required because the payload window is a per-tenant setting:
+   * counting "stale" frames against the deployment default declared frames
+   * stale while the gateway still held them as live, and under-counted them
+   * for a tenant that had shortened its window.
    */
-  const payloadMax = (): number => config.payloadRetentionMaxMs ?? config.payloadRetentionMs;
-
-  async function usage(): Promise<DiskUsageResponse> {
-    const retentionCutoff = Date.now() - config.retentionDays * 24 * 60 * 60_000;
-    const payloadCutoff = Date.now() - payloadMax();
+  async function usage(tenantId: string | null): Promise<DiskUsageResponse> {
+    const retentionMs = await config.payloadRetentionMs(tenantId);
+    const payloadCutoff = Date.now() - retentionMs;
 
-    const [hourly, compacted, staleCompacted, frames, staleFrames, healthEventCount] = await Promise.all([
-      scan(config.telemetryDir, isHourly),
-      scan(config.telemetryDir, isIndex),
-      scan(config.telemetryDir, (name) => isIndex(name) && dayBefore(name, retentionCutoff)),
+    const [events, frames, staleFrames, healthEventCount] = await Promise.all([
+      scan(config.telemetryDir, isEventLog),
       scan(payloadDir(), isFrame),
       scan(payloadDir(), isFrame, payloadCutoff),
       config.healthEvents?.count(),
     ]);
 
+    /*
+     * The notes name the same knobs Operations exposes, read at request time
+     * rather than written into the copy. A fixed "15 min" was wrong the moment
+     * an operator changed the tenant's window: the panel kept quoting the
+     * deployment default while the gateway applied their number, so the one
+     * place that could correct the assumption repeated it.
+     */
     const buckets: DiskUsageBucket[] = [
       {
         id: "telemetry_events",
         label: "Request event files",
-        bytes: hourly.bytes,
-        files: hourly.files,
-        note: "Feeds the request list and detail drawer.",
+        bytes: events.bytes,
+        files: events.files,
+        note: `Feeds the request list and detail drawer. Kept ${config.retentionDays} days.`,
         reclaimableBytes: null,
         reclaimableFiles: null,
       },
-      {
-        id: "telemetry_index",
-        label: "Day indexes",
-        bytes: compacted.bytes,
-        files: compacted.files,
-        note: "Feeds usage totals, breakdowns and the chart.",
-        reclaimableBytes: staleCompacted.bytes,
-        reclaimableFiles: staleCompacted.files,
-      },
       {
         id: "payload_frames",
         label: "Payload frames",
         bytes: frames.bytes,
         files: frames.files,
-        note: `Captured bodies, expiring ${Math.round(
-          config.payloadRetentionMs / 60_000,
-        )} min after write by default.`,
+        note: `Captured bodies, expiring ${formatMinutes(retentionMs)} after write.`,
         reclaimableBytes: staleFrames.bytes,
         reclaimableFiles: staleFrames.files,
       },
@@ -150,8 +170,7 @@ export function createDataManagementOperations(config: DataManagementConfig) {
       buckets,
       totalBytes: buckets.reduce((sum, bucket) => sum + bucket.bytes, 0),
       retentionDays: config.retentionDays,
-      payloadRetentionMs: config.payloadRetentionMs,
-      payloadRetentionMaxMs: payloadMax(),
+      payloadRetentionMs: retentionMs,
       ...(healthEventCount === undefined ? {} : { healthEventCount }),
     };
   }
@@ -168,10 +187,7 @@ export function createDataManagementOperations(config: DataManagementConfig) {
       // written after that bound might still hold a live frame in the part
       // that failed to parse, so it is left for a later pass.
       const now = new Date();
-      const deletedFiles = await prunePayloadFrames(
-        now,
-        new Date(now.getTime() - payloadMax()),
-      );
+      const deletedFiles = await prunePayloadFrames(now, payloadPruneBound(now));
       const after = await scan(payloadDir(), isFrame);
       return {
         action,
@@ -180,12 +196,9 @@ export function createDataManagementOperations(config: DataManagementConfig) {
       };
     }
     if (action === "telemetry_retention") {
-      // Only day indexes past retention, and only together with their events.
-      // Deleting one without the other is the failure this avoids: an index
-      // with no events reports totals for requests that are gone.
       const cutoff = Date.now() - config.retentionDays * 24 * 60 * 60_000;
       return unlinkWhere(action, config.telemetryDir, (name) =>
-        (isIndex(name) || isHourly(name)) && dayBefore(name, cutoff),
+        isEventLog(name) && eventBefore(name, cutoff),
       );
     }
     throw new ReclaimNotAllowedError(`Unknown reclaim action: ${action}`);

package/src/console/data-management/routes.ts

@@ -46,8 +46,10 @@ export function createDataManagementRoutes(
     .get("/usage", async ({ request, set }) => {
       try {
         const access = requireAnyScope(config.accessResolver(request), WRITE_SCOPES);
-        void access;
-        return await operations.usage();
+        // The tenant decides the payload window, so the scan needs it: the
+        // count of reclaimable frames is measured against that tenant's own
+        // retention, not the deployment's.
+        return await operations.usage(access.tenantId ?? null);
       } catch (error) {
         return errorResponse(error, set, "Could not read disk usage");
       }

package/src/console/domain-registration.ts

@@ -5,6 +5,8 @@ import { createAccountQuotaRoutes } from "./quota/account-quota";
 import { createApiKeyRoutes } from "./api-keys/routes";
 import { familyBucketSpend } from "./api-keys/bucket-spend";
 import { createProviderCatalogRoutes } from "./providers/catalog/routes";
+import { createInferhubRoutes } from "./inferhub/routes";
+import { createInferhubKeyStore } from "./inferhub/key-store";
 import {
   createProviderDetailRoutes,
 } from "./providers/detail/routes";
@@ -43,7 +45,7 @@ import { createBackupRoutes } from "./backup/routes";
 import { BackupService } from "./backup/service";
 import type { ConsoleCredentialService } from "./auth/credentials";
 import { resolveTelemetryRetentionDays } from "../config/telemetry";
-import { MAX_PAYLOAD_RETENTION_MS, payloadRetentionMs } from "../observability/payload-capture";
+import { payloadRetentionMs, resolvePayloadCapture } from "../observability/payload-capture";
 import { TELEMETRY_EVENT_DIR } from "../observability/event-log";
 
 import { InMemoryOAuthFlowStore, OAuthFlowStore } from "../providers/authentication/oauth-flow-store";
@@ -249,6 +251,14 @@ export function registerConsoleDomains(
     service: createRemoteSupportService({ port: resolvePort() }),
   }));
   console.use(createAuditRoutes({ store: auditReadStore, accessResolver: ctx.accessResolver }));
+  // InferHub market data. On demand only: a route fetches when its snapshot is
+  // past its freshness window, so a page nobody opens causes no upstream calls.
+  const inferhubKeys = createInferhubKeyStore(ctx.db);
+  console.use(createInferhubRoutes({
+    accessResolver: ctx.accessResolver,
+    resolveConfigKey: () => inferhubKeys.read(),
+    keyStore: inferhubKeys,
+  }));
   if (ctx.modelStrikes) {
     console.use(createModelAbuseRoutes({
       strikes: ctx.modelStrikes,
@@ -293,8 +303,20 @@ export function registerConsoleDomains(
     createDataManagementRoutes({
       telemetryDir: TELEMETRY_EVENT_DIR,
       retentionDays: resolveTelemetryRetentionDays(),
-      payloadRetentionMs: payloadRetentionMs(),
-      payloadRetentionMaxMs: MAX_PAYLOAD_RETENTION_MS,
+      /*
+       * Resolved per tenant, not once at boot: the Request detail window is a
+       * per-tenant setting, and this panel is the only place that reports the
+       * number back. A deployment-level value made it show the default while
+       * the gateway applied the tenant's own window.
+       *
+       * It goes through the same `resolvePayloadCapture` the dispatch path
+       * uses, so the panel and the gateway cannot disagree about how long a
+       * frame lives.
+       */
+      payloadRetentionMs: async (tenantId) => {
+        const resolved = await resolvePayloadCapture(ctx.db, tenantId);
+        return resolved.ok ? resolved.retentionMs : payloadRetentionMs();
+      },
       accessResolver: ctx.accessResolver,
       auditSink: ctx.auditRecorder,
       flusher: ctx.flushBuffers,

package/src/console/inferhub/client.ts

@@ -0,0 +1,139 @@
+/**
+ * InferHub management-API client.
+ *
+ * Called only from route handlers — there is no scheduler, no poller, and no
+ * background loop anywhere in this design. A page that nobody opens issues no
+ * requests.
+ *
+ * Two constraints the API imposes:
+ * - The documented budget is 30 req/min per account for Management + MCP. All
+ *   calls share one bucket capped at 20/min to leave headroom, and the public
+ *   endpoints are assumed to share it because the docs do not prove otherwise.
+ * - Every value here is untrusted remote data. A response is parsed defensively
+ *   and a failure returns `undefined` — never a half-parsed object that a route
+ *   would render as if it were good.
+ */
+import { createValidatedFetch, type ValidatedFetch } from "../../network/outbound-fetch";
+
+export const INFERHUB_API_BASE = "https://inferhub.dev/api";
+
+/** Leave headroom under the documented 30/min Management budget. */
+const RATE_LIMIT_PER_MINUTE = 20;
+const RATE_LIMIT_WINDOW_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+/** Bounded: one retry, and only when the server asked us to wait. */
+const MAX_ATTEMPTS = 2;
+
+/** One shared bucket for every management call this process makes. */
+interface Bucket {
+  windowStart: number;
+  used: number;
+}
+const bucket: Bucket = { windowStart: Date.now(), used: 0 };
+
+function takeToken(now: number): boolean {
+  if (now - bucket.windowStart >= RATE_LIMIT_WINDOW_MS) {
+    bucket.windowStart = now;
+    bucket.used = 0;
+  }
+  if (bucket.used >= RATE_LIMIT_PER_MINUTE) return false;
+  bucket.used += 1;
+  return true;
+}
+
+/** Test seam: lets a test drive the bucket without waiting a minute. */
+export function __resetRateLimit(now: number = Date.now()): void {
+  bucket.windowStart = now;
+  bucket.used = 0;
+}
+
+export interface InferhubClientOptions {
+  /** `config_read` key; required for `/catalog`, ignored by the public endpoints. */
+  readonly configKey?: string | undefined;
+  readonly fetchFn?: ValidatedFetch | typeof fetch;
+  readonly now?: () => number;
+}
+
+export class InferhubRateLimited extends Error {
+  constructor() {
+    super("inferhub management rate limit reached");
+    this.name = "InferhubRateLimited";
+  }
+}
+
+/**
+ * One management GET.
+ *
+ * Returns `undefined` for any non-2xx, timeout, rate-limit exhaustion, or parse
+ * failure. A caller that gets `undefined` keeps its last good snapshot, so a
+ * transient upstream problem never blanks an operator's view.
+ */
+async function get(
+  path: string,
+  options: InferhubClientOptions,
+): Promise<unknown> {
+  const now = options.now?.() ?? Date.now();
+  if (!takeToken(now)) return undefined;
+
+  const fetchFn = (options.fetchFn ?? createValidatedFetch()) as ValidatedFetch;
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (options.configKey !== undefined && options.configKey.length > 0)
+    headers.authorization = `Bearer ${options.configKey}`;
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const response = await fetchFn(`${INFERHUB_API_BASE}${path}`, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+      if (response.status === 429) {
+        // Honor `Retry-After` rather than retrying immediately, but only once:
+        // the bounded loop is the guard against a retry storm.
+        const retryAfter = Number(response.headers.get("retry-after"));
+        if (attempt < MAX_ATTEMPTS && Number.isFinite(retryAfter) && retryAfter > 0) {
+          await new Promise((resolve) => setTimeout(resolve, Math.min(retryAfter * 1000, 5_000)));
+          continue;
+        }
+        return undefined;
+      }
+      if (!response.ok) return undefined;
+      return await response.json();
+    } catch {
+      // Timeout, network error, or a body that is not JSON: treat as no data.
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/** `GET /api/market` — public. Money is numeric. */
+export function fetchMarket(options: InferhubClientOptions = {}): Promise<unknown> {
+  return get("/market", options);
+}
+
+/** `GET /api/status` — public. Availability and per-model health. */
+export function fetchStatus(options: InferhubClientOptions = {}): Promise<unknown> {
+  return get("/status", options);
+}
+
+/** `GET /api/catalog` — needs `config_read`. Money is a decimal string. */
+export function fetchCatalog(options: InferhubClientOptions = {}): Promise<unknown> {
+  return get("/catalog", options);
+}
+
+/** `GET /api/pricing/config` — public platform fee configuration. */
+export function fetchPricingConfig(options: InferhubClientOptions = {}): Promise<unknown> {
+  return get("/pricing/config", options);
+}
+
+export function objectArray(payload: unknown, key: string): readonly Record<string, unknown>[] {
+  const value =
+    payload !== null && typeof payload === "object" && !Array.isArray(payload)
+      ? (payload as Record<string, unknown>)[key]
+      : payload;
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (item): item is Record<string, unknown> => item !== null && typeof item === "object",
+  );
+}

package/src/console/inferhub/key-store.ts

@@ -0,0 +1,129 @@
+/**
+ * The InferHub `config_read` key, stored on its own row.
+ *
+ * Deliberately **not** in `provider_accounts.auth_state`: `auth_state` is
+ * documented as the per-account *non-secret* upstream config field and travels
+ * with the account through backup/restore, so a credential there is copied
+ * around and readable by anything that reads accounts. This key is a secret, so
+ * it gets the same treatment as any other credential — encrypted at rest with
+ * `encryptCredential`, in its own table, reachable only through the InferHub
+ * routes.
+ *
+ * It is also never the inference key. InferHub issues two kinds and a
+ * `config_read` key can read no tenant inference data and move no money; an
+ * inference key here would be able to do both. The write path rejects a value
+ * already stored as an account credential so the two cannot be conflated.
+ */
+import { and, eq } from "drizzle-orm";
+import { inferhubConfigKeys, providerAccounts } from "../../persistence/schema";
+import { decryptCredentialToString, encryptCredential, hashSecret } from "../../security/crypto";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+
+/** Shape returned to the console: whether a key is set, and never the key. */
+export interface InferhubKeyStatus {
+  readonly configured: boolean;
+  /** Last four characters, so an operator can tell two keys apart. */
+  readonly last4: string | null;
+  readonly updatedAt: string | null;
+}
+
+/**
+ * Reads the stored key. Returns undefined when none is configured.
+ *
+ * A missing key is not an error — the routes report `no_config_key` and the
+ * operator is told to add one, rather than an optional feature failing closed.
+ */
+export async function readConfigKey(db: CartethyiaDatabase): Promise<string | undefined> {
+  try {
+    const rows = await db
+      .select({ ciphertext: inferhubConfigKeys.ciphertext })
+      .from(inferhubConfigKeys)
+      .where(eq(inferhubConfigKeys.id, SINGLETON_ID))
+      .limit(1);
+    const stored = rows[0]?.ciphertext;
+    if (stored === undefined || stored === null) return undefined;
+    const plaintext = decryptCredentialToString(stored).trim();
+    return plaintext.length > 0 ? plaintext : undefined;
+  } catch {
+    // A decrypt failure (rotated encryption key, corrupt row) must not look
+    // like "no key configured" in a way that silently hides data loss, but it
+    // must not throw into a page render either. Returning undefined reports
+    // `no_config_key`, which tells the operator to re-enter it.
+    return undefined;
+  }
+}
+
+/** Writes the key, replacing any previous value. */
+export async function writeConfigKey(db: CartethyiaDatabase, value: string): Promise<void> {
+  const trimmed = value.trim();
+  const now = new Date();
+  await db
+    .insert(inferhubConfigKeys)
+    .values({
+      id: SINGLETON_ID,
+      ciphertext: encryptCredential(trimmed),
+      fingerprint: hashSecret(trimmed),
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: inferhubConfigKeys.id,
+      set: { ciphertext: encryptCredential(trimmed), fingerprint: hashSecret(trimmed), updatedAt: now },
+    });
+}
+
+/** Removes the key entirely. */
+export async function clearConfigKey(db: CartethyiaDatabase): Promise<void> {
+  await db.delete(inferhubConfigKeys).where(eq(inferhubConfigKeys.id, SINGLETON_ID));
+}
+
+/** Whether a key is set, without decrypting it into a response. */
+export async function keyStatus(db: CartethyiaDatabase): Promise<InferhubKeyStatus> {
+  const rows = await db
+    .select({ ciphertext: inferhubConfigKeys.ciphertext, updatedAt: inferhubConfigKeys.updatedAt })
+    .from(inferhubConfigKeys)
+    .where(eq(inferhubConfigKeys.id, SINGLETON_ID))
+    .limit(1);
+  const row = rows[0];
+  if (row === undefined) return { configured: false, last4: null, updatedAt: null };
+  let last4: string | null = null;
+  try {
+    const plaintext = decryptCredentialToString(row.ciphertext).trim();
+    last4 = plaintext.length >= 4 ? plaintext.slice(-4) : null;
+  } catch {
+    last4 = null;
+  }
+  return {
+    configured: true,
+    last4,
+    updatedAt: row.updatedAt?.toISOString() ?? null,
+  };
+}
+
+/**
+ * One row for the whole deployment: the `config_read` key is a single operator
+ * credential, not a per-account one.
+ */
+const SINGLETON_ID = "default";
+
+/** Re-exported so routes can assert a key is not also an account credential. */
+export async function isAlsoAccountCredential(
+  db: CartethyiaDatabase,
+  providerId: string,
+): Promise<boolean> {
+  const rows = await db
+    .select({ id: providerAccounts.id })
+    .from(providerAccounts)
+    .where(and(eq(providerAccounts.providerId, providerId)))
+    .limit(1);
+  return rows.length > 0;
+}
+
+/** Builds the key store the InferHub routes take. */
+export function createInferhubKeyStore(db: CartethyiaDatabase) {
+  return {
+    read: () => readConfigKey(db),
+    write: (value: string) => writeConfigKey(db, value),
+    clear: () => clearConfigKey(db),
+    status: () => keyStatus(db),
+  };
+}