@autter/otlp-ingester 1.4.0 → 1.5.0

package/dist/log-promotion.d.ts

@@ -0,0 +1,55 @@
+import type { RuntimeLogRecord } from "./logs.js";
+import type { RuntimeMetricPoint, RuntimeOccurrence, RuntimeOccurrenceInput } from "./types.js";
+/**
+ * Log promotion — errors from SDKs running WITHOUT a trace pipeline.
+ *
+ * Logger-only mode (`initAutterLogging`) and `@autter/runtime-edge` have no
+ * span to record an exception on, so they emit an error log record with
+ * `exception.*` and `autter.capture.mode = "log"`. /v1/logs turns those
+ * records into ordinary server occurrences (fingerprinted, stored in
+ * runtime_error_occurrences, forwarded to the sink) — otherwise their
+ * errors would never reach issue grouping.
+ *
+ * Dedupe, so one failure never becomes two occurrences through two export
+ * paths:
+ * - in-batch: at most one promoted occurrence per trace id (first wins);
+ * - cross-batch: a trace id that already produced an occurrence for this
+ *   tenant within ±PROMOTION_DEDUPE_WINDOW_MS (ClickHouse lookup) is skipped.
+ * Records without a trace id are always promoted. The lookup is
+ * best-effort and bounded (see promotionLookups, plus a per-tenant lookup
+ * budget in server.ts): when it fails, is skipped or is over budget the
+ * record is promoted anyway — a rare duplicate beats a silently dropped
+ * error.
+ */
+export declare const PROMOTION_DEDUPE_WINDOW_MS = 60000;
+/** Widest single lookup window. Candidate timestamps come from the client,
+ * so one batch could otherwise ask ClickHouse to scan an arbitrary range. */
+export declare const MAX_LOOKUP_SPAN_MS: number;
+/** At most this many lookup windows (queries) per request. */
+export declare const MAX_LOOKUP_WINDOWS = 4;
+/** Candidates outside [now − 24 h, now + 5 min] are never looked up: their
+ * trace cannot plausibly have a recent occurrence to dedupe against. */
+export declare const LOOKUP_PAST_MS: number;
+export declare const LOOKUP_FUTURE_MS: number;
+/** Promotion candidates in record order, deduped by trace id in-batch. */
+export declare function logPromotionCandidates(rows: RuntimeLogRecord[]): RuntimeOccurrenceInput[];
+export interface PromotionLookup {
+    from: Date;
+    to: Date;
+    traceIds: string[];
+}
+/**
+ * Bounded dedupe lookups for the candidates that carry a trace id: each
+ * window is [oldest − 60 s, newest + 60 s] over candidates taken newest first
+ * and spans at most MAX_LOOKUP_SPAN_MS; at most MAX_LOOKUP_WINDOWS windows are
+ * planned.
+ * Candidates outside the plausible time range or beyond the window cap are
+ * not looked up — they are still deduped in-batch and promoted.
+ */
+export declare function promotionLookups(occurrences: RuntimeOccurrenceInput[], now?: number): PromotionLookup[];
+/**
+ * One event / one error event per promoted occurrence — the same counting
+ * the trace path applies to occurrences outside a server span, so issue
+ * counters for logger-only services don't read 0.
+ */
+export declare function promotionRollups(occurrences: RuntimeOccurrence[]): RuntimeMetricPoint[];

package/dist/log-promotion.js

@@ -0,0 +1,119 @@
+import { normalizeRoute } from "./fingerprint.js";
+/**
+ * Log promotion — errors from SDKs running WITHOUT a trace pipeline.
+ *
+ * Logger-only mode (`initAutterLogging`) and `@autter/runtime-edge` have no
+ * span to record an exception on, so they emit an error log record with
+ * `exception.*` and `autter.capture.mode = "log"`. /v1/logs turns those
+ * records into ordinary server occurrences (fingerprinted, stored in
+ * runtime_error_occurrences, forwarded to the sink) — otherwise their
+ * errors would never reach issue grouping.
+ *
+ * Dedupe, so one failure never becomes two occurrences through two export
+ * paths:
+ * - in-batch: at most one promoted occurrence per trace id (first wins);
+ * - cross-batch: a trace id that already produced an occurrence for this
+ *   tenant within ±PROMOTION_DEDUPE_WINDOW_MS (ClickHouse lookup) is skipped.
+ * Records without a trace id are always promoted. The lookup is
+ * best-effort and bounded (see promotionLookups, plus a per-tenant lookup
+ * budget in server.ts): when it fails, is skipped or is over budget the
+ * record is promoted anyway — a rare duplicate beats a silently dropped
+ * error.
+ */
+export const PROMOTION_DEDUPE_WINDOW_MS = 60_000;
+/** Widest single lookup window. Candidate timestamps come from the client,
+ * so one batch could otherwise ask ClickHouse to scan an arbitrary range. */
+export const MAX_LOOKUP_SPAN_MS = 10 * 60_000;
+/** At most this many lookup windows (queries) per request. */
+export const MAX_LOOKUP_WINDOWS = 4;
+/** Candidates outside [now − 24 h, now + 5 min] are never looked up: their
+ * trace cannot plausibly have a recent occurrence to dedupe against. */
+export const LOOKUP_PAST_MS = 24 * 60 * 60_000;
+export const LOOKUP_FUTURE_MS = 5 * 60_000;
+/** Promotion candidates in record order, deduped by trace id in-batch. */
+export function logPromotionCandidates(rows) {
+    const traces = new Set();
+    const out = [];
+    for (const row of rows) {
+        const occurrence = row.occurrence;
+        if (!occurrence)
+            continue;
+        if (occurrence.traceId) {
+            if (traces.has(occurrence.traceId))
+                continue;
+            traces.add(occurrence.traceId);
+        }
+        out.push(occurrence);
+    }
+    return out;
+}
+/**
+ * Bounded dedupe lookups for the candidates that carry a trace id: each
+ * window is [oldest − 60 s, newest + 60 s] over candidates taken newest first
+ * and spans at most MAX_LOOKUP_SPAN_MS; at most MAX_LOOKUP_WINDOWS windows are
+ * planned.
+ * Candidates outside the plausible time range or beyond the window cap are
+ * not looked up — they are still deduped in-batch and promoted.
+ */
+export function promotionLookups(occurrences, now = Date.now()) {
+    const eligible = occurrences
+        .filter((o) => !!o.traceId)
+        .map((o) => ({ traceId: o.traceId, at: o.occurredAt.getTime() }))
+        .filter((o) => o.at >= now - LOOKUP_PAST_MS && o.at <= now + LOOKUP_FUTURE_MS)
+        // Newest first: recent records are the likeliest duplicates of an
+        // occurrence the trace path just wrote, so they get the windows.
+        .sort((a, b) => b.at - a.at);
+    const lookups = [];
+    let start = 0;
+    while (start < eligible.length && lookups.length < MAX_LOOKUP_WINDOWS) {
+        const newest = eligible[start].at;
+        let end = start;
+        while (end + 1 < eligible.length &&
+            newest - eligible[end + 1].at + 2 * PROMOTION_DEDUPE_WINDOW_MS <= MAX_LOOKUP_SPAN_MS)
+            end++;
+        lookups.push({
+            from: new Date(eligible[end].at - PROMOTION_DEDUPE_WINDOW_MS),
+            to: new Date(newest + PROMOTION_DEDUPE_WINDOW_MS),
+            traceIds: [...new Set(eligible.slice(start, end + 1).map((o) => o.traceId))],
+        });
+        start = end + 1;
+    }
+    return lookups;
+}
+/**
+ * One event / one error event per promoted occurrence — the same counting
+ * the trace path applies to occurrences outside a server span, so issue
+ * counters for logger-only services don't read 0.
+ */
+export function promotionRollups(occurrences) {
+    const rollups = new Map();
+    for (const occ of occurrences) {
+        const bucketAt = new Date(Math.floor(occ.occurredAt.getTime() / 60_000) * 60_000);
+        const route = normalizeRoute(occ.route);
+        const key = [
+            occ.service,
+            occ.environment,
+            occ.release ?? "",
+            route,
+            bucketAt.getTime(),
+        ].join(" ");
+        const existing = rollups.get(key);
+        if (existing) {
+            existing.requestCount += 1;
+            existing.errorCount += 1;
+            continue;
+        }
+        rollups.set(key, {
+            service: occ.service,
+            environment: occ.environment,
+            release: occ.release,
+            route,
+            bucketAt,
+            requestCount: 1,
+            errorCount: 1,
+            durationSumMs: 0,
+            sessionCount: 0,
+        });
+    }
+    return [...rollups.values()];
+}

package/dist/logs.d.ts

@@ -1,4 +1,5 @@
 import { type OtlpAttribute, type OtlpValue } from "./context.js";
+import type { RuntimeOccurrenceInput } from "./types.js";
 export interface RuntimeLogRecord {
     id: string;
     service: string;
@@ -15,6 +16,28 @@ export interface RuntimeLogRecord {
     durationMs: number;
     attributes: Record<string, unknown>;
     occurredAt: Date;
+    /**
+     * Lifted wide-event columns (migration 0012). `kind` is "request" for
+     * request summaries, "operation" for operation summaries (including
+     * pre-1.5.0 SDKs that never sent `autter.operation.kind`), "" for plain
+     * log records. The rest default to ""/0 when the record doesn't carry them.
+     */
+    kind: "" | "request" | "operation";
+    requestId: string;
+    /** `http.route`, query-stripped and id-normalised. */
+    route: string;
+    statusCode: number;
+    /** `autter.error.code`, only when it matches CODE_PATTERN. */
+    errorCode: string;
+    aiCostUsd: number;
+    aiCalls: number;
+    /**
+     * Not persisted on runtime_logs. Set for logger-only/edge error records
+     * (`autter.capture.mode = "log"`, severity ≥ error, `exception.*`
+     * present): the occurrence /v1/logs promotes into issue grouping —
+     * see log-promotion.ts.
+     */
+    occurrence?: RuntimeOccurrenceInput;
 }
 export interface OtlpLogsRequest {
     resourceLogs?: Array<{
@@ -39,4 +62,37 @@ export interface OtlpLogsRequest {
     }>;
 }
 export declare function normalizeLogs(request: OtlpLogsRequest): RuntimeLogRecord[];
-export declare function logTableDDL(db: string): string;
+/**
+ * Baseline for fresh databases. The 0012 columns and request-id skip index
+ * are included so a fresh DB matches a migrated one. `ttlDays` is
+ * LOG_TTL_DAYS; existing tables are brought in line at boot
+ * (ClickHouseStore.applyLogTtl), not here.
+ */
+export declare function logTableDDL(db: string, ttlDays?: number): string;
+/** Migration 0012 columns — shared by the baseline DDL and the migration. */
+export declare const LOG_REQUEST_COLUMNS: Array<{
+    name: string;
+    ddl: string;
+}>;
+export declare const LOG_REQUEST_ID_INDEX = "INDEX idx_logs_request_id request_id TYPE bloom_filter GRANULARITY 4";
+/**
+ * Per-minute request rollup (migration 0014), fed by runtime_request_1m_mv
+ * from `runtime_logs` rows with kind = 'request'. Route stats read this
+ * instead of scanning raw summaries:
+ *   sum(request_count), sum(failed_count), sum(duration_sum_ms),
+ *   quantilesMerge(0.5, 0.95)(duration_quantiles)
+ */
+export declare function requestRollupTableDDL(db: string): string;
+/**
+ * The view only sees rows inserted AFTER it exists (no backfill) and is
+ * created by migration 0014 only — not the baseline — because it reads the
+ * 0012 columns, which an existing runtime_logs table lacks until migrations
+ * run. runtime_logs is a ReplacingMergeTree keyed by a content-derived
+ * event_id, so a retried batch collapses there on merge — but the view
+ * aggregates every INSERT, so retries can count a summary twice. The
+ * rollup is therefore approximate under exporter retries (rare: a retry
+ * needs a 503 or a lost 2xx); exact per-request answers come from
+ * runtime_logs itself. `method` is read from the attributes JSON since
+ * runtime_logs has no method column.
+ */
+export declare function requestRollupViewDDL(db: string): string;

package/dist/logs.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { decodeOtlpAttributes, sanitizeRuntimeContext, } from "./context.js";
+import { declaredLink, liftErrorFields } from "./error-fields.js";
 import { normalizeRoute } from "./fingerprint.js";
 export function normalizeLogs(request) {
     if (!request || !Array.isArray(request.resourceLogs))
@@ -73,6 +74,56 @@ export function normalizeLogs(request) {
                     : "";
                 if (typeof attributes.path === "string")
                     attributes.path = normalizeRoute(attributes.path.split(/[?#]/)[0]);
+                const service = String(info["service.name"] ?? "unknown").slice(0, 200);
+                const environment = String(info["deployment.environment.name"] ??
+                    info["deployment.environment"] ??
+                    "production").slice(0, 100);
+                const release = String(info["service.version"] ?? "").slice(0, 200);
+                const declared = liftErrorFields(attributes);
+                // The sanitiser strips URL fragments; the declared docs link keeps
+                // its #anchor from the raw attribute (still validated).
+                const rawLink = declaredLink(record.attributes?.find((a) => a?.key === "autter.error.link")
+                    ?.value?.stringValue);
+                if (rawLink)
+                    declared.link = rawLink;
+                const rawRoute = typeof attributes["http.route"] === "string"
+                    ? attributes["http.route"].split(/[?#]/)[0]
+                    : "";
+                const route = normalizeRoute(rawRoute).slice(0, 500);
+                const status = Number(attributes["http.response.status_code"]);
+                const statusCode = Number.isInteger(status) && status > 0 && status < 1000 ? status : 0;
+                const declaredKind = attributes["autter.operation.kind"];
+                const type = attributes["autter.event.type"] === "operation" ? "operation" : "log";
+                const ai = attributes["autter.operation.ai"];
+                const aiRollup = ai && typeof ai === "object" && !Array.isArray(ai)
+                    ? ai
+                    : {};
+                const occurrence = attributes["autter.capture.mode"] === "log" &&
+                    (severity === "error" || severity === "fatal") &&
+                    hasException(attributes)
+                    ? {
+                        source: "server",
+                        severity: severity,
+                        service,
+                        environment,
+                        release: release || null,
+                        errorType: String(attributes["exception.type"] || "Error").slice(0, 200),
+                        message: String(attributes["exception.message"] || message || "Unknown error").slice(0, 4000),
+                        stack: typeof attributes["exception.stacktrace"] === "string"
+                            ? attributes["exception.stacktrace"]
+                            : null,
+                        route: rawRoute || stringOrNull(attributes["url.path"]),
+                        method: typeof attributes["http.request.method"] === "string"
+                            ? attributes["http.request.method"].toUpperCase().slice(0, 16)
+                            : null,
+                        statusCode: statusCode || null,
+                        traceId: traceId || null,
+                        sessionId: null,
+                        attributes,
+                        occurredAt,
+                        ...declared,
+                    }
+                    : undefined;
                 rows.push({
                     id: createHash("sha256")
                         .update(JSON.stringify([
@@ -86,31 +137,55 @@ export function normalizeLogs(request) {
                     ]))
                         .digest("hex")
                         .slice(0, 32),
-                    service: String(info["service.name"] ?? "unknown").slice(0, 200),
-                    environment: String(info["deployment.environment.name"] ??
-                        info["deployment.environment"] ??
-                        "production").slice(0, 100),
-                    release: String(info["service.version"] ?? "").slice(0, 200),
+                    service,
+                    environment,
+                    release,
                     traceId,
                     spanId,
                     operationId,
                     operation: String(attributes["autter.operation.name"] ?? "").slice(0, 200),
-                    type: attributes["autter.event.type"] === "operation"
-                        ? "operation"
-                        : "log",
+                    type,
                     severity,
                     message,
                     outcome: String(attributes["autter.operation.outcome"] ?? "").slice(0, 30),
                     durationMs: Math.max(0, Number(attributes["autter.operation.duration_ms"]) || 0),
                     attributes,
                     occurredAt,
+                    kind: declaredKind === "request" || declaredKind === "operation"
+                        ? declaredKind
+                        : type === "operation"
+                            ? "operation"
+                            : "",
+                    requestId: declared.requestId ?? "",
+                    route,
+                    statusCode,
+                    errorCode: declared.errorCode ?? "",
+                    aiCostUsd: nonNegative(attributes["autter.operation.ai.cost_usd"] ?? aiRollup.cost_usd),
+                    aiCalls: Math.min(4_294_967_295, Math.round(nonNegative(attributes["autter.operation.ai.calls"] ?? aiRollup.calls))),
+                    ...(occurrence ? { occurrence } : {}),
                 });
             }
         }
     }
     return rows;
 }
-export function logTableDDL(db) {
+function hasException(attributes) {
+    return ["exception.type", "exception.message", "exception.stacktrace"].some((key) => typeof attributes[key] === "string" && attributes[key] !== "");
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value ? value.split(/[?#]/)[0] : null;
+}
+function nonNegative(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+/**
+ * Baseline for fresh databases. The 0012 columns and request-id skip index
+ * are included so a fresh DB matches a migrated one. `ttlDays` is
+ * LOG_TTL_DAYS; existing tables are brought in line at boot
+ * (ClickHouseStore.applyLogTtl), not here.
+ */
+export function logTableDDL(db, ttlDays = 14) {
     return `CREATE TABLE IF NOT EXISTS ${db}.runtime_logs (
 		org_id String, repository_id String, event_id String,
 		service LowCardinality(String), environment LowCardinality(String), release String DEFAULT '',
@@ -119,8 +194,68 @@ export function logTableDDL(db) {
 		severity LowCardinality(String) DEFAULT 'info', message String CODEC(ZSTD(1)),
 		outcome LowCardinality(String) DEFAULT '', duration_ms Float64 DEFAULT 0,
 		attributes String DEFAULT '{}' CODEC(ZSTD(1)), occurred_at DateTime64(3, 'UTC'),
-		ingested_at DateTime64(3, 'UTC') DEFAULT now64(3)
+		ingested_at DateTime64(3, 'UTC') DEFAULT now64(3),
+		${LOG_REQUEST_COLUMNS.map((column) => column.ddl).join(", ")},
+		${LOG_REQUEST_ID_INDEX}
 	) ENGINE = ReplacingMergeTree PARTITION BY toDate(occurred_at)
 	ORDER BY (org_id, repository_id, occurred_at, event_id)
-	TTL toDateTime(occurred_at) + INTERVAL 14 DAY`;
+	TTL toDateTime(occurred_at) + INTERVAL ${ttlDays} DAY`;
+}
+/** Migration 0012 columns — shared by the baseline DDL and the migration. */
+export const LOG_REQUEST_COLUMNS = [
+    { name: "kind", ddl: "kind LowCardinality(String) DEFAULT ''" },
+    { name: "request_id", ddl: "request_id String DEFAULT ''" },
+    { name: "route", ddl: "route String DEFAULT ''" },
+    { name: "status_code", ddl: "status_code UInt16 DEFAULT 0" },
+    { name: "error_code", ddl: "error_code String DEFAULT ''" },
+    { name: "ai_cost_usd", ddl: "ai_cost_usd Float64 DEFAULT 0" },
+    { name: "ai_calls", ddl: "ai_calls UInt32 DEFAULT 0" },
+];
+export const LOG_REQUEST_ID_INDEX = "INDEX idx_logs_request_id request_id TYPE bloom_filter GRANULARITY 4";
+/**
+ * Per-minute request rollup (migration 0014), fed by runtime_request_1m_mv
+ * from `runtime_logs` rows with kind = 'request'. Route stats read this
+ * instead of scanning raw summaries:
+ *   sum(request_count), sum(failed_count), sum(duration_sum_ms),
+ *   quantilesMerge(0.5, 0.95)(duration_quantiles)
+ */
+export function requestRollupTableDDL(db) {
+    return `CREATE TABLE IF NOT EXISTS ${db}.runtime_request_1m (
+		org_id String, repository_id String,
+		service LowCardinality(String), environment LowCardinality(String),
+		route String, method LowCardinality(String), bucket_at DateTime('UTC'),
+		request_count SimpleAggregateFunction(sum, UInt64),
+		failed_count SimpleAggregateFunction(sum, UInt64),
+		duration_sum_ms SimpleAggregateFunction(sum, Float64),
+		duration_quantiles AggregateFunction(quantiles(0.5, 0.95), Float64)
+	) ENGINE = AggregatingMergeTree PARTITION BY toYYYYMM(bucket_at)
+	ORDER BY (org_id, repository_id, service, environment, route, method, bucket_at)
+	TTL bucket_at + INTERVAL 90 DAY`;
+}
+/**
+ * The view only sees rows inserted AFTER it exists (no backfill) and is
+ * created by migration 0014 only — not the baseline — because it reads the
+ * 0012 columns, which an existing runtime_logs table lacks until migrations
+ * run. runtime_logs is a ReplacingMergeTree keyed by a content-derived
+ * event_id, so a retried batch collapses there on merge — but the view
+ * aggregates every INSERT, so retries can count a summary twice. The
+ * rollup is therefore approximate under exporter retries (rare: a retry
+ * needs a 503 or a lost 2xx); exact per-request answers come from
+ * runtime_logs itself. `method` is read from the attributes JSON since
+ * runtime_logs has no method column.
+ */
+export function requestRollupViewDDL(db) {
+    return `CREATE MATERIALIZED VIEW IF NOT EXISTS ${db}.runtime_request_1m_mv
+	TO ${db}.runtime_request_1m AS
+	SELECT
+		org_id, repository_id, service, environment, route,
+		upper(JSONExtractString(attributes, 'http.request.method')) AS method,
+		toDateTime(toStartOfMinute(occurred_at), 'UTC') AS bucket_at,
+		count() AS request_count,
+		countIf(outcome = 'failed') AS failed_count,
+		sum(duration_ms) AS duration_sum_ms,
+		quantilesState(0.5, 0.95)(duration_ms) AS duration_quantiles
+	FROM ${db}.runtime_logs
+	WHERE kind = 'request'
+	GROUP BY org_id, repository_id, service, environment, route, method, bucket_at`;
 }

package/dist/migrations.d.ts

@@ -32,6 +32,9 @@
  *     ],
  *   },
  */
+/** Migration 0013 columns — shared with the baseline DDL in clickhouse.ts. */
+export declare const OCCURRENCE_CODE_COLUMNS: string[];
+export declare const OCCURRENCE_REQUEST_ID_INDEX = "INDEX idx_occ_request_id request_id TYPE bloom_filter GRANULARITY 4";
 export interface Migration {
     /** Unique, ordered id: "<serial>-<slug>". Never reuse or reorder. */
     id: string;

package/dist/migrations.js

@@ -35,8 +35,20 @@
 import { latencyTableDDL } from "./latency.js";
 import { profileTableDDL } from "./profiles.js";
 import { sourceMapTableDDL } from "./source-maps.js";
-import { logTableDDL } from "./logs.js";
+import { LOG_REQUEST_COLUMNS, LOG_REQUEST_ID_INDEX, logTableDDL, requestRollupTableDDL, requestRollupViewDDL, } from "./logs.js";
 import { memoryTableDDL, platformEventTableDDL } from "./memory.js";
+import { ingesterInfoTableDDL, sdkVersionTableDDL } from "./sdk-versions.js";
+/** Migration 0013 columns — shared with the baseline DDL in clickhouse.ts. */
+export const OCCURRENCE_CODE_COLUMNS = [
+    "error_code String DEFAULT ''",
+    "error_why String DEFAULT ''",
+    "error_fix String DEFAULT ''",
+    "error_link String DEFAULT ''",
+    "expected UInt8 DEFAULT 0",
+    "request_id String DEFAULT ''",
+    "fingerprint_scheme LowCardinality(String) DEFAULT 'message-v1'",
+];
+export const OCCURRENCE_REQUEST_ID_INDEX = "INDEX idx_occ_request_id request_id TYPE bloom_filter GRANULARITY 4";
 export const MIGRATIONS = [
     // 0001 intentionally reserved as the baseline marker: databases created
     // before the migration runner existed record it as applied without
@@ -129,6 +141,36 @@ export const MIGRATIONS = [
             `ALTER TABLE {db}.runtime_memory_samples ADD COLUMN IF NOT EXISTS temporality LowCardinality(String) DEFAULT 'gauge'`,
         ] },
     { id: "0011-runtime-logs", statements: [logTableDDL("{db}")] },
+    // Request wide events: request summaries share runtime_logs with
+    // operations and plain logs; the lifted columns make "requests on this
+    // route", "everything for request X" and "coded failures" plain column
+    // filters. The skip index only covers parts written after it exists
+    // (no MATERIALIZE INDEX mutation) — older rows predate request ids.
+    {
+        id: "0012-runtime-logs-requests",
+        statements: [
+            ...LOG_REQUEST_COLUMNS.map((column) => `ALTER TABLE {db}.runtime_logs ADD COLUMN IF NOT EXISTS ${column.ddl}`),
+            `ALTER TABLE {db}.runtime_logs ADD ${LOG_REQUEST_ID_INDEX.replace("INDEX ", "INDEX IF NOT EXISTS ")}`,
+        ],
+    },
+    // Declared error metadata and code-based grouping (fingerprint_scheme
+    // "code-v1" vs the historical "message-v1").
+    {
+        id: "0013-occurrence-codes",
+        statements: [
+            ...OCCURRENCE_CODE_COLUMNS.map((column) => `ALTER TABLE {db}.runtime_error_occurrences ADD COLUMN IF NOT EXISTS ${column}`),
+            `ALTER TABLE {db}.runtime_error_occurrences ADD ${OCCURRENCE_REQUEST_ID_INDEX.replace("INDEX ", "INDEX IF NOT EXISTS ")}`,
+        ],
+    },
+    // Per-minute route rollup of request summaries. Table first, then the
+    // view (which needs both the table and the 0012 columns).
+    {
+        id: "0014-runtime-request-1m",
+        statements: [requestRollupTableDDL("{db}"), requestRollupViewDDL("{db}")],
+    },
+    // Version compatibility: SDK name/version seen per service, and this
+    // ingester's own version + schema level for the Autter dashboard.
+    { id: "0015-runtime-compat", statements: [sdkVersionTableDDL("{db}"), ingesterInfoTableDDL("{db}")] },
 ];
 /** The tracking table itself — created by the runner before anything else. */
 export function migrationsTableDDL(db) {

package/dist/normalize-browser.d.ts

@@ -6,6 +6,8 @@ export declare const browserPayloadSchema: z.ZodObject<{
     service: z.ZodString;
     environment: z.ZodString;
     release: z.ZodOptional<z.ZodString>;
+    /** @autter/runtime-browser version (1.4+); recorded for compatibility checks. */
+    sdk: z.ZodCatch<z.ZodOptional<z.ZodString>>;
     events: z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodEnum<["exception", "unhandled_rejection", "message", "session_start", "track_event", "outcome", "request_failure", "csp_violation", "timing"]>;
@@ -23,9 +25,17 @@ export declare const browserPayloadSchema: z.ZodObject<{
         column: z.ZodOptional<z.ZodNumber>;
         /** Path only; query strings are stripped defensively anyway. */
         route: z.ZodOptional<z.ZodString>;
+        /**
+         * Free-form, scrubbed context. runtime-browser ≥1.4.0 also sends the
+         * declared-error keys `autter.error.code|why|fix|link|expected` (from
+         * coded errors / `autterErrorFromResponse`) and `autter.request.id` (the
+         * `x-request-id` of a failed fetch/XHR). They are validated one by one
+         * in normalizeBrowserPayload — a malformed value is dropped on its own
+         * instead of rejecting the whole beacon.
+         */
         context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
-        type: "exception" | "message" | "unhandled_rejection" | "session_start" | "track_event" | "outcome" | "request_failure" | "csp_violation" | "timing";
+        type: "exception" | "message" | "request_failure" | "timing" | "outcome" | "csp_violation" | "unhandled_rejection" | "session_start" | "track_event";
         message: string;
         timestamp: string;
         durationMs?: number | undefined;
@@ -40,7 +50,7 @@ export declare const browserPayloadSchema: z.ZodObject<{
         column?: number | undefined;
         context?: Record<string, unknown> | undefined;
     }, {
-        type: "exception" | "message" | "unhandled_rejection" | "session_start" | "track_event" | "outcome" | "request_failure" | "csp_violation" | "timing";
+        type: "exception" | "message" | "request_failure" | "timing" | "outcome" | "csp_violation" | "unhandled_rejection" | "session_start" | "track_event";
         timestamp: string;
         durationMs?: number | undefined;
         route?: string | undefined;
@@ -60,7 +70,7 @@ export declare const browserPayloadSchema: z.ZodObject<{
     environment: string;
     version: 1;
     events: {
-        type: "exception" | "message" | "unhandled_rejection" | "session_start" | "track_event" | "outcome" | "request_failure" | "csp_violation" | "timing";
+        type: "exception" | "message" | "request_failure" | "timing" | "outcome" | "csp_violation" | "unhandled_rejection" | "session_start" | "track_event";
         message: string;
         timestamp: string;
         durationMs?: number | undefined;
@@ -77,12 +87,13 @@ export declare const browserPayloadSchema: z.ZodObject<{
     }[];
     release?: string | undefined;
     sessionId?: string | undefined;
+    sdk?: string | undefined;
 }, {
     service: string;
     environment: string;
     version: 1;
     events: {
-        type: "exception" | "message" | "unhandled_rejection" | "session_start" | "track_event" | "outcome" | "request_failure" | "csp_violation" | "timing";
+        type: "exception" | "message" | "request_failure" | "timing" | "outcome" | "csp_violation" | "unhandled_rejection" | "session_start" | "track_event";
         timestamp: string;
         durationMs?: number | undefined;
         route?: string | undefined;
@@ -99,6 +110,7 @@ export declare const browserPayloadSchema: z.ZodObject<{
     }[];
     release?: string | undefined;
     sessionId?: string | undefined;
+    sdk?: unknown;
 }>;
 export type BrowserPayload = z.infer<typeof browserPayloadSchema>;
 export interface NormalizedBrowser {