@autter/runtime-node 1.9.0 → 1.10.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier, I as IgnoreErrorPattern, i as CaptureLoggedErrorsOption, B as BreadcrumbInput } from './sinks-CLtQFPnn.cjs';
-export { j as Breadcrumb, k as BreadcrumbLevel, l as BreadcrumbType, n as CODE_PATTERN, o as ClientErrorBody, p as ConsoleSinkOptions, L as LoggedErrorSource, O as OtlpSinkOptions, q as RuntimeError, r as RuntimeErrorCatalog, s as RuntimeErrorDefinition, t as RuntimeErrorExtras, u as RuntimeErrorFactory, v as RuntimeErrorLike, w as RuntimeErrorOptions, R as RuntimeEvent, x as RuntimeLogContextValue, y as RuntimeSinkContext, z as consoleSink, A as defineRuntimeErrors, D as errorAttributes, E as fileSink, G as isRuntimeErrorLike, H as otlpSink, J as redactAttributes, K as redactText, N as toClientError } from './sinks-CLtQFPnn.cjs';
+import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier, I as IgnoreErrorPattern, i as CaptureLoggedErrorsOption, B as BreadcrumbInput } from './sinks-BfUoE96B.cjs';
+export { j as Breadcrumb, k as BreadcrumbLevel, l as BreadcrumbType, n as CODE_PATTERN, o as ClientErrorBody, p as ConsoleSinkOptions, L as LoggedErrorSource, O as OtlpSinkOptions, q as RuntimeError, r as RuntimeErrorCatalog, s as RuntimeErrorDefinition, t as RuntimeErrorExtras, u as RuntimeErrorFactory, v as RuntimeErrorLike, w as RuntimeErrorOptions, R as RuntimeEvent, x as RuntimeLogContextValue, y as RuntimeSinkContext, z as consoleSink, A as defineRuntimeErrors, D as errorAttributes, E as fileSink, G as isRuntimeErrorLike, H as otlpSink, J as redactAttributes, K as redactText, N as toClientError } from './sinks-BfUoE96B.cjs';
 import { Attributes } from '@opentelemetry/api';
 
 /**
@@ -11,8 +11,12 @@ import { Attributes } from '@opentelemetry/api';
  * the browser, and there is no CORS/CSP surface.
  */
 interface RelayOptions {
-    /** Private ingest key (autter_rt_…). Keep it in an env var. */
-    apiKey: string;
+    /**
+     * Private ingest key (autter_rt_…). Keep it in an env var. Default:
+     * AUTTER_RUNTIME_KEY. Without one the relay answers 500 and warns once
+     * at startup, instead of forwarding with "Bearer undefined".
+     */
+    apiKey?: string;
     /** Ingester base URL. Default: https://otlp.autter.dev */
     endpoint?: string;
     /** Max accepted request body. Default 64 KB. */
@@ -75,6 +79,22 @@ interface RelayOptions {
     compatCheck?: boolean;
 }
 declare function sanitizeBrowserPayload(raw: unknown, redactor?: Redactor$1): object | null;
+/** Why a browser payload was refused: the field and what was wrong. Same
+ * shape as the ingester's `issues` (a path into the payload, a message). */
+interface RelayPayloadIssue {
+    path: Array<string | number>;
+    message: string;
+}
+/**
+ * Validate and sanitise a browser payload. On failure, the first few
+ * problems with their field paths (`["events", 3, "type"]`), so a 400 from
+ * the relay says what to fix instead of only "invalid payload".
+ */
+declare function checkBrowserPayload(raw: unknown, redactor?: Redactor$1): {
+    payload: object;
+} | {
+    issues: RelayPayloadIssue[];
+};
 /**
  * Fetch-style handler (Next.js App Router route, Remix, Hono, Bun, Deno):
  *
@@ -259,8 +279,11 @@ type RuntimeContextHandle = typeof runtimeContext;
 interface AutterServerOptions {
     /** Structured logs and completed operation summaries. */
     logging?: RuntimeLoggingOptions;
-    /** Private ingest key (autter_rt_…). */
-    apiKey: string;
+    /**
+     * Private ingest key (autter_rt_…). Default: AUTTER_RUNTIME_KEY. Without
+     * one nothing is sent and one warning says so at startup.
+     */
+    apiKey?: string;
     /** Ingester base URL. Default: https://otlp.autter.dev */
     endpoint?: string;
     service: string;
@@ -337,6 +360,18 @@ interface AutterServerOptions {
      * crashes the process. Default true.
      */
     captureUnhandledRejections?: boolean;
+    /**
+     * Express (4 and 5): report the error behind a 5xx response with no
+     * setup. Every error a handler throws, rejects with (Express 5) or passes
+     * to `next(err)`, in any router, is noted on its request; when the
+     * response ends with a 5xx, the error is recorded on the request span
+     * with its type, message and stack, once (an error `autterErrorHandler`
+     * or `captureException` already reported is skipped). Errors answered
+     * with a 4xx are not reported here. Express's own behaviour is
+     * unchanged. Default true; false leaves Express errors to
+     * `autterErrorHandler()`.
+     */
+    captureExpressErrors?: boolean;
     /**
      * Flush all exporters when the process exits (`beforeExit`, SIGINT,
      * SIGTERM) so a forgotten `shutdown()` doesn't silently drop buffered
@@ -1021,11 +1056,42 @@ declare function fetchIngesterCompat(endpoint: string, options?: {
 }>;
 
 /**
- * `npx @autter/runtime-node doctor` — one-shot version compatibility report:
- * installed Autter SDK versions, the ingester's version and ClickHouse schema
- * level, the ingest key (optional), and every feature the installed SDKs can
- * use that the ingester can't store. Exit codes: 0 compatible, 1 a mismatch
- * or rejected key, 2 the ingester could not be reached or identified.
+ * Where the path to an ingester breaks: DNS, TCP, TLS or HTTP. Used by
+ * `doctor` when the ingester can't be reached and as the first step of
+ * `verify`. "Timed out" alone (what an exporter reports) can mean a
+ * firewall dropping packets, an IPv6 route that goes nowhere, a proxy
+ * that is required but not used, or TLS interception; each step below
+ * narrows it to one.
+ */
+type ConnectivityStepName = "dns" | "tcp" | "tls" | "http";
+interface ConnectivityStep {
+    step: ConnectivityStepName;
+    ok: boolean;
+    ms: number;
+    detail: string;
+}
+interface ConnectivityReport {
+    ok: boolean;
+    host: string;
+    port: number;
+    steps: ConnectivityStep[];
+    /** The first failed step, with what to try. */
+    failed?: {
+        step: ConnectivityStepName;
+        detail: string;
+        hint: string;
+    };
+}
+
+/**
+ * `npx @autter/runtime-node doctor` — one-shot setup report: installed
+ * Autter SDK versions against the ingester's (version skew), which features
+ * are active, whether the ingester can store anything right now (`/healthz`),
+ * and the ingest key ("not checked" when none is given). When the ingester
+ * can't be reached it says where the path breaks (DNS, TCP, TLS, HTTP).
+ * Exit codes: 0 everything checked is fine, 1 a mismatch, rejected key or
+ * unready storage, 2 the ingester could not be reached or identified.
+ * `verify` goes further: it sends a test event and reads it back.
  */
 interface DoctorOptions {
     endpoint?: string;
@@ -1040,17 +1106,92 @@ interface DoctorReport {
     sdks: SdkIdentity[];
     ingester: IngesterCompatInfo | null;
     ingesterError?: string;
-    key?: "accepted" | "rejected" | "client_key" | "storage_unavailable" | "unknown";
+    /** Always set: "not_checked" when no key was given. */
+    key: "accepted" | "rejected" | "client_key" | "storage_unavailable" | "unverified" | "unknown" | "not_checked";
+    /** The ingester's reason when it refused the key. */
+    keyDetail?: string;
+    /** `/healthz`: can the ingester store what it is sent right now? */
+    storage: StorageReport | null;
+    /** "ok" = active: the SDK sends it and the ingester stores it. */
     features: Array<{
         id: string;
         title: string;
         status: "ok" | "incompatible" | "unknown";
     }>;
+    /** Each SDK against the ingester: who is behind, and on what. */
+    skew: SkewLine[];
     issues: CompatIssue[];
+    /** Only when the ingester could not be reached. */
+    connectivity?: ConnectivityReport;
     exitCode: 0 | 1 | 2;
 }
+interface StorageReport {
+    /** up | down | auth_failed | schema_missing | unconfigured | unknown */
+    state: string;
+    ok: boolean;
+    /** False for ingesters before 1.12, whose /healthz only pinged ClickHouse. */
+    writeChecked: boolean;
+    detail: string;
+}
+interface SkewLine {
+    sdk: string;
+    version: string;
+    /** "in_sync", "ingester_behind" (features it can't store), "sdk_behind" (features it doesn't send yet). */
+    status: "in_sync" | "ingester_behind" | "sdk_behind" | "unknown";
+    detail: string;
+}
 declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
 
+/**
+ * `npx @autter/runtime-node verify` — send one tagged test event through the
+ * real path and read it back, step by step, stopping at the first step
+ * that fails and naming it:
+ *
+ *   key → network → ingester → storage → auth → ingest → stored → trace → release → logs
+ *
+ * The test request carries `autter.verify.id` on its resource, so the
+ * ingester stores it (that is what is checked) but never rolls it up or
+ * forwards it to the sink: it never opens an issue or moves a dashboard.
+ * Against an ingester without `/v1/verify` (older than this feature) only
+ * a plain span is sent, and "stored" is reported as not checked.
+ *
+ * Exit codes: 0 every check passed, 1 a step failed, 2 the ingester could
+ * not be reached.
+ */
+type VerifyStepName = "key" | "network" | "ingester" | "storage" | "auth" | "ingest" | "stored" | "trace" | "release" | "logs";
+interface VerifyStep {
+    step: VerifyStepName;
+    status: "pass" | "fail" | "warn" | "skip";
+    detail: string;
+    /** On failure: what to do. */
+    fix?: string;
+}
+interface VerifyReport {
+    endpoint: string;
+    service: string;
+    environment: string;
+    release: string | null;
+    traceId: string;
+    steps: VerifyStep[];
+    firstFailure: VerifyStep | null;
+    exitCode: 0 | 1 | 2;
+}
+interface VerifyOptions {
+    endpoint?: string;
+    key?: string;
+    service?: string;
+    environment?: string;
+    release?: string;
+    /** How long to wait for the test event to be stored. Default 20 s. */
+    waitMs?: number;
+    timeoutMs?: number;
+    json?: boolean;
+    cwd?: string;
+    /** Test hook: the poll interval. */
+    pollMs?: number;
+}
+declare function runVerify(options?: VerifyOptions, env?: NodeJS.ProcessEnv): Promise<VerifyReport>;
+
 /**
  * Record a step (type "custom" unless you say otherwise) on the current
  * request. The next exception captured in it carries the last 30. Message
@@ -1060,4 +1201,4 @@ declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
  */
 declare function addBreadcrumb(input: BreadcrumbInput): void;
 
-export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, CaptureLoggedErrorsOption, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, type UnhandledRejectionsMode, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureException, captureMessage, captureRequestError, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, unhandledRejectionsMode, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, CaptureLoggedErrorsOption, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, type RelayPayloadIssue, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, type UnhandledRejectionsMode, type VerifyOptions, type VerifyReport, type VerifyStep, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureException, captureMessage, captureRequestError, checkBrowserPayload, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runVerify, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, unhandledRejectionsMode, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier, I as IgnoreErrorPattern, i as CaptureLoggedErrorsOption, B as BreadcrumbInput } from './sinks-CLtQFPnn.js';
-export { j as Breadcrumb, k as BreadcrumbLevel, l as BreadcrumbType, n as CODE_PATTERN, o as ClientErrorBody, p as ConsoleSinkOptions, L as LoggedErrorSource, O as OtlpSinkOptions, q as RuntimeError, r as RuntimeErrorCatalog, s as RuntimeErrorDefinition, t as RuntimeErrorExtras, u as RuntimeErrorFactory, v as RuntimeErrorLike, w as RuntimeErrorOptions, R as RuntimeEvent, x as RuntimeLogContextValue, y as RuntimeSinkContext, z as consoleSink, A as defineRuntimeErrors, D as errorAttributes, E as fileSink, G as isRuntimeErrorLike, H as otlpSink, J as redactAttributes, K as redactText, N as toClientError } from './sinks-CLtQFPnn.js';
+import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier, I as IgnoreErrorPattern, i as CaptureLoggedErrorsOption, B as BreadcrumbInput } from './sinks-BfUoE96B.js';
+export { j as Breadcrumb, k as BreadcrumbLevel, l as BreadcrumbType, n as CODE_PATTERN, o as ClientErrorBody, p as ConsoleSinkOptions, L as LoggedErrorSource, O as OtlpSinkOptions, q as RuntimeError, r as RuntimeErrorCatalog, s as RuntimeErrorDefinition, t as RuntimeErrorExtras, u as RuntimeErrorFactory, v as RuntimeErrorLike, w as RuntimeErrorOptions, R as RuntimeEvent, x as RuntimeLogContextValue, y as RuntimeSinkContext, z as consoleSink, A as defineRuntimeErrors, D as errorAttributes, E as fileSink, G as isRuntimeErrorLike, H as otlpSink, J as redactAttributes, K as redactText, N as toClientError } from './sinks-BfUoE96B.js';
 import { Attributes } from '@opentelemetry/api';
 
 /**
@@ -11,8 +11,12 @@ import { Attributes } from '@opentelemetry/api';
  * the browser, and there is no CORS/CSP surface.
  */
 interface RelayOptions {
-    /** Private ingest key (autter_rt_…). Keep it in an env var. */
-    apiKey: string;
+    /**
+     * Private ingest key (autter_rt_…). Keep it in an env var. Default:
+     * AUTTER_RUNTIME_KEY. Without one the relay answers 500 and warns once
+     * at startup, instead of forwarding with "Bearer undefined".
+     */
+    apiKey?: string;
     /** Ingester base URL. Default: https://otlp.autter.dev */
     endpoint?: string;
     /** Max accepted request body. Default 64 KB. */
@@ -75,6 +79,22 @@ interface RelayOptions {
     compatCheck?: boolean;
 }
 declare function sanitizeBrowserPayload(raw: unknown, redactor?: Redactor$1): object | null;
+/** Why a browser payload was refused: the field and what was wrong. Same
+ * shape as the ingester's `issues` (a path into the payload, a message). */
+interface RelayPayloadIssue {
+    path: Array<string | number>;
+    message: string;
+}
+/**
+ * Validate and sanitise a browser payload. On failure, the first few
+ * problems with their field paths (`["events", 3, "type"]`), so a 400 from
+ * the relay says what to fix instead of only "invalid payload".
+ */
+declare function checkBrowserPayload(raw: unknown, redactor?: Redactor$1): {
+    payload: object;
+} | {
+    issues: RelayPayloadIssue[];
+};
 /**
  * Fetch-style handler (Next.js App Router route, Remix, Hono, Bun, Deno):
  *
@@ -259,8 +279,11 @@ type RuntimeContextHandle = typeof runtimeContext;
 interface AutterServerOptions {
     /** Structured logs and completed operation summaries. */
     logging?: RuntimeLoggingOptions;
-    /** Private ingest key (autter_rt_…). */
-    apiKey: string;
+    /**
+     * Private ingest key (autter_rt_…). Default: AUTTER_RUNTIME_KEY. Without
+     * one nothing is sent and one warning says so at startup.
+     */
+    apiKey?: string;
     /** Ingester base URL. Default: https://otlp.autter.dev */
     endpoint?: string;
     service: string;
@@ -337,6 +360,18 @@ interface AutterServerOptions {
      * crashes the process. Default true.
      */
     captureUnhandledRejections?: boolean;
+    /**
+     * Express (4 and 5): report the error behind a 5xx response with no
+     * setup. Every error a handler throws, rejects with (Express 5) or passes
+     * to `next(err)`, in any router, is noted on its request; when the
+     * response ends with a 5xx, the error is recorded on the request span
+     * with its type, message and stack, once (an error `autterErrorHandler`
+     * or `captureException` already reported is skipped). Errors answered
+     * with a 4xx are not reported here. Express's own behaviour is
+     * unchanged. Default true; false leaves Express errors to
+     * `autterErrorHandler()`.
+     */
+    captureExpressErrors?: boolean;
     /**
      * Flush all exporters when the process exits (`beforeExit`, SIGINT,
      * SIGTERM) so a forgotten `shutdown()` doesn't silently drop buffered
@@ -1021,11 +1056,42 @@ declare function fetchIngesterCompat(endpoint: string, options?: {
 }>;
 
 /**
- * `npx @autter/runtime-node doctor` — one-shot version compatibility report:
- * installed Autter SDK versions, the ingester's version and ClickHouse schema
- * level, the ingest key (optional), and every feature the installed SDKs can
- * use that the ingester can't store. Exit codes: 0 compatible, 1 a mismatch
- * or rejected key, 2 the ingester could not be reached or identified.
+ * Where the path to an ingester breaks: DNS, TCP, TLS or HTTP. Used by
+ * `doctor` when the ingester can't be reached and as the first step of
+ * `verify`. "Timed out" alone (what an exporter reports) can mean a
+ * firewall dropping packets, an IPv6 route that goes nowhere, a proxy
+ * that is required but not used, or TLS interception; each step below
+ * narrows it to one.
+ */
+type ConnectivityStepName = "dns" | "tcp" | "tls" | "http";
+interface ConnectivityStep {
+    step: ConnectivityStepName;
+    ok: boolean;
+    ms: number;
+    detail: string;
+}
+interface ConnectivityReport {
+    ok: boolean;
+    host: string;
+    port: number;
+    steps: ConnectivityStep[];
+    /** The first failed step, with what to try. */
+    failed?: {
+        step: ConnectivityStepName;
+        detail: string;
+        hint: string;
+    };
+}
+
+/**
+ * `npx @autter/runtime-node doctor` — one-shot setup report: installed
+ * Autter SDK versions against the ingester's (version skew), which features
+ * are active, whether the ingester can store anything right now (`/healthz`),
+ * and the ingest key ("not checked" when none is given). When the ingester
+ * can't be reached it says where the path breaks (DNS, TCP, TLS, HTTP).
+ * Exit codes: 0 everything checked is fine, 1 a mismatch, rejected key or
+ * unready storage, 2 the ingester could not be reached or identified.
+ * `verify` goes further: it sends a test event and reads it back.
  */
 interface DoctorOptions {
     endpoint?: string;
@@ -1040,17 +1106,92 @@ interface DoctorReport {
     sdks: SdkIdentity[];
     ingester: IngesterCompatInfo | null;
     ingesterError?: string;
-    key?: "accepted" | "rejected" | "client_key" | "storage_unavailable" | "unknown";
+    /** Always set: "not_checked" when no key was given. */
+    key: "accepted" | "rejected" | "client_key" | "storage_unavailable" | "unverified" | "unknown" | "not_checked";
+    /** The ingester's reason when it refused the key. */
+    keyDetail?: string;
+    /** `/healthz`: can the ingester store what it is sent right now? */
+    storage: StorageReport | null;
+    /** "ok" = active: the SDK sends it and the ingester stores it. */
     features: Array<{
         id: string;
         title: string;
         status: "ok" | "incompatible" | "unknown";
     }>;
+    /** Each SDK against the ingester: who is behind, and on what. */
+    skew: SkewLine[];
     issues: CompatIssue[];
+    /** Only when the ingester could not be reached. */
+    connectivity?: ConnectivityReport;
     exitCode: 0 | 1 | 2;
 }
+interface StorageReport {
+    /** up | down | auth_failed | schema_missing | unconfigured | unknown */
+    state: string;
+    ok: boolean;
+    /** False for ingesters before 1.12, whose /healthz only pinged ClickHouse. */
+    writeChecked: boolean;
+    detail: string;
+}
+interface SkewLine {
+    sdk: string;
+    version: string;
+    /** "in_sync", "ingester_behind" (features it can't store), "sdk_behind" (features it doesn't send yet). */
+    status: "in_sync" | "ingester_behind" | "sdk_behind" | "unknown";
+    detail: string;
+}
 declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
 
+/**
+ * `npx @autter/runtime-node verify` — send one tagged test event through the
+ * real path and read it back, step by step, stopping at the first step
+ * that fails and naming it:
+ *
+ *   key → network → ingester → storage → auth → ingest → stored → trace → release → logs
+ *
+ * The test request carries `autter.verify.id` on its resource, so the
+ * ingester stores it (that is what is checked) but never rolls it up or
+ * forwards it to the sink: it never opens an issue or moves a dashboard.
+ * Against an ingester without `/v1/verify` (older than this feature) only
+ * a plain span is sent, and "stored" is reported as not checked.
+ *
+ * Exit codes: 0 every check passed, 1 a step failed, 2 the ingester could
+ * not be reached.
+ */
+type VerifyStepName = "key" | "network" | "ingester" | "storage" | "auth" | "ingest" | "stored" | "trace" | "release" | "logs";
+interface VerifyStep {
+    step: VerifyStepName;
+    status: "pass" | "fail" | "warn" | "skip";
+    detail: string;
+    /** On failure: what to do. */
+    fix?: string;
+}
+interface VerifyReport {
+    endpoint: string;
+    service: string;
+    environment: string;
+    release: string | null;
+    traceId: string;
+    steps: VerifyStep[];
+    firstFailure: VerifyStep | null;
+    exitCode: 0 | 1 | 2;
+}
+interface VerifyOptions {
+    endpoint?: string;
+    key?: string;
+    service?: string;
+    environment?: string;
+    release?: string;
+    /** How long to wait for the test event to be stored. Default 20 s. */
+    waitMs?: number;
+    timeoutMs?: number;
+    json?: boolean;
+    cwd?: string;
+    /** Test hook: the poll interval. */
+    pollMs?: number;
+}
+declare function runVerify(options?: VerifyOptions, env?: NodeJS.ProcessEnv): Promise<VerifyReport>;
+
 /**
  * Record a step (type "custom" unless you say otherwise) on the current
  * request. The next exception captured in it carries the last 30. Message
@@ -1060,4 +1201,4 @@ declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
  */
 declare function addBreadcrumb(input: BreadcrumbInput): void;
 
-export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, CaptureLoggedErrorsOption, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, type UnhandledRejectionsMode, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureException, captureMessage, captureRequestError, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, unhandledRejectionsMode, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, CaptureLoggedErrorsOption, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, type RelayPayloadIssue, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, type UnhandledRejectionsMode, type VerifyOptions, type VerifyReport, type VerifyStep, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureException, captureMessage, captureRequestError, checkBrowserPayload, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runVerify, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, unhandledRejectionsMode, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };