effect-inspect 0.1.1 → 0.2.0

package/dist/query/Query.d.ts

@@ -0,0 +1,599 @@
+/**
+ * Headless, read-only trace queries with one contract for every source.
+ *
+ * A {@link TraceSource} is a frozen session: a collector snapshot or a saved
+ * `.eitrace`. Both are the same protocol message stream, so both are analysed
+ * by the same code — the browser's {@link TraceStore} reconstruction and
+ * {@link timings} math — and a snapshot queried live answers exactly as its
+ * exported file does.
+ *
+ * Every answer is JSON, bounded in size, names its source and time reference,
+ * and says what it cannot vouch for: a response never presents partial or
+ * conflicting evidence as a complete, unambiguous run. Requests and responses
+ * are plain data so the CLI can print them and the collector can serve them.
+ *
+ * Timing is observation, not diagnosis. `durationMs` is elapsed time between a
+ * span's recorded start and end; `outsideChildrenMs` is the part of it not
+ * covered by any recorded direct child. Neither is CPU time, and neither says
+ * an operation is slow, stuck or under-instrumented on its own.
+ */
+import { Result, Schema } from 'effect';
+import type * as Protocol from '../protocol/Schema.ts';
+/** Version of this request/response contract. Bumped on a breaking change. */
+export declare const apiVersion = 1;
+/** Defaults and caps for every bounded part of a response. */
+export declare const limits: {
+    /** `sessions` page size. */
+    readonly sessions: {
+        readonly default: 50;
+        readonly max: 500;
+    };
+    /** `spans` page size. */
+    readonly spans: {
+        readonly default: 20;
+        readonly max: 200;
+    };
+    /** `logs` page size. */
+    readonly logs: {
+        readonly default: 50;
+        readonly max: 500;
+    };
+    /** Items per ranked list in `summary`. */
+    readonly top: {
+        readonly default: 5;
+        readonly max: 50;
+    };
+    /** Children listed by `span`. */
+    readonly children: {
+        readonly default: 20;
+        readonly max: 200;
+    };
+    /** Span events listed by `span`. */
+    readonly events: {
+        readonly default: 20;
+        readonly max: 200;
+    };
+    /** Nearest ancestors listed by `span`. */
+    readonly ancestry: 32;
+    /** Attribute/annotation keys kept per object; the rest are counted, not sent. */
+    readonly attributeKeys: 32;
+    /** Characters of one JSON-encoded attribute value before it is cut. */
+    readonly valueChars: 500;
+    /** Characters of a failure message. */
+    readonly errorChars: 500;
+    /** Characters of a failure stack. */
+    readonly stackChars: 4000;
+    /** Characters of a log message. */
+    readonly logMessageChars: 2000;
+    /** Characters of a span, event or group name, a log's span name, or a program/runtime. */
+    readonly nameChars: 200;
+    /** Characters of one attribute or annotation key. */
+    readonly keyChars: 100;
+    /** Characters of an error `message`. */
+    readonly errorMessageChars: 1000;
+    /** Longest `sessionId`, `spanId` or `name` a request may carry. */
+    readonly requestTextChars: 1024;
+    /**
+     * UTF-8 bytes of a whole serialized JSON response, envelope included. A
+     * response that would be larger is replaced by `ResponseTooLarge`.
+     * Identifiers are never shortened to fit. `.eitrace` export is a lossless
+     * artifact transfer, not a query response, and is not held to this.
+     */
+    readonly responseBytes: 1048576;
+};
+/**
+ * Loss counters the collector keeps for a session. Mirrors
+ * {@link Protocol.TraceCapture}; `undefined` on a source means unknown.
+ */
+export type Capture = Protocol.TraceCapture;
+/** One frozen session, from the collector or from a file. */
+export interface TraceSource {
+    readonly kind: 'live' | 'file';
+    /** Path (or label) of the file, for `kind: 'file'`. */
+    readonly file?: string | undefined;
+    readonly session: Protocol.Session;
+    /** Retained protocol messages in arrival order. */
+    readonly messages: ReadonlyArray<Protocol.ClientMessage>;
+    /** Collector loss counters, or `undefined` when the source never recorded them. */
+    readonly capture: Capture | undefined;
+    /** Undecodable trailing file lines; 0 for live sources. */
+    readonly truncatedLines: number;
+    /** When the snapshot was taken (live) or the file saved, epoch millis. */
+    readonly snapshotAtEpochMillis: number;
+}
+/** A live source from a collector `Store` snapshot taken at `now`. */
+export declare const fromSnapshot: (snapshot: {
+    readonly session: Protocol.Session;
+    readonly messages: ReadonlyArray<Protocol.ClientMessage>;
+    readonly droppedMessages: number;
+    readonly skippedLines: number;
+    readonly conflictDetection: boolean;
+}, now: number) => TraceSource;
+/**
+ * Trace-file text for a source, with its loss counters in the header so a
+ * query against the file reports the same completeness as the snapshot.
+ */
+export declare const toTraceFile: (source: TraceSource) => string;
+/** Parses trace-file text into a file source, or the `TraceFileError` response. */
+export declare const fromTraceFile: (text: string, file: string) => Result.Result<TraceSource, QueryFailure>;
+/** Span status values a span can have. */
+export declare const spanStatuses: readonly ['ok', 'error', 'defect', 'interrupted', 'open'];
+export type SpanStatus = (typeof spanStatuses)[number];
+/** `spans` status filter: a {@link SpanStatus}, `failed` (any failure) or `any`. */
+export declare const StatusFilter: Schema.Literals<readonly ["any", "failed", "ok", "error", "defect", "interrupted", "open"]>;
+export type StatusFilter = Schema.Schema.Type<typeof StatusFilter>;
+export declare const SpanSort: Schema.Literals<readonly ["start", "duration", "outsideChildren"]>;
+export type SpanSort = Schema.Schema.Type<typeof SpanSort>;
+/** Log levels a `minLevel` filter accepts, least severe first. */
+export declare const logLevels: readonly ['Trace', 'Debug', 'Info', 'Warn', 'Error', 'Fatal'];
+export declare const MinLevel: Schema.Literals<readonly ["Trace", "Debug", "Info", "Warn", "Error", "Fatal"]>;
+export declare const LogScope: Schema.Literals<readonly ["span", "subtree"]>;
+/** Lists sessions. Live: every session the collector holds. File: the file's one session. */
+export declare const SessionsRequest: Schema.Struct<{
+    readonly op: Schema.Literal<"sessions">;
+    readonly limit: Schema.optional<Schema.Int>;
+    readonly offset: Schema.optional<Schema.Natural>;
+}>;
+/** Counts, failures and ranked timings for one session. */
+export declare const SummaryRequest: Schema.Struct<{
+    readonly op: Schema.Literal<"summary">;
+    readonly sessionId: Schema.optional<Schema.String>;
+    readonly top: Schema.optional<Schema.Int>;
+}>;
+/** A filtered, sorted page of spans. */
+export declare const SpansRequest: Schema.Struct<{
+    readonly op: Schema.Literal<"spans">;
+    readonly sessionId: Schema.optional<Schema.String>;
+    readonly status: Schema.optional<Schema.Literals<readonly ["any", "failed", "ok", "error", "defect", "interrupted", "open"]>>;
+    /** Case-insensitive substring of the span name. */
+    readonly name: Schema.optional<Schema.String>;
+    /** Only spans whose duration (or, while open, elapsed lower bound) is at least this. */
+    readonly minDurationMs: Schema.optional<Schema.Finite>;
+    /** Only spans overlapping `[fromMs, toMs]`. Timings are not clipped to it. */
+    readonly fromMs: Schema.optional<Schema.Finite>;
+    readonly toMs: Schema.optional<Schema.Finite>;
+    readonly sort: Schema.optional<Schema.Literals<readonly ["start", "duration", "outsideChildren"]>>;
+    readonly limit: Schema.optional<Schema.Int>;
+    readonly offset: Schema.optional<Schema.Natural>;
+}>;
+/** One span with bounded ancestry, children, events and attributes. */
+export declare const SpanRequest: Schema.Struct<{
+    readonly op: Schema.Literal<"span">;
+    readonly sessionId: Schema.optional<Schema.String>;
+    readonly spanId: Schema.String;
+    readonly children: Schema.optional<Schema.Int>;
+    readonly events: Schema.optional<Schema.Int>;
+}>;
+/** A page of logs, optionally correlated with a span. */
+export declare const LogsRequest: Schema.Struct<{
+    readonly op: Schema.Literal<"logs">;
+    readonly sessionId: Schema.optional<Schema.String>;
+    readonly spanId: Schema.optional<Schema.String>;
+    /** Requires `spanId`: that span's own logs, or its whole subtree's (default). */
+    readonly scope: Schema.optional<Schema.Literals<readonly ["span", "subtree"]>>;
+    readonly minLevel: Schema.optional<Schema.Literals<readonly ["Trace", "Debug", "Info", "Warn", "Error", "Fatal"]>>;
+    readonly fromMs: Schema.optional<Schema.Finite>;
+    readonly toMs: Schema.optional<Schema.Finite>;
+    readonly limit: Schema.optional<Schema.Int>;
+    readonly offset: Schema.optional<Schema.Natural>;
+}>;
+export declare const QueryRequest: Schema.Union<readonly [Schema.Struct<{
+    readonly op: Schema.Literal<"sessions">;
+    readonly limit: Schema.optional<Schema.Int>;
+    readonly offset: Schema.optional<Schema.Natural>;
+}>, Schema.Struct<{
+    readonly op: Schema.Literal<"summary">;
+    readonly sessionId: Schema.optional<Schema.String>;
+    readonly top: Schema.optional<Schema.Int>;
+}>, Schema.Struct<{
+    readonly op: Schema.Literal<"spans">;
+    readonly sessionId: Schema.optional<Schema.String>;
+    readonly status: Schema.optional<Schema.Literals<readonly ["any", "failed", "ok", "error", "defect", "interrupted", "open"]>>;
+    /** Case-insensitive substring of the span name. */
+    readonly name: Schema.optional<Schema.String>;
+    /** Only spans whose duration (or, while open, elapsed lower bound) is at least this. */
+    readonly minDurationMs: Schema.optional<Schema.Finite>;
+    /** Only spans overlapping `[fromMs, toMs]`. Timings are not clipped to it. */
+    readonly fromMs: Schema.optional<Schema.Finite>;
+    readonly toMs: Schema.optional<Schema.Finite>;
+    readonly sort: Schema.optional<Schema.Literals<readonly ["start", "duration", "outsideChildren"]>>;
+    readonly limit: Schema.optional<Schema.Int>;
+    readonly offset: Schema.optional<Schema.Natural>;
+}>, Schema.Struct<{
+    readonly op: Schema.Literal<"span">;
+    readonly sessionId: Schema.optional<Schema.String>;
+    readonly spanId: Schema.String;
+    readonly children: Schema.optional<Schema.Int>;
+    readonly events: Schema.optional<Schema.Int>;
+}>, Schema.Struct<{
+    readonly op: Schema.Literal<"logs">;
+    readonly sessionId: Schema.optional<Schema.String>;
+    readonly spanId: Schema.optional<Schema.String>;
+    /** Requires `spanId`: that span's own logs, or its whole subtree's (default). */
+    readonly scope: Schema.optional<Schema.Literals<readonly ["span", "subtree"]>>;
+    readonly minLevel: Schema.optional<Schema.Literals<readonly ["Trace", "Debug", "Info", "Warn", "Error", "Fatal"]>>;
+    readonly fromMs: Schema.optional<Schema.Finite>;
+    readonly toMs: Schema.optional<Schema.Finite>;
+    readonly limit: Schema.optional<Schema.Int>;
+    readonly offset: Schema.optional<Schema.Natural>;
+}>]>;
+export type QueryRequest = Schema.Schema.Type<typeof QueryRequest>;
+export type SessionQuery = Exclude<QueryRequest, {
+    readonly op: 'sessions';
+}>;
+/**
+ * Validates an untrusted request. Unknown keys are rejected rather than
+ * ignored, so a misspelt filter can never silently widen a result.
+ */
+export declare const decodeRequest: (input: unknown) => Result.Result<QueryRequest, QueryFailure>;
+export type ErrorTag = 'InvalidRequest' | 'SessionNotFound' | 'SessionConflict' | 'SpanNotFound' | 'TraceFileError' | 'CollectorUnavailable' | 'CollectorError' | 'ResponseTooLarge'
+/** CLI only: `export` could not write its output file. */
+ | 'OutputError';
+/** Every failed query, whatever the source or transport. */
+export interface QueryFailure {
+    readonly ok: false;
+    readonly apiVersion: typeof apiVersion;
+    readonly op: string | null;
+    readonly error: {
+        readonly _tag: ErrorTag;
+        readonly message: string;
+        /** What to try next. */
+        readonly hint: string;
+        readonly [detail: string]: unknown;
+    };
+}
+/**
+ * A failure response. `op` is echoed only when it is a known operation and
+ * `message` is cut to `errorMessageChars`, so untrusted input cannot inflate it.
+ */
+export declare const failure: (op: string | null, tag: ErrorTag, message: string, hint: string, details?: Record<string, unknown>) => QueryFailure;
+/**
+ * Enforces {@link limits.responseBytes} on a complete response. An oversized
+ * response, success or failure, becomes a small fixed-shape
+ * `ResponseTooLarge` failure that echoes no caller text.
+ */
+export declare const limitResponse: <R extends QueryResponse>(response: R) => R | QueryFailure;
+/** Which session answered, and from where. */
+export interface SourceInfo {
+    readonly kind: 'live' | 'file';
+    readonly file: string | null;
+    readonly sessionId: string;
+    /** Cut to `nameChars`. */
+    readonly program: string;
+    readonly programTruncated: boolean;
+    readonly pid: number;
+    /** Cut to `nameChars`. */
+    readonly runtime: string;
+    readonly runtimeTruncated: boolean;
+    /** Live: the client was still connected at snapshot time, so more may arrive. */
+    readonly active: boolean;
+    /** Wall clock of the session's time origin (`startMs` 0). */
+    readonly startedAtEpochMillis: number;
+    readonly endedAtEpochMillis: number | null;
+    /** Live: snapshot time. File: save time. */
+    readonly snapshotAtEpochMillis: number;
+}
+/** How to read every `...Ms` field in a response. */
+export interface TimeInfo {
+    readonly unit: 'ms';
+    /**
+     * `sessionStart`: milliseconds since the session's clock origin, taken when
+     * its inspect client started. Wall clock = `startedAtEpochMillis + ms`.
+     * Monotonic, so comparable within a session only. Values can be negative:
+     * work that started before the inspect client did.
+     */
+    readonly reference: 'sessionStart';
+    /** Earliest retained timestamp (span start/end, event, log, memory), or `null` with no timed data. */
+    readonly observedFromMs: number | null;
+    /** Latest retained timestamp, or `null` with no timed data. Open spans are measured up to here. */
+    readonly observedUntilMs: number | null;
+}
+/**
+ * What the evidence may be missing. `status`:
+ * - `lossRecorded`: at least one loss or gap counter below
+ *   (`collectorDroppedMessages` … `spansMissingParent`) is non-zero.
+ * - `noLossRecorded`: collector counters are known and every loss or gap
+ *   counter is 0.
+ *   Not proof of completeness — only what was measured.
+ * - `unknown`: nothing was recorded as lost, but the source never kept the
+ *   collector counters (a browser save or older file).
+ */
+export interface Completeness {
+    readonly status: 'lossRecorded' | 'noLossRecorded' | 'unknown';
+    /** Evicted by the collector's per-session capacity; `null` = unknown. */
+    readonly collectorDroppedMessages: number | null;
+    /** Undecodable lines the collector skipped; `null` = unknown. */
+    readonly collectorSkippedLines: number | null;
+    /** Drops the client reported (its `effect_inspect.dropped` Warn logs) in retained logs. */
+    readonly clientDroppedMessages: number;
+    /** Undecodable trailing lines of a file (a cut-short save). */
+    readonly fileTruncatedLines: number;
+    /** Distinct span ids with a retained end or event but no retained start anywhere. */
+    readonly spansMissingStart: number;
+    /**
+     * Distinct span ids whose end or event arrived before their retained start.
+     * That end or event is not applied, so the span can read as open or lack
+     * events. A single client does not send this order.
+     */
+    readonly spansOutOfOrder: number;
+    /** Spans whose local parent span is not retained. */
+    readonly spansMissingParent: number;
+    /** Spans with no recorded end: still running, or their end was never received. */
+    readonly openSpans: number;
+    readonly retainedMessages: number;
+    /**
+     * Messages the collector accepted for the session (retained + evicted);
+     * `null` = unknown. Unchanged between two responses means same data.
+     */
+    readonly messagesObserved: number | null;
+}
+/**
+ * Collision state. A query never succeeds against a session with
+ * `count > 0` (see `SessionConflict`). `detection`:
+ * - `enforced`: the collector would have refused and counted a reused ID.
+ * - `unavailable`: the owning client predates instance IDs; a reused ID
+ *   would have merged silently, so `count: 0` proves nothing.
+ * - `unknown`: a file without collector metadata.
+ */
+export interface ConflictInfo {
+    readonly count: number | null;
+    readonly detection: 'enforced' | 'unavailable' | 'unknown';
+}
+/** Shared context of every successful per-session response. */
+export interface Context {
+    readonly source: SourceInfo;
+    readonly time: TimeInfo;
+    readonly completeness: Completeness;
+    readonly conflict: ConflictInfo;
+}
+export interface ErrorInfo {
+    readonly kind: 'Fail' | 'Die' | 'Interrupt';
+    readonly message: string;
+    readonly messageTruncated: boolean;
+}
+/**
+ * One span, compactly. For a completed span `durationMs = childCoveredMs +
+ * outsideChildrenMs`; for an open span those three are `null` and
+ * `elapsedLowerBoundMs` says how long it had been open by `observedUntilMs`.
+ */
+export interface SpanItem {
+    /** Exact, never shortened. */
+    readonly spanId: string;
+    /** Exact, never shortened. */
+    readonly traceId: string;
+    /** Cut to `nameChars`. */
+    readonly name: string;
+    readonly nameTruncated: boolean;
+    readonly kind: Protocol.SpanKind;
+    /** Local parent id, or `null` for a root or externally-parented span. */
+    readonly parentSpanId: string | null;
+    readonly status: SpanStatus;
+    readonly startMs: number;
+    readonly endMs: number | null;
+    readonly durationMs: number | null;
+    /** Union of recorded direct-child intervals, clipped to this span. */
+    readonly childCoveredMs: number | null;
+    /** `durationMs - childCoveredMs`: not covered by a recorded child. Not CPU time. */
+    readonly outsideChildrenMs: number | null;
+    readonly elapsedLowerBoundMs: number | null;
+    readonly childCount: number;
+    /** Children without an end; counted as covering until this span's end. */
+    readonly openChildCount: number;
+    readonly eventCount: number;
+    readonly logCount: number;
+    readonly error: ErrorInfo | null;
+}
+/**
+ * A JSON object cut down to a bounded size, as entries in the source's key
+ * order. Entries (not an object) so two keys cut to the same prefix stay apart.
+ */
+export interface BoundedAttributes {
+    readonly entries: ReadonlyArray<{
+        /** Cut to `keyChars`. */
+        readonly key: string;
+        readonly keyTruncated: boolean;
+        /**
+         * The value; if its JSON encoding exceeds `valueChars`, the first
+         * `valueChars` characters of that encoding, as a string.
+         */
+        readonly value: Protocol.Json;
+        readonly valueTruncated: boolean;
+    }>;
+    /** Keys dropped beyond the first `attributeKeys`. */
+    readonly omittedKeys: number;
+}
+export interface SpanRef {
+    readonly spanId: string;
+    readonly name: string;
+    readonly nameTruncated: boolean;
+    readonly status: SpanStatus;
+    readonly startMs: number;
+    readonly durationMs: number | null;
+}
+export interface SpanDetail extends SpanItem {
+    readonly attributes: BoundedAttributes;
+    readonly stack: string | null;
+    readonly stackTruncated: boolean;
+    readonly parent: {
+        readonly kind: 'none';
+    } | {
+        readonly kind: 'local';
+        readonly spanId: string;
+        readonly retained: boolean;
+    } | {
+        readonly kind: 'external';
+        readonly spanId: string;
+        readonly traceId: string;
+    };
+    /** Root-most first, ending at the direct parent. */
+    readonly ancestry: {
+        readonly items: ReadonlyArray<SpanRef>;
+        /** More ancestors exist above the first item. */
+        readonly truncated: boolean;
+    };
+    /** First children by start time. */
+    readonly children: {
+        readonly total: number;
+        readonly items: ReadonlyArray<SpanItem>;
+    };
+    /** First span events by time. */
+    readonly events: {
+        readonly total: number;
+        readonly items: ReadonlyArray<{
+            /** Cut to `nameChars`. */
+            readonly name: string;
+            readonly nameTruncated: boolean;
+            readonly timeMs: number;
+            readonly attributes: BoundedAttributes;
+        }>;
+    };
+}
+export interface LogItem {
+    readonly timeMs: number;
+    readonly level: Protocol.LogLevel;
+    /** The message; a non-string message is JSON-encoded. */
+    readonly message: string;
+    readonly messageTruncated: boolean;
+    readonly spanId: string | null;
+    /** The span's name cut to `nameChars`, or `null` when unknown or not retained. */
+    readonly spanName: string | null;
+    readonly spanNameTruncated: boolean;
+    readonly fiberId: number | null;
+    readonly annotations: BoundedAttributes;
+}
+export interface Page<A> {
+    readonly total: number;
+    readonly offset: number;
+    readonly limit: number;
+    /** Offset of the next page, or `null` on the last. */
+    readonly nextOffset: number | null;
+    readonly items: ReadonlyArray<A>;
+}
+export interface NameGroup {
+    /** Cut to `nameChars`; groups are formed on the full name. */
+    readonly name: string;
+    readonly nameTruncated: boolean;
+    readonly count: number;
+    readonly completed: number;
+    readonly open: number;
+    /** Spans with any failure outcome, interruptions included. */
+    readonly failed: number;
+    /** Sum over completed spans. Nested and concurrent spans overlap. */
+    readonly totalDurationMs: number;
+    readonly maxDurationMs: number | null;
+    readonly totalOutsideChildrenMs: number;
+}
+export interface Summary {
+    readonly spans: {
+        readonly total: number;
+        readonly ok: number;
+        readonly error: number;
+        readonly defect: number;
+        readonly interrupted: number;
+        readonly open: number;
+    };
+    readonly spanEvents: number;
+    readonly logs: {
+        readonly total: number;
+        readonly byLevel: Partial<Record<Protocol.LogLevel, number>>;
+    };
+    readonly memory: {
+        readonly samples: number;
+        readonly peakHeapUsedBytes: number;
+        readonly peakRssBytes: number;
+        readonly lastHeapUsedBytes: number;
+    } | null;
+    /** `error`/`defect` spans (not interruptions), earliest start first. */
+    readonly failures: {
+        readonly total: number;
+        readonly items: ReadonlyArray<SpanItem>;
+    };
+    /** Completed spans, largest `durationMs` first. */
+    readonly longest: ReadonlyArray<SpanItem>;
+    /** Completed spans, largest `outsideChildrenMs` first. */
+    readonly largestOutsideChildren: ReadonlyArray<SpanItem>;
+    /** Open spans, largest `elapsedLowerBoundMs` first. */
+    readonly longestOpen: ReadonlyArray<SpanItem>;
+    /** Span names, largest `totalDurationMs` first. */
+    readonly names: {
+        readonly total: number;
+        readonly items: ReadonlyArray<NameGroup>;
+    };
+}
+export type SessionsResult = Page<{
+    readonly sessionId: string;
+    readonly program: string;
+    readonly programTruncated: boolean;
+    readonly pid: number;
+    readonly runtime: string;
+    readonly runtimeTruncated: boolean;
+    readonly active: boolean;
+    readonly startedAtEpochMillis: number;
+    readonly endedAtEpochMillis: number | null;
+    /** Refused reuses of this ID; `null` when none were recorded (see `conflict`). */
+    readonly conflicts: number | null;
+}>;
+interface Success<Op extends string, R> {
+    readonly ok: true;
+    readonly apiVersion: typeof apiVersion;
+    readonly op: Op;
+    /** The request as applied, defaults filled in. */
+    readonly query: Record<string, unknown>;
+    readonly result: R;
+}
+export type SessionsResponse = Success<'sessions', SessionsResult> & {
+    readonly source: {
+        readonly kind: 'live' | 'file';
+        readonly file: string | null;
+    };
+};
+export type SummaryResponse = Success<'summary', Summary> & Context;
+/**
+ * How `fromMs`/`toMs` were applied to `spans`, or `null` without either:
+ * spans whose `[startMs, endMs]` (open: `[startMs, observedUntilMs]`)
+ * overlaps `[fromMs, toMs]`, bounds inclusive, are selected, and their
+ * timings are for the whole span, not clipped to the window.
+ */
+export interface SpanWindow {
+    readonly fromMs: number | null;
+    readonly toMs: number | null;
+    readonly match: 'overlap';
+    readonly inclusive: true;
+    readonly timings: 'fullSpan';
+}
+/** How `fromMs`/`toMs` were applied to `logs`: log times within the range, inclusive. */
+export interface LogWindow {
+    readonly fromMs: number | null;
+    readonly toMs: number | null;
+    readonly match: 'within';
+    readonly inclusive: true;
+}
+export type SpansResponse = Success<'spans', Page<SpanItem>> & Context & {
+    readonly window: SpanWindow | null;
+};
+export type SpanResponse = Success<'span', SpanDetail> & Context;
+export type LogsResponse = Success<'logs', Page<LogItem>> & Context & {
+    readonly window: LogWindow | null;
+};
+export type QueryResponse = SessionsResponse | SummaryResponse | SpansResponse | SpanResponse | LogsResponse | QueryFailure;
+/**
+ * Lists `sessions`, newest start first (ties by id). Discovery only: a caller
+ * that chose its session ID should query it directly instead.
+ */
+export declare const listSessions: (source: SessionsResponse['source'], sessions: ReadonlyArray<Protocol.Session>, request: Extract<QueryRequest, {
+    readonly op: 'sessions';
+}>) => SessionsResponse | QueryFailure;
+/**
+ * Answers a per-session query against one frozen source. The caller has
+ * already matched `request.sessionId` to `source` exactly; this refuses a
+ * session with a recorded ID conflict instead of answering for it. The
+ * response is held to {@link limits.responseBytes}.
+ */
+export declare const run: (source: TraceSource, request: SessionQuery) => QueryResponse;
+/** Answers a request against trace-file text: the offline equivalent of a collector query. */
+export declare const queryFile: (text: string, file: string, input: unknown) => QueryResponse;
+/** The live `SessionNotFound` failure, shared by the collector's handlers. */
+export declare const liveSessionNotFound: (op: string, sessionId: string) => QueryFailure;
+/** The live failure for a per-session request without a `sessionId`. */
+export declare const sessionRequired: (op: string) => QueryFailure;
+export {};