@autter/otlp-ingester 1.4.0 → 1.5.0

package/README.md

@@ -9,10 +9,13 @@ one per-repo signal model, fingerprints errors, and writes ClickHouse.
 | Route | Payload | Purpose |
 | --- | --- | --- |
 | `POST /v1/traces` | OTLP/JSON `ExportTraceServiceRequest` | Error spans → occurrences; all spans → `runtime_spans`; server spans → usage rollups; GenAI spans → `runtime_llm_calls` |
+| `POST /v1/logs` | OTLP `ExportLogsServiceRequest`, server key | Wide events (request/operation summaries, logs) → `runtime_logs` (+ `runtime_request_1m` rollup); logger-only error records (`autter.capture.mode=log`) → occurrences |
 | `POST /v1/metrics` | OTLP `ExportMetricsServiceRequest` | HTTP-server duration histograms → usage rollups; portable process memory/GC metrics → per-instance memory samples |
 | `POST /v1/platform-events` | JSON, server key | ECS/Kubernetes OOM kills and restarts → memory incident correlation |
 | `POST /v1/profiles` | Symbolized pprof, server key | CPU/in-use heap profile samples |
 | `POST /v1/browser` | Browser payload `version: 1` | Errors/rejections → occurrences; session pings → rollups |
+| `POST /v1/logs` | OTLP logs, server key | Structured logs and operation summaries → `runtime_logs` |
+| `GET /v1/compat` | — | Version, schema level and supported features (public) |
 | `GET /healthz` | — | Liveness + ClickHouse reachability |
 
 Auth on every ingest route: `Authorization: Bearer <ingest key>`,
@@ -45,6 +48,17 @@ AUTTER_INGEST_KEYS='[
 The validator webhook may return the same extra fields:
 `{ orgId, repositoryId, scope?, allowedOrigins? }`.
 
+### Version compatibility
+
+`GET /v1/compat` (public, no tenant data) returns this ingester's version,
+its ClickHouse schema state, and which features from
+`src/compat-manifest.json` it supports. Add
+`?features=operation_logging&sdk=@autter/runtime-node@1.3.0` to get the evaluated
+incompatibilities. Every response carries `x-autter-ingester-version`. The
+ingester records the SDK name and version each service sends with
+(`runtime_sdk_versions`) and its own version (`runtime_ingester_info`), and
+the Autter dashboard reads both. See [docs/COMPATIBILITY.md](../../docs/COMPATIBILITY.md).
+
 ## Configuration
 
 | Env | Default | Description |
@@ -64,8 +78,44 @@ The validator webhook may return the same extra fields:
 | `MAX_BODY_BYTES` | `1048576` | Request body cap |
 | `RATE_LIMIT_PER_MINUTE` | `300` | Per-key fixed window (server keys) |
 | `CLIENT_RATE_LIMIT_PER_MINUTE` | `120` | Per-key fixed window (client keys) |
+| `PROMOTION_LOOKUPS_PER_MINUTE` | `30` | Per-tenant ClickHouse dedupe lookups for `/v1/logs` error promotion; over budget, records are promoted with in-batch dedupe only |
 | `OCCURRENCE_TTL_DAYS` / `SPAN_TTL_DAYS` / `METRICS_TTL_DAYS` | `14` / `7` / `90` | ClickHouse TTLs (applied at table creation) |
 | `LLM_CALL_TTL_DAYS` | `90` | Retention for `runtime_llm_calls` rows |
+| `LOG_TTL_DAYS` | `14` | Retention for `runtime_logs` (request summaries are always kept, never sampled, so this is the main volume knob). Unlike the other TTLs it is also applied to **existing** tables: at boot the ingester compares it with the table's TTL and runs `ALTER TABLE … MODIFY TTL` only when they differ; a failure is logged and retried next boot |
+| `AUTTER_REDACT_VALUE_PATTERNS` | — | JSON array of extra regex sources masked in stored/forwarded text and attribute values (built-in secret/PII patterns always apply) |
+| `AUTTER_REDACT_KEY_PATTERNS` | — | JSON array of extra regex sources for attribute keys whose values are masked wholesale |
+
+## Coded errors and request summaries (1.5.0)
+
+- **Code-based grouping.** An occurrence carrying a valid `autter.error.code`
+  (`^[a-z][a-z0-9_]*(\.[a-z0-9_]+){0,3}$`, ≤80 chars) is fingerprinted by
+  scheme `code-v1`: `sha256("code-v1\0" + service + "\0" + code)[:32]` —
+  independent of source, message, stack and route, so one code is one issue
+  across traces, log promotion, the browser and external connectors.
+  Uncoded errors keep the historical fingerprint (`message-v1`) byte-for-byte.
+  `fingerprint_scheme` is stored per occurrence and sent to the sink.
+- **Declared fields.** `autter.error.why|fix|link|expected` and
+  `autter.request.id` are lifted from span/exception-event attributes, log
+  attributes and browser context into `runtime_error_occurrences`
+  (`error_why`, `error_fix`, `error_link`, `expected`, `request_id`) and the
+  sink payload. why/fix are scrubbed and capped at 1000 chars; links must be
+  http(s) and ≤500 chars. Exception spans inherit the request id of their
+  server span.
+- **Request summaries.** `/v1/logs` lifts `autter.operation.kind`,
+  `autter.request.id`, `http.route` (id-normalised), `http.response.status_code`,
+  `autter.error.code` and the `autter.operation.ai` rollup (`cost_usd`, `calls`)
+  into `runtime_logs` columns. `kind = 'request'` rows feed the
+  `runtime_request_1m` materialized view (per route/method/minute: count,
+  failed, duration sum, p50/p95). The view counts every insert, so a retried
+  batch can be counted twice — route stats are approximate under exporter
+  retries; `runtime_logs` itself collapses duplicates.
+- **Log promotion.** SDKs without a trace pipeline (logger-only mode,
+  `@autter/runtime-edge`) send errors as log records with `exception.*` and
+  `autter.capture.mode = "log"`. `/v1/logs` promotes those (severity ≥ error)
+  to server occurrences — stored, counted and forwarded to the sink —
+  skipping a record when its trace id already produced an occurrence in the
+  same batch or (ClickHouse lookup) within ±60 s. If the lookup fails the
+  record is promoted anyway.
 
 ## LLM / GenAI calls
 

package/dist/clickhouse.d.ts

@@ -3,12 +3,16 @@ import { type LatencyHistogram } from "./latency.js";
 import { type ProfileSample } from "./profiles.js";
 import { type MemorySample, type PlatformEvent } from "./memory.js";
 import { type RuntimeLogRecord } from "./logs.js";
+import { type SdkVersionRow } from "./sdk-versions.js";
+import type { SchemaStatus } from "./compat.js";
 import { type Migration } from "./migrations.js";
 import type { IngestContext, RuntimeLlmCall, RuntimeMetricPoint, RuntimeOccurrence, RuntimeSpanRow } from "./types.js";
 export declare class ClickHouseStore {
     private readonly config;
     private client;
     private ensurePromise;
+    private schemaState;
+    private appliedIds;
     constructor(config: IngesterConfig);
     get configured(): boolean;
     private getClient;
@@ -23,6 +27,35 @@ export declare class ClickHouseStore {
      * next request retries.
      */
     ensureSchema(migrations?: Migration[]): Promise<void>;
+    /**
+     * Bring runtime_logs' TTL in line with LOG_TTL_DAYS. Idempotent: reads the
+     * current TTL from system.tables and only issues `MODIFY TTL` when it
+     * differs (MODIFY TTL rewrites TTL info for existing parts, so it must not
+     * run on every boot). Best-effort — a failure is logged and never blocks
+     * ingest; the next boot retries.
+     */
+    applyLogTtl(): Promise<void>;
+    /**
+     * Trace ids (from `traceIds`) that already produced an occurrence for
+     * this tenant in [from, to] — the cross-batch half of the log-promotion
+     * dedupe. `excludeIds` are the candidate occurrences' own deterministic
+     * ids, so a retried batch does not dedupe against its own earlier,
+     * partially-committed write. Throws on failure; the caller decides.
+     */
+    recentOccurrenceTraceIds(ctx: IngestContext, traceIds: string[], from: Date, to: Date, excludeIds: string[]): Promise<Set<string>>;
+    /** Schema state as of the last ensureSchema attempt — never triggers DDL
+     * (it backs the unauthenticated /v1/compat endpoint). */
+    schemaStatus(): {
+        status: SchemaStatus;
+        applied: string[];
+    };
+    insertSdkVersions(ctx: IngestContext, rows: SdkVersionRow[]): Promise<void>;
+    /** Record this ingester's version and schema level (global, not tenant data). */
+    insertIngesterInfo(info: {
+        version: string;
+        schemaLevel: string;
+        report: unknown;
+    }): Promise<void>;
     ping(): Promise<boolean>;
     insertOccurrences(ctx: IngestContext, occurrences: RuntimeOccurrence[]): Promise<void>;
     insertSpans(ctx: IngestContext, spans: RuntimeSpanRow[]): Promise<void>;

package/dist/clickhouse.js

@@ -3,8 +3,9 @@ import { latencyTableDDL } from "./latency.js";
 import { profileTableDDL } from "./profiles.js";
 import { memoryTableDDL, platformEventTableDDL } from "./memory.js";
 import { sourceMapTableDDL } from "./source-maps.js";
-import { logTableDDL } from "./logs.js";
-import { MIGRATIONS, migrationsTableDDL, } from "./migrations.js";
+import { logTableDDL, requestRollupTableDDL, } from "./logs.js";
+import { ingesterInfoTableDDL, sdkVersionTableDDL, } from "./sdk-versions.js";
+import { MIGRATIONS, OCCURRENCE_CODE_COLUMNS, OCCURRENCE_REQUEST_ID_INDEX, migrationsTableDDL, } from "./migrations.js";
 /**
  * ClickHouse persistence. The schema is idempotent and applied lazily once
  * per process. Every row is keyed by (org_id, repository_id) — tenant
@@ -16,10 +17,16 @@ const INSERT_SETTINGS = {
     async_insert: 1,
     wait_for_async_insert: 1,
 };
+/** "YYYY-MM-DD hh:mm:ss.sss" (UTC) — the DateTime64 query-parameter form. */
+function chDateTime(date) {
+    return date.toISOString().replace("T", " ").replace("Z", "");
+}
 export class ClickHouseStore {
     config;
     client = null;
     ensurePromise = null;
+    schemaState = "pending";
+    appliedIds = [];
     constructor(config) {
         this.config = config;
     }
@@ -47,6 +54,7 @@ export class ClickHouseStore {
     schemaStatements() {
         const db = this.config.clickhouseDatabase;
         const { occurrenceTtlDays, spanTtlDays, metricsTtlDays, llmCallTtlDays } = this.config;
+        const logTtlDays = this.config.logTtlDays ?? 14;
         return [
             `CREATE DATABASE IF NOT EXISTS ${db}`,
             latencyTableDDL(db, metricsTtlDays),
@@ -54,7 +62,13 @@ export class ClickHouseStore {
             memoryTableDDL(db),
             platformEventTableDDL(db),
             sourceMapTableDDL(db),
-            logTableDDL(db),
+            logTableDDL(db, logTtlDays),
+            // The table only: its materialized view reads 0012 columns that an
+            // existing runtime_logs lacks until migrations run, so the view is
+            // created by migration 0014 alone (migrations also run on fresh DBs).
+            requestRollupTableDDL(db),
+            sdkVersionTableDDL(db, metricsTtlDays),
+            ingesterInfoTableDDL(db),
             `CREATE TABLE IF NOT EXISTS ${db}.runtime_error_occurrences (
 				org_id             String,
 				repository_id      String,
@@ -79,7 +93,9 @@ export class ClickHouseStore {
 				session_id         String DEFAULT '',
 				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),
+				${OCCURRENCE_CODE_COLUMNS.join(",\n\t\t\t\t")},
+				${OCCURRENCE_REQUEST_ID_INDEX}
 			)
 			ENGINE = MergeTree
 			PARTITION BY toDate(occurred_at)
@@ -192,12 +208,126 @@ export class ClickHouseStore {
                 });
                 console.log(`clickhouse migration applied: ${migration.id}`);
             }
+            await this.applyLogTtl();
+            this.appliedIds = migrations.map((migration) => migration.id);
+            this.schemaState = "ready";
         })().catch((err) => {
             this.ensurePromise = null;
+            this.schemaState = "failed";
             throw err;
         });
         return this.ensurePromise;
     }
+    /**
+     * Bring runtime_logs' TTL in line with LOG_TTL_DAYS. Idempotent: reads the
+     * current TTL from system.tables and only issues `MODIFY TTL` when it
+     * differs (MODIFY TTL rewrites TTL info for existing parts, so it must not
+     * run on every boot). Best-effort — a failure is logged and never blocks
+     * ingest; the next boot retries.
+     */
+    async applyLogTtl() {
+        const days = this.config.logTtlDays ?? 14;
+        const db = this.config.clickhouseDatabase;
+        try {
+            const client = this.getClient();
+            const rows = await client.query({
+                query: `SELECT engine_full FROM system.tables WHERE database = {db:String} AND name = 'runtime_logs'`,
+                query_params: { db },
+                format: "JSONEachRow",
+            });
+            const [table] = await rows.json();
+            if (!table)
+                return;
+            const current = /\bTTL\b[^]*?toIntervalDay\((\d+)\)/.exec(table.engine_full);
+            if (!current) {
+                console.warn("runtime_logs TTL not recognised — LOG_TTL_DAYS not applied");
+                return;
+            }
+            if (Number(current[1]) === days)
+                return;
+            await client.command({
+                query: `ALTER TABLE ${db}.runtime_logs MODIFY TTL toDateTime(occurred_at) + INTERVAL ${days} DAY`,
+            });
+            console.log(`runtime_logs TTL changed from ${current[1]} to ${days} days (LOG_TTL_DAYS)`);
+        }
+        catch (err) {
+            console.warn("applying LOG_TTL_DAYS to runtime_logs failed (will retry next boot):", err instanceof Error ? err.message : err);
+        }
+    }
+    /**
+     * Trace ids (from `traceIds`) that already produced an occurrence for
+     * this tenant in [from, to] — the cross-batch half of the log-promotion
+     * dedupe. `excludeIds` are the candidate occurrences' own deterministic
+     * ids, so a retried batch does not dedupe against its own earlier,
+     * partially-committed write. Throws on failure; the caller decides.
+     */
+    async recentOccurrenceTraceIds(ctx, traceIds, from, to, excludeIds) {
+        if (traceIds.length === 0 || !this.configured)
+            return new Set();
+        await this.ensureSchema();
+        const rows = await this.getClient().query({
+            query: `SELECT DISTINCT trace_id FROM ${this.table("runtime_error_occurrences")}
+				WHERE org_id = {org:String} AND repository_id = {repo:String}
+					AND occurred_at >= {from:DateTime64(3, 'UTC')} AND occurred_at <= {to:DateTime64(3, 'UTC')}
+					AND has({traces:Array(String)}, trace_id)
+					AND NOT has({exclude:Array(String)}, occurrence_id)`,
+            query_params: {
+                org: ctx.orgId,
+                repo: ctx.repositoryId,
+                from: chDateTime(from),
+                to: chDateTime(to),
+                traces: traceIds,
+                exclude: excludeIds,
+            },
+            format: "JSONEachRow",
+        });
+        return new Set((await rows.json()).map((row) => row.trace_id));
+    }
+    /** Schema state as of the last ensureSchema attempt — never triggers DDL
+     * (it backs the unauthenticated /v1/compat endpoint). */
+    schemaStatus() {
+        if (!this.configured)
+            return { status: "unconfigured", applied: [] };
+        return { status: this.schemaState, applied: [...this.appliedIds] };
+    }
+    async insertSdkVersions(ctx, rows) {
+        if (!rows.length || !this.configured)
+            return;
+        await this.ensureSchema();
+        await this.getClient().insert({
+            table: this.table("runtime_sdk_versions"),
+            format: "JSONEachRow",
+            clickhouse_settings: INSERT_SETTINGS,
+            values: rows.map((row) => ({
+                org_id: ctx.orgId,
+                repository_id: ctx.repositoryId,
+                service: row.service,
+                environment: row.environment,
+                sdk_name: row.sdkName,
+                sdk_version: row.sdkVersion,
+                sdk_language: row.sdkLanguage,
+                ingester_version: row.ingesterVersion,
+                last_seen: row.seenAt.toISOString(),
+            })),
+        });
+    }
+    /** Record this ingester's version and schema level (global, not tenant data). */
+    async insertIngesterInfo(info) {
+        if (!this.configured)
+            return;
+        await this.ensureSchema();
+        await this.getClient().insert({
+            table: this.table("runtime_ingester_info"),
+            format: "JSONEachRow",
+            clickhouse_settings: INSERT_SETTINGS,
+            values: [{
+                    ingester_version: info.version,
+                    schema_level: info.schemaLevel,
+                    report: JSON.stringify(info.report),
+                    reported_at: new Date().toISOString(),
+                }],
+        });
+    }
     async ping() {
         if (!this.configured)
             return false;
@@ -236,6 +366,13 @@ export class ClickHouseStore {
                 session_id: o.sessionId ?? "",
                 attributes: JSON.stringify(o.attributes ?? {}),
                 occurred_at: o.occurredAt.toISOString(),
+                error_code: o.errorCode ?? "",
+                error_why: o.why ?? "",
+                error_fix: o.fix ?? "",
+                error_link: o.link ?? "",
+                expected: o.expected ? 1 : 0,
+                request_id: o.requestId ?? "",
+                fingerprint_scheme: o.fingerprintScheme,
             })),
         });
     }
@@ -278,7 +415,9 @@ export class ClickHouseStore {
                 service: row.service, environment: row.environment, release: row.release, trace_id: row.traceId,
                 span_id: row.spanId, operation_id: row.operationId, operation: row.operation, event_type: row.type,
                 severity: row.severity, message: row.message, outcome: row.outcome, duration_ms: row.durationMs,
-                attributes: JSON.stringify(row.attributes), occurred_at: row.occurredAt.toISOString() })) });
+                attributes: JSON.stringify(row.attributes), occurred_at: row.occurredAt.toISOString(),
+                kind: row.kind, request_id: row.requestId, route: row.route, status_code: row.statusCode,
+                error_code: row.errorCode, ai_cost_usd: row.aiCostUsd, ai_calls: row.aiCalls })) });
     }
     async insertProfileSamples(ctx, samples) {
         if (!samples.length)

package/dist/compat-manifest.json

@@ -0,0 +1,94 @@
+{
+    "manifestVersion": 1,
+    "docs": "https://github.com/Autter-dev/autter-runtime/blob/main/docs/COMPATIBILITY.md",
+    "upgrade": {
+        "ingester": "docker pull ghcr.io/autter-dev/otlp-ingester:latest and restart it (ClickHouse migrations run at boot)",
+        "sdk": "npm install {package}@latest"
+    },
+    "features": [
+        {
+            "id": "llm_calls",
+            "title": "LLM call tracking",
+            "ingester": "1.1.0",
+            "migrations": ["0004-llm-calls"],
+            "sdks": { "@autter/runtime-node": "1.1.0", "@autter/runtime-next": "1.1.0" }
+        },
+        {
+            "id": "endpoint_latency",
+            "title": "Endpoint latency regression detection",
+            "ingester": "1.3.1",
+            "migrations": ["0005-latency-histograms"],
+            "sdks": { "@autter/runtime-node": "1.3.0", "@autter/runtime-next": "1.3.0" }
+        },
+        {
+            "id": "browser_network_events",
+            "title": "Browser network, timing and outcome capture",
+            "ingester": "1.3.2",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.3.2", "@autter/runtime-next": "1.3.2" },
+            "browserEvents": ["request_failure", "timing", "outcome"]
+        },
+        {
+            "id": "profiles",
+            "title": "Profile ingestion",
+            "ingester": "1.3.2",
+            "migrations": ["0006-profile-samples"],
+            "route": "/v1/profiles",
+            "sdks": {}
+        },
+        {
+            "id": "source_maps",
+            "title": "Source map upload",
+            "ingester": "1.3.2",
+            "migrations": ["0007-source-maps"],
+            "route": "/v1/sourcemaps",
+            "sdks": {}
+        },
+        {
+            "id": "memory_metrics",
+            "title": "Memory pressure detection",
+            "ingester": "1.3.3",
+            "migrations": ["0008-memory-signals", "0010-memory-temporality"],
+            "sdks": { "@autter/runtime-node": "1.3.3", "@autter/runtime-next": "1.3.3" }
+        },
+        {
+            "id": "platform_events",
+            "title": "Platform OOM/restart events",
+            "ingester": "1.3.3",
+            "migrations": ["0008-memory-signals"],
+            "route": "/v1/platform-events",
+            "sdks": {}
+        },
+        {
+            "id": "csp_violations",
+            "title": "Browser CSP violation capture",
+            "ingester": "1.3.4",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.3.3", "@autter/runtime-next": "1.3.4" },
+            "browserEvents": ["csp_violation"]
+        },
+        {
+            "id": "operation_logging",
+            "title": "Operation logging",
+            "ingester": "1.4.0",
+            "migrations": ["0011-runtime-logs"],
+            "route": "/v1/logs",
+            "sdks": { "@autter/runtime-node": "1.4.0", "@autter/runtime-next": "1.4.0" }
+        },
+        {
+            "id": "request_summaries",
+            "title": "Request summaries and the per-route request rollup",
+            "ingester": "1.5.0",
+            "migrations": ["0012-runtime-logs-requests", "0014-runtime-request-1m"],
+            "route": "/v1/logs",
+            "sdks": { "@autter/runtime-node": "1.5.0", "@autter/runtime-next": "1.5.0", "@autter/runtime-edge": "1.0.0" }
+        },
+        {
+            "id": "coded_errors",
+            "title": "Coded errors and code-based grouping",
+            "ingester": "1.5.0",
+            "migrations": ["0013-occurrence-codes"],
+            "sdks": { "@autter/runtime-node": "1.5.0", "@autter/runtime-next": "1.5.0", "@autter/runtime-browser": "1.4.0", "@autter/runtime-edge": "1.0.0" }
+        }
+    ]
+}

package/dist/compat.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Version compatibility between Autter Runtime SDKs, this ingester and its
+ * ClickHouse schema — the single source of truth.
+ *
+ * `compat-manifest.json` lists every feature that needs a minimum ingester
+ * version, a ClickHouse migration, a dedicated ingest route, or a minimum SDK
+ * version. Everything else derives from it:
+ *
+ * - the ingester serves it (evaluated against its own version and applied
+ *   migrations) at `GET /v1/compat`;
+ * - `@autter/runtime-node` / `@autter/runtime-next` bundle this file at build
+ *   time to warn once when an enabled feature needs a newer ingester, and to
+ *   power `npx @autter/runtime-node doctor`;
+ * - the Python adapter (`adapters/python/compat.py`) embeds a copy that a
+ *   parity test keeps identical.
+ *
+ * This module is dependency-free and side-effect-free on purpose: it is
+ * bundled into the Node SDK. Keep it that way.
+ *
+ * Adding a feature: append an entry to compat-manifest.json with the first
+ * ingester release that handles it, the migrations it writes to, its route
+ * (if it has its own), and the first SDK release that emits it. The
+ * consistency test in compat.test.ts checks ids, migrations and routes.
+ */
+export interface CompatFeature {
+    id: string;
+    title: string;
+    /** First ingester release that stores this feature correctly. */
+    ingester: string;
+    /** ClickHouse migrations (migrations.ts ids) the feature writes to. */
+    migrations: string[];
+    /** Dedicated ingest route, when the feature has one. */
+    route?: string;
+    /** First release of each SDK package that emits the feature. */
+    sdks: Record<string, string>;
+    /** Browser payload event types that belong to this feature. */
+    browserEvents?: string[];
+}
+export interface CompatManifest {
+    manifestVersion: number;
+    docs: string;
+    upgrade: {
+        ingester: string;
+        sdk: string;
+    };
+    features: CompatFeature[];
+}
+export declare const COMPAT_MANIFEST: CompatManifest;
+export declare const INGESTER_PACKAGE = "@autter/otlp-ingester";
+/** Response header carrying the ingester version on every ingest response. */
+export declare const INGESTER_VERSION_HEADER = "x-autter-ingester-version";
+/** Semver-ish comparison; null when either side is unparsable. */
+export declare function compareVersions(a: string, b: string): number | null;
+/** True/false when comparable, null when the version is unknown/unparsable. */
+export declare function versionAtLeast(version: string | null | undefined, minimum: string): boolean | null;
+export type SchemaStatus = "ready" | "pending" | "failed" | "unconfigured";
+/** What is known about the ingester an SDK talks to. */
+export interface IngesterCompatInfo {
+    /** Exact version, or null when the ingester predates /v1/compat. */
+    version: string | null;
+    /** True when /v1/compat returned 404 (ingester 1.4.0 or older). */
+    legacy?: boolean;
+    schema?: {
+        status: SchemaStatus;
+        applied: string[];
+    };
+    /** Legacy ingesters: route → exists, learned by probing. */
+    routes?: Record<string, boolean>;
+}
+export type CompatIssueKind = "ingester_too_old" | "schema_not_applied" | "sdk_too_old";
+export interface CompatIssue {
+    feature: string;
+    title: string;
+    kind: CompatIssueKind;
+    /** Package that must change: the ingester or an SDK package name. */
+    component: string;
+    required: string;
+    /** What was found ("1.3.4", "1.4.0 or older", …). */
+    actual: string;
+    /** One line: what is wrong, versions, and the fix. */
+    message: string;
+    fix: string;
+}
+export interface SdkIdentity {
+    name: string;
+    version: string;
+}
+export declare function featureById(id: string, manifest?: CompatManifest): CompatFeature | undefined;
+/** Features the given browser payload event types belong to. */
+export declare function featuresForBrowserEvents(types: Iterable<string>, manifest?: CompatManifest): string[];
+export declare function ingesterUpgradeHint(manifest?: CompatManifest): string;
+/**
+ * Every incompatibility for the features in use. Unknown is never an issue:
+ * when the ingester version can't be determined (and a legacy route probe
+ * didn't prove a route missing) nothing is reported, so the check has no
+ * false positives.
+ */
+export declare function evaluateCompat(input: {
+    features: Iterable<string>;
+    ingester: IngesterCompatInfo | null;
+    sdk?: SdkIdentity | null;
+    manifest?: CompatManifest;
+}): CompatIssue[];
+export interface CompatFeatureStatus {
+    id: string;
+    title: string;
+    ingester: string;
+    migrations: string[];
+    route?: string;
+    sdks: Record<string, string>;
+    browserEvents?: string[];
+    /** This ingester's version is new enough. */
+    ingesterSupported: boolean;
+    /** Migrations the feature needs that are not applied yet. */
+    missingMigrations: string[];
+    /** Ingester new enough AND schema ready with every migration applied. */
+    available: boolean;
+}
+export interface CompatReport {
+    ingester: {
+        name: string;
+        version: string;
+    };
+    schema: {
+        status: SchemaStatus;
+        /** Highest applied migration id ("" when none known). */
+        level: string;
+        /** Highest migration this ingester ships. */
+        latest: string;
+        applied: string[];
+    };
+    features: CompatFeatureStatus[];
+    manifestVersion: number;
+    docs: string;
+    upgrade: CompatManifest["upgrade"];
+    /** Present when the request named features (and optionally an SDK). */
+    issues?: CompatIssue[];
+}
+export declare function buildCompatReport(input: {
+    version: string;
+    schemaStatus: SchemaStatus;
+    applied: string[];
+    allMigrations: string[];
+    manifest?: CompatManifest;
+}): CompatReport;
+/** IngesterCompatInfo from a /v1/compat response body (defensive: it's network input). */
+export declare function ingesterInfoFromReport(body: unknown): IngesterCompatInfo | null;