nuxt-observe 0.0.2

package/dist/runtime/server/utils/groups.js

@@ -0,0 +1,59 @@
+import { uuidv7 } from "../../shared/utils/uuid.js";
+import { useObserveDb } from "./db.js";
+export async function createGroup(input, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const id = uuidv7();
+  const now = Date.now();
+  await db.sql`INSERT INTO groups (id, slug, name, created_at, updated_at) VALUES (${id}, ${input.slug}, ${input.name}, ${now}, ${now})`;
+  return await getGroupById(id, opts);
+}
+export async function getGroupById(id, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const row = await db.prepare("SELECT * FROM groups WHERE id = ?").get(id);
+  return row ?? null;
+}
+export async function getGroupBySlug(slug, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const row = await db.prepare("SELECT * FROM groups WHERE slug = ?").get(slug);
+  return row ?? null;
+}
+export async function listGroups(opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  return await db.prepare("SELECT * FROM groups ORDER BY created_at").all();
+}
+export async function updateGroup(id, patch, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const existing = await getGroupById(id, opts);
+  if (!existing) return null;
+  await db.sql`UPDATE groups SET name = ${patch.name}, updated_at = ${Date.now()} WHERE id = ${id}`;
+  return await getGroupById(id, opts);
+}
+export async function deleteGroup(id, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const existing = await getGroupById(id, opts);
+  if (!existing) return false;
+  await db.sql`BEGIN`;
+  try {
+    await db.sql`UPDATE services SET group_id = NULL, updated_at = ${Date.now()} WHERE group_id = ${id}`;
+    await db.sql`DELETE FROM groups WHERE id = ${id}`;
+    await db.sql`COMMIT`;
+  } catch (e) {
+    await db.sql`ROLLBACK`;
+    throw e;
+  }
+  return true;
+}
+export async function assignServiceToGroup(serviceId, groupId, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  await db.sql`UPDATE services SET group_id = ${groupId}, updated_at = ${Date.now()} WHERE id = ${serviceId}`;
+}
+export async function listServicesInGroup(groupId, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  return await db.prepare("SELECT * FROM services WHERE group_id = ? ORDER BY created_at").all(groupId);
+}
+export async function getGroupWithServices(groupId, opts = {}) {
+  const group = await getGroupById(groupId, opts);
+  if (!group) return null;
+  const services = await listServicesInGroup(groupId, opts);
+  return { group, services };
+}

package/dist/runtime/server/utils/ingest-cors.d.ts

@@ -0,0 +1,23 @@
+import { type H3Event, type H3CorsOptions } from 'h3';
+import type { ServiceCorsMeta } from './services.js';
+/**
+ * Pure origin-decision for the ingest CORS policy, extracted so it is unit
+ * testable without an H3Event. A browser service with a non-empty allowlist
+ * echoes those origins ('*' if the list holds the wildcard). Every other case
+ * (server client, keyless, revoked, empty allowlist) yields the configured
+ * fallback, which never affects server-side clients (they send no Origin).
+ */
+export declare function resolveIngestCorsOrigin(corsMeta: ServiceCorsMeta | null | undefined, fallbackOrigin: H3CorsOptions['origin']): H3CorsOptions['origin'];
+/**
+ * Per-service CORS. `corsMeta` is resolved by the handler from ?key= BEFORE this
+ * call. CORS only ever governs browsers: the API key is the sole ingest gate, so
+ * a null meta (server/keyless/revoked) simply grants no cross-origin access and
+ * lets the request proceed to normal key auth. Returns true if a preflight was
+ * answered (the handler must then `return` immediately).
+ *
+ * The default fallback origin is `[]` (no grant unless the service opts in), a
+ * deliberate change from the pre-CP10.5 `'*'`; set `observe.ingest.cors.origin`
+ * to restore a global collector. No `credentials: true` because the key rides
+ * `?key=`/`x-api-key`, not a cookie.
+ */
+export declare function handleCorsForIngest(event: H3Event, corsMeta?: ServiceCorsMeta | null): boolean;

package/dist/runtime/server/utils/ingest-cors.js

@@ -0,0 +1,27 @@
+import { handleCors } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+const DEFAULT_ALLOW_HEADERS = [
+  "content-type",
+  "x-api-key",
+  "traceparent",
+  "x-frogger-reporter",
+  "x-frogger-reporter-id",
+  "x-frogger-processed",
+  "x-frogger-source"
+];
+export function resolveIngestCorsOrigin(corsMeta, fallbackOrigin) {
+  if (corsMeta && corsMeta.kind === "browser" && corsMeta.allowedOrigins.length) {
+    return corsMeta.allowedOrigins.includes("*") ? "*" : corsMeta.allowedOrigins;
+  }
+  return fallbackOrigin;
+}
+export function handleCorsForIngest(event, corsMeta) {
+  const cors = useRuntimeConfig().observe?.ingest?.cors;
+  const fallbackOrigin = cors?.origin ?? [];
+  return handleCors(event, {
+    origin: resolveIngestCorsOrigin(corsMeta, fallbackOrigin),
+    methods: cors?.methods ?? ["POST", "OPTIONS"],
+    allowHeaders: cors?.allowHeaders ?? DEFAULT_ALLOW_HEADERS,
+    maxAge: cors?.maxAge ?? "600"
+  });
+}

package/dist/runtime/server/utils/journey.d.ts

@@ -0,0 +1,20 @@
+import type { LogRow } from '../../shared/schema/log-row.js';
+import type { Database } from './db.js';
+import type { JourneyEvent, JourneyMode } from '../../shared/schema/journey.js';
+/**
+ * The journey query layer (CP12). A thin wrapper over the ONE tested query path
+ * (queryLogs / LogFilter): reusing it inherits CP6 scoping (serviceIds), ordering,
+ * from/to, the limit cap, and the `user_id AS user` SELECT alias for free, instead
+ * of a second hand-rolled WHERE. Correlation is a plain equality on an indexed
+ * column (trace_id / session / user_id), so there is no join.
+ */
+export interface JourneyOpts {
+    from?: number;
+    to?: number;
+    limit: number;
+    serviceIds: string[] | '*';
+    db?: Database;
+}
+/** Project a physical row to the light timeline shape, offset from the journey start. */
+export declare function toJourneyEvent(row: LogRow, journeyStart: number): JourneyEvent;
+export declare function getJourney(mode: JourneyMode, key: string, opts: JourneyOpts): Promise<JourneyEvent[]>;

package/dist/runtime/server/utils/journey.js

@@ -0,0 +1,44 @@
+import { queryLogs } from "./logs.js";
+import { rowToDetail } from "../../shared/schema/logs-query.js";
+export function toJourneyEvent(row, journeyStart) {
+  const d = rowToDetail(row);
+  return {
+    id: d.id,
+    time: d.time,
+    offsetMs: d.time - journeyStart,
+    level: d.level,
+    message: d.message,
+    app: d.app,
+    version: d.version,
+    service_id: d.service_id,
+    route: d.route,
+    feature: d.feature,
+    session: d.session,
+    error: d.error ? {
+      ...d.error.name ? { name: d.error.name } : {},
+      ...d.error.message ? { message: d.error.message } : {},
+      ...d.error.code ? { code: d.error.code } : {}
+      // stack omitted from the timeline wire
+    } : null,
+    traceId: d.trace?.traceId ?? null,
+    spanId: d.trace?.spanId ?? null,
+    parentId: d.trace?.parentId ?? null,
+    hasTrace: !!(d.trace?.traceId && d.trace?.spanId),
+    hasParent: !!d.trace?.parentId
+  };
+}
+export async function getJourney(mode, key, opts) {
+  const base = {
+    serviceIds: opts.serviceIds,
+    order: "asc",
+    // the waterfall reads earliest-first
+    limit: opts.limit,
+    // A trace link must never dangle because the navbar window moved on, so trace
+    // mode ignores from/to (idx_logs_trace carries the query); session/user apply them.
+    ...mode === "trace" ? {} : { from: opts.from, to: opts.to }
+  };
+  const filter = mode === "trace" ? { ...base, traceId: key } : mode === "session" ? { ...base, session: key } : { ...base, user: key };
+  const rows = await queryLogs(filter, { db: opts.db });
+  const start = rows.length ? rows[0].time : 0;
+  return rows.map((r) => toJourneyEvent(r, start));
+}

package/dist/runtime/server/utils/logs.d.ts

@@ -0,0 +1,50 @@
+import type { CanonicalEvent } from '../../shared/schema/event.js';
+import type { LogRow } from '../../shared/schema/log-row.js';
+import type { LogFilter } from '../../shared/types/storage.js';
+import { type Database } from './db.js';
+/**
+ * Pure canonical -> physical-row mapper: flattens `error` into `error_*`, splits
+ * `source`/`trace`, JSON-encodes `tags`/`ctx` (null when absent), clamps `level`.
+ * Assigns a time-sortable uuidv7 id. No DB access.
+ */
+export declare function eventToRow(event: CanonicalEvent, receivedAt: number, serviceId?: string | null): LogRow;
+/**
+ * Insert a batch as a single all-or-nothing transaction. `serviceId` is stamped
+ * onto every row. Rolls back and rethrows on any per-row error.
+ */
+export declare function insertEvents(events: CanonicalEvent[], opts?: {
+    db?: Database;
+    serviceId?: string | null;
+}): Promise<{
+    inserted: number;
+}>;
+/** Escape LIKE metacharacters so user text matches literally. Exported for tests. */
+export declare function escapeLike(s: string): string;
+export declare function queryLogs(filter: LogFilter, opts?: {
+    db?: Database;
+}): Promise<LogRow[]>;
+export declare function countLogs(filter: LogFilter, opts?: {
+    db?: Database;
+}): Promise<number>;
+/** Single row by PK, unscoped: the handler decides 404 vs 403 from the row's service_id. */
+export declare function getLogById(id: string, opts?: {
+    db?: Database;
+}): Promise<LogRow | null>;
+/** Distinct non-null versions over the caller's resolved scope, newest-ish first. */
+export declare function queryDistinctVersions(scope: string[] | '*', opts?: {
+    db?: Database;
+}): Promise<string[]>;
+/**
+ * Deletes rows with `time < now - retentionDays*DAY_MS`. Returns the deleted
+ * count. `retentionDays`/`now` are injectable so the cutoff is unit-testable
+ * without a running Nitro; when omitted, retention falls back to
+ * runtimeConfig.observe.retentionDays (default 30). Strict `<` keeps a row
+ * sitting exactly on the boundary.
+ */
+export declare function purgeOldLogs(opts?: {
+    db?: Database;
+    now?: number;
+    retentionDays?: number;
+}): Promise<{
+    deleted: number;
+}>;

package/dist/runtime/server/utils/logs.js

@@ -0,0 +1,154 @@
+import { useRuntimeConfig } from "nitropack/runtime";
+import { uuidv7 } from "../../shared/utils/uuid.js";
+import { fingerprintError } from "../../shared/schema/error-fingerprint.js";
+import { useObserveDb } from "./db.js";
+const DAY_MS = 864e5;
+const DEFAULT_RETENTION_DAYS = 30;
+const clampLevel = (n) => n < 0 ? 0 : n > 5 ? 5 : Math.trunc(n);
+export function eventToRow(event, receivedAt, serviceId) {
+  return {
+    id: uuidv7(),
+    time: event.time,
+    received_at: receivedAt,
+    level: clampLevel(event.level),
+    message: event.message,
+    error_name: event.error?.name,
+    error_message: event.error?.message,
+    error_stack: event.error?.stack,
+    error_code: event.error?.code === void 0 ? void 0 : String(event.error.code),
+    // Stable error grouping key (CP14): computed once at ingest, NULL for non-error rows.
+    error_fingerprint: event.error ? fingerprintError(event.error).fingerprint : void 0,
+    app: event.source?.app ?? "",
+    version: event.source?.version,
+    env: event.source?.env,
+    service_id: serviceId ?? void 0,
+    trace_id: event.trace?.traceId,
+    span_id: event.trace?.spanId,
+    parent_id: event.trace?.parentId,
+    session: event.session,
+    user: event.user,
+    route: event.route,
+    feature: event.feature,
+    tags: event.tags ? JSON.stringify(event.tags) : void 0,
+    ctx: event.ctx ? JSON.stringify(event.ctx) : void 0
+  };
+}
+export async function insertEvents(events, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const receivedAt = Date.now();
+  const rows = events.map((e) => eventToRow(e, receivedAt, opts.serviceId));
+  await db.sql`BEGIN`;
+  try {
+    for (const r of rows) {
+      await db.sql`
+        INSERT INTO logs (
+          id, time, received_at, level, message,
+          error_name, error_message, error_stack, error_code, error_fingerprint,
+          app, version, env, service_id,
+          trace_id, span_id, parent_id,
+          session, user_id, route, feature, tags, ctx
+        ) VALUES (
+          ${r.id}, ${r.time}, ${r.received_at}, ${r.level}, ${r.message},
+          ${r.error_name ?? null}, ${r.error_message ?? null}, ${r.error_stack ?? null}, ${r.error_code ?? null}, ${r.error_fingerprint ?? null},
+          ${r.app}, ${r.version ?? null}, ${r.env ?? null}, ${r.service_id ?? null},
+          ${r.trace_id ?? null}, ${r.span_id ?? null}, ${r.parent_id ?? null},
+          ${r.session ?? null}, ${r.user ?? null}, ${r.route ?? null}, ${r.feature ?? null}, ${r.tags ?? null}, ${r.ctx ?? null}
+        )
+      `;
+    }
+    await db.sql`COMMIT`;
+  } catch (e) {
+    await db.sql`ROLLBACK`;
+    throw e;
+  }
+  return { inserted: rows.length };
+}
+function buildWhere(filter) {
+  const conds = [];
+  const params = [];
+  const eq = (col, val) => {
+    if (val !== void 0 && val !== null) {
+      conds.push(`${col} = ?`);
+      params.push(val);
+    }
+  };
+  const range = (col, val) => {
+    if (val !== void 0) {
+      conds.push(col);
+      params.push(val);
+    }
+  };
+  range("time >= ?", filter.from);
+  range("time <= ?", filter.to);
+  range("level = ?", filter.level);
+  range("level <= ?", filter.minLevel);
+  eq("app", filter.app);
+  eq("service_id", filter.serviceId);
+  eq("trace_id", filter.traceId);
+  eq("session", filter.session);
+  eq("user_id", filter.user);
+  eq("route", filter.route);
+  eq("feature", filter.feature);
+  eq("version", filter.version);
+  eq("error_fingerprint", filter.errorFingerprint);
+  if (filter.levels && filter.levels.length > 0) {
+    conds.push(`level IN (${filter.levels.map(() => "?").join(",")})`);
+    params.push(...filter.levels);
+  }
+  if (filter.versions && filter.versions.length > 0) {
+    conds.push(`version IN (${filter.versions.map(() => "?").join(",")})`);
+    params.push(...filter.versions);
+  }
+  if (filter.q) {
+    conds.push(`message LIKE ? ESCAPE '\\'`);
+    params.push(`%${escapeLike(filter.q)}%`);
+  }
+  if (filter.serviceIds && filter.serviceIds !== "*") {
+    if (filter.serviceIds.length === 0) {
+      conds.push("1=0");
+    } else {
+      conds.push(`service_id IN (${filter.serviceIds.map(() => "?").join(",")})`);
+      params.push(...filter.serviceIds);
+    }
+  }
+  return { clause: conds.length ? `WHERE ${conds.join(" AND ")}` : "", params };
+}
+export function escapeLike(s) {
+  return s.replace(/[\\%_]/g, (m) => `\\${m}`);
+}
+const SELECT_COLS = "*, user_id AS user";
+export async function queryLogs(filter, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const { clause, params } = buildWhere(filter);
+  const order = filter.order === "asc" ? "ASC" : "DESC";
+  const limit = filter.limit ?? 100;
+  const offset = filter.offset ?? 0;
+  const sql = `SELECT ${SELECT_COLS} FROM logs ${clause} ORDER BY time ${order}, id ${order} LIMIT ? OFFSET ?`;
+  return await db.prepare(sql).all(...params, limit, offset);
+}
+export async function countLogs(filter, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const { clause, params } = buildWhere(filter);
+  const row = await db.prepare(`SELECT COUNT(*) AS n FROM logs ${clause}`).get(...params);
+  return row.n;
+}
+export async function getLogById(id, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const row = await db.prepare(`SELECT ${SELECT_COLS} FROM logs WHERE id = ?`).get(id);
+  return row ?? null;
+}
+export async function queryDistinctVersions(scope, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const scoped = scope === "*" ? { clause: "", params: [] } : scope.length === 0 ? { clause: "AND 1=0", params: [] } : { clause: `AND service_id IN (${scope.map(() => "?").join(",")})`, params: [...scope] };
+  const rows = await db.prepare(
+    `SELECT DISTINCT version FROM logs WHERE version IS NOT NULL ${scoped.clause} ORDER BY version DESC`
+  ).all(...scoped.params);
+  return rows.map((r) => r.version);
+}
+export async function purgeOldLogs(opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const retentionDays = opts.retentionDays ?? useRuntimeConfig().observe?.retentionDays ?? DEFAULT_RETENTION_DAYS;
+  const cutoff = (opts.now ?? Date.now()) - retentionDays * DAY_MS;
+  const res = await db.sql`DELETE FROM logs WHERE time < ${cutoff}`;
+  return { deleted: res.changes ?? 0 };
+}

package/dist/runtime/server/utils/loop-guard.d.ts

@@ -0,0 +1,11 @@
+import type { H3Event } from 'h3';
+/**
+ * Lightweight port of frogger's detectLoggingLoop (logger.post.ts:21-84), minus
+ * its NUXT_APP_NAME self-source check (meaningless in a sink, which never relays).
+ * observe rejects only a circular processChain or a >10min-stale batch; the
+ * x-frogger-* headers are advisory here. `meta` is the batch meta object.
+ */
+export declare function checkIngestLoop(_event: H3Event, meta: unknown): {
+    reject: boolean;
+    reason?: string;
+};

package/dist/runtime/server/utils/loop-guard.js

@@ -0,0 +1,11 @@
+const STALE_MS = 6e5;
+export function checkIngestLoop(_event, meta) {
+  const m = meta ?? {};
+  if (Array.isArray(m.processChain) && new Set(m.processChain).size !== m.processChain.length) {
+    return { reject: true, reason: "Circular processing chain" };
+  }
+  if (typeof m.time === "number" && Date.now() - m.time > STALE_MS) {
+    return { reject: true, reason: "Stale batch (>10m) \u2014 possible retry loop" };
+  }
+  return { reject: false };
+}

package/dist/runtime/server/utils/migrate.d.ts

@@ -0,0 +1,21 @@
+import { type Database } from './db.js';
+/**
+ * Full baseline schema as a single multi-statement string. Every statement is
+ * `CREATE ... IF NOT EXISTS`, so running it repeatedly is a no-op. It includes the
+ * `schema_migrations` ledger (CP17), created here so it exists before the runner queries
+ * it on the very first boot. Additive column changes on already-existing tables now live
+ * in the versioned migration registry (server/migrations/), not in `ensure*` helpers here;
+ * the runner applies and records them (server/utils/migration-runner.ts).
+ */
+export declare const OBSERVE_DDL = "\nCREATE TABLE IF NOT EXISTS schema_migrations (\n  id          TEXT PRIMARY KEY,          -- e.g. '0004-logs-error-fingerprint'\n  class       TEXT NOT NULL,             -- 'additive' | 'destructive' (audit record)\n  checksum    TEXT NOT NULL,             -- sha1 of the migration's up() source at author time\n  applied_at  INTEGER NOT NULL,          -- ms epoch\n  duration_ms INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS groups (\n  id          TEXT PRIMARY KEY,\n  slug        TEXT NOT NULL UNIQUE,\n  name        TEXT NOT NULL,\n  created_at  INTEGER NOT NULL,\n  updated_at  INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS services (\n  id               TEXT PRIMARY KEY,\n  slug             TEXT NOT NULL UNIQUE,\n  name             TEXT NOT NULL,\n  group_id         TEXT NULL REFERENCES groups(id),\n  env              TEXT NULL,\n  version_tracking INTEGER NOT NULL DEFAULT 0,\n  current_version  TEXT NULL,\n  kind             TEXT NOT NULL DEFAULT 'server',   -- 'server' | 'browser'; toggles browser CORS only\n  type             TEXT NOT NULL DEFAULT 'service',   -- descriptive category; UI badge only, no runtime effect\n  deleted_at       INTEGER NULL,                      -- soft-delete marker; NULL = active. Purged after the retention window.\n  created_by       TEXT NULL,\n  created_at       INTEGER NOT NULL,\n  updated_at       INTEGER NOT NULL\n);\nCREATE INDEX IF NOT EXISTS idx_services_group ON services(group_id);\n\nCREATE TABLE IF NOT EXISTS service_app_names (\n  service_id  TEXT NOT NULL REFERENCES services(id),\n  app_name    TEXT NOT NULL UNIQUE,\n  PRIMARY KEY (service_id, app_name)\n);\n\nCREATE TABLE IF NOT EXISTS service_allowed_origins (\n  service_id  TEXT NOT NULL REFERENCES services(id),\n  origin      TEXT NOT NULL,\n  PRIMARY KEY (service_id, origin)\n);\n\nCREATE TABLE IF NOT EXISTS api_keys (\n  id           TEXT PRIMARY KEY,\n  service_id   TEXT NOT NULL REFERENCES services(id),\n  key_hash     TEXT NOT NULL UNIQUE,\n  key_prefix   TEXT NOT NULL,\n  label        TEXT NULL,\n  created_at   INTEGER NOT NULL,\n  revoked_at   INTEGER NULL,\n  last_used_at INTEGER NULL\n);\nCREATE INDEX IF NOT EXISTS idx_api_keys_service ON api_keys(service_id);\n\nCREATE TABLE IF NOT EXISTS users (\n  id            TEXT PRIMARY KEY,\n  username      TEXT NOT NULL UNIQUE,\n  display_name  TEXT NULL,\n  password_hash TEXT NULL,             -- NULL => JWT-only / no local login\n  role          TEXT NOT NULL DEFAULT 'viewer',   -- global role (drives admin/manager/viewer)\n  disabled      INTEGER NOT NULL DEFAULT 0,        -- 0 => active, 1 => cannot authenticate\n  source        TEXT NOT NULL,\n  created_by    TEXT NULL,\n  created_at    INTEGER NOT NULL,\n  updated_at    INTEGER NULL\n);\nCREATE TABLE IF NOT EXISTS user_service_roles (\n  user_id    TEXT NOT NULL,\n  service_id TEXT NOT NULL,\n  role       TEXT NOT NULL,\n  PRIMARY KEY (user_id, service_id)\n);\nCREATE TABLE IF NOT EXISTS user_group_roles (\n  user_id  TEXT NOT NULL,\n  group_id TEXT NOT NULL,\n  role     TEXT NOT NULL,\n  PRIMARY KEY (user_id, group_id)\n);\nCREATE TABLE IF NOT EXISTS user_identities (\n  id         TEXT PRIMARY KEY,\n  user_id    TEXT NOT NULL,\n  provider   TEXT NOT NULL,          -- 'jwt' (room for future external sources)\n  subject    TEXT NOT NULL,          -- the token sub claim\n  created_at INTEGER NOT NULL,\n  UNIQUE (provider, subject)\n);\nCREATE INDEX IF NOT EXISTS idx_user_identities_user ON user_identities(user_id);\nCREATE INDEX IF NOT EXISTS idx_user_service_roles_user ON user_service_roles(user_id);\nCREATE INDEX IF NOT EXISTS idx_user_group_roles_user ON user_group_roles(user_id);\n\nCREATE TABLE IF NOT EXISTS logs (\n  id            TEXT PRIMARY KEY,\n  time          INTEGER NOT NULL,\n  received_at   INTEGER NOT NULL,\n  level         INTEGER NOT NULL,\n  message       TEXT,\n  error_name    TEXT,\n  error_message TEXT,\n  error_stack   TEXT,\n  error_code    TEXT,\n  app           TEXT,\n  version       TEXT,\n  env           TEXT,\n  service_id    TEXT,\n  trace_id      TEXT,\n  span_id       TEXT,\n  parent_id     TEXT,\n  session       TEXT,\n  user_id       TEXT,\n  route         TEXT,\n  feature       TEXT,\n  tags          TEXT,\n  ctx           TEXT,\n  error_fingerprint TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_logs_time         ON logs(time);\nCREATE INDEX IF NOT EXISTS idx_logs_level_time   ON logs(level, time);\nCREATE INDEX IF NOT EXISTS idx_logs_app_time     ON logs(app, time);\nCREATE INDEX IF NOT EXISTS idx_logs_service_time ON logs(service_id, time);\nCREATE INDEX IF NOT EXISTS idx_logs_trace        ON logs(trace_id);\nCREATE INDEX IF NOT EXISTS idx_logs_session      ON logs(session);\nCREATE INDEX IF NOT EXISTS idx_logs_user         ON logs(user_id);\nCREATE INDEX IF NOT EXISTS idx_logs_route        ON logs(route);\nCREATE INDEX IF NOT EXISTS idx_logs_feature      ON logs(feature);\nCREATE INDEX IF NOT EXISTS idx_logs_version      ON logs(version);\n";
+/**
+ * Runs the baseline CREATE TABLE/INDEX IF NOT EXISTS batch, then the boot-mode migration
+ * runner (additive migrations only, stopping at the first pending destructive one; those
+ * wait for an admin, see server/migrations/ + migration-runner.ts). The cached-promise
+ * once-guard makes concurrent/HMR calls a no-op after the first. An install predating the
+ * ledger is adopted here: the runner sees the legacy additive migrations as pending, runs
+ * their guarded (no-op) bodies, and records them.
+ */
+export declare function ensureObserveSchema(db?: Database): Promise<void>;
+/** Resets the once-guard so a test can migrate a fresh in-memory db. */
+export declare function __resetMigrationGuardForTests(): void;

package/dist/runtime/server/utils/migrate.js

@@ -0,0 +1,144 @@
+import { useObserveDb } from "./db.js";
+import { runPendingMigrations } from "./migration-runner.js";
+export const OBSERVE_DDL = `
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  id          TEXT PRIMARY KEY,          -- e.g. '0004-logs-error-fingerprint'
+  class       TEXT NOT NULL,             -- 'additive' | 'destructive' (audit record)
+  checksum    TEXT NOT NULL,             -- sha1 of the migration's up() source at author time
+  applied_at  INTEGER NOT NULL,          -- ms epoch
+  duration_ms INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS groups (
+  id          TEXT PRIMARY KEY,
+  slug        TEXT NOT NULL UNIQUE,
+  name        TEXT NOT NULL,
+  created_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS services (
+  id               TEXT PRIMARY KEY,
+  slug             TEXT NOT NULL UNIQUE,
+  name             TEXT NOT NULL,
+  group_id         TEXT NULL REFERENCES groups(id),
+  env              TEXT NULL,
+  version_tracking INTEGER NOT NULL DEFAULT 0,
+  current_version  TEXT NULL,
+  kind             TEXT NOT NULL DEFAULT 'server',   -- 'server' | 'browser'; toggles browser CORS only
+  type             TEXT NOT NULL DEFAULT 'service',   -- descriptive category; UI badge only, no runtime effect
+  deleted_at       INTEGER NULL,                      -- soft-delete marker; NULL = active. Purged after the retention window.
+  created_by       TEXT NULL,
+  created_at       INTEGER NOT NULL,
+  updated_at       INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_services_group ON services(group_id);
+
+CREATE TABLE IF NOT EXISTS service_app_names (
+  service_id  TEXT NOT NULL REFERENCES services(id),
+  app_name    TEXT NOT NULL UNIQUE,
+  PRIMARY KEY (service_id, app_name)
+);
+
+CREATE TABLE IF NOT EXISTS service_allowed_origins (
+  service_id  TEXT NOT NULL REFERENCES services(id),
+  origin      TEXT NOT NULL,
+  PRIMARY KEY (service_id, origin)
+);
+
+CREATE TABLE IF NOT EXISTS api_keys (
+  id           TEXT PRIMARY KEY,
+  service_id   TEXT NOT NULL REFERENCES services(id),
+  key_hash     TEXT NOT NULL UNIQUE,
+  key_prefix   TEXT NOT NULL,
+  label        TEXT NULL,
+  created_at   INTEGER NOT NULL,
+  revoked_at   INTEGER NULL,
+  last_used_at INTEGER NULL
+);
+CREATE INDEX IF NOT EXISTS idx_api_keys_service ON api_keys(service_id);
+
+CREATE TABLE IF NOT EXISTS users (
+  id            TEXT PRIMARY KEY,
+  username      TEXT NOT NULL UNIQUE,
+  display_name  TEXT NULL,
+  password_hash TEXT NULL,             -- NULL => JWT-only / no local login
+  role          TEXT NOT NULL DEFAULT 'viewer',   -- global role (drives admin/manager/viewer)
+  disabled      INTEGER NOT NULL DEFAULT 0,        -- 0 => active, 1 => cannot authenticate
+  source        TEXT NOT NULL,
+  created_by    TEXT NULL,
+  created_at    INTEGER NOT NULL,
+  updated_at    INTEGER NULL
+);
+CREATE TABLE IF NOT EXISTS user_service_roles (
+  user_id    TEXT NOT NULL,
+  service_id TEXT NOT NULL,
+  role       TEXT NOT NULL,
+  PRIMARY KEY (user_id, service_id)
+);
+CREATE TABLE IF NOT EXISTS user_group_roles (
+  user_id  TEXT NOT NULL,
+  group_id TEXT NOT NULL,
+  role     TEXT NOT NULL,
+  PRIMARY KEY (user_id, group_id)
+);
+CREATE TABLE IF NOT EXISTS user_identities (
+  id         TEXT PRIMARY KEY,
+  user_id    TEXT NOT NULL,
+  provider   TEXT NOT NULL,          -- 'jwt' (room for future external sources)
+  subject    TEXT NOT NULL,          -- the token sub claim
+  created_at INTEGER NOT NULL,
+  UNIQUE (provider, subject)
+);
+CREATE INDEX IF NOT EXISTS idx_user_identities_user ON user_identities(user_id);
+CREATE INDEX IF NOT EXISTS idx_user_service_roles_user ON user_service_roles(user_id);
+CREATE INDEX IF NOT EXISTS idx_user_group_roles_user ON user_group_roles(user_id);
+
+CREATE TABLE IF NOT EXISTS logs (
+  id            TEXT PRIMARY KEY,
+  time          INTEGER NOT NULL,
+  received_at   INTEGER NOT NULL,
+  level         INTEGER NOT NULL,
+  message       TEXT,
+  error_name    TEXT,
+  error_message TEXT,
+  error_stack   TEXT,
+  error_code    TEXT,
+  app           TEXT,
+  version       TEXT,
+  env           TEXT,
+  service_id    TEXT,
+  trace_id      TEXT,
+  span_id       TEXT,
+  parent_id     TEXT,
+  session       TEXT,
+  user_id       TEXT,
+  route         TEXT,
+  feature       TEXT,
+  tags          TEXT,
+  ctx           TEXT,
+  error_fingerprint TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_logs_time         ON logs(time);
+CREATE INDEX IF NOT EXISTS idx_logs_level_time   ON logs(level, time);
+CREATE INDEX IF NOT EXISTS idx_logs_app_time     ON logs(app, time);
+CREATE INDEX IF NOT EXISTS idx_logs_service_time ON logs(service_id, time);
+CREATE INDEX IF NOT EXISTS idx_logs_trace        ON logs(trace_id);
+CREATE INDEX IF NOT EXISTS idx_logs_session      ON logs(session);
+CREATE INDEX IF NOT EXISTS idx_logs_user         ON logs(user_id);
+CREATE INDEX IF NOT EXISTS idx_logs_route        ON logs(route);
+CREATE INDEX IF NOT EXISTS idx_logs_feature      ON logs(feature);
+CREATE INDEX IF NOT EXISTS idx_logs_version      ON logs(version);
+`;
+let _migrated;
+export async function ensureObserveSchema(db = useObserveDb()) {
+  if (_migrated) return _migrated;
+  _migrated = (async () => {
+    await db.exec(OBSERVE_DDL);
+    await runPendingMigrations(db, { mode: "boot" });
+  })();
+  return _migrated;
+}
+export function __resetMigrationGuardForTests() {
+  _migrated = void 0;
+}

package/dist/runtime/server/utils/migration-runner.d.ts

@@ -0,0 +1,42 @@
+import type { Database } from './db.js';
+import type { Migration, MigrationLog } from '../migrations/types.js';
+import type { MigrationStatus } from '../../shared/schema/migrations.js';
+/**
+ * The versioned migration runner (CP17). Pure functions taking an explicit `db` (and an
+ * optional registry override) so they are node-testable against an in-memory db0 sqlite,
+ * following the getStats/getJourney convention. The ledger table `schema_migrations` is the
+ * single source of truth for "what has run"; it is created by OBSERVE_DDL before the runner
+ * ever queries it. Boot mode auto-applies additive migrations only and stops at the first
+ * pending destructive one; admin mode applies an explicit (in-order) subset, additive or
+ * destructive, each wrapped in its own transaction with a pre-destructive file backup.
+ */
+export type { MigrationStatus };
+export interface RunOptions {
+    mode: 'boot' | 'admin';
+    ids?: string[];
+    log?: MigrationLog;
+    dbPath?: string;
+    migrations?: readonly Migration[];
+}
+export interface RunResult {
+    applied: string[];
+    skipped: string[];
+    failedAt?: string;
+}
+/** sha1 of the migration's up() source. Detects an accidental post-ship edit (drift). */
+export declare function computeChecksum(m: Migration): string;
+/**
+ * Applied/pending/blocked per registry entry, in id order. `blocked` is the crucial one:
+ * a pending migration that comes AFTER the first pending destructive migration cannot run
+ * (strict in-order application), so the UI shows it as held rather than runnable.
+ */
+export declare function getMigrationStatus(db: Database, migrations?: readonly Migration[]): Promise<MigrationStatus[]>;
+/**
+ * Apply pending migrations. Boot mode auto-applies additive migrations in strict id order
+ * and STOPS at the first pending destructive one, never touching it. Admin mode applies the
+ * requested `ids` (or all pending) in id order, but refuses to skip ahead of an earlier
+ * pending migration. Each migration runs in its own transaction; the ledger row is written
+ * inside that same transaction so a rollback leaves nothing recorded and a re-run resumes
+ * cleanly from the failure.
+ */
+export declare function runPendingMigrations(db: Database, opts: RunOptions): Promise<RunResult>;