cartethyia 2.7.3 → 2.7.5

package/src/observability/metrics.ts

@@ -5,18 +5,18 @@
  * `render()` emits the Prometheus exposition format on demand.
  */
 
-export type MetricLabels = Readonly<Record<string, string | number>>;
+type MetricLabels = Readonly<Record<string, string | number>>;
 
-export interface CounterMetric {
+interface CounterMetric {
   inc(value?: number, labels?: MetricLabels): void;
 }
 
-export interface GaugeMetric extends CounterMetric {
+interface GaugeMetric extends CounterMetric {
   set(value: number, labels?: MetricLabels): void;
   dec(value?: number, labels?: MetricLabels): void;
 }
 
-export interface HistogramMetric {
+interface HistogramMetric {
   observe(value: number, labels?: MetricLabels): void;
 }
 

package/src/observability/payload-capture.ts

@@ -8,7 +8,7 @@ import type {
   TelemetryPayloadDepth,
   TelemetryPayloadMode,
 } from "../console/settings/contracts";
-export type CaptureScope = "tenant" | "debug_session" | "operator_flag";
+type CaptureScope = "tenant" | "debug_session" | "operator_flag";
 
 /**
  * How long a captured payload frame lives when the deployment has not chosen.
@@ -203,13 +203,13 @@ export interface PayloadCaptureInput {
   operatorFlagOptIn?: boolean;
 }
 
-export interface PayloadSignals {
+interface PayloadSignals {
   readonly toolCalls: number;
   readonly images: number;
   readonly attachments: number;
 }
 
-export interface StoredPayload {
+interface StoredPayload {
   id: string;
   /**
    * JSON text of the five body surfaces, in drawer order, built while the
@@ -412,8 +412,9 @@ export function buildPayloadRecord(
 
 /**
  * Postgres-backed redacted request/response payload capture. Payloads live for
- * the tenant's chosen retention — 15 minutes by default — and are pruned by the
- * sweep.
+ * the tenant's chosen retention — an hour by default (see
+ * {@link payloadRetentionMs} / `DEFAULT_PAYLOAD_RETENTION_MS`) — and are pruned
+ * by the sweep.
 
  */
 export class TelemetryPayloadCapture {

package/src/observability/payload-store.ts

@@ -22,7 +22,7 @@ interface PayloadFrame {
   readonly payload: unknown;
 }
 
-export function isPayloadFileReference(value: unknown): value is PayloadFileReference {
+function isPayloadFileReference(value: unknown): value is PayloadFileReference {
   if (typeof value !== "object" || value === null) return false;
   const record = value as Record<string, unknown>;
   return (

package/src/observability/runtime-metrics.ts

@@ -32,7 +32,7 @@ export interface RuntimeMemorySnapshot {
 }
 
 /** Live collection sizes sampled alongside process memory. */
-export interface RuntimeMetricSources {
+interface RuntimeMetricSources {
   readonly routingRoundRobinEntries: () => { readonly combo: number; readonly provider: number };
   /**
    * Tracked keys in the in-memory IP abuse store, or 0 when the store is

package/src/observability/telemetry-buffer.ts

@@ -158,7 +158,7 @@ function telemetryEventRow(event: TelemetryEventInput) {
   };
 }
 
-export interface TelemetryBatchBufferOptions {
+interface TelemetryBatchBufferOptions {
   readonly flushIntervalMs?: number;
   readonly maxBatch?: number;
   readonly maxItems?: number;
@@ -184,8 +184,17 @@ function drainRetryDelayMs(attempt: number, baseDelayMs = DRAIN_RETRY_BASE_MS):
   return exponentialBackoff(attempt, options);
 }
 
-/** Floor for the adaptive active interval so a full queue still drains promptly. */
-const ADAPTIVE_FLUSH_MIN_MS = 50;
+/**
+ * Floor for the adaptive active interval so a full queue still drains promptly.
+ *
+ * Raised to 200ms (from 50ms) so a flush does not collide with console reads:
+ * under load the queue saturates `maxBatch`, the interval fell to 50ms, and a
+ * drain landed in the middle of the console's own telemetry reads — the GROUP BY
+ * behind the Usage/ConsoleLog pages — making the page's queries wait on the
+ * drain's insert lock. 200ms still drains a 500-row batch ~5x/sec, which is a
+ * steady 2500 rows/sec ceiling; the adaptive curve otherwise keeps its shape.
+ */
+const ADAPTIVE_FLUSH_MIN_MS = 200;
 /** Multiplier applied to the base interval while the queue is empty. */
 const ADAPTIVE_IDLE_MULTIPLIER = 4;
 

package/src/observability/telemetry-reconciliation.ts

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

package/src/observability/telemetry-status.ts

@@ -30,7 +30,7 @@
  *   rule as well, so it needs no special case.
  * - **`503`** is capacity or availability: the gateway *correctly* refusing work
  *   it cannot do right now (`admission_unavailable`, `accounts_unavailable`,
- *   `shutting_down`, `restart_for_update`, `platform_unavailable`). Retryable,
+ *   `shutting_down` (incl. update restart), `platform_unavailable`). Retryable,
  *   self-inflicted, and an operator-capacity signal rather than a defect.
  * - **`504`** is a timeout, not a malfunction. It represents a deadline that
  *   expired: the request deadline, the stream-stall

package/src/observability/token-speed.ts

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

package/src/persistence/connection-url.ts

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

package/src/persistence/db-handle.ts

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

package/src/persistence/db-pg.ts

@@ -81,7 +81,7 @@ function databaseUrlFromLibpqEnv(): string | undefined {
   return `postgres://${credentials}${authorityHost}:${port}${path}`;
 }
 
-export function requireDatabaseUrl(): string {
+function requireDatabaseUrl(): string {
   return requireConnectionUrl({
     schemes: ["postgres:", "postgresql:"],
     candidates: databaseUrlCandidates(),
@@ -124,7 +124,7 @@ export function poolIdleFloorFromEnv(): number {
  * only closes an idle client after `idleTimeoutMillis` (60s here); this gives
  * the pool a faster, explicit shrink path while still keeping the floor warm.
  */
-export function startPoolShrinker(pool: Pool, floor: number): () => void {
+function startPoolShrinker(pool: Pool, floor: number): () => void {
   const interval = setInterval(() => {
     try {
       const idle = pool.idleCount;

package/src/persistence/db-sqlite.ts

@@ -326,8 +326,9 @@ const AUTH_KEY_COLUMNS = [
   "id", "tenant_id", "key_hash", "key_mode", "parent_key_id", "issued_client_ip",
   "issued_client_ip_key", "label", "scopes", "requests_per_minute", "daily_token_limit",
   "monthly_token_limit", "lifetime_token_budget", "lifetime_tokens_consumed",
-  "max_concurrent_requests", "model_access_mode", "model_list", "client_router_denylist",
-  "model_prefix", "created_at", "enabled", "revoked_at", "key_prefix", "key_encrypted",
+  "max_concurrent_requests", "concurrency_scope", "model_access_mode", "model_list", "client_router_denylist",
+  "model_prefix", "created_at", "enabled", "revoked_at", "banned_at", "ban_reason", "banned_until",
+  "key_prefix", "key_encrypted",
   "notes_title", "notes_subtitle", "notes_body", "is_default", "sort_index",
 ].join(", ");
 
@@ -340,8 +341,12 @@ export interface SqliteAuthStatements {
   readonly childrenConsumed: { get: (parentId: string) => { total: number } | null };
 }
 
-export function prepareAuthStatements(sqlite: Database): SqliteAuthStatements {
-  const active = `enabled = 1 AND revoked_at IS NULL`;
+function prepareAuthStatements(sqlite: Database): SqliteAuthStatements {
+  // A key is active while not revoked and not under an active ban: a ban is
+  // active when `banned_at` is set and `banned_until` is null (permanent) or
+  // still in the future. SQLite stores timestamps as ISO text, so the
+  // comparison is lexical (ISO sorts chronologically).
+  const active = `enabled = 1 AND revoked_at IS NULL AND (banned_at IS NULL OR (banned_until IS NOT NULL AND banned_until <= datetime('now')))`;
   // `query`, not `prepare`: bun's `prepare` compiles a statement per call and
   // never finalizes one, while `query` caches the compiled statement behind an
   // LRU of its own. All three are constant text run once per authenticated
@@ -502,7 +507,7 @@ function applyFilePragmas(db: Database): void {
 }
 
 /** The SQLite set lives beside the PostgreSQL one, never inside it. */
-export function resolveSqliteMigrationsFolder(): string {
+function resolveSqliteMigrationsFolder(): string {
   return resolvePackagePath("migrations", "lite-sqlite3");
 }
 

package/src/persistence/dialect.ts

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

package/src/persistence/readiness.ts

@@ -45,7 +45,7 @@ function sameMemoKey(left: ReadinessMemoKey, right: ReadinessMemoKey): boolean {
  * Returns typed ready/not_ready response.
  */
 
-export type ReadinessStatus = "ready" | "not_ready";
+type ReadinessStatus = "ready" | "not_ready";
 
 export interface ReadinessCheckResult {
   readonly status: ReadinessStatus;
@@ -89,12 +89,15 @@ async function runReadinessChecks(
 
   // 1. Check database connectivity via simple query
   let dbOk = false;
+  let dbTimedOut = false;
   try {
     const result = await withTimeoutCheck(
       () => db.execute(sql`SELECT 1`),
       "Database connectivity check",
     );
-    if (result !== "timeout") {
+    if (result === "timeout") {
+      dbTimedOut = true;
+    } else {
       dbOk = true;
     }
   } catch {
@@ -107,7 +110,10 @@ async function runReadinessChecks(
       db: "disconnected",
       migrations: "pending",
       redis: "disconnected",
-      reason: "database not connected",
+      // A timed-out probe under load is not evidence the database is down —
+      // it is the probe itself failing to get a backend in time. The guard
+      // reads this to call it overload rather than a dependency failure.
+      reason: dbTimedOut ? "database probe timed out" : "database not connected",
     };
   }
 
@@ -115,13 +121,16 @@ async function runReadinessChecks(
   // Readiness requires every discovered migration to have a ledger row; a
   // reachable ledger alone is not proof the upgrade finished.
   let migrationsApplied = false;
+  let migrationsTimedOut = false;
   try {
     const result = await withTimeoutCheck(
       () => readMigrationLedgerStatus(db),
       "Migrations check",
     );
 
-    if (result !== "timeout") {
+    if (result === "timeout") {
+      migrationsTimedOut = true;
+    } else {
       migrationsApplied = result.applied;
     }
   } catch {
@@ -134,18 +143,21 @@ async function runReadinessChecks(
       db: "connected",
       migrations: "pending",
       redis: "disconnected",
-      reason: "migrations not yet applied",
+      reason: migrationsTimedOut ? "migrations probe timed out" : "migrations not yet applied",
     };
   }
 
   // 3. Check Redis. The memory backend is healthy by construction — there is
   // no connection to probe — so it passes without a round trip.
   let redisOk = redisBackend === "memory";
+  let redisTimedOut = false;
 
   if (redisBackend === "redis" && redis) {
     try {
       const result = await withTimeoutCheck(() => redis.ping(), "Redis connectivity check");
-      if (result !== "timeout" && result === "PONG") {
+      if (result === "timeout") {
+        redisTimedOut = true;
+      } else if (result === "PONG") {
         redisOk = true;
       }
     } catch {
@@ -159,7 +171,7 @@ async function runReadinessChecks(
       db: "connected",
       migrations: "applied",
       redis: "disconnected",
-      reason: "redis not connected",
+      reason: redisTimedOut ? "redis probe timed out" : "redis not connected",
     };
   }
 

package/src/persistence/redis.ts

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