nuxt-observe 0.0.2

package/dist/schema.d.mts

@@ -0,0 +1,1318 @@
+import { z } from 'zod';
+
+/** Canonical severity: 0..5, lower = more severe (preserves frogger `lvl` 1:1). */
+declare const CANONICAL_LEVELS: {
+    readonly 0: "error";
+    readonly 1: "warn";
+    readonly 2: "notice";
+    readonly 3: "info";
+    readonly 4: "debug";
+    readonly 5: "trace";
+};
+type CanonicalLevel = keyof typeof CANONICAL_LEVELS;
+type CanonicalLevelName = (typeof CANONICAL_LEVELS)[CanonicalLevel];
+/** zod: an int strictly in 0..5. Sentinels are NOT valid stored levels. */
+declare const zLevel: z.ZodNumber;
+/** frogger numeric `lvl` -> canonical level. 1:1 for 0..5; sentinels handled in parseLevel(). */
+declare const FROGGER_LEVEL_MAP: Record<number, CanonicalLevel>;
+/** frogger `type` string / any known level name -> canonical level (mirrors frogger LEVEL_TO_NUMBER). */
+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).
+ */
+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
+ */
+declare function otelSeverityToCanonical(severityNumber: number): CanonicalLevel;
+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).
+ */
+declare function parseLevel(input: number | string): CanonicalLevel | null;
+
+declare const zErrorInfo: z.ZodObject<{
+    name: z.ZodString;
+    message: z.ZodString;
+    stack: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+declare const zTraceContext: z.ZodObject<{
+    traceId: z.ZodString;
+    spanId: z.ZodString;
+    parentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const zSource: z.ZodObject<{
+    app: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const zCanonicalEvent: z.ZodObject<{
+    time: z.ZodNumber;
+    level: z.ZodNumber;
+    message: z.ZodString;
+    error: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        message: z.ZodString;
+        stack: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>>;
+    trace: z.ZodOptional<z.ZodObject<{
+        traceId: z.ZodString;
+        spanId: z.ZodString;
+        parentId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    source: z.ZodOptional<z.ZodObject<{
+        app: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        env: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    session: z.ZodOptional<z.ZodString>;
+    user: z.ZodOptional<z.ZodString>;
+    route: z.ZodOptional<z.ZodString>;
+    feature: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type ErrorInfo = z.infer<typeof zErrorInfo>;
+type TraceContextInfo = z.infer<typeof zTraceContext>;
+type EventSource = z.infer<typeof zSource>;
+type CanonicalEvent = z.infer<typeof zCanonicalEvent>;
+
+declare const MAX_BATCH_EVENTS = 500;
+declare const zCanonicalBatch: z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        time: z.ZodNumber;
+        level: z.ZodNumber;
+        message: z.ZodString;
+        error: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            message: z.ZodString;
+            stack: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strip>>;
+        trace: z.ZodOptional<z.ZodObject<{
+            traceId: z.ZodString;
+            spanId: z.ZodString;
+            parentId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        source: z.ZodOptional<z.ZodObject<{
+            app: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        session: z.ZodOptional<z.ZodString>;
+        user: z.ZodOptional<z.ZodString>;
+        route: z.ZodOptional<z.ZodString>;
+        feature: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type CanonicalBatch = z.infer<typeof zCanonicalBatch>;
+
+/**
+ * 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.
+ */
+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;
+}
+
+declare const PROGRESSIVE_TIERS: readonly ["stream", "grouping", "journey", "activity", "rollout"];
+type Tier = (typeof PROGRESSIVE_TIERS)[number];
+/** Which tiers a given event satisfies. `stream` is always included for a valid event. */
+declare function classifyTiers(event: CanonicalEvent): Tier[];
+
+/**
+ * Documented frogger -> canonical field map. Data + JSDoc ONLY. CP1 writes no
+ * transform. This is the reference the CP4 ingest adapter implements against.
+ * Grounded in frogger's log.ts, batch.ts, trace-headers.ts, normalize-log-args.ts,
+ * global-error.server.ts.
+ *
+ * ## Error derivation (adapter implements in CP4)
+ * frogger lifts errors into `ctx` in two shapes:
+ *   - normalize-log-args serializeError() writes ctx.error = { name, message, stack }.
+ *   - global-error.server writes fields flat onto ctx (message, name, stack, cause,
+ *     and for H3Error: statusCode, statusMessage, data).
+ * Resolution order:
+ *   - error.name    <- ctx.error.name    ?? ctx.name
+ *   - error.message <- ctx.error.message ?? ctx.message
+ *   - error.stack   <- ctx.error.stack   ?? ctx.stack
+ *   - error.code    <- ctx.error.code    ?? ctx.code ?? ctx.statusCode
+ * Emit `error` only if at least name+message (or message) resolve.
+ *
+ * ## Gap fields: ctx-key convention (frozen for CP4 + CP15)
+ * frogger emits no native session/user/route/feature; they are read from
+ * ctx.session / ctx.user / ctx.route / ctx.feature.
+ *
+ * ## Caveats
+ *   - source.env is frogger EXECUTION context (ssr/csr/client/server), NOT deploy
+ *     env. Mapped verbatim; deploy env rides in tags/ctx until a dedicated field exists.
+ *   - Dropped fields: `type` (redundant with numeric lvl) and `trace.flags`
+ *     (canonical omits). Both optionally preservable via ctx (froggerType / traceFlags).
+ *   - frogger client transport sends no API-key header (bare $fetch); CP4 ingest must
+ *     accept ?key= on the query string. CP1 designs no ingest.
+ */
+/** Every frogger LoggerObject/LoggerObjectBatch key -> canonical destination (or documented drop). */
+declare const FROGGER_FIELD_MAP: {
+    readonly log: {
+        readonly time: "time";
+        readonly lvl: "level";
+        readonly type: "(dropped: redundant with lvl)";
+        readonly msg: "message";
+        readonly ctx: "ctx (+ derived: error/session/user/route/feature)";
+        readonly tags: "tags";
+        readonly env: "source.env";
+        readonly 'source.name': "source.app";
+        readonly 'source.version': "source.version";
+        readonly 'trace.traceId': "trace.traceId";
+        readonly 'trace.spanId': "trace.spanId";
+        readonly 'trace.parentId': "trace.parentId";
+        readonly 'trace.flags': "(dropped: canonical omits flags)";
+    };
+    readonly batch: {
+        readonly logs: "events";
+        readonly 'app.name': "source.app";
+        readonly 'app.version': "source.version";
+        readonly meta: "meta (passthrough)";
+    };
+    readonly ctxDerived: {
+        readonly 'ctx.error': "error";
+        readonly 'ctx.session': "session";
+        readonly 'ctx.user': "user";
+        readonly 'ctx.route': "route";
+        readonly 'ctx.feature': "feature";
+    };
+};
+type FroggerFieldMap = typeof FROGGER_FIELD_MAP;
+
+/**
+ * Permissive wire schema for a frogger LoggerObjectBatch. Deliberately does NOT
+ * hex-validate trace (the canonical zTraceContext does; the adapter demotes an
+ * invalid trace into ctx instead of 400-ing the batch) and passes unknown
+ * ctx/meta keys through. zod-only: keeps the `nuxt-observe/schema` subpath pure.
+ */
+declare const zFroggerLog: z.ZodObject<{
+    time: z.ZodNumber;
+    lvl: z.ZodNumber;
+    type: z.ZodOptional<z.ZodString>;
+    msg: z.ZodString;
+    ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        version: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>;
+    trace: z.ZodOptional<z.ZodObject<{
+        traceId: z.ZodOptional<z.ZodString>;
+        spanId: z.ZodOptional<z.ZodString>;
+        parentId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+declare const zFroggerBatch: z.ZodObject<{
+    logs: z.ZodArray<z.ZodObject<{
+        time: z.ZodNumber;
+        lvl: z.ZodNumber;
+        type: z.ZodOptional<z.ZodString>;
+        msg: z.ZodString;
+        ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            version: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>>;
+        trace: z.ZodOptional<z.ZodObject<{
+            traceId: z.ZodOptional<z.ZodString>;
+            spanId: z.ZodOptional<z.ZodString>;
+            parentId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$loose>>;
+    app: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    meta: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$loose>;
+type FroggerLogInput = z.infer<typeof zFroggerLog>;
+type FroggerBatchInput = z.infer<typeof zFroggerBatch>;
+
+/**
+ * Config-seed contracts for the service registry. Pure zod + local only: this
+ * file is part of the `nuxt-observe/schema` subpath and must never import
+ * node:crypto, #imports, or any server util.
+ */
+declare const zServiceSeed: z.ZodPipe<z.ZodObject<{
+    slug: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        website: "website";
+        webapp: "webapp";
+        api: "api";
+        worker: "worker";
+        mobile: "mobile";
+        other: "other";
+    }>>;
+    kind: z.ZodDefault<z.ZodEnum<{
+        server: "server";
+        browser: "browser";
+    }>>;
+    appNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodString>;
+    versionTracking: z.ZodOptional<z.ZodBoolean>;
+    currentVersion: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    slug: string;
+    name: string;
+    type: "service" | "website" | "webapp" | "api" | "worker" | "mobile" | "other";
+    kind: "server" | "browser";
+    appNames: string[];
+    allowedOrigins: string[];
+    env?: string | undefined;
+    versionTracking?: boolean | undefined;
+    currentVersion?: string | undefined;
+    group?: string | undefined;
+    key?: string | undefined;
+}, {
+    slug: string;
+    name: string;
+    type: "service" | "website" | "webapp" | "api" | "worker" | "mobile" | "other";
+    kind: "server" | "browser";
+    appNames: string[];
+    allowedOrigins: string[];
+    env?: string | undefined;
+    versionTracking?: boolean | undefined;
+    currentVersion?: string | undefined;
+    group?: string | undefined;
+    key?: string | undefined;
+}>>;
+declare const zGroupSeed: z.ZodObject<{
+    slug: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+declare const zObserveSeedConfig: z.ZodObject<{
+    services: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            service: "service";
+            website: "website";
+            webapp: "webapp";
+            api: "api";
+            worker: "worker";
+            mobile: "mobile";
+            other: "other";
+        }>>;
+        kind: z.ZodDefault<z.ZodEnum<{
+            server: "server";
+            browser: "browser";
+        }>>;
+        appNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodString>;
+        versionTracking: z.ZodOptional<z.ZodBoolean>;
+        currentVersion: z.ZodOptional<z.ZodString>;
+        group: z.ZodOptional<z.ZodString>;
+        key: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodTransform<{
+        slug: string;
+        name: string;
+        type: "service" | "website" | "webapp" | "api" | "worker" | "mobile" | "other";
+        kind: "server" | "browser";
+        appNames: string[];
+        allowedOrigins: string[];
+        env?: string | undefined;
+        versionTracking?: boolean | undefined;
+        currentVersion?: string | undefined;
+        group?: string | undefined;
+        key?: string | undefined;
+    }, {
+        slug: string;
+        name: string;
+        type: "service" | "website" | "webapp" | "api" | "worker" | "mobile" | "other";
+        kind: "server" | "browser";
+        appNames: string[];
+        allowedOrigins: string[];
+        env?: string | undefined;
+        versionTracking?: boolean | undefined;
+        currentVersion?: string | undefined;
+        group?: string | undefined;
+        key?: string | undefined;
+    }>>>>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type ServiceSeed = z.input<typeof zServiceSeed>;
+type GroupSeed = z.input<typeof zGroupSeed>;
+type ObserveSeedConfig = z.input<typeof zObserveSeedConfig>;
+
+/**
+ * Provisioning contracts (CP11). Pure zod + local only: this file loads in the
+ * browser UForm, the Nitro routes, and node unit tests, so it must never import
+ * #imports, node:crypto, or any server util (same rule as registry.ts).
+ *
+ * `type` is orthogonal to `kind`: `kind` (server|browser) drives dynamic CORS,
+ * `type` is a descriptive UI-only category (badge + icon + filter metadata).
+ */
+declare const SERVICE_TYPES: readonly ["website", "webapp", "api", "service", "worker", "mobile", "other"];
+type ServiceType = (typeof SERVICE_TYPES)[number];
+declare const serviceTypeSchema: z.ZodEnum<{
+    service: "service";
+    website: "website";
+    webapp: "webapp";
+    api: "api";
+    worker: "worker";
+    mobile: "mobile";
+    other: "other";
+}>;
+declare const SERVICE_KINDS: readonly ["server", "browser"];
+type ServiceKind = (typeof SERVICE_KINDS)[number];
+declare const serviceKindSchema: z.ZodEnum<{
+    server: "server";
+    browser: "browser";
+}>;
+/**
+ * Presentation map for the `type` axis: one source of truth for the USelectMenu
+ * options, the table badge, and the detail header. lucide names follow the repo's
+ * `i-lucide-*` convention. An unknown/hand-edited `type` falls back to `other`
+ * at render time (see serviceTypeMeta).
+ */
+declare const SERVICE_TYPE_META: {
+    readonly website: {
+        readonly label: "Website";
+        readonly icon: "i-lucide-globe";
+    };
+    readonly webapp: {
+        readonly label: "Web app";
+        readonly icon: "i-lucide-app-window";
+    };
+    readonly api: {
+        readonly label: "API";
+        readonly icon: "i-lucide-webhook";
+    };
+    readonly service: {
+        readonly label: "Service";
+        readonly icon: "i-lucide-server";
+    };
+    readonly worker: {
+        readonly label: "Worker";
+        readonly icon: "i-lucide-cog";
+    };
+    readonly mobile: {
+        readonly label: "Mobile";
+        readonly icon: "i-lucide-smartphone";
+    };
+    readonly other: {
+        readonly label: "Other";
+        readonly icon: "i-lucide-box";
+    };
+};
+/** Lenient lookup: any unrecognised value renders as `other` rather than throwing. */
+declare function serviceTypeMeta(type: string): {
+    label: string;
+    icon: string;
+};
+declare const serviceCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        website: "website";
+        webapp: "webapp";
+        api: "api";
+        worker: "worker";
+        mobile: "mobile";
+        other: "other";
+    }>>;
+    kind: z.ZodDefault<z.ZodEnum<{
+        server: "server";
+        browser: "browser";
+    }>>;
+    appNames: z.ZodArray<z.ZodString>;
+    allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodString>;
+    versionTracking: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const serviceUpdateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        service: "service";
+        website: "website";
+        webapp: "webapp";
+        api: "api";
+        worker: "worker";
+        mobile: "mobile";
+        other: "other";
+    }>>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        server: "server";
+        browser: "browser";
+    }>>;
+    appNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    groupId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    versionTracking: z.ZodOptional<z.ZodBoolean>;
+    currentVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+declare const keyCreateSchema: z.ZodObject<{
+    label: z.ZodString;
+}, z.core.$strip>;
+declare const groupCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+declare const groupUpdateSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+declare const groupMembershipSchema: z.ZodObject<{
+    serviceIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const assignmentSchema: z.ZodObject<{
+    userIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const serviceIdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const keyIdParams: z.ZodObject<{
+    id: z.ZodString;
+    keyId: z.ZodString;
+}, z.core.$strip>;
+declare const groupIdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+type ServiceCreate = z.infer<typeof serviceCreateSchema>;
+type ServiceUpdate = z.infer<typeof serviceUpdateSchema>;
+type KeyCreate = z.infer<typeof keyCreateSchema>;
+type GroupCreate = z.infer<typeof groupCreateSchema>;
+type GroupMembership = z.infer<typeof groupMembershipSchema>;
+/**
+ * Wire shapes the composables type against. Kept here (framework-free) so the
+ * client and the routes never drift on field names.
+ */
+interface ServiceListItem {
+    id: string;
+    slug: string;
+    name: string;
+    type: ServiceType;
+    kind: ServiceKind;
+    env: string | null;
+    groupId: string | null;
+    versionTracking: boolean;
+    currentVersion: string | null;
+    keyCount: number;
+    managedByConfig: boolean;
+    deletedAt: number | null;
+    /** epoch ms at which a soft-deleted service is eligible for permanent purge, else null. */
+    purgeAt: number | null;
+}
+interface ServiceDetail extends ServiceListItem {
+    appNames: string[];
+    allowedOrigins: string[];
+    group: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+}
+interface KeyMeta {
+    id: string;
+    keyPrefix: string;
+    label: string | null;
+    createdAt: number;
+    revokedAt: number | null;
+    lastUsedAt: number | null;
+}
+interface MintedKey {
+    key: string;
+    prefix: string;
+    ingestUrl: string;
+    snippet: {
+        rawUrl: string;
+        serverPluginSnippet: string;
+        configSnippet: string;
+    };
+}
+interface GroupListItem {
+    id: string;
+    slug: string;
+    name: string;
+    serviceCount: number;
+}
+interface UserPick {
+    id: string;
+    name: string;
+    role: string;
+    assignment: {
+        services: string[];
+        groups: string[];
+    };
+}
+/**
+ * Full DB-backed user (CP16), for the edit page. `services`/`groups` carry ids + per-scope
+ * role (the assignment editor edits by id); `assignment` carries slugs for display parity
+ * with UserPick. `disabled` is a boolean on the wire (0/1 in the row).
+ */
+interface UserDetail {
+    id: string;
+    username: string;
+    displayName: string | null;
+    name: string;
+    role: string;
+    disabled: boolean;
+    source: string;
+    hasPassword: boolean;
+    createdAt: number;
+    updatedAt: number | null;
+    assignment: {
+        services: string[];
+        groups: string[];
+    };
+    services: Array<{
+        serviceId: string;
+        role: string;
+    }>;
+    groups: Array<{
+        groupId: string;
+        role: string;
+    }>;
+}
+
+/**
+ * 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.
+ */
+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>;
+type OverviewQuery = z.infer<typeof overviewQuerySchema>;
+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;
+    };
+}
+interface OverviewServiceRollup {
+    id: string;
+    slug: string;
+    name: string;
+    env?: string;
+    totalEvents: number;
+    errorCount: number;
+    errorRate: number;
+    warnCount: number;
+    lastSeen: number;
+    versions: string[];
+}
+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;
+}
+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. */
+type OverviewData = Pick<OverviewResponse, 'stats' | 'services' | 'activity'>;
+
+/**
+ * Contract for GET /api/observe/stats (CP8): the bucketed time-series the charts
+ * render. Framework-free (zod only) so it loads in node-env unit tests, the Nitro
+ * handler, and the browser composable alike.
+ */
+declare const statsQuerySchema: 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>;
+    version: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    bucketMs: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type StatsQuery = z.infer<typeof statsQuerySchema>;
+/** Legend entry for the per-service breakdown; the folded tail is { id: 'other', slug: 'other', name: 'Other' }. */
+interface StatsSeriesMeta {
+    id: string;
+    slug: string;
+    name: string;
+}
+interface StatsBucket {
+    /** bucket start, ms epoch, aligned to floor(time / bucketMs) * bucketMs */
+    t: number;
+    count: number;
+    /** level = 0 */
+    errorCount: number;
+    /** level = 1 */
+    warnCount: number;
+    /** serviceId (or 'other') -> count; only top-N + 'other' keys present */
+    byService: Record<string, number>;
+}
+interface StatsResponse {
+    period: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    /** isAll=true for admin ('*'); serviceIds is [] then, not the full id list */
+    scope: {
+        serviceIds: string[];
+        isAll: boolean;
+    };
+    bucketMs: number;
+    /** zero-filled, contiguous, ascending by t */
+    buckets: StatsBucket[];
+    /** legend for the breakdown chart: top-N by volume desc, + 'other' when folded */
+    services: StatsSeriesMeta[];
+    totals: {
+        count: number;
+        errorCount: number;
+        warnCount: number;
+        /** errorCount / count * 100, 0 when count === 0 */
+        errorRatePct: number;
+    };
+}
+/** The db-derived slice getStats() assembles; the handler adds period + scope + bucketMs. */
+type StatsData = Pick<StatsResponse, 'buckets' | 'services' | 'totals'>;
+
+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>;
+type LogsQuery = z.infer<typeof logsQuerySchema>;
+/** The facets endpoint narrows its version list by the same scope slugs. */
+declare const logsFacetsQuerySchema: z.ZodObject<{
+    service: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LogsFacetsQuery = z.infer<typeof logsFacetsQuerySchema>;
+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;
+}
+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;
+}
+interface LogListResponse {
+    period: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    rows: LogListItem[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+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.
+ */
+declare function rowToDetail(row: LogRow): LogDetail;
+
+/**
+ * Contract for GET /api/observe/activity (CP10): the ranked "top endpoints/features
+ * being hit" list. A GROUP BY over the canonical route/feature columns of `logs`,
+ * scoped and time-bounded exactly like /stats. Framework-free (zod only) so it loads
+ * in node-env unit tests, the Nitro handler, and the browser composable alike.
+ */
+declare const ACTIVITY_DIMENSIONS: readonly ["auto", "route", "feature"];
+type ActivityDimension = (typeof ACTIVITY_DIMENSIONS)[number];
+declare const ACTIVITY_SORTS: readonly ["count", "errors", "errorRate", "lastSeen"];
+type ActivitySort = (typeof ACTIVITY_SORTS)[number];
+declare const activityQuerySchema: 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>;
+    dimension: z.ZodDefault<z.ZodEnum<{
+        route: "route";
+        feature: "feature";
+        auto: "auto";
+    }>>;
+    env: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    q: z.ZodOptional<z.ZodString>;
+    sort: z.ZodDefault<z.ZodEnum<{
+        count: "count";
+        errors: "errors";
+        errorRate: "errorRate";
+        lastSeen: "lastSeen";
+    }>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type ActivityQuery = z.infer<typeof activityQuerySchema>;
+interface ActivityItem {
+    key: string;
+    /** which column the key came from; resolved per item in 'auto' (route wins) */
+    dim: 'route' | 'feature';
+    count: number;
+    /** rows with level = 0 (CP10 D1: same predicate as overview/stats) */
+    errors: number;
+    /** 0..1, computed server-side from the integer sums */
+    errorRate: number;
+    /** MAX(time), ms epoch */
+    lastSeen: number;
+    /** MIN(time), ms epoch */
+    firstSeen: number;
+}
+/** The db-derived slice getActivity() assembles; the handler adds the envelope. */
+interface ActivityData {
+    items: ActivityItem[];
+    /** rows in scope+window+filters, keyed or not */
+    total: number;
+    /** rows carrying the selected dimension */
+    withKey: number;
+    /** total > 0 && withKey === 0: events exist but none carry the dimension (CP15 emit gap) */
+    degraded: boolean;
+}
+interface ActivityResponse extends ActivityData {
+    dimension: ActivityDimension;
+    period: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    /** isAll=true for admin ('*'); serviceIds is [] then, not the full id list */
+    scope: {
+        serviceIds: string[];
+        isAll: boolean;
+    };
+    sort: ActivitySort;
+    limit: number;
+}
+
+/**
+ * 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.
+ */
+declare function isValidTraceId(traceId: unknown): traceId is string;
+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>;
+type JourneyQuery = z.infer<typeof journeyQuerySchema>;
+type JourneyMode = 'trace' | 'session' | 'user';
+/** Resolve which mode a validated query is in (exactly one selector guaranteed by the refine). */
+declare function journeyMode(q: JourneyQuery): {
+    mode: JourneyMode;
+    key: string;
+};
+/** The selector param name each mode maps to on the wire (trace -> traceId). */
+declare const MODE_PARAM: Record<JourneyMode, 'traceId' | 'session' | 'user'>;
+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;
+}
+interface JourneyStats {
+    count: number;
+    start: number | null;
+    end: number | null;
+    durationMs: number;
+    services: string[];
+    levels: Record<string, number>;
+}
+type JourneyReason = 'empty' | 'missing-correlation' | 'dangling-parent' | 'truncated';
+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.
+ */
+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).
+ */
+declare function detectPartial(events: JourneyEvent[], hitLimit: boolean): {
+    partial: boolean;
+    reasons: JourneyReason[];
+};
+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.
+ */
+declare function buildSpanTree(events: JourneyEvent[]): SpanNode[];
+/** Depth-first flatten of the span forest into render rows, tree order preserved. */
+declare function flattenSpanTree(roots: SpanNode[]): Array<{
+    event: JourneyEvent;
+    depth: number;
+}>;
+
+/**
+ * Contract for GET /api/observe/rollout/{versions,compare,regressions} (CP13): the
+ * per-version rollout view. Framework-free (zod only + pure fns) so it loads in
+ * node-env unit tests, the Nitro handlers, and the browser composable alike. The DB
+ * query builders live in server/utils/rollout.ts; everything here is pure, matching
+ * the CP12 precedent of keeping node-testable algorithms in shared/schema/*.
+ *
+ * NULL `version` is folded under the '(unversioned)' sentinel everywhere (SQL COALESCE
+ * on the query side, and this constant on the algorithm side) so a NULL never fragments
+ * or vanishes from a GROUP BY.
+ */
+declare const UNVERSIONED = "(unversioned)";
+declare const rolloutQuerySchema: 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>;
+    env: z.ZodOptional<z.ZodString>;
+    bucketMs: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type RolloutQuery = z.infer<typeof rolloutQuerySchema>;
+interface VersionStat {
+    /** '(unversioned)' for NULL */
+    version: string;
+    total: number;
+    /** level = 0 count */
+    errors: number;
+    /** errors / total, 0 when total === 0 */
+    errorRate: number;
+    /** MIN(time) */
+    firstSeen: number;
+    /** MAX(time) */
+    lastSeen: number;
+}
+interface VersionSeries {
+    version: string;
+    /** per-bucket event count, aligned to `buckets`, zero-filled */
+    volume: number[];
+    /** per-bucket errors/total, aligned to `buckets`, 0 for empty buckets */
+    errorRate: number[];
+}
+interface VersionCompare {
+    /** contiguous ascending bucket start times, ms epoch */
+    buckets: number[];
+    /** one series per distinct version, volume-desc then version-asc for stable ordering */
+    series: VersionSeries[];
+}
+/** Flat grouped row from the CP8-shaped bucketed query, pre-pivot. */
+interface VersionSeriesRow {
+    b: number;
+    version: string;
+    total: number;
+    errors: number | null;
+}
+interface RegressionConfig {
+    /** ignore any version below this sample size */
+    minEvents: number;
+    /** absolute error-rate increase threshold (e.g. 0.05) */
+    errorRateDelta: number;
+    /** relative threshold (e.g. 1.5x baseline) */
+    errorRateMultiplier: number;
+    /** candidate must be first-seen within this of `now`; omit to skip the freshness gate */
+    baselineWindowMs?: number;
+}
+interface RegressionFinding {
+    version: string;
+    errorRate: number;
+    baselineVersion: string | null;
+    baselineErrorRate: number;
+    /** candidate.errorRate - baseline.errorRate */
+    delta: number;
+    /** candidate.errorRate / baseline.errorRate (Infinity when baseline has zero errors) */
+    ratio: number;
+    /** candidate.total */
+    sampleSize: number;
+    severity: 'warn' | 'critical';
+}
+interface RegressionResponse {
+    /** false when the single ?service has version_tracking = 0 */
+    trackingEnabled: boolean;
+    findings: RegressionFinding[];
+}
+/**
+ * Pivot flat {b, version, total, errors} rows into a chart-ready {buckets, series}.
+ * Pure + DB-free: the bucket-index math mirrors zeroFilledBuckets (floor(time/bucketMs))
+ * but is inlined so this stays free of any server import. Every series is the same
+ * length and aligns to the shared `buckets` x-axis; gaps are zero-filled.
+ */
+declare function pivotVersionSeries(rows: VersionSeriesRow[], from: number, to: number, bucketMs: number): VersionCompare;
+/**
+ * Deterministic baseline-vs-candidate regression flag. Pure: `now` is injected so
+ * tests are stable and no wall-clock read happens inside. The candidate is the
+ * newest-by-firstSeen versioned build; the baseline is the highest-volume build that
+ * appeared strictly earlier. A spike is flagged only when the candidate clears BOTH
+ * the absolute delta and the relative multiplier over that baseline.
+ */
+declare function detectRegressions(stats: VersionStat[], config: RegressionConfig, now: number): RegressionFinding[];
+
+/**
+ * Stable error fingerprinting (CP14): a deterministic hash of the normalized
+ * stack top-frames + templatized message + code + name. Co-located under
+ * shared/schema/ next to journey.ts / logs-query.ts (pure fns + types beside the
+ * barrel). The ONLY input is the first-class CanonicalEvent.error object.
+ *
+ * `node:crypto` makes this server-only in practice (ingest, backfill, tests are
+ * all node). It is re-exported from #observe/schema, but Vite tree-shakes an
+ * uncalled value export, so no client bundle pulls in `node:crypto` as long as
+ * no client code CALLS fingerprintError (CP14-HANDOFF R1).
+ */
+interface FingerprintResult {
+    /** `v1:` + 16 lowercase hex */
+    fingerprint: string;
+    /** algorithm version, always 'v1' here */
+    version: string;
+    normalizedMessage: string;
+    /** the normalized top-N frames actually used (empty when no usable stack) */
+    frames: string[];
+}
+interface ErrorLike {
+    name?: string;
+    message?: string;
+    stack?: string;
+    code?: string | number;
+}
+/**
+ * Collapse dynamic values in a message to fixed placeholders so two occurrences of
+ * the same logical error (different ids/numbers/paths) hash identically. Applied in
+ * order: timestamps, then uuids, then long hex blobs, then urls/paths, then quoted
+ * literals, then bare numbers. The order matters (a timestamp contains digits a bare
+ * number rule would otherwise shred first).
+ */
+declare function normalizeMessage(message: string): string;
+/**
+ * Reduce one V8 stack frame to a stable `func (basename)` (or just `basename`) token:
+ * keep the function name + the file basename, drop `:line:col`, collapse a bundle chunk
+ * hash (`app.ab12cd.js` -> `app.js`), and drop anonymous / eval / native frames. Returns
+ * null for a line that is not a usable frame.
+ */
+declare function normalizeFrame(line: string): string | null;
+/** Top-N usable frames from a raw stack; [] when absent or fully unusable. */
+declare function normalizeStack(stack: string | undefined, topFrames: number): string[];
+/**
+ * Compute a stable fingerprint for an error. The hash input is, in this exact field
+ * order: `name | code | normalizedMessage | frames.join('\n')`, sha1-hexed, first 16
+ * chars, prefixed `v1:`. When the stack is absent or yields no usable frames, the
+ * fingerprint falls back to name + code + normalizedMessage only (frames = []), which
+ * is still deterministic.
+ */
+declare function fingerprintError(err: ErrorLike, opts?: {
+    topFrames?: number;
+}): FingerprintResult;
+
+/**
+ * Contract for the error dashboard (CP14): the query schemas behind
+ * GET /api/observe/errors + /errors/:fingerprint, the wire shapes, and the pure
+ * query-time regression heuristic. Framework-free (zod v4 only + pure fns) so it
+ * loads in node-env unit tests, the Nitro handlers, and the browser composable
+ * alike, mirroring logs-query.ts / rollout.ts. The fingerprint hash itself lives in
+ * error-fingerprint.ts (server-only, node:crypto); nothing here imports it.
+ */
+declare const NULL_VERSION = "(unversioned)";
+/** How the grouped list is ordered; each maps to a fixed, never-interpolated column. */
+declare const ERROR_SORTS: readonly ["recent", "count", "first"];
+type ErrorSort = (typeof ERROR_SORTS)[number];
+declare const errorsQuerySchema: 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>;
+    app: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    q: z.ZodOptional<z.ZodString>;
+    sort: z.ZodDefault<z.ZodEnum<{
+        count: "count";
+        recent: "recent";
+        first: "first";
+    }>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type ErrorsQuery = z.infer<typeof errorsQuerySchema>;
+/** The drill-down route: same window/scope selectors plus the occurrences pager. */
+declare const errorDetailQuerySchema: 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>;
+    bucketMs: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type ErrorDetailQuery = z.infer<typeof errorDetailQuerySchema>;
+interface ErrorGroup {
+    fingerprint: string;
+    count: number;
+    firstSeen: number;
+    lastSeen: number;
+    /** MIN(level): 0 = error is MOST severe, so a group's headline is its minimum level */
+    worstLevel: number;
+    /** COUNT(DISTINCT app) */
+    serviceCount: number;
+    /** distinct source apps, split from GROUP_CONCAT */
+    apps: string[];
+    /** distinct versions, split from GROUP_CONCAT */
+    versions: string[];
+    /** representative name/message from the latest occurrence (null when never set) */
+    name: string | null;
+    message: string | null;
+    /** query-time gap-heuristic flag (CP14 §6); never stored */
+    regressed: boolean;
+}
+interface ErrorGroupsResponse {
+    period: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    groups: ErrorGroup[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface ErrorVersionBreakdown {
+    /** '(unversioned)' for NULL */
+    version: string;
+    count: number;
+}
+interface ErrorServiceBreakdown {
+    serviceId: string | null;
+    slug: string | null;
+    name: string | null;
+    count: number;
+}
+interface ErrorGroupHeader extends ErrorGroup {
+    /** representative error code from the latest occurrence */
+    code: string | null;
+}
+interface ErrorGroupDetailResponse {
+    period: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    header: ErrorGroupHeader;
+    bucketMs: number;
+    /** zero-filled occurrences-over-time, StatsBucket-shaped so it feeds ObserveVolumeChart */
+    series: StatsBucket[];
+    versions: ErrorVersionBreakdown[];
+    services: ErrorServiceBreakdown[];
+    occurrences: LogListItem[];
+    occurrencesTotal: number;
+    limit: number;
+    offset: number;
+}
+interface RegressionThresholds {
+    /** a group is "active now" when its lastSeen is within this of `now` (default 24h) */
+    activeWindowMs: number;
+    /** the silent gap before the active window that qualifies as a regression (default 72h) */
+    regressionGapMs: number;
+}
+declare const DEFAULT_REGRESSION_THRESHOLDS: RegressionThresholds;
+/**
+ * Query-time regression flag (CP14 §6), pure over the conditional aggregates the group
+ * query returns. A group is regressed when it is active now AND it returned after a
+ * silent gap. A brand-new error has no `prevBeforeActive` and so can never false-positive.
+ */
+declare function isRegressed(row: {
+    lastSeen: number;
+    firstInActive: number | null;
+    prevBeforeActive: number | null;
+}, thresholds: RegressionThresholds, now: number): boolean;
+/** Split a SQLite GROUP_CONCAT(DISTINCT ...) result into a clean array (NULLs already dropped). */
+declare function splitConcat(value: string | null | undefined): string[];
+
+export { ACTIVITY_DIMENSIONS, ACTIVITY_SORTS, CANONICAL_LEVELS, DEFAULT_REGRESSION_THRESHOLDS, ERROR_SORTS, FROGGER_FIELD_MAP, FROGGER_LEVEL_MAP, MAX_BATCH_EVENTS, MODE_PARAM, NAME_TO_LEVEL, NULL_VERSION, PROGRESSIVE_TIERS, SERVICE_KINDS, SERVICE_TYPES, SERVICE_TYPE_META, SYSLOG_TO_CANONICAL, UNVERSIONED, activityQuerySchema, assignmentSchema, buildSpanTree, classifyTiers, computeJourneyStats, detectPartial, detectRegressions, errorDetailQuerySchema, errorsQuerySchema, fingerprintError, flattenSpanTree, groupCreateSchema, groupIdParams, groupMembershipSchema, groupUpdateSchema, isRegressed, isValidTraceId, journeyMode, journeyQuerySchema, keyCreateSchema, keyIdParams, levelName, logsFacetsQuerySchema, logsQuerySchema, normalizeFrame, normalizeMessage, normalizeStack, otelSeverityToCanonical, overviewQuerySchema, parseLevel, pivotVersionSeries, rolloutQuerySchema, rowToDetail, serviceCreateSchema, serviceIdParams, serviceKindSchema, serviceTypeMeta, serviceTypeSchema, serviceUpdateSchema, splitConcat, statsQuerySchema, zCanonicalBatch, zCanonicalEvent, zErrorInfo, zFroggerBatch, zFroggerLog, zGroupSeed, zLevel, zObserveSeedConfig, zServiceSeed, zSource, zTraceContext };
+export type { ActivityData, ActivityDimension, ActivityItem, ActivityQuery, ActivityResponse, ActivitySort, CanonicalBatch, CanonicalEvent, CanonicalLevel, CanonicalLevelName, ErrorDetailQuery, ErrorGroup, ErrorGroupDetailResponse, ErrorGroupHeader, ErrorGroupsResponse, ErrorInfo, ErrorLike, ErrorServiceBreakdown, ErrorSort, ErrorVersionBreakdown, ErrorsQuery, EventSource, FingerprintResult, FroggerBatchInput, FroggerFieldMap, FroggerLogInput, GroupCreate, GroupListItem, GroupMembership, GroupSeed, JourneyEvent, JourneyMode, JourneyQuery, JourneyReason, JourneyResponse, JourneyStats, KeyCreate, KeyMeta, LogDetail, LogListItem, LogListResponse, LogRow, LogsFacetsQuery, LogsFacetsResponse, LogsQuery, MintedKey, ObserveSeedConfig, OverviewActivityItem, OverviewData, OverviewQuery, OverviewResponse, OverviewServiceRollup, OverviewStats, RegressionConfig, RegressionFinding, RegressionResponse, RegressionThresholds, RolloutQuery, ServiceCreate, ServiceDetail, ServiceKind, ServiceListItem, ServiceSeed, ServiceType, ServiceUpdate, SpanNode, StatsBucket, StatsData, StatsQuery, StatsResponse, StatsSeriesMeta, Tier, TraceContextInfo, UserDetail, UserPick, VersionCompare, VersionSeries, VersionSeriesRow, VersionStat };