nuxt-observe 0.0.2

package/dist/runtime/shared/schema/frogger-map.js

@@ -0,0 +1,30 @@
+export const FROGGER_FIELD_MAP = {
+  log: {
+    "time": "time",
+    "lvl": "level",
+    "type": "(dropped: redundant with lvl)",
+    "msg": "message",
+    "ctx": "ctx (+ derived: error/session/user/route/feature)",
+    "tags": "tags",
+    "env": "source.env",
+    "source.name": "source.app",
+    "source.version": "source.version",
+    "trace.traceId": "trace.traceId",
+    "trace.spanId": "trace.spanId",
+    "trace.parentId": "trace.parentId",
+    "trace.flags": "(dropped: canonical omits flags)"
+  },
+  batch: {
+    "logs": "events",
+    "app.name": "source.app",
+    "app.version": "source.version",
+    "meta": "meta (passthrough)"
+  },
+  ctxDerived: {
+    "ctx.error": "error",
+    "ctx.session": "session",
+    "ctx.user": "user",
+    "ctx.route": "route",
+    "ctx.feature": "feature"
+  }
+};

package/dist/runtime/shared/schema/index.d.ts

@@ -0,0 +1,17 @@
+export * from './levels.js';
+export * from './event.js';
+export * from './batch.js';
+export * from './log-row.js';
+export * from './tiers.js';
+export * from './frogger-map.js';
+export * from './adapters/frogger.js';
+export * from './registry.js';
+export * from './provisioning.js';
+export * from './overview.js';
+export * from './stats.js';
+export * from './logs-query.js';
+export * from './activity.js';
+export * from './journey.js';
+export * from './rollout.js';
+export * from './error-fingerprint.js';
+export * from './errors-query.js';

package/dist/runtime/shared/schema/index.js

@@ -0,0 +1,17 @@
+export * from "./levels.js";
+export * from "./event.js";
+export * from "./batch.js";
+export * from "./log-row.js";
+export * from "./tiers.js";
+export * from "./frogger-map.js";
+export * from "./adapters/frogger.js";
+export * from "./registry.js";
+export * from "./provisioning.js";
+export * from "./overview.js";
+export * from "./stats.js";
+export * from "./logs-query.js";
+export * from "./activity.js";
+export * from "./journey.js";
+export * from "./rollout.js";
+export * from "./error-fingerprint.js";
+export * from "./errors-query.js";

package/dist/runtime/shared/schema/journey.d.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+/**
+ * Mirrored from frogger trace-headers.ts:63-79 (frogger is a read-only companion,
+ * not a dependency): rejects the all-zero id that the W3C spec forbids but the
+ * canonical zTraceContext regex alone would accept.
+ */
+export declare function isValidTraceId(traceId: unknown): traceId is string;
+export declare const journeyQuerySchema: z.ZodObject<{
+    traceId: z.ZodOptional<z.ZodString>;
+    session: z.ZodOptional<z.ZodString>;
+    user: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    to: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type JourneyQuery = z.infer<typeof journeyQuerySchema>;
+export type JourneyMode = 'trace' | 'session' | 'user';
+/** Resolve which mode a validated query is in (exactly one selector guaranteed by the refine). */
+export declare function journeyMode(q: JourneyQuery): {
+    mode: JourneyMode;
+    key: string;
+};
+/** The selector param name each mode maps to on the wire (trace -> traceId). */
+export declare const MODE_PARAM: Record<JourneyMode, 'traceId' | 'session' | 'user'>;
+export interface JourneyEvent {
+    id: string;
+    time: number;
+    offsetMs: number;
+    level: number;
+    message: string;
+    app: string;
+    version: string | null;
+    service_id: string | null;
+    route: string | null;
+    feature: string | null;
+    session: string | null;
+    error: {
+        name?: string;
+        message?: string;
+        code?: string;
+    } | null;
+    traceId: string | null;
+    spanId: string | null;
+    parentId: string | null;
+    hasTrace: boolean;
+    hasParent: boolean;
+}
+export interface JourneyStats {
+    count: number;
+    start: number | null;
+    end: number | null;
+    durationMs: number;
+    services: string[];
+    levels: Record<string, number>;
+}
+export type JourneyReason = 'empty' | 'missing-correlation' | 'dangling-parent' | 'truncated';
+export interface JourneyResponse {
+    mode: JourneyMode;
+    key: string;
+    partial: boolean;
+    reasons: JourneyReason[];
+    stats: JourneyStats;
+    events: JourneyEvent[];
+}
+/**
+ * Aggregate over an already-ordered journey. Pure (uses only the levels.ts name
+ * map), so it unit-tests in node env alongside buildSpanTree/detectPartial.
+ */
+export declare function computeJourneyStats(events: JourneyEvent[]): JourneyStats;
+/**
+ * Flags the ways a journey can be an incomplete picture, so the page can signal
+ * it honestly rather than look broken. `hitLimit` is passed in (the DB layer
+ * knows whether the row count reached the scan cap).
+ */
+export declare function detectPartial(events: JourneyEvent[], hitLimit: boolean): {
+    partial: boolean;
+    reasons: JourneyReason[];
+};
+export interface SpanNode {
+    event: JourneyEvent;
+    children: SpanNode[];
+    depth: number;
+}
+/**
+ * Links parentId -> spanId into a forest for the trace-mode waterfall. Session/
+ * user modes render a flat chronological list instead and do NOT call this.
+ *
+ * Edge cases: an event with no spanId becomes its own root; a dangling parentId
+ * (parent not in the set) promotes the node to a root lane; a parentId cycle
+ * cannot form a tree because a child is only ever attached to a parent already
+ * in `bySpan` and no node is re-parented after placement; a duplicate spanId
+ * (retries) is last-writer-wins in the map, which is acceptable here.
+ */
+export declare function buildSpanTree(events: JourneyEvent[]): SpanNode[];
+/** Depth-first flatten of the span forest into render rows, tree order preserved. */
+export declare function flattenSpanTree(roots: SpanNode[]): Array<{
+    event: JourneyEvent;
+    depth: number;
+}>;

package/dist/runtime/shared/schema/journey.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { levelName } from "./levels.js";
+const TRACE_ID_RE = /^[0-9a-f]{32}$/;
+const ALL_ZERO_TRACE = "00000000000000000000000000000000";
+export function isValidTraceId(traceId) {
+  return typeof traceId === "string" && TRACE_ID_RE.test(traceId) && traceId !== ALL_ZERO_TRACE;
+}
+export const journeyQuerySchema = z.object({
+  traceId: z.string().optional(),
+  session: z.string().min(1).max(200).optional(),
+  user: z.string().min(1).max(200).optional(),
+  from: z.coerce.number().int().positive().optional(),
+  to: z.coerce.number().int().positive().optional(),
+  limit: z.coerce.number().int().min(1).max(5e3).default(2e3)
+}).superRefine((v, ctx) => {
+  const present = [v.traceId, v.session, v.user].filter((x) => x !== void 0);
+  if (present.length !== 1) {
+    ctx.addIssue({ code: "custom", message: "Provide exactly one of traceId, session, or user" });
+    return;
+  }
+  if (v.traceId !== void 0 && !isValidTraceId(v.traceId)) {
+    ctx.addIssue({ code: "custom", path: ["traceId"], message: "traceId must be 32 lowercase hex, non-zero" });
+  }
+});
+export function journeyMode(q) {
+  if (q.traceId !== void 0) return { mode: "trace", key: q.traceId };
+  if (q.session !== void 0) return { mode: "session", key: q.session };
+  return { mode: "user", key: q.user };
+}
+export const MODE_PARAM = {
+  trace: "traceId",
+  session: "session",
+  user: "user"
+};
+export function computeJourneyStats(events) {
+  if (events.length === 0) {
+    return { count: 0, start: null, end: null, durationMs: 0, services: [], levels: {} };
+  }
+  let start = events[0].time;
+  let end = events[0].time;
+  const services = [];
+  const seen = /* @__PURE__ */ new Set();
+  const levels = {};
+  for (const e of events) {
+    if (e.time < start) start = e.time;
+    if (e.time > end) end = e.time;
+    if (e.app && !seen.has(e.app)) {
+      seen.add(e.app);
+      services.push(e.app);
+    }
+    const name = levelName(e.level);
+    levels[name] = (levels[name] ?? 0) + 1;
+  }
+  return { count: events.length, start, end, durationMs: end - start, services, levels };
+}
+export function detectPartial(events, hitLimit) {
+  const reasons = /* @__PURE__ */ new Set();
+  if (events.length === 0) reasons.add("empty");
+  const spans = new Set(events.map((e) => e.spanId).filter(Boolean));
+  for (const e of events) {
+    if (!e.hasTrace) reasons.add("missing-correlation");
+    if (e.parentId && !spans.has(e.parentId)) reasons.add("dangling-parent");
+  }
+  if (hitLimit) reasons.add("truncated");
+  return { partial: reasons.size > 0, reasons: [...reasons] };
+}
+export function buildSpanTree(events) {
+  const bySpan = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.spanId) bySpan.set(e.spanId, { event: e, children: [], depth: 0 });
+  }
+  const roots = [];
+  for (const e of events) {
+    const node = e.spanId ? bySpan.get(e.spanId) : { event: e, children: [], depth: 0 };
+    const parent = e.parentId ? bySpan.get(e.parentId) : void 0;
+    if (parent && parent !== node) parent.children.push(node);
+    else roots.push(node);
+  }
+  const walk = (n, d) => {
+    n.depth = d;
+    n.children.sort((a, b) => a.event.time - b.event.time);
+    n.children.forEach((c) => walk(c, d + 1));
+  };
+  roots.sort((a, b) => a.event.time - b.event.time);
+  roots.forEach((r) => walk(r, 0));
+  return roots;
+}
+export function flattenSpanTree(roots) {
+  const out = [];
+  const walk = (n) => {
+    out.push({ event: n.event, depth: n.depth });
+    n.children.forEach(walk);
+  };
+  roots.forEach(walk);
+  return out;
+}

package/dist/runtime/shared/schema/levels.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+/** Canonical severity: 0..5, lower = more severe (preserves frogger `lvl` 1:1). */
+export declare const CANONICAL_LEVELS: {
+    readonly 0: "error";
+    readonly 1: "warn";
+    readonly 2: "notice";
+    readonly 3: "info";
+    readonly 4: "debug";
+    readonly 5: "trace";
+};
+export type CanonicalLevel = keyof typeof CANONICAL_LEVELS;
+export type CanonicalLevelName = (typeof CANONICAL_LEVELS)[CanonicalLevel];
+/** zod: an int strictly in 0..5. Sentinels are NOT valid stored levels. */
+export declare const zLevel: z.ZodNumber;
+/** frogger numeric `lvl` -> canonical level. 1:1 for 0..5; sentinels handled in parseLevel(). */
+export declare const FROGGER_LEVEL_MAP: Record<number, CanonicalLevel>;
+/** frogger `type` string / any known level name -> canonical level (mirrors frogger LEVEL_TO_NUMBER). */
+export declare const NAME_TO_LEVEL: Record<string, CanonicalLevel>;
+/**
+ * syslog severity (0=Emergency..7=Debug) -> canonical. Same orientation (lower=severe).
+ * Note: syslog Notice(5) maps cleanly to canonical notice(2).
+ */
+export declare const SYSLOG_TO_CANONICAL: Record<number, CanonicalLevel>;
+/**
+ * OTel severityNumber (1..24) -> canonical. INVERTED orientation: OTel is higher=severe
+ * while this scale is lower=severe, so this is a hand-authored range table, not arithmetic.
+ * No OTel range maps to notice(2); that level is frogger-specific.
+ *   TRACE 1-4 -> 5 · DEBUG 5-8 -> 4 · INFO 9-12 -> 3 · WARN 13-16 -> 1 · ERROR 17-20 -> 0 · FATAL 21-24 -> 0
+ */
+export declare function otelSeverityToCanonical(severityNumber: number): CanonicalLevel;
+export declare function levelName(n: number): CanonicalLevelName | 'unknown';
+/**
+ * Normalise an incoming frogger numeric `lvl` OR a level name into canonical 0..5.
+ * verbose(999) -> 5 (clamp). silent(-999) -> null (drop, never store).
+ * Out-of-range or unknown -> null (caller decides: reject or default).
+ */
+export declare function parseLevel(input: number | string): CanonicalLevel | null;

package/dist/runtime/shared/schema/levels.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export const CANONICAL_LEVELS = {
+  0: "error",
+  1: "warn",
+  2: "notice",
+  // frogger alias: 'log'
+  3: "info",
+  4: "debug",
+  5: "trace"
+};
+export const zLevel = z.number().int().min(0).max(5);
+export const FROGGER_LEVEL_MAP = {
+  0: 0,
+  1: 1,
+  2: 2,
+  3: 3,
+  4: 4,
+  5: 5
+};
+export const NAME_TO_LEVEL = {
+  fatal: 0,
+  error: 0,
+  warn: 1,
+  log: 2,
+  notice: 2,
+  info: 3,
+  success: 3,
+  fail: 3,
+  ready: 3,
+  start: 3,
+  debug: 4,
+  trace: 5
+};
+export const SYSLOG_TO_CANONICAL = {
+  0: 0,
+  // Emergency
+  1: 0,
+  // Alert
+  2: 0,
+  // Critical
+  3: 0,
+  // Error
+  4: 1,
+  // Warning
+  5: 2,
+  // Notice
+  6: 3,
+  // Informational
+  7: 4
+  // Debug
+};
+export function otelSeverityToCanonical(severityNumber) {
+  if (severityNumber >= 21) return 0;
+  if (severityNumber >= 17) return 0;
+  if (severityNumber >= 13) return 1;
+  if (severityNumber >= 9) return 3;
+  if (severityNumber >= 5) return 4;
+  return 5;
+}
+export function levelName(n) {
+  return CANONICAL_LEVELS[n] ?? "unknown";
+}
+export function parseLevel(input) {
+  if (typeof input === "string") {
+    const byName = NAME_TO_LEVEL[input.toLowerCase()];
+    return byName ?? null;
+  }
+  if (input === 999) return 5;
+  if (input === -999) return null;
+  if (Number.isInteger(input) && input >= 0 && input <= 5) return input;
+  return null;
+}

package/dist/runtime/shared/schema/log-row.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Flat DB projection of a CanonicalEvent (one table row).
+ * `id` and `received_at` are ingest-assigned (NOT from the event).
+ * `app` is non-optional: the CP4 adapter guarantees it before insert
+ * (from batch app.name / log source.name), even though event.source is optional.
+ */
+export interface LogRow {
+    id: string;
+    time: number;
+    received_at: number;
+    level: number;
+    message: string;
+    error_name?: string;
+    error_message?: string;
+    error_stack?: string;
+    error_code?: string;
+    error_fingerprint?: string;
+    app: string;
+    version?: string;
+    env?: string;
+    service_id?: string;
+    session?: string;
+    user?: string;
+    route?: string;
+    feature?: string;
+    trace_id?: string;
+    span_id?: string;
+    parent_id?: string;
+    tags?: string;
+    ctx?: string;
+}

package/dist/runtime/shared/schema/logs-query.d.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import type { LogRow } from './log-row.js';
+export declare const logsQuerySchema: z.ZodObject<{
+    period: z.ZodDefault<z.ZodEnum<{
+        "15m": "15m";
+        "1h": "1h";
+        "24h": "24h";
+        "7d": "7d";
+        "30d": "30d";
+    }>>;
+    service: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+    levels: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number[], string>>, z.ZodArray<z.ZodNumber>>>;
+    versions: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodString>>>;
+    route: z.ZodOptional<z.ZodString>;
+    feature: z.ZodOptional<z.ZodString>;
+    q: z.ZodOptional<z.ZodString>;
+    traceId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type LogsQuery = z.infer<typeof logsQuerySchema>;
+/** The facets endpoint narrows its version list by the same scope slugs. */
+export declare const logsFacetsQuerySchema: z.ZodObject<{
+    service: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LogsFacetsQuery = z.infer<typeof logsFacetsQuerySchema>;
+export interface LogListItem {
+    id: string;
+    time: number;
+    level: number;
+    message: string;
+    app: string;
+    version: string | null;
+    env: string | null;
+    service_id: string | null;
+    route: string | null;
+    feature: string | null;
+    error_name: string | null;
+    trace_id: string | null;
+}
+export interface LogDetail {
+    id: string;
+    time: number;
+    received_at: number;
+    level: number;
+    message: string;
+    app: string;
+    version: string | null;
+    env: string | null;
+    service_id: string | null;
+    session: string | null;
+    user: string | null;
+    route: string | null;
+    feature: string | null;
+    error: {
+        name?: string;
+        message?: string;
+        stack?: string;
+        code?: string;
+    } | null;
+    trace: {
+        traceId?: string;
+        spanId?: string;
+        parentId?: string;
+    } | null;
+    tags: string[] | null;
+    ctx: Record<string, unknown> | null;
+}
+export interface LogListResponse {
+    period: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    rows: LogListItem[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface LogsFacetsResponse {
+    versions: string[];
+}
+/**
+ * Reassembles error/trace objects from the flat error and trace columns (null when
+ * every part is absent), JSON-parses tags/ctx inside a guard (malformed JSON -> null,
+ * never a 500), and passes `user` through (the SELECT alias already restored it).
+ * Pure, so it unit-tests in node env.
+ */
+export declare function rowToDetail(row: LogRow): LogDetail;

package/dist/runtime/shared/schema/logs-query.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { PERIODS } from "../utils/period.js";
+const csvLevels = z.string().transform((s) => s.split(",").map((v) => v.trim()).filter((v) => v.length > 0).map(Number)).pipe(z.array(z.number().int().min(0).max(5)).min(1).max(6)).optional();
+const csvStrings = z.string().transform((s) => s.split(",").map((v) => v.trim()).filter((v) => v.length > 0)).pipe(z.array(z.string().min(1).max(100)).min(1).max(20)).optional();
+export const logsQuerySchema = z.object({
+  period: z.enum(PERIODS).default("24h"),
+  /** service slug; resolved to an id and intersected with the caller's scope */
+  service: z.string().optional(),
+  /** group slug; expanded to member service ids and intersected with the caller's scope */
+  group: z.string().optional(),
+  /** CSV of exact levels, e.g. "0,1" -> level IN (0,1) */
+  levels: csvLevels,
+  /** CSV of exact versions -> version IN (...) */
+  versions: csvStrings,
+  /** exact route filter, e.g. from the activity drill-through (CP10) */
+  route: z.string().min(1).max(200).optional(),
+  /** exact feature filter, e.g. from the activity drill-through (CP10) */
+  feature: z.string().min(1).max(200).optional(),
+  /** free-text message search; message LIKE %q% ESCAPE '\' */
+  q: z.string().trim().min(1).max(200).optional(),
+  /** exact trace id; when present the period window is NOT applied (see handler §3.3) */
+  traceId: z.string().min(1).max(64).optional(),
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+  offset: z.coerce.number().int().min(0).default(0)
+});
+export const logsFacetsQuerySchema = z.object({
+  service: z.string().optional(),
+  group: z.string().optional()
+});
+function parseJson(raw, guard) {
+  if (raw == null) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return guard(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function rowToDetail(row) {
+  const error = row.error_name || row.error_message || row.error_stack || row.error_code ? {
+    ...row.error_name ? { name: row.error_name } : {},
+    ...row.error_message ? { message: row.error_message } : {},
+    ...row.error_stack ? { stack: row.error_stack } : {},
+    ...row.error_code ? { code: row.error_code } : {}
+  } : null;
+  const trace = row.trace_id || row.span_id || row.parent_id ? {
+    ...row.trace_id ? { traceId: row.trace_id } : {},
+    ...row.span_id ? { spanId: row.span_id } : {},
+    ...row.parent_id ? { parentId: row.parent_id } : {}
+  } : null;
+  return {
+    id: row.id,
+    time: row.time,
+    received_at: row.received_at,
+    level: row.level,
+    message: row.message,
+    app: row.app,
+    version: row.version ?? null,
+    env: row.env ?? null,
+    service_id: row.service_id ?? null,
+    session: row.session ?? null,
+    user: row.user ?? null,
+    route: row.route ?? null,
+    feature: row.feature ?? null,
+    error,
+    trace,
+    tags: parseJson(row.tags, isStringArray),
+    ctx: parseJson(row.ctx, isObject)
+  };
+}

package/dist/runtime/shared/schema/migrations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Framework-free wire types for the CP17 migration console, shared by the server routes
+ * (server/utils/migration-runner.ts, server/api/observe/migrations/*) and the client
+ * composable (app/composables/useObserveMigrations.ts) so the status shape and the SSE
+ * frame shape never drift between the two sides.
+ */
+export type MigrationClass = 'additive' | 'destructive';
+/** 'blocked' = pending but sits behind an earlier pending destructive migration. */
+export type MigrationState = 'applied' | 'pending' | 'blocked';
+export interface MigrationStatus {
+    id: string;
+    class: MigrationClass;
+    description: string;
+    state: MigrationState;
+    applied_at?: number;
+    driftWarning?: boolean;
+}
+export interface MigrationStatusResponse {
+    statuses: MigrationStatus[];
+    pendingDestructive: number;
+    driftWarnings: string[];
+}
+/** One SSE frame from POST /api/observe/migrations/run. */
+export type MigrationRunFrame = {
+    type: 'log';
+    line: string;
+} | {
+    type: 'complete';
+    applied: string[];
+    failedAt?: string;
+} | {
+    type: 'error';
+    message: string;
+};

package/dist/runtime/shared/schema/overview.d.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+/**
+ * Contract for GET /api/observe/overview (CP7): the query the client may send and
+ * the response shape both sides type against. Framework-free (zod only) so it loads
+ * in node-env unit tests, the Nitro handler, and the browser composable alike.
+ */
+export declare const overviewQuerySchema: z.ZodObject<{
+    period: z.ZodDefault<z.ZodEnum<{
+        "15m": "15m";
+        "1h": "1h";
+        "24h": "24h";
+        "7d": "7d";
+        "30d": "30d";
+    }>>;
+    service: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OverviewQuery = z.infer<typeof overviewQuerySchema>;
+export interface OverviewStats {
+    totalEvents: number;
+    errorCount: number;
+    /** errorCount / totalEvents, 0 when totalEvents === 0 */
+    errorRate: number;
+    warnCount: number;
+    activeServices: number;
+    activeVersions: number;
+    latestError?: {
+        time: number;
+        message: string;
+        name?: string;
+        /** human slug, falling back to the raw `app` column when service_id did not join */
+        service: string;
+        route?: string;
+        traceId?: string;
+    };
+}
+export interface OverviewServiceRollup {
+    id: string;
+    slug: string;
+    name: string;
+    env?: string;
+    totalEvents: number;
+    errorCount: number;
+    errorRate: number;
+    warnCount: number;
+    lastSeen: number;
+    versions: string[];
+}
+export interface OverviewActivityItem {
+    time: number;
+    level: number;
+    message: string;
+    /** human slug, falling back to the raw `app` column when service_id did not join */
+    service: string;
+    route?: string;
+    session?: string;
+    user?: string;
+    traceId?: string;
+    errorName?: string;
+}
+export interface OverviewResponse {
+    period: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    /** isAll=true for admin ('*'); serviceIds is [] then, not the full id list */
+    scope: {
+        serviceIds: string[];
+        isAll: boolean;
+    };
+    stats: OverviewStats;
+    services: OverviewServiceRollup[];
+    /** newest first, LIMIT 50 */
+    activity: OverviewActivityItem[];
+}
+/** The db-derived slice getOverview() assembles; the handler adds period + scope. */
+export type OverviewData = Pick<OverviewResponse, 'stats' | 'services' | 'activity'>;