cartethyia 2.7.3 → 2.7.5

package/src/observability/event-query.ts

@@ -18,8 +18,9 @@
  * - `isGatewayError()` semantics live in one shared SQL predicate.
  */
 import { and, desc, eq, gte, inArray, isNotNull, or, sql, type SQL } from "drizzle-orm";
+import { PgDialect } from "drizzle-orm/pg-core";
 import type { CartethyiaDatabase } from "../persistence/db-handle";
-import { apiKeys, telemetryEvents } from "../persistence/schema";
+import { apiKeys, telemetryEvents, telemetryUsageTotals } from "../persistence/schema";
 import type { TelemetryEventRecord } from "./event-log";
 import { gatewayErrorSql } from "./telemetry-status";
 
@@ -31,7 +32,21 @@ import { gatewayErrorSql } from "./telemetry-status";
  * totals, and the durable usage rollup cannot drift apart — an unknown status
  * must be classified identically in all three.
  */
-const IS_GATEWAY_ERROR_SQL = gatewayErrorSql(telemetryEvents.status, telemetryEvents.httpStatus);
+export const IS_GATEWAY_ERROR_SQL = gatewayErrorSql(telemetryEvents.status, telemetryEvents.httpStatus);
+
+/**
+ * The aggregate select fragments shared by every tenant-window read. The
+ * `errors` count uses the single shared gateway-error predicate (see
+ * {@link IS_GATEWAY_ERROR_SQL}) so the row-level rule and the SQL aggregate
+ * cannot drift; the sum fragments coalesce to 0 so an empty window reads as
+ * zero rather than null.
+ */
+const AGGREGATE_SELECT = {
+  errors: sql<number>`sum(case when ${IS_GATEWAY_ERROR_SQL} then 1 else 0 end)`,
+  inputTokens: sql<number>`coalesce(sum(${telemetryEvents.inputTokens}), 0)`,
+  outputTokens: sql<number>`coalesce(sum(${telemetryEvents.outputTokens}), 0)`,
+  cachedInputTokens: sql<number>`coalesce(sum(${telemetryEvents.cachedInputTokens}), 0)`,
+} as const;
 
 /** One bounded page of events, newest first. */
 export interface EventPage {
@@ -40,7 +55,7 @@ export interface EventPage {
   readonly nextCursor?: string;
 }
 
-export interface EventListQuery {
+interface EventListQuery {
   readonly tenantId: string;
   /**
    * Lower bound. Omitting it means "the whole retained window" — the SQL table
@@ -96,7 +111,7 @@ export interface UsageSummary {
   readonly unpriced: number;
 }
 
-export interface BreakdownGroup {
+interface BreakdownGroup {
   readonly key: string;
   readonly requests: number;
   readonly errors: number;
@@ -116,15 +131,8 @@ export interface ChartBucket {
   readonly errors: number;
   readonly inputTokens: number;
   readonly outputTokens: number;
-}
-
-export interface HealthTotals {
-  readonly requests: number;
-  readonly errors: number;
-  readonly inputTokens: number;
-  readonly outputTokens: number;
+  /** Cached-input share of the prompt, summed for the bucket. */
   readonly cachedInputTokens: number;
-  readonly latencyAvgMs: number | null;
 }
 
 const DEFAULT_LIMIT = 50;
@@ -141,7 +149,7 @@ function numericNullable(value: unknown): number | null {
 }
 
 /** Maps one `telemetry_events` row to the console's record shape. */
-export function eventRecordFromRow(row: {
+function eventRecordFromRow(row: {
   readonly id: string | null;
   readonly createdAt: Date;
   readonly tenantId: string;
@@ -225,11 +233,28 @@ export function eventRecordFromRow(row: {
  * renders the SQL, so it is the only answer that cannot disagree with it.
  */
 function isPostgres(db: CartethyiaDatabase): boolean {
-  const dialect = (db as unknown as { dialect?: { constructor?: { name?: string } } }).dialect;
-  const name = dialect?.constructor?.name;
+  const dialect = (db as unknown as { dialect?: unknown }).dialect;
+  if (dialect instanceof PgDialect) return true;
+  const name = (dialect as { constructor?: { name?: string } } | undefined)?.constructor?.name;
   return name === "PostgresDialect" || name === "PgDialect";
 }
 
+/**
+ * The epoch-bucket SQL expression for one time column.
+ *
+ * Inlined (not parameterised) so Postgres sees the SELECT and GROUP BY
+ * expressions as identical: parameter numbers differing between the two
+ * clauses made Postgres treat them as unrelated expressions referencing
+ * `created_at`, which 42803-rejected the query. The width is a raw SQL
+ * literal for the same reason.
+ */
+function bucketExpression(db: CartethyiaDatabase, column: typeof telemetryEvents.createdAt, widthSeconds: number): SQL {
+  const w = sql.raw(String(Math.max(1, Math.trunc(widthSeconds))));
+  return isPostgres(db)
+    ? sql<number>`(cast(extract(epoch from ${column}) as bigint) / ${w}) * ${w}`
+    : sql<number>`(cast(strftime('%s', ${column}) as integer) / ${w}) * ${w}`;
+}
+
 /**
  * The tenant predicate — the scope every read shares — plus the window when
  * one is given.
@@ -400,90 +425,9 @@ export async function queryTelemetryEvents(
   };
 }
 
-/** One event by request id — a single indexed row, never a window scan. */
-export async function eventByRequestId(
-  db: CartethyiaDatabase,
-  tenantId: string,
-  requestId: string,
-): Promise<TelemetryEventRecord | undefined> {
-  const [row] = await db
-    .select()
-    .from(telemetryEvents)
-    .where(and(eq(telemetryEvents.tenantId, tenantId), eq(telemetryEvents.requestId, requestId)))
-    .limit(1);
-  if (!row) return undefined;
-  return eventRecordFromRow(row as Parameters<typeof eventRecordFromRow>[0]);
-}
-
 /**
- * Totals plus latency percentiles for one tenant window.
- *
- * Percentiles are computed by the database. Postgres uses `percentile_cont`;
- * SQLite (no ordered-set aggregates) computes nearest-rank percentiles from
- * the ordered latency column via OFFSET/LIMIT. Either way, latency values are
- * never returned to JavaScript — the array that the old raw reader built to
- * sort in JS was the memory cost this replaces.
+ * The SQL column one breakdown dimension groups by.
  */
-export async function summarizeTelemetry(
-  db: CartethyiaDatabase,
-  tenantId: string,
-  since: Date,
-): Promise<UsageSummary> {
-  const condition = scoped(tenantId, since);
-  const [row] = await db
-    .select({
-      requests: sql<number>`count(*)`,
-      errors: sql<number>`sum(case when ${IS_GATEWAY_ERROR_SQL} then 1 else 0 end)`,
-      cancelled: sql<number>`sum(case when ${telemetryEvents.status} = 'cancelled' then 1 else 0 end)`,
-      truncated: sql<number>`sum(case when ${telemetryEvents.status} = 'truncated' then 1 else 0 end)`,
-      inputTokens: sql<number>`coalesce(sum(${telemetryEvents.inputTokens}), 0)`,
-      outputTokens: sql<number>`coalesce(sum(${telemetryEvents.outputTokens}), 0)`,
-      cachedInputTokens: sql<number>`coalesce(sum(${telemetryEvents.cachedInputTokens}), 0)`,
-      reasoningTokens: sql<number>`coalesce(sum(${telemetryEvents.reasoningTokens}), 0)`,
-      estimatedCostUsd: sql<number>`coalesce(sum(${telemetryEvents.estimatedCostUsd}), 0)`,
-      sampled: sql<number>`count(${telemetryEvents.latencyMs})`,
-      latencyAvg: sql<number>`avg(${telemetryEvents.latencyMs})`,
-      unpriced: sql<number>`sum(case when ${telemetryEvents.estimatedCostUsd} is null then 1 else 0 end)`,
-    })
-    .from(telemetryEvents)
-    .where(condition);
-  if (!row) {
-    return {
-      requests: 0,
-      errors: 0,
-      cancelled: 0,
-      truncated: 0,
-      inputTokens: 0,
-      outputTokens: 0,
-      cachedInputTokens: 0,
-      reasoningTokens: 0,
-      estimatedCostUsd: 0,
-      sampled: 0,
-      latencyMs: { avg: null, p50: null, p95: null, p99: null },
-      unpriced: 0,
-    };
-  }
-
-  const sampled = numeric(row.sampled);
-  const percentiles = await latencyPercentiles(db, tenantId, since, sampled);
-  return {
-    requests: numeric(row.requests),
-    errors: numeric(row.errors),
-    cancelled: numeric(row.cancelled),
-    truncated: numeric(row.truncated),
-    inputTokens: numeric(row.inputTokens),
-    outputTokens: numeric(row.outputTokens),
-    cachedInputTokens: numeric(row.cachedInputTokens),
-    reasoningTokens: numeric(row.reasoningTokens),
-    estimatedCostUsd: numeric(row.estimatedCostUsd),
-    sampled,
-    latencyMs: {
-      avg: numericNullable(row.latencyAvg),
-      ...percentiles,
-    },
-    unpriced: numeric(row.unpriced),
-  };
-}
 
 type Percentiles = { p50: number | null; p95: number | null; p99: number | null };
 
@@ -516,23 +460,36 @@ async function latencyPercentiles(
   }
 
   // SQLite: nearest-rank percentile = the value at ceil(p * n) rows into the
-  // ordered latency column, via ORDER BY + OFFSET/LIMIT in SQL.
-  const rankAt = async (fraction: number): Promise<number | null> => {
-    const offset = Math.max(0, Math.ceil(fraction * sampled) - 1);
-    const [row] = await db
-      .select({ value: telemetryEvents.latencyMs })
-      .from(telemetryEvents)
-      .where(and(...base))
-      .orderBy(telemetryEvents.latencyMs)
-      .limit(1)
-      .offset(offset);
-    return row?.value ?? null;
+  // ordered latency column. One query computes all three ranks via a window
+  // function, instead of three separate OFFSET/LIMIT passes over the same
+  // ordered column (one per percentile).
+  const n = Math.max(1, sampled);
+  const ranks = [
+    Math.ceil(0.5 * n),
+    Math.ceil(0.95 * n),
+    Math.ceil(0.99 * n),
+  ];
+  const [row] = await db
+    .select({
+      p50: sql<number | null>`max(case when rn = ${ranks[0]} then value end)`,
+      p95: sql<number | null>`max(case when rn = ${ranks[1]} then value end)`,
+      p99: sql<number | null>`max(case when rn = ${ranks[2]} then value end)`,
+    })
+    .from(
+      sql`(
+        select ${telemetryEvents.latencyMs} as value,
+               row_number() over (order by ${telemetryEvents.latencyMs}) as rn
+        from ${telemetryEvents}
+        where ${and(...base)}
+      )`,
+    );
+  return {
+    p50: numericNullable(row?.p50 ?? null),
+    p95: numericNullable(row?.p95 ?? null),
+    p99: numericNullable(row?.p99 ?? null),
   };
-  const [p50, p95, p99] = await Promise.all([rankAt(0.5), rankAt(0.95), rankAt(0.99)]);
-  return { p50, p95, p99 };
 }
 
-/** The SQL column one breakdown dimension groups by. */
 function dimensionColumn(dimension: string) {
   if (dimension === "model") return telemetryEvents.requestedModel;
   if (dimension === "provider") return telemetryEvents.providerId;
@@ -571,9 +528,7 @@ export async function breakdownTelemetry(
     .select({
       key: column,
       requests: sql<number>`count(*)`,
-      errors: sql<number>`sum(case when ${IS_GATEWAY_ERROR_SQL} then 1 else 0 end)`,
-      inputTokens: sql<number>`coalesce(sum(${telemetryEvents.inputTokens}), 0)`,
-      outputTokens: sql<number>`coalesce(sum(${telemetryEvents.outputTokens}), 0)`,
+      ...AGGREGATE_SELECT,
       cachedInputTokens: sql<number>`coalesce(sum(${telemetryEvents.cachedInputTokens}), 0)`,
       costUsd: sql<number>`coalesce(sum(${telemetryEvents.estimatedCostUsd}), 0)`,
       avgTokensPerSec: sql<number>`coalesce(avg(${telemetryEvents.tokensPerSec}), 0)`,
@@ -610,32 +565,23 @@ export async function chartTelemetry(
   since: Date,
   bucketSeconds: number,
 ): Promise<ChartBucket[]> {
-  const width = Math.max(1, Math.trunc(bucketSeconds));
-  // Inlined (not parameterised) so Postgres sees the SELECT and GROUP BY
-  // expressions as identical: parameter numbers differing between the two
-  // clauses made Postgres treat them as unrelated expressions referencing
-  // `created_at`, which 42803-rejected the query.
-  const w = sql.raw(String(width));
-  const bucketExpression = isPostgres(db)
-    ? sql<number>`(cast(extract(epoch from ${telemetryEvents.createdAt}) as bigint) / ${w}) * ${w}`
-    : sql<number>`(cast(strftime('%s', ${telemetryEvents.createdAt}) as integer) / ${w}) * ${w}`;
+  const bucketExpr = bucketExpression(db, telemetryEvents.createdAt, bucketSeconds);
   const rows = await db
     .select({
-      at: bucketExpression,
+      at: bucketExpr,
       requests: sql<number>`count(*)`,
-      errors: sql<number>`sum(case when ${IS_GATEWAY_ERROR_SQL} then 1 else 0 end)`,
-      inputTokens: sql<number>`coalesce(sum(${telemetryEvents.inputTokens}), 0)`,
-      outputTokens: sql<number>`coalesce(sum(${telemetryEvents.outputTokens}), 0)`,
+      ...AGGREGATE_SELECT,
     })
     .from(telemetryEvents)
     .where(scoped(tenantId, since))
-    .groupBy(bucketExpression);
+    .groupBy(bucketExpr);
   return rows.map((row) => ({
     at: numeric(row.at) * 1000,
     requests: numeric(row.requests),
     errors: numeric(row.errors),
     inputTokens: numeric(row.inputTokens),
     outputTokens: numeric(row.outputTokens),
+    cachedInputTokens: numeric(row.cachedInputTokens),
   }));
 }
 
@@ -665,20 +611,15 @@ export async function providerUsageMatrix(
   providerId: string,
   since: Date,
 ): Promise<ProviderUsageDayRow[]> {
-  // Same inlining rule as chartTelemetry: SELECT and GROUP BY must spell the
-  // identical expression or Postgres 42803-rejects the grouped reference.
-  const w = sql.raw(String(86400));
-  const dayExpression = isPostgres(db)
-    ? sql<number>`(cast(extract(epoch from ${telemetryEvents.createdAt}) as bigint) / ${w}) * ${w}`
-    : sql<number>`(cast(strftime('%s', ${telemetryEvents.createdAt}) as integer) / ${w}) * ${w}`;
+  const dayExpression = bucketExpression(db, telemetryEvents.createdAt, 86400);
   const rows = await db
     .select({
       day: dayExpression,
       model: telemetryEvents.requestedModel,
       requests: sql<number>`count(*)`,
-      inputTokens: sql<number>`coalesce(sum(${telemetryEvents.inputTokens}), 0)`,
+      inputTokens: AGGREGATE_SELECT.inputTokens,
       cachedInputTokens: sql<number>`coalesce(sum(${telemetryEvents.cachedInputTokens}), 0)`,
-      outputTokens: sql<number>`coalesce(sum(${telemetryEvents.outputTokens}), 0)`,
+      outputTokens: AGGREGATE_SELECT.outputTokens,
       costUsd: sql<number>`coalesce(sum(${telemetryEvents.estimatedCostUsd}), 0)`,
     })
     .from(telemetryEvents)
@@ -696,43 +637,6 @@ export async function providerUsageMatrix(
   }));
 }
 
-/** Overview/health totals for one tenant window. */
-export async function healthTelemetry(
-  db: CartethyiaDatabase,
-  tenantId: string,
-  since: Date,
-): Promise<HealthTotals> {
-  const [row] = await db
-    .select({
-      requests: sql<number>`count(*)`,
-      errors: sql<number>`sum(case when ${IS_GATEWAY_ERROR_SQL} then 1 else 0 end)`,
-      inputTokens: sql<number>`coalesce(sum(${telemetryEvents.inputTokens}), 0)`,
-      outputTokens: sql<number>`coalesce(sum(${telemetryEvents.outputTokens}), 0)`,
-      cachedInputTokens: sql<number>`coalesce(sum(${telemetryEvents.cachedInputTokens}), 0)`,
-      latencyAvg: sql<number>`avg(${telemetryEvents.latencyMs})`,
-    })
-    .from(telemetryEvents)
-    .where(scoped(tenantId, since));
-  if (!row) {
-    return {
-      requests: 0,
-      errors: 0,
-      inputTokens: 0,
-      outputTokens: 0,
-      cachedInputTokens: 0,
-      latencyAvgMs: null,
-    };
-  }
-  return {
-    requests: numeric(row.requests),
-    errors: numeric(row.errors),
-    inputTokens: numeric(row.inputTokens),
-    outputTokens: numeric(row.outputTokens),
-    cachedInputTokens: numeric(row.cachedInputTokens),
-    latencyAvgMs: numericNullable(row.latencyAvg),
-  };
-}
-
 /**
  * Summed input+output tokens for a set of API keys over one window — the
  * family bucket spend query.
@@ -768,54 +672,157 @@ export async function sumTelemetryTokens(
 }
 
 /**
- * The health card's latency and throughput figures for one window.
+ * All-time family counts from the durable rollup, not from a scan of the
+ * retained telemetry window.
  *
- * Same principle as {@link summarizeTelemetry}: `avg(tokens_per_sec)` and the
- * latency percentiles are computed by the database. The console's health card
- * used to pull every retained event into an array to average `tokensPerSec`
- * and sort latencies in JavaScript.
+ * The share KPI cards need lifetime numbers. `telemetry_usage_totals` is
+ * charged at write time and accumulates per identity, so a family's lifetime
+ * requests/errors/tokens are a SUM over its rows (keyed by
+ * `family_template_key_id`) — sub-millisecond on a small table, versus a
+ * full-window aggregate over `telemetry_events` that reads every retained
+ * event on every tick. The rollup is the same definition as the read-side
+ * counts, so the two cannot drift.
  */
-export interface HealthPerformance {
-  readonly latencyAvgMs: number | null;
-  readonly latencyP50Ms: number | null;
-  readonly latencyP95Ms: number | null;
-  readonly latencyP99Ms: number | null;
-  readonly avgTokensPerSec: number;
+interface FamilyKpiTotals {
+  readonly requests: number;
+  readonly errors: number;
+  readonly tokens: number;
 }
 
-export async function summarizeHealthPerformance(
+/** Sums one share family's durable lifetime totals. */
+export async function familyKpiTotals(
   db: CartethyiaDatabase,
   tenantId: string,
-  since: Date,
-): Promise<HealthPerformance> {
+  familyKeyId: string,
+): Promise<FamilyKpiTotals> {
   const [row] = await db
     .select({
-      latencyAvg: sql<number>`avg(${telemetryEvents.latencyMs})`,
-      sampled: sql<number>`count(${telemetryEvents.latencyMs})`,
-      avgTokensPerSec: sql<number>`coalesce(avg(${telemetryEvents.tokensPerSec}), 0)`,
+      requests: sql<number>`coalesce(sum(${telemetryUsageTotals.requests}), 0)`,
+      errors: sql<number>`coalesce(sum(${telemetryUsageTotals.errors}), 0)`,
+      tokens: sql<number>`coalesce(sum(coalesce(${telemetryUsageTotals.inputTokens}, 0) + coalesce(${telemetryUsageTotals.outputTokens}, 0)), 0)`,
     })
-    .from(telemetryEvents)
-    .where(scoped(tenantId, since));
-  const sampled = numeric(row?.sampled ?? 0);
-  const percentiles = await latencyPercentiles(db, tenantId, since, sampled);
+    .from(telemetryUsageTotals)
+    .where(
+      and(
+        eq(telemetryUsageTotals.tenantId, tenantId),
+        eq(telemetryUsageTotals.familyTemplateKeyId, familyKeyId),
+      ),
+    );
   return {
-    latencyAvgMs: numericNullable(row?.latencyAvg ?? null),
-    latencyP50Ms: percentiles.p50,
-    latencyP95Ms: percentiles.p95,
-    latencyP99Ms: percentiles.p99,
-    avgTokensPerSec: numeric(row?.avgTokensPerSec ?? 0),
+    requests: numeric(row?.requests ?? 0),
+    errors: numeric(row?.errors ?? 0),
+    tokens: numeric(row?.tokens ?? 0),
   };
 }
 
+/** Counts one share family's requests in a bounded window — a range scan, not a full-window aggregate. */
+export async function familyWindowRequests(
+  db: CartethyiaDatabase,
+  tenantId: string,
+  familyKeyId: string,
+  since: Date,
+): Promise<number> {
+  const [row] = await db
+    .select({
+      requests: sql<number>`count(*)`,
+    })
+    .from(telemetryEvents)
+    .where(
+      and(
+        eq(telemetryEvents.tenantId, tenantId),
+        familyKeyCondition(familyKeyId),
+        gte(telemetryEvents.createdAt, since),
+      ),
+    );
+  return numeric(row?.requests ?? 0);
+}
+
+/**
+ * One share family's client-IP breakdown, computed in SQL.
+ *
+ * Unlike the 24-hour page read, this covers a bounded history so an address
+ * that stopped before the last day still appears — marked inactive. The
+ * `active` flag is decided in the caller from `lastSeenAt` vs a cutoff; here
+ * we only aggregate. The window is bounded (`since`, default the whole
+ * retained window) so an unbounded scan is never the default for callers
+ * that only need recent addresses.
+ */
+export async function familyIpBreakdown(
+  db: CartethyiaDatabase,
+  tenantId: string,
+  familyKeyId: string,
+  limit = 50,
+  since?: Date,
+): Promise<{ ip: string; requests: number; tokens: number; lastSeenAt: Date | null }[]> {
+  const conditions = [
+    eq(telemetryEvents.tenantId, tenantId),
+    familyKeyCondition(familyKeyId),
+    ...(since === undefined ? [] : [gte(telemetryEvents.createdAt, since)]),
+  ];
+  const rows = await db
+    .select({
+      ip: telemetryEvents.clientIp,
+      requests: sql<number>`count(*)`,
+      tokens: sql<number>`coalesce(sum(coalesce(${telemetryEvents.inputTokens}, 0) + coalesce(${telemetryEvents.outputTokens}, 0)), 0)`,
+      lastSeenAt: sql<Date>`max(${telemetryEvents.createdAt})`,
+    })
+    .from(telemetryEvents)
+    .where(and(...conditions))
+    .groupBy(telemetryEvents.clientIp)
+    // Highest volume first: the table answers "who has used the link most",
+    // not just who is active right now.
+    .orderBy(desc(sql`count(*)`))
+    .limit(limit);
+  return rows.flatMap((row) =>
+    row.ip === null ? [] : [{ ip: row.ip, requests: numeric(row.requests), tokens: numeric(row.tokens), lastSeenAt: row.lastSeenAt }],
+  );
+}
+
+/**
+ * One share family's time-series buckets, computed in SQL with the family
+ * membership filter.
+ *
+ * Mirrors {@link chartTelemetry} but scoped to a share family. The share page's
+ * 24-hour strip must not be truncated to the bounded page (500 events), or a
+ * busy family's chart undercounts every hour bucket.
+ */
+export async function familyHourlyTelemetry(
+  db: CartethyiaDatabase,
+  tenantId: string,
+  familyKeyId: string,
+  since: Date,
+  bucketSeconds: number,
+): Promise<ChartBucket[]> {
+  const bucketExpr = bucketExpression(db, telemetryEvents.createdAt, bucketSeconds);
+  const conditions = [scoped(tenantId, since), familyKeyCondition(familyKeyId)];
+  const rows = await db
+    .select({
+      at: bucketExpr,
+      requests: sql<number>`count(*)`,
+      ...AGGREGATE_SELECT,
+    })
+    .from(telemetryEvents)
+    .where(and(...conditions))
+    .groupBy(bucketExpr);
+  return rows.map((row) => ({
+    at: numeric(row.at) * 1000,
+    requests: numeric(row.requests),
+    errors: numeric(row.errors),
+    inputTokens: numeric(row.inputTokens),
+    outputTokens: numeric(row.outputTokens),
+    cachedInputTokens: numeric(row.cachedInputTokens),
+  }));
+}
+
 /**
  * The Usage summary's performance block, computed in SQL.
  *
  * Replaces `summarizeUsagePerformance` (which sorted a latency array in
  * JavaScript): `avg(resolve_ms)` and `avg(tokens_per_sec)` are SQL averages,
  * and the latency percentiles come from the same database-side percentile
- * path {@link summarizeTelemetry} uses.
+ * path {@link summarizeUsageWithPerformance} uses.
  */
-export interface UsagePerformanceTotals {
+interface UsagePerformanceTotals {
   readonly avgResolveMs: number;
   readonly avgDurationMs: number;
   /**
@@ -832,32 +839,97 @@ export interface UsagePerformanceTotals {
   readonly avgTokensPerSec: number;
 }
 
-export async function summarizeUsagePerformanceSql(
+/**
+ * Combined usage totals + performance in ONE window scan.
+ *
+ * This runs the combined SELECT once and one percentile pass, returning both
+ * shapes so the caller needs no second query.
+ */
+export async function summarizeUsageWithPerformance(
   db: CartethyiaDatabase,
   tenantId: string,
   since: Date,
-): Promise<UsagePerformanceTotals> {
+): Promise<{ summary: UsageSummary; performance: UsagePerformanceTotals }> {
+  const condition = scoped(tenantId, since);
   const [row] = await db
     .select({
+      requests: sql<number>`count(*)`,
+      errors: AGGREGATE_SELECT.errors,
+      cancelled: sql<number>`sum(case when ${telemetryEvents.status} = 'cancelled' then 1 else 0 end)`,
+      truncated: sql<number>`sum(case when ${telemetryEvents.status} = 'truncated' then 1 else 0 end)`,
+      inputTokens: AGGREGATE_SELECT.inputTokens,
+      outputTokens: AGGREGATE_SELECT.outputTokens,
+      cachedInputTokens: sql<number>`coalesce(sum(${telemetryEvents.cachedInputTokens}), 0)`,
+      reasoningTokens: sql<number>`coalesce(sum(${telemetryEvents.reasoningTokens}), 0)`,
+      estimatedCostUsd: sql<number>`coalesce(sum(${telemetryEvents.estimatedCostUsd}), 0)`,
       sampled: sql<number>`count(${telemetryEvents.latencyMs})`,
       latencyAvg: sql<number>`avg(${telemetryEvents.latencyMs})`,
+      unpriced: sql<number>`sum(case when ${telemetryEvents.estimatedCostUsd} is null then 1 else 0 end)`,
       resolveSum: sql<number>`coalesce(sum(${telemetryEvents.resolveMs}), 0)`,
       resolveCount: sql<number>`count(${telemetryEvents.resolveMs})`,
       avgTokensPerSec: sql<number>`coalesce(avg(${telemetryEvents.tokensPerSec}), 0)`,
     })
     .from(telemetryEvents)
-    .where(scoped(tenantId, since));
-  const sampled = numeric(row?.sampled ?? 0);
-  const resolveCount = numeric(row?.resolveCount ?? 0);
+    .where(condition);
+
+  if (!row) {
+    const empty: UsageSummary = {
+      requests: 0,
+      errors: 0,
+      cancelled: 0,
+      truncated: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      cachedInputTokens: 0,
+      reasoningTokens: 0,
+      estimatedCostUsd: 0,
+      sampled: 0,
+      latencyMs: { avg: null, p50: null, p95: null, p99: null },
+      unpriced: 0,
+    };
+    const emptyPerformance: UsagePerformanceTotals = {
+      avgResolveMs: 0,
+      avgDurationMs: 0,
+      latencyP50Ms: 0,
+      latencyP95Ms: 0,
+      latencyP99Ms: 0,
+      latencySampleCount: 0,
+      resolveSampleCount: 0,
+      avgTokensPerSec: 0,
+    };
+    return { summary: empty, performance: emptyPerformance };
+  }
+
+  const sampled = numeric(row.sampled);
   const percentiles = await latencyPercentiles(db, tenantId, since, sampled);
+  const resolveCount = numeric(row.resolveCount);
   return {
-    avgResolveMs: resolveCount > 0 ? numeric(row?.resolveSum ?? 0) / resolveCount : 0,
-    avgDurationMs: numericNullable(row?.latencyAvg ?? null) ?? 0,
-    latencyP50Ms: percentiles.p50 ?? 0,
-    latencyP95Ms: percentiles.p95 ?? 0,
-    latencyP99Ms: percentiles.p99 ?? 0,
-    latencySampleCount: sampled,
-    resolveSampleCount: resolveCount,
-    avgTokensPerSec: numeric(row?.avgTokensPerSec ?? 0),
+    summary: {
+      requests: numeric(row.requests),
+      errors: numeric(row.errors),
+      cancelled: numeric(row.cancelled),
+      truncated: numeric(row.truncated),
+      inputTokens: numeric(row.inputTokens),
+      outputTokens: numeric(row.outputTokens),
+      cachedInputTokens: numeric(row.cachedInputTokens),
+      reasoningTokens: numeric(row.reasoningTokens),
+      estimatedCostUsd: numeric(row.estimatedCostUsd),
+      sampled,
+      latencyMs: {
+        avg: numericNullable(row.latencyAvg),
+        ...percentiles,
+      },
+      unpriced: numeric(row.unpriced),
+    },
+    performance: {
+      avgResolveMs: resolveCount > 0 ? numeric(row.resolveSum) / resolveCount : 0,
+      avgDurationMs: numericNullable(row.latencyAvg) ?? 0,
+      latencyP50Ms: percentiles.p50 ?? 0,
+      latencyP95Ms: percentiles.p95 ?? 0,
+      latencyP99Ms: percentiles.p99 ?? 0,
+      latencySampleCount: sampled,
+      resolveSampleCount: resolveCount,
+      avgTokensPerSec: numeric(row.avgTokensPerSec),
+    },
   };
 }

package/src/observability/log-sanitize.ts

@@ -36,7 +36,7 @@ export const LOG_RING_MAX_CODE_UNITS = 8_192;
 
 /** Marker appended wherever content was dropped. */
 export const LOG_TRUNCATED_MARKER = "[truncated]";
-export const LOG_CIRCULAR_MARKER = "[circular]";
+const LOG_CIRCULAR_MARKER = "[circular]";
 
 function isHighSurrogate(code: number): boolean {
   return code >= 0xd800 && code <= 0xdbff;