nuxt-observe 0.0.2

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

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+/**
+ * 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.
+ */
+export declare const ACTIVITY_DIMENSIONS: readonly ["auto", "route", "feature"];
+export type ActivityDimension = (typeof ACTIVITY_DIMENSIONS)[number];
+export declare const ACTIVITY_SORTS: readonly ["count", "errors", "errorRate", "lastSeen"];
+export type ActivitySort = (typeof ACTIVITY_SORTS)[number];
+export 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<{
+        auto: "auto";
+        route: "route";
+        feature: "feature";
+    }>>;
+    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>;
+export type ActivityQuery = z.infer<typeof activityQuerySchema>;
+export 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. */
+export 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;
+}
+export 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;
+}

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

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { PERIODS } from "../utils/period.js";
+export const ACTIVITY_DIMENSIONS = ["auto", "route", "feature"];
+export const ACTIVITY_SORTS = ["count", "errors", "errorRate", "lastSeen"];
+export const activityQuerySchema = 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(),
+  /** grouping dimension; auto = COALESCE(route, feature) */
+  dimension: z.enum(ACTIVITY_DIMENSIONS).default("auto"),
+  /** exact env filter */
+  env: z.string().optional(),
+  /** exact-level filter, 0..5 (mirrors statsQuerySchema, CP8 D3) */
+  level: z.coerce.number().int().min(0).max(5).optional(),
+  /** substring match on the key; escaped LIKE (shared escapeLike) */
+  q: z.string().trim().min(1).max(200).optional(),
+  sort: z.enum(ACTIVITY_SORTS).default("count"),
+  /** rejected with 400 past the ceiling, never silently clamped */
+  limit: z.coerce.number().int().min(1).max(200).default(50)
+});

package/dist/runtime/shared/schema/adapters/frogger.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+/**
+ * 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.
+ */
+export 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>;
+export 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>;
+export type FroggerLogInput = z.infer<typeof zFroggerLog>;
+export type FroggerBatchInput = z.infer<typeof zFroggerBatch>;

package/dist/runtime/shared/schema/adapters/frogger.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export const zFroggerLog = z.object({
+  time: z.number(),
+  lvl: z.number(),
+  type: z.string().optional(),
+  msg: z.string(),
+  ctx: z.record(z.string(), z.unknown()).optional(),
+  tags: z.array(z.string()).optional(),
+  env: z.string().optional(),
+  source: z.object({ name: z.string().optional(), version: z.string().optional() }).partial().optional(),
+  trace: z.object({ traceId: z.string(), spanId: z.string(), parentId: z.string().optional() }).partial().optional()
+}).passthrough();
+export const zFroggerBatch = z.object({
+  logs: z.array(zFroggerLog).min(1),
+  app: z.object({ name: z.string(), version: z.string() }).partial().optional(),
+  meta: z.object({}).passthrough().optional()
+}).passthrough();

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

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export declare const MAX_BATCH_EVENTS = 500;
+export 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>;
+export type CanonicalBatch = z.infer<typeof zCanonicalBatch>;

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

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import { zCanonicalEvent } from "./event.js";
+export const MAX_BATCH_EVENTS = 500;
+export const zCanonicalBatch = z.object({
+  events: z.array(zCanonicalEvent).max(MAX_BATCH_EVENTS),
+  // empty allowed: a valid no-op batch
+  meta: z.record(z.string(), z.unknown()).optional()
+  // frogger meta.{processed,processChain,source,time} passes through
+});

package/dist/runtime/shared/schema/error-fingerprint.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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).
+ */
+export 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[];
+}
+export 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).
+ */
+export 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.
+ */
+export declare function normalizeFrame(line: string): string | null;
+/** Top-N usable frames from a raw stack; [] when absent or fully unusable. */
+export 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.
+ */
+export declare function fingerprintError(err: ErrorLike, opts?: {
+    topFrames?: number;
+}): FingerprintResult;

package/dist/runtime/shared/schema/error-fingerprint.js

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+const VERSION = "v1";
+const DEFAULT_TOP_FRAMES = 3;
+export function normalizeMessage(message) {
+  return message.replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g, "<ts>").replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, "<uuid>").replace(/\b[0-9a-f]{8,}\b/gi, "<hex>").replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s'"]+/gi, "<path>").replace(/(?:[a-z]:\\|\.{0,2}\/)[^\s'"]*[^\s'".,;:]/gi, "<path>").replace(/'[^']*'/g, "<str>").replace(/"[^"]*"/g, "<str>").replace(/-?\d+(?:\.\d+)?/g, "<n>").trim();
+}
+const ANON_RE = /<anonymous>|\beval\b|\[native code\]/i;
+export function normalizeFrame(line) {
+  const trimmed = line.trim().replace(/^at\s+/, "").replace(/^async\s+/, "");
+  if (!trimmed) return null;
+  const open = trimmed.lastIndexOf(" (");
+  let fn = "";
+  let loc = trimmed;
+  if (open > 0 && trimmed.endsWith(")")) {
+    fn = trimmed.slice(0, open).trim();
+    loc = trimmed.slice(open + 2, -1).trim();
+  }
+  if (loc.startsWith("node:") || /^(?:internal|native)\b/.test(loc)) return null;
+  if (ANON_RE.test(fn) || ANON_RE.test(loc)) return null;
+  loc = loc.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "");
+  loc = loc.replace(/(?::\d+)+$/, "");
+  const base = loc.split(/[\\/]/).pop() ?? loc;
+  const cleaned = base.replace(/\.[0-9a-f]{6,}(?=\.[a-z0-9]+$)/i, "");
+  if (!cleaned) return fn || null;
+  return fn ? `${fn} (${cleaned})` : cleaned;
+}
+export function normalizeStack(stack, topFrames) {
+  if (!stack) return [];
+  const out = [];
+  for (const line of stack.split("\n")) {
+    if (!/^\s*at\s+/.test(line)) continue;
+    const frame = normalizeFrame(line);
+    if (frame) out.push(frame);
+    if (out.length >= topFrames) break;
+  }
+  return out;
+}
+export function fingerprintError(err, opts = {}) {
+  const topFrames = opts.topFrames ?? DEFAULT_TOP_FRAMES;
+  const name = err.name ?? "";
+  const code = String(err.code ?? "");
+  const normalizedMessage = normalizeMessage(err.message ?? "");
+  const frames = normalizeStack(err.stack, topFrames);
+  const input = [name, code, normalizedMessage, frames.join("\n")].join("|");
+  const hash = createHash("sha1").update(input).digest("hex").slice(0, 16);
+  return { fingerprint: `${VERSION}:${hash}`, version: VERSION, normalizedMessage, frames };
+}

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

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import type { LogListItem } from './logs-query.js';
+import type { StatsBucket } from './stats.js';
+/**
+ * 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.
+ */
+export declare const NULL_VERSION = "(unversioned)";
+/** How the grouped list is ordered; each maps to a fixed, never-interpolated column. */
+export declare const ERROR_SORTS: readonly ["recent", "count", "first"];
+export type ErrorSort = (typeof ERROR_SORTS)[number];
+export 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<{
+        first: "first";
+        count: "count";
+        recent: "recent";
+    }>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type ErrorsQuery = z.infer<typeof errorsQuerySchema>;
+/** The drill-down route: same window/scope selectors plus the occurrences pager. */
+export 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>;
+export type ErrorDetailQuery = z.infer<typeof errorDetailQuerySchema>;
+export 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;
+}
+export interface ErrorGroupsResponse {
+    period: {
+        from: number;
+        to: number;
+        label: string;
+    };
+    groups: ErrorGroup[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface ErrorVersionBreakdown {
+    /** '(unversioned)' for NULL */
+    version: string;
+    count: number;
+}
+export interface ErrorServiceBreakdown {
+    serviceId: string | null;
+    slug: string | null;
+    name: string | null;
+    count: number;
+}
+export interface ErrorGroupHeader extends ErrorGroup {
+    /** representative error code from the latest occurrence */
+    code: string | null;
+}
+export 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;
+}
+export 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;
+}
+export 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.
+ */
+export 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). */
+export declare function splitConcat(value: string | null | undefined): string[];

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

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { PERIODS } from "../utils/period.js";
+export const NULL_VERSION = "(unversioned)";
+export const ERROR_SORTS = ["recent", "count", "first"];
+export const errorsQuerySchema = 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(),
+  /** exact source-app filter */
+  app: z.string().min(1).max(200).optional(),
+  /** exact version filter */
+  version: z.string().min(1).max(200).optional(),
+  /** exact env filter */
+  env: z.string().min(1).max(200).optional(),
+  /** exact level filter, 0..5 */
+  level: z.coerce.number().int().min(0).max(5).optional(),
+  /** free-text search over the representative error message; LIKE %q% ESCAPE '\' */
+  q: z.string().trim().min(1).max(200).optional(),
+  sort: z.enum(ERROR_SORTS).default("recent"),
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+  offset: z.coerce.number().int().min(0).default(0)
+});
+export const errorDetailQuerySchema = z.object({
+  period: z.enum(PERIODS).default("24h"),
+  service: z.string().optional(),
+  group: z.string().optional(),
+  /** advanced bucket-size override in ms for the occurrences chart; > 500 buckets is a 400 */
+  bucketMs: z.coerce.number().int().positive().optional(),
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+  offset: z.coerce.number().int().min(0).default(0)
+});
+export const DEFAULT_REGRESSION_THRESHOLDS = {
+  activeWindowMs: 864e5,
+  // 24h
+  regressionGapMs: 2592e5
+  // 72h
+};
+export function isRegressed(row, thresholds, now) {
+  const activeStart = now - thresholds.activeWindowMs;
+  return row.lastSeen >= activeStart && row.firstInActive != null && row.prevBeforeActive != null && row.firstInActive - row.prevBeforeActive >= thresholds.regressionGapMs;
+}
+export function splitConcat(value) {
+  if (!value) return [];
+  return value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}

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

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+export 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>;
+export declare const zTraceContext: z.ZodObject<{
+    traceId: z.ZodString;
+    spanId: z.ZodString;
+    parentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const zSource: z.ZodObject<{
+    app: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export 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>;
+export type ErrorInfo = z.infer<typeof zErrorInfo>;
+export type TraceContextInfo = z.infer<typeof zTraceContext>;
+export type EventSource = z.infer<typeof zSource>;
+export type CanonicalEvent = z.infer<typeof zCanonicalEvent>;

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

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { zLevel } from "./levels.js";
+const TRACE_ID_RE = /^[0-9a-f]{32}$/;
+const SPAN_ID_RE = /^[0-9a-f]{16}$/;
+export const zErrorInfo = z.object({
+  name: z.string(),
+  message: z.string(),
+  stack: z.string().optional(),
+  code: z.union([z.string(), z.number()]).optional()
+  // frogger statusCode is number; app codes may be string
+});
+export const zTraceContext = z.object({
+  traceId: z.string().regex(TRACE_ID_RE),
+  spanId: z.string().regex(SPAN_ID_RE),
+  parentId: z.string().regex(SPAN_ID_RE).optional()
+  // frogger's trace.flags is intentionally dropped here; see frogger-map.ts.
+});
+export const zSource = z.object({
+  app: z.string().min(1),
+  // required WHEN source is present
+  version: z.string().optional(),
+  env: z.string().optional()
+  // frogger execution context (ssr/csr/client/server); see caveat in frogger-map.ts
+});
+export const zCanonicalEvent = z.object({
+  time: z.number().int().positive(),
+  // ms epoch
+  level: zLevel,
+  message: z.string().min(1),
+  error: zErrorInfo.optional(),
+  trace: zTraceContext.optional(),
+  source: zSource.optional(),
+  // optional so the minimal stream tier ({time,level,message}) parses
+  session: z.string().optional(),
+  user: z.string().optional(),
+  route: z.string().optional(),
+  feature: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  ctx: z.record(z.string(), z.unknown()).optional()
+  // zod v4: record REQUIRES (keyType, valueType)
+});

package/dist/runtime/shared/schema/frogger-map.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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). */
+export 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";
+    };
+};
+export type FroggerFieldMap = typeof FROGGER_FIELD_MAP;