cartethyia 2.5.3 → 2.5.6

package/src/console/observability/contracts.ts

@@ -1,485 +1,524 @@
-import type { ConsoleAccessResolver } from "../auth/access";
-// Telemetry domain: system health, usage, and telemetry-event read API.
-
-import { ConsoleDomainError, requireTenantScope } from "../shared/errors";
-import { conditionalResponse, type CachedResult } from "../shared/read-through-cache";
-import { parseQueryLimit } from "../shared/query";
-import type { AccessDecision } from "../../security/access-control";
-import { USAGE_DIMENSIONS, type UsageDimension } from "./usage-dimensions";
-
-/**
- * Whitelisted usage periods. Numeric tokens bound the aggregation window;
- * `"all"` is the single explicit unbounded token. Anything else is rejected
- * before any database query so a typo cannot trigger a full-table scan.
- */
-export function isSupportedUsagePeriod(period: string): boolean {
-  if (period === "all") return true;
-  const match = /^(\d+)([hd])$/.exec(period);
-  if (!match) return false;
-  const amount = Number(match[1]);
-  const cap = match[2] === "h" ? 8760 : 365;
-  return Number.isSafeInteger(amount) && amount >= 1 && amount <= cap;
-}
-
-export { USAGE_PERIODS, type UsagePeriod } from "./usage-periods";
-
-export interface SystemHealthResponse {
-  version: string;
-  status: "healthy" | "degraded" | "unhealthy";
-  uptime_seconds: number;
-  database_healthy: boolean;
-  redis_healthy: boolean;
-  /** False when no Redis client is configured and coordination stays in memory. */
-  redis_configured: boolean;
-  /** JavaScript heap used by this process. */
-  memory_heap_bytes: number;
-  /** Native buffers and malloc outside the JavaScript heap. */
-  memory_external_bytes: number;
-  memory_bytes: number;
-  /** RSS as a percentage of system memory, not of the JS heap. */
-  memory_percent: number;
-  /**
-   * True when the database runs inside this process (SQLite). Then RSS covers
-   * the gateway *and* a whole PostgreSQL build, so it is not comparable with a
-   * driver-only process and the console must say so rather than imply the
-   * gateway itself grew.
-   */
-  database_in_process: boolean;
-  /**
-   * `null` when the platform does not report it — there is no `loadavg` on
-   * Windows and Node hands back a zeroed tuple rather than failing, so on
-   * Windows this is always `null` rather than a confident-looking `0`.
-   *
-   * Nullable rather than `NaN`: `NaN` is not a JSON value and serializes to
-   * `null` anyway, which means a client validating the field as a number
-   * rejects the *whole* health payload. One unavailable metric then reads as
-   * every metric being unavailable.
-   */
-  cpu_percent: number | null;
-  cpu_cores: number;
-  pid: number;
-  platform: string;
-  request_count: number;
-  error_count: number;
-  latency_avg_ms: number;
-  latency_p95_ms: number;
-  latency_p99_ms: number;
-  cache_hit_rate_percent: number;
-  avg_tokens_per_sec: number;
-}
-export interface UsageResponse {
-  tenantId: string;
-  period: string;
-  requestsTotal: number;
-  requestsSucceeded: number;
-  requestsFailed: number;
-  tokensUsed: number;
-  estimatedCost: number;
-  topModels: Array<{ modelId: string; count: number }>;
-  topProviders: Array<{ providerId: string; count: number }>;
-}
-
-/** Period-bound usage summary mirroring the 20-beta analytics surface. */
-export interface UsageSummaryTotals {
-  requests: number;
-  inputTokens: number;
-  cachedTokens: number;
-  outputTokens: number;
-  /**
-   * Failed and truncated requests. Client aborts (`cancelled`, rendered 499)
-   * are expected client behavior, never an error, and are tracked separately.
-   */
-  errors: number;
-  /** Client-cancelled requests (rendered `499`) — a sub-count, never an error. */
-  cancelled: number;
-  /** Streams that ended early (`502`); also included in `errors`. */
-  truncated: number;
-  /** Counts by actual HTTP status for the clickable Requests filters. */
-  statusCounts: Array<{ status: number; count: number }>;
-  /** Average gateway routing and preparation delay before upstream dispatch. */
-  avgResolveMs: number;
-  avgDurationMs: number;
-  /** Nearest-rank latency percentiles over the selected usage period. */
-  latencyP50Ms: number;
-  latencyP95Ms: number;
-  latencyP99Ms: number;
-  /**
-   * How many events each latency series was computed from. A percentile over
-   * twenty requests and one over twenty thousand do not deserve the same
-   * confidence, and the count is the only thing that says which it is.
-   */
-  latencySampleCount: number;
-  /** Events carrying a resolve measurement; differs when a row never dispatched. */
-  resolveSampleCount: number;
-  estimatedCostUsd: number;
-  /** True when completed rows without persisted cost exist in the window. */
-  partial: boolean;
-  /** Cache hit rate percentage (0-100). */
-  cacheHitRate: number;
-  /** Average tokens per second across the period. */
-  avgTokensPerSec: number;
-}
-export interface UsageSummaryResponse {
-  period: string;
-  totals: UsageSummaryTotals;
-}
-export interface UsageChartBucket {
-  /** Bucket start as ISO timestamp. */
-  t: string;
-  requests: number;
-  input: number;
-  cached: number;
-  output: number;
-}
-export interface UsageChartResponse {
-  buckets: UsageChartBucket[];
-}
-export interface UsageByRow {
-  name: string;
-  requests: number;
-  input: number;
-  output: number;
-  cached: number;
-  total: number;
-  errors: number;
-  /** Null when no row in the group carries persisted cost. */
-  costUsd: number | null;
-  /** Resolved API key label for the `key` dimension; absent otherwise. */
-  label?: string;
-  /** Cache hit rate percentage (0-100). */
-  cacheHitRate: number;
-  /** Average tokens per second for this dimension. */
-  avgTokensPerSec: number;
-}
-/**
- * Breakdown dimensions the usage endpoint accepts. Declared in `./usage-dimensions`
- * and re-exported here, because three layers read the same binding: the route
- * table registers one `by-<dimension>` path per member, the operations validator
- * rejects anything outside it, and the dashboard's `Dimension` union mirrors it
- * (kept in sync by hand).
- */
-export { USAGE_DIMENSIONS, type UsageDimension };
-
-export interface UsageByResponse {
-  /** The dimension these rows were grouped by, so a stale response can never be read as another tab's data. */
-  dimension: UsageDimension;
-  rows: UsageByRow[];
-}
-export interface UsageCacheResponse {
-  period: string;
-  inputTokens: number;
-  cachedTokens: number;
-  /** Always zero: cache-write tokens are not tracked by the telemetry schema. */
-  cacheWriteTokens: number;
-  hitRate: number;
-}
-export type UsageRequestMode = "stream" | "non_stream";
-export interface UsageRequestItem {
-  requestId: string;
-  surface?: string;
-  providerId?: string;
-  /** Provider account (credential) that served this request, if any. */
-  accountId?: string;
-  model?: string;
-  /**
-   * The model the upstream named in its own response, verbatim — not the one
-   * the client asked for. Absent when the response carried no `model`; never
-   * backfilled from `model`, because that would report the ask as the answer.
-   */
-  reportedModel?: string;
-  endpoint?: string;
-  apiKeyId?: string;
-  userAgent?: string;
-  clientName?: string;
-  estimatedCost?: number;
-  /** Provider-billed credits; absent when the upstream reported no credit field. */
-  creditUsed?: number;
-  /** Gateway-side time from request start to upstream dispatch, in ms. */
-  resolveMs?: number;
-  /** Resolved API key label; absent when the key is gone or unknown. */
-  apiKeyLabel?: string;
-  /** HTTP status the client actually received; absent on historical rows. */
-  httpStatus?: number;
-  status: string;
-  errorKind?: string;
-  /**
-   * Which layer failed: `cartethyia` (the gateway), `upstream` (the provider),
-   * or `network`. Absent for rows written before the column existed.
-   */
-  errorOrigin?: string;
-  mode: UsageRequestMode;
-  startedAt: string;
-  clientIp?: string;
-  durationMs?: number;
-  inputTokens?: number;
-  outputTokens?: number;
-  cachedTokens?: number;
-  reasoningTokens?: number;
-  totalTokens?: number;
-  ttfbMs?: number;
-  tokensPerSec?: number;
-  firstContentDeltaAtMs?: number;
-  lastEventAtMs?: number;
-  /**
-   * Why this request's drawer payloads are empty, or `captured` when they are
-   * not. Remote-diagnosis field: the four panels read blank for every reason
-   * alike, so without this an operator cannot tell "capture is off" from
-   * "capture is broken" without access to the server's logs. Absent on rows
-   * written before the column existed.
-   */
-  payloadCaptureState?: string;
-  /**
-   * Bitmask of the payload stages captured for this request: 1 request,
-   * 2 provider request, 4 provider response, 8 client response. Read from the
-   * payload row so the list can mark each drawer panel without inflating a
-   * frame per row. Absent when nothing was captured for the request — the same
-   * state a pre-migration row reports, rendered as every stage uncaptured
-   * rather than as a measured zero.
-   */
-  payloadStages?: number;
-}
-export interface UsageRequestsResponse {
-  items: UsageRequestItem[];
-}
-export interface UsageRequestDetail extends UsageRequestItem {
-  proxy?: string;
-  payloads?: {
-    request?: unknown;
-    response?: unknown;
-    /** Body Cartethyia returned to the client (post-translation). */
-    clientResponse?: unknown;
-    providerRequest?: unknown;
-    providerResponse?: unknown;
-  } | null;
-  payloadSignals?: {
-    toolCalls: number;
-    images: number;
-    attachments: number;
-  };
-}
-export interface TelemetryEventView {
-  id: string;
-  createdAt: string;
-  tenantId: string;
-  requestId: string;
-  sourceSurface?: string;
-  requestedModel?: string;
-  providerId?: string;
-  latencyMs?: number;
-  status?: string;
-  inputTokens?: number;
-  outputTokens?: number;
-  estimatedCost?: number;
-  firstContentDeltaAtMs?: number;
-  lastEventAtMs?: number;
-}
-export interface TelemetryEventDetail extends TelemetryEventView {
-  payload?: { requestBody?: unknown; responseBody?: unknown };
-}
-export interface TelemetryEventListPage {
-  entries: readonly TelemetryEventView[];
-  /** Opaque cursor for the next page; `undefined` when the tail is reached. */
-  nextCursor?: string;
-}
-export interface ObservabilityStore {
-  /**
-   * Every member below that is served from the read-through cache returns a
-   * {@link CachedResult}, carrying the strong validator for the bytes the
-   * client would otherwise receive. A repeated poll is then a `304` instead of
-   * a full payload. The reads that are per-row and already bounded — the event
-   * list and the detail views — have no cache entry and no validator.
-   */
-  health(tenantId: string): Promise<CachedResult<SystemHealthResponse>>;
-  /**
-   * Process memory as it is right now, bypassing the read-through cache.
-   *
-   * `health` is cached for 10 s, which is correct for a dashboard tile and
-   * wrong for anything sampling a trend: a memory watcher polling on that same
-   * 10 s cadence reads the cached bytes often enough that consecutive samples
-   * can be identical, and a monotonic-growth test over identical samples is
-   * meaningless. The values are read in-process and cost nothing, so there is
-   * no reason to serve them stale.
-   */
-  liveMemory(): Promise<{ memory_bytes: number; memory_percent: number }>;
-  usage(tenantId: string, period: string): Promise<CachedResult<UsageResponse>>;
-  listEvents(tenantId: string, limit: number, cursor?: string): Promise<TelemetryEventListPage>;
-  getEvent(
-    tenantId: string,
-    eventId: string,
-    includePayload: boolean,
-    createdAt?: string,
-  ): Promise<TelemetryEventDetail | undefined>;
-  usageSummary(tenantId: string, period: string): Promise<CachedResult<UsageSummaryResponse>>;
-  usageChart(tenantId: string, period: string): Promise<CachedResult<UsageChartResponse>>;
-  usageBy(
-    tenantId: string,
-    dimension: UsageDimension,
-    period: string,
-  ): Promise<CachedResult<UsageByResponse>>;
-  usageCache(tenantId: string, period: string): Promise<CachedResult<UsageCacheResponse>>;
-  usageRequests(
-    tenantId: string,
-    period: string,
-    limit: number,
-    httpStatus?: number,
-  ): Promise<CachedResult<UsageRequestsResponse>>;
-  usageRequestDetail(tenantId: string, requestId: string): Promise<UsageRequestDetail | undefined>;
-}
-export interface ObservabilityConfig {
-  readonly store: ObservabilityStore;
-  readonly accessResolver: ConsoleAccessResolver;
-}
-
-export function createObservabilityOperations(config: ObservabilityConfig) {
-  const operations = {
-    /**
-     * The cached reads below answer with a `Response` rather than a plain
-     * object, because a repeated poll is a `304` and a `304` has no body to
-     * serialize. `ifNoneMatch` is the client's `If-None-Match`; a match costs
-     * ~200 bytes instead of the whole payload.
-     */
-    async getSystemHealth(
-        access: AccessDecision | undefined,
-        ifNoneMatch: string | null,
-      ): Promise<Response> {
-        const a = requireTenantScope(access, "dashboard:read");
-        const result = await config.store.health(a.tenantId);
-        return conditionalResponse(ifNoneMatch, result, result.value);
-      },
-    async getTenantUsage(
-        access: AccessDecision | undefined,
-        period = "7d",
-        ifNoneMatch: string | null = null,
-      ): Promise<Response> {
-        const a = requireTenantScope(access, "dashboard:read");
-        if (!isSupportedUsagePeriod(period)) {
-          throw new ConsoleDomainError(
-            "invalid_period",
-            400,
-            `Unsupported usage period: ${period}. Use "24h", "7d", "30d", or "all".`,
-          );
-        }
-        const result = await config.store.usage(a.tenantId, period);
-        return conditionalResponse(ifNoneMatch, result, result.value);
-      },
-    async listEvents(
-        access: AccessDecision | undefined,
-        limit?: string,
-        cursor?: string,
-      ): Promise<TelemetryEventListPage> {
-        const a = requireTenantScope(access, "dashboard:read");
-        const lim = parseQueryLimit(limit, 50, 100);
-        const page = await config.store.listEvents(a.tenantId, lim, cursor);
-        const entries = page.entries;
-        return page.nextCursor ? { entries, nextCursor: page.nextCursor } : { entries };
-      },
-    async getEventDetail(
-        access: AccessDecision | undefined,
-        eventId: string,
-        includePayload = false,
-        createdAt?: string,
-      ): Promise<TelemetryEventDetail> {
-        const a = requireTenantScope(access, "dashboard:read");
-        const detail = await config.store.getEvent(
-          a.tenantId,
-          eventId,
-          includePayload,
-          createdAt,
-        );
-        if (!detail) throw new ConsoleDomainError("event_not_found", 404, `Event ${eventId} not found`);
-        return detail;
-      },
-    requirePeriod(period: string): string {
-        if (!isSupportedUsagePeriod(period)) {
-          throw new ConsoleDomainError(
-            "invalid_period",
-            400,
-            `Unsupported usage period: ${period}. Use "1h", "24h", "7d", "30d", or "all".`,
-          );
-        }
-        return period;
-      },
-    requireTenant(access: AccessDecision | undefined): string {
-        const a = requireTenantScope(access, "dashboard:read");
-        return a.tenantId;
-      },
-    async getUsageSummary(
-        access: AccessDecision | undefined,
-        period = "24h",
-        ifNoneMatch: string | null = null,
-      ): Promise<Response> {
-        const tenantId = operations.requireTenant(access);
-        const result = await config.store.usageSummary(tenantId, operations.requirePeriod(period));
-        return conditionalResponse(ifNoneMatch, result, result.value);
-      },
-    async getUsageChart(
-        access: AccessDecision | undefined,
-        period = "24h",
-        ifNoneMatch: string | null = null,
-      ): Promise<Response> {
-        const tenantId = operations.requireTenant(access);
-        const result = await config.store.usageChart(tenantId, operations.requirePeriod(period));
-        return conditionalResponse(ifNoneMatch, result, result.value);
-      },
-    async getUsageBy(
-        access: AccessDecision | undefined,
-        dimension: UsageDimension,
-        period = "24h",
-        ifNoneMatch: string | null = null,
-      ): Promise<Response> {
-        const tenantId = operations.requireTenant(access);
-        if (!(USAGE_DIMENSIONS as readonly string[]).includes(dimension)) {
-          throw new ConsoleDomainError(
-            "invalid_dimension",
-            400,
-            `Unsupported usage dimension: ${dimension}. Use ${USAGE_DIMENSIONS.map((d) => `"${d}"`).join(", ")}.`,
-          );
-        }
-        const result = await config.store.usageBy(tenantId, dimension, operations.requirePeriod(period));
-        return conditionalResponse(ifNoneMatch, result, result.value);
-      },
-    async getUsageCache(
-        access: AccessDecision | undefined,
-        period = "24h",
-        ifNoneMatch: string | null = null,
-      ): Promise<Response> {
-        const tenantId = operations.requireTenant(access);
-        const result = await config.store.usageCache(tenantId, operations.requirePeriod(period));
-        return conditionalResponse(ifNoneMatch, result, result.value);
-      },
-    async listUsageRequests(
-      access: AccessDecision | undefined,
-      period = "24h",
-      limit?: string,
-      httpStatus?: string,
-      ifNoneMatch: string | null = null,
-    ): Promise<Response> {
-      const tenantId = operations.requireTenant(access);
-      let parsedStatus: number | undefined;
-      if (httpStatus !== undefined) {
-        parsedStatus = Number(httpStatus);
-        if (!Number.isInteger(parsedStatus) || parsedStatus < 100 || parsedStatus > 599) {
-          throw new ConsoleDomainError("invalid_request", 400, "Invalid HTTP status filter");
-        }
-      }
-      const result = await config.store.usageRequests(
-        tenantId,
-        operations.requirePeriod(period),
-        parseQueryLimit(limit, 50, 500),
-        parsedStatus,
-      );
-      return conditionalResponse(ifNoneMatch, result, result.value);
-    },
-    async getUsageRequestDetail(
-        access: AccessDecision | undefined,
-        requestId: string,
-      ): Promise<UsageRequestDetail> {
-        const tenantId = operations.requireTenant(access);
-        const detail = await config.store.usageRequestDetail(tenantId, requestId);
-        if (!detail) throw new ConsoleDomainError("event_not_found", 404, `Request ${requestId} not found`);
-        const payloads = detail.payloads ?? null;
-        return { ...detail, payloads };
-      },
-  };
-  return operations;
-}
+import type { ConsoleAccessResolver } from "../auth/access";
+// Telemetry domain: system health, usage, and telemetry-event read API.
+
+import { readdir } from "node:fs/promises";
+import { ConsoleDomainError, requireTenantScope } from "../shared/errors";
+import { conditionalResponse, type CachedResult } from "../shared/read-through-cache";
+import { parseQueryLimit } from "../shared/query";
+import type { AccessDecision } from "../../security/access-control";
+import { resolveTelemetryCompactAfterDays } from "../../config/telemetry";
+import { USAGE_DIMENSIONS, type UsageDimension } from "./usage-dimensions";
+
+/**
+ * Whitelisted usage periods. Numeric tokens bound the aggregation window;
+ * `"all"` is the single explicit unbounded token. Anything else is rejected
+ * before any database query so a typo cannot trigger a full-table scan.
+ */
+export function isSupportedUsagePeriod(period: string): boolean {
+  if (period === "all") return true;
+  const match = /^(\d+)([hd])$/.exec(period);
+  if (!match) return false;
+  const amount = Number(match[1]);
+  const cap = match[2] === "h" ? 8760 : 365;
+  return Number.isSafeInteger(amount) && amount >= 1 && amount <= cap;
+}
+
+/**
+ * Why a request detail cannot be shown.
+ *
+ * A compacted request is genuinely gone: past the compaction age its row was
+ * folded into a per-day summary, and the individual request no longer exists
+ * anywhere. That is by design, not data loss — but "Request not found" reads
+ * like the latter, and an operator who thinks history was lost will go looking
+ * for a bug that is not there.
+ *
+ * The age is checked against the summary files rather than assumed: a request
+ * from before retention is aged out, not compacted, and the two deserve
+ * different words.
+ */
+async function detailNotFoundMessage(requestId: string, noun = "Request"): Promise<string> {
+  const compacted = await readdir("./data/telemetry-events").catch(() => [] as string[]);
+  const hasSummaries = compacted.some((file) => file.endsWith(".index.json"));
+  if (!hasSummaries) return `${noun} ${requestId} not found`;
+  return (
+    `${noun} ${requestId} is no longer stored individually: requests older than ` +
+    `${resolveTelemetryCompactAfterDays()} day(s) are compacted into daily summaries. ` +
+    `Its totals still count in Usage — raise CARTETHYIA_TELEMETRY_COMPACT_AFTER_DAYS ` +
+    `to keep individual requests longer.`
+  );
+}
+
+export { USAGE_PERIODS, type UsagePeriod } from "./usage-periods";
+
+export interface SystemHealthResponse {
+  version: string;
+  status: "healthy" | "degraded" | "unhealthy";
+  uptime_seconds: number;
+  database_healthy: boolean;
+  redis_healthy: boolean;
+  /** False when no Redis client is configured and coordination stays in memory. */
+  redis_configured: boolean;
+  /** JavaScript heap used by this process. */
+  memory_heap_bytes: number;
+  /** Native buffers and malloc outside the JavaScript heap. */
+  memory_external_bytes: number;
+  memory_bytes: number;
+  /** RSS as a percentage of system memory, not of the JS heap. */
+  memory_percent: number;
+  /**
+   * True when the database runs inside this process (SQLite). Then RSS covers
+   * the gateway *and* a whole PostgreSQL build, so it is not comparable with a
+   * driver-only process and the console must say so rather than imply the
+   * gateway itself grew.
+   */
+  database_in_process: boolean;
+  /**
+   * `null` when the platform does not report it — there is no `loadavg` on
+   * Windows and Node hands back a zeroed tuple rather than failing, so on
+   * Windows this is always `null` rather than a confident-looking `0`.
+   *
+   * Nullable rather than `NaN`: `NaN` is not a JSON value and serializes to
+   * `null` anyway, which means a client validating the field as a number
+   * rejects the *whole* health payload. One unavailable metric then reads as
+   * every metric being unavailable.
+   */
+  cpu_percent: number | null;
+  cpu_cores: number;
+  pid: number;
+  platform: string;
+  request_count: number;
+  error_count: number;
+  latency_avg_ms: number;
+  latency_p95_ms: number;
+  latency_p99_ms: number;
+  cache_hit_rate_percent: number;
+  avg_tokens_per_sec: number;
+}
+export interface UsageResponse {
+  tenantId: string;
+  period: string;
+  requestsTotal: number;
+  requestsSucceeded: number;
+  requestsFailed: number;
+  tokensUsed: number;
+  estimatedCost: number;
+  topModels: Array<{ modelId: string; count: number }>;
+  topProviders: Array<{ providerId: string; count: number }>;
+}
+
+/** Period-bound usage summary mirroring the 20-beta analytics surface. */
+export interface UsageSummaryTotals {
+  requests: number;
+  inputTokens: number;
+  cachedTokens: number;
+  outputTokens: number;
+  /**
+   * Failed and truncated requests. Client aborts (`cancelled`, rendered 499)
+   * are expected client behavior, never an error, and are tracked separately.
+   */
+  errors: number;
+  /** Client-cancelled requests (rendered `499`) — a sub-count, never an error. */
+  cancelled: number;
+  /** Streams that ended early (`502`); also included in `errors`. */
+  truncated: number;
+  /** Counts by actual HTTP status for the clickable Requests filters. */
+  statusCounts: Array<{ status: number; count: number }>;
+  /** Average gateway routing and preparation delay before upstream dispatch. */
+  avgResolveMs: number;
+  avgDurationMs: number;
+  /** Nearest-rank latency percentiles over the selected usage period. */
+  latencyP50Ms: number;
+  latencyP95Ms: number;
+  latencyP99Ms: number;
+  /**
+   * How many events each latency series was computed from. A percentile over
+   * twenty requests and one over twenty thousand do not deserve the same
+   * confidence, and the count is the only thing that says which it is.
+   */
+  latencySampleCount: number;
+  /** Events carrying a resolve measurement; differs when a row never dispatched. */
+  resolveSampleCount: number;
+  estimatedCostUsd: number;
+  /** True when completed rows without persisted cost exist in the window. */
+  partial: boolean;
+  /** Cache hit rate percentage (0-100). */
+  cacheHitRate: number;
+  /** Average tokens per second across the period. */
+  avgTokensPerSec: number;
+}
+export interface UsageSummaryResponse {
+  period: string;
+  totals: UsageSummaryTotals;
+}
+export interface UsageChartBucket {
+  /** Bucket start as ISO timestamp. */
+  t: string;
+  requests: number;
+  input: number;
+  cached: number;
+  output: number;
+}
+export interface UsageChartResponse {
+  buckets: UsageChartBucket[];
+}
+export interface UsageByRow {
+  name: string;
+  requests: number;
+  input: number;
+  output: number;
+  cached: number;
+  total: number;
+  errors: number;
+  /** Null when no row in the group carries persisted cost. */
+  costUsd: number | null;
+  /** Resolved API key label for the `key` dimension; absent otherwise. */
+  label?: string;
+  /** Cache hit rate percentage (0-100). */
+  cacheHitRate: number;
+  /** Average tokens per second for this dimension. */
+  avgTokensPerSec: number;
+}
+/**
+ * Breakdown dimensions the usage endpoint accepts. Declared in `./usage-dimensions`
+ * and re-exported here, because three layers read the same binding: the route
+ * table registers one `by-<dimension>` path per member, the operations validator
+ * rejects anything outside it, and the dashboard's `Dimension` union mirrors it
+ * (kept in sync by hand).
+ */
+export { USAGE_DIMENSIONS, type UsageDimension };
+
+export interface UsageByResponse {
+  /** The dimension these rows were grouped by, so a stale response can never be read as another tab's data. */
+  dimension: UsageDimension;
+  rows: UsageByRow[];
+}
+export interface UsageCacheResponse {
+  period: string;
+  inputTokens: number;
+  cachedTokens: number;
+  /** Always zero: cache-write tokens are not tracked by the telemetry schema. */
+  cacheWriteTokens: number;
+  hitRate: number;
+}
+export type UsageRequestMode = "stream" | "non_stream";
+export interface UsageRequestItem {
+  requestId: string;
+  surface?: string;
+  providerId?: string;
+  /** Provider account (credential) that served this request, if any. */
+  accountId?: string;
+  model?: string;
+  /**
+   * The model the upstream named in its own response, verbatim — not the one
+   * the client asked for. Absent when the response carried no `model`; never
+   * backfilled from `model`, because that would report the ask as the answer.
+   */
+  reportedModel?: string;
+  endpoint?: string;
+  apiKeyId?: string;
+  userAgent?: string;
+  clientName?: string;
+  estimatedCost?: number;
+  /** Provider-billed credits; absent when the upstream reported no credit field. */
+  creditUsed?: number;
+  /** Gateway-side time from request start to upstream dispatch, in ms. */
+  resolveMs?: number;
+  /** Resolved API key label; absent when the key is gone or unknown. */
+  apiKeyLabel?: string;
+  /** HTTP status the client actually received; absent on historical rows. */
+  httpStatus?: number;
+  status: string;
+  errorKind?: string;
+  /**
+   * Which layer failed: `cartethyia` (the gateway), `upstream` (the provider),
+   * or `network`. Absent for rows written before the column existed.
+   */
+  errorOrigin?: string;
+  mode: UsageRequestMode;
+  startedAt: string;
+  clientIp?: string;
+  durationMs?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedTokens?: number;
+  reasoningTokens?: number;
+  totalTokens?: number;
+  ttfbMs?: number;
+  tokensPerSec?: number;
+  firstContentDeltaAtMs?: number;
+  lastEventAtMs?: number;
+  /**
+   * Why this request's drawer payloads are empty, or `captured` when they are
+   * not. Remote-diagnosis field: the four panels read blank for every reason
+   * alike, so without this an operator cannot tell "capture is off" from
+   * "capture is broken" without access to the server's logs. Absent on rows
+   * written before the column existed.
+   */
+  payloadCaptureState?: string;
+  /**
+   * Bitmask of the payload stages captured for this request: 1 request,
+   * 2 provider request, 4 provider response, 8 client response. Read from the
+   * payload row so the list can mark each drawer panel without inflating a
+   * frame per row. Absent when nothing was captured for the request — the same
+   * state a pre-migration row reports, rendered as every stage uncaptured
+   * rather than as a measured zero.
+   */
+  payloadStages?: number;
+}
+export interface UsageRequestsResponse {
+  items: UsageRequestItem[];
+}
+export interface UsageRequestDetail extends UsageRequestItem {
+  proxy?: string;
+  payloads?: {
+    request?: unknown;
+    response?: unknown;
+    /** Body Cartethyia returned to the client (post-translation). */
+    clientResponse?: unknown;
+    providerRequest?: unknown;
+    providerResponse?: unknown;
+  } | null;
+  payloadSignals?: {
+    toolCalls: number;
+    images: number;
+    attachments: number;
+  };
+}
+export interface TelemetryEventView {
+  id: string;
+  createdAt: string;
+  tenantId: string;
+  requestId: string;
+  sourceSurface?: string;
+  requestedModel?: string;
+  providerId?: string;
+  latencyMs?: number;
+  status?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  estimatedCost?: number;
+  firstContentDeltaAtMs?: number;
+  lastEventAtMs?: number;
+}
+export interface TelemetryEventDetail extends TelemetryEventView {
+  payload?: { requestBody?: unknown; responseBody?: unknown };
+}
+export interface TelemetryEventListPage {
+  entries: readonly TelemetryEventView[];
+  /** Opaque cursor for the next page; `undefined` when the tail is reached. */
+  nextCursor?: string;
+}
+export interface ObservabilityStore {
+  /**
+   * Every member below that is served from the read-through cache returns a
+   * {@link CachedResult}, carrying the strong validator for the bytes the
+   * client would otherwise receive. A repeated poll is then a `304` instead of
+   * a full payload. The reads that are per-row and already bounded — the event
+   * list and the detail views — have no cache entry and no validator.
+   */
+  health(tenantId: string): Promise<CachedResult<SystemHealthResponse>>;
+  /**
+   * Process memory as it is right now, bypassing the read-through cache.
+   *
+   * `health` is cached for 10 s, which is correct for a dashboard tile and
+   * wrong for anything sampling a trend: a memory watcher polling on that same
+   * 10 s cadence reads the cached bytes often enough that consecutive samples
+   * can be identical, and a monotonic-growth test over identical samples is
+   * meaningless. The values are read in-process and cost nothing, so there is
+   * no reason to serve them stale.
+   */
+  liveMemory(): Promise<{ memory_bytes: number; memory_percent: number }>;
+  usage(tenantId: string, period: string): Promise<CachedResult<UsageResponse>>;
+  listEvents(tenantId: string, limit: number, cursor?: string): Promise<TelemetryEventListPage>;
+  getEvent(
+    tenantId: string,
+    eventId: string,
+    includePayload: boolean,
+    createdAt?: string,
+  ): Promise<TelemetryEventDetail | undefined>;
+  usageSummary(tenantId: string, period: string): Promise<CachedResult<UsageSummaryResponse>>;
+  usageChart(tenantId: string, period: string): Promise<CachedResult<UsageChartResponse>>;
+  usageBy(
+    tenantId: string,
+    dimension: UsageDimension,
+    period: string,
+  ): Promise<CachedResult<UsageByResponse>>;
+  usageCache(tenantId: string, period: string): Promise<CachedResult<UsageCacheResponse>>;
+  usageRequests(
+    tenantId: string,
+    period: string,
+    limit: number,
+    httpStatus?: number,
+  ): Promise<CachedResult<UsageRequestsResponse>>;
+  usageRequestDetail(tenantId: string, requestId: string): Promise<UsageRequestDetail | undefined>;
+}
+export interface ObservabilityConfig {
+  readonly store: ObservabilityStore;
+  readonly accessResolver: ConsoleAccessResolver;
+}
+
+export function createObservabilityOperations(config: ObservabilityConfig) {
+  const operations = {
+    /**
+     * The cached reads below answer with a `Response` rather than a plain
+     * object, because a repeated poll is a `304` and a `304` has no body to
+     * serialize. `ifNoneMatch` is the client's `If-None-Match`; a match costs
+     * ~200 bytes instead of the whole payload.
+     */
+    async getSystemHealth(
+        access: AccessDecision | undefined,
+        ifNoneMatch: string | null,
+      ): Promise<Response> {
+        const a = requireTenantScope(access, "dashboard:read");
+        const result = await config.store.health(a.tenantId);
+        return conditionalResponse(ifNoneMatch, result, result.value);
+      },
+    async getTenantUsage(
+        access: AccessDecision | undefined,
+        period = "7d",
+        ifNoneMatch: string | null = null,
+      ): Promise<Response> {
+        const a = requireTenantScope(access, "dashboard:read");
+        if (!isSupportedUsagePeriod(period)) {
+          throw new ConsoleDomainError(
+            "invalid_period",
+            400,
+            `Unsupported usage period: ${period}. Use "24h", "7d", "30d", or "all".`,
+          );
+        }
+        const result = await config.store.usage(a.tenantId, period);
+        return conditionalResponse(ifNoneMatch, result, result.value);
+      },
+    async listEvents(
+        access: AccessDecision | undefined,
+        limit?: string,
+        cursor?: string,
+      ): Promise<TelemetryEventListPage> {
+        const a = requireTenantScope(access, "dashboard:read");
+        const lim = parseQueryLimit(limit, 50, 100);
+        const page = await config.store.listEvents(a.tenantId, lim, cursor);
+        const entries = page.entries;
+        return page.nextCursor ? { entries, nextCursor: page.nextCursor } : { entries };
+      },
+    async getEventDetail(
+        access: AccessDecision | undefined,
+        eventId: string,
+        includePayload = false,
+        createdAt?: string,
+      ): Promise<TelemetryEventDetail> {
+        const a = requireTenantScope(access, "dashboard:read");
+        const detail = await config.store.getEvent(
+          a.tenantId,
+          eventId,
+          includePayload,
+          createdAt,
+        );
+        if (!detail) {
+          throw new ConsoleDomainError(
+            "event_not_found",
+            404,
+            await detailNotFoundMessage(eventId, "Event"),
+          );
+        }
+        return detail;
+      },
+    requirePeriod(period: string): string {
+        if (!isSupportedUsagePeriod(period)) {
+          throw new ConsoleDomainError(
+            "invalid_period",
+            400,
+            `Unsupported usage period: ${period}. Use "1h", "24h", "7d", "30d", or "all".`,
+          );
+        }
+        return period;
+      },
+    requireTenant(access: AccessDecision | undefined): string {
+        const a = requireTenantScope(access, "dashboard:read");
+        return a.tenantId;
+      },
+    async getUsageSummary(
+        access: AccessDecision | undefined,
+        period = "24h",
+        ifNoneMatch: string | null = null,
+      ): Promise<Response> {
+        const tenantId = operations.requireTenant(access);
+        const result = await config.store.usageSummary(tenantId, operations.requirePeriod(period));
+        return conditionalResponse(ifNoneMatch, result, result.value);
+      },
+    async getUsageChart(
+        access: AccessDecision | undefined,
+        period = "24h",
+        ifNoneMatch: string | null = null,
+      ): Promise<Response> {
+        const tenantId = operations.requireTenant(access);
+        const result = await config.store.usageChart(tenantId, operations.requirePeriod(period));
+        return conditionalResponse(ifNoneMatch, result, result.value);
+      },
+    async getUsageBy(
+        access: AccessDecision | undefined,
+        dimension: UsageDimension,
+        period = "24h",
+        ifNoneMatch: string | null = null,
+      ): Promise<Response> {
+        const tenantId = operations.requireTenant(access);
+        if (!(USAGE_DIMENSIONS as readonly string[]).includes(dimension)) {
+          throw new ConsoleDomainError(
+            "invalid_dimension",
+            400,
+            `Unsupported usage dimension: ${dimension}. Use ${USAGE_DIMENSIONS.map((d) => `"${d}"`).join(", ")}.`,
+          );
+        }
+        const result = await config.store.usageBy(tenantId, dimension, operations.requirePeriod(period));
+        return conditionalResponse(ifNoneMatch, result, result.value);
+      },
+    async getUsageCache(
+        access: AccessDecision | undefined,
+        period = "24h",
+        ifNoneMatch: string | null = null,
+      ): Promise<Response> {
+        const tenantId = operations.requireTenant(access);
+        const result = await config.store.usageCache(tenantId, operations.requirePeriod(period));
+        return conditionalResponse(ifNoneMatch, result, result.value);
+      },
+    async listUsageRequests(
+      access: AccessDecision | undefined,
+      period = "24h",
+      limit?: string,
+      httpStatus?: string,
+      ifNoneMatch: string | null = null,
+    ): Promise<Response> {
+      const tenantId = operations.requireTenant(access);
+      let parsedStatus: number | undefined;
+      if (httpStatus !== undefined) {
+        parsedStatus = Number(httpStatus);
+        if (!Number.isInteger(parsedStatus) || parsedStatus < 100 || parsedStatus > 599) {
+          throw new ConsoleDomainError("invalid_request", 400, "Invalid HTTP status filter");
+        }
+      }
+      const result = await config.store.usageRequests(
+        tenantId,
+        operations.requirePeriod(period),
+        parseQueryLimit(limit, 50, 500),
+        parsedStatus,
+      );
+      return conditionalResponse(ifNoneMatch, result, result.value);
+    },
+    async getUsageRequestDetail(
+        access: AccessDecision | undefined,
+        requestId: string,
+      ): Promise<UsageRequestDetail> {
+        const tenantId = operations.requireTenant(access);
+        const detail = await config.store.usageRequestDetail(tenantId, requestId);
+        if (!detail) {
+          throw new ConsoleDomainError(
+            "event_not_found",
+            404,
+            await detailNotFoundMessage(requestId),
+          );
+        }
+        const payloads = detail.payloads ?? null;
+        return { ...detail, payloads };
+      },
+  };
+  return operations;
+}