effect-inspect 0.1.1 → 0.3.0

package/dist/query/Query.js

@@ -0,0 +1,1017 @@
+/**
+ * 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 { timings } from '../trace/Timing.js';
+import { parseTraceFile, serializeTraceFile } from '../trace/TraceFile.js';
+import { TraceStore } from '../trace/TraceStore.js';
+/** Version of this request/response contract. Bumped on a breaking change. */
+export const apiVersion = 1;
+/** Defaults and caps for every bounded part of a response. */
+export const limits = {
+    /** `sessions` page size. */
+    sessions: { default: 50, max: 500 },
+    /** `spans` page size. */
+    spans: { default: 20, max: 200 },
+    /** `logs` page size. */
+    logs: { default: 50, max: 500 },
+    /** Items per ranked list in `summary`. */
+    top: { default: 5, max: 50 },
+    /** Children listed by `span`. */
+    children: { default: 20, max: 200 },
+    /** Span events listed by `span`. */
+    events: { default: 20, max: 200 },
+    /** Nearest ancestors listed by `span`. */
+    ancestry: 32,
+    /** Attribute/annotation keys kept per object; the rest are counted, not sent. */
+    attributeKeys: 32,
+    /** Characters of one JSON-encoded attribute value before it is cut. */
+    valueChars: 500,
+    /** Characters of a failure message. */
+    errorChars: 500,
+    /** Characters of a failure stack. */
+    stackChars: 4000,
+    /** Characters of a log message. */
+    logMessageChars: 2000,
+    /** Characters of a span, event or group name, a log's span name, or a program/runtime. */
+    nameChars: 200,
+    /** Characters of one attribute or annotation key. */
+    keyChars: 100,
+    /** Characters of an error `message`. */
+    errorMessageChars: 1000,
+    /** Longest `sessionId`, `spanId` or `name` a request may carry. */
+    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.
+     */
+    responseBytes: 1_048_576,
+};
+/** A live source from a collector `Store` snapshot taken at `now`. */
+export const fromSnapshot = (snapshot, now) => ({
+    kind: 'live',
+    session: snapshot.session,
+    messages: snapshot.messages,
+    capture: {
+        droppedMessages: snapshot.droppedMessages,
+        skippedLines: snapshot.skippedLines,
+        conflictDetection: snapshot.conflictDetection,
+    },
+    truncatedLines: 0,
+    snapshotAtEpochMillis: now,
+});
+/**
+ * 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 const toTraceFile = (source) => serializeTraceFile(source.session, source.messages, source.snapshotAtEpochMillis, source.capture);
+/** Parses trace-file text into a file source, or the `TraceFileError` response. */
+export const fromTraceFile = (text, file) => Result.match(parseTraceFile(text), {
+    onFailure: (error) => Result.fail(failure(null, 'TraceFileError', error.message, 'Check the path points at a saved .eitrace file.', {
+        file,
+    })),
+    onSuccess: ({ header, messages, truncatedLines }) => Result.succeed({
+        kind: 'file',
+        file,
+        session: header.session,
+        messages,
+        capture: header.capture,
+        truncatedLines,
+        snapshotAtEpochMillis: header.savedAtEpochMillis,
+    }),
+});
+// ---------------------------------------------------------------------------
+// Requests
+// ---------------------------------------------------------------------------
+const pageSize = (max) => Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: max }));
+const Millis = Schema.Finite;
+const RequestText = Schema.String.check(Schema.isMaxLength(limits.requestTextChars));
+const sessionId = Schema.optional(RequestText);
+/** Span status values a span can have. */
+export const spanStatuses = ['ok', 'error', 'defect', 'interrupted', 'open'];
+/** `spans` status filter: a {@link SpanStatus}, `failed` (any failure) or `any`. */
+export const StatusFilter = Schema.Literals(['any', 'failed', ...spanStatuses]);
+export const SpanSort = Schema.Literals(['start', 'duration', 'outsideChildren']);
+/** Log levels a `minLevel` filter accepts, least severe first. */
+export const logLevels = ['Trace', 'Debug', 'Info', 'Warn', 'Error', 'Fatal'];
+export const MinLevel = Schema.Literals(logLevels);
+export const LogScope = Schema.Literals(['span', 'subtree']);
+/** Lists sessions. Live: every session the collector holds. File: the file's one session. */
+export const SessionsRequest = Schema.Struct({
+    op: Schema.Literal('sessions'),
+    limit: Schema.optional(pageSize(limits.sessions.max)),
+    offset: Schema.optional(Schema.Natural),
+});
+/** Counts, failures and ranked timings for one session. */
+export const SummaryRequest = Schema.Struct({
+    op: Schema.Literal('summary'),
+    sessionId,
+    top: Schema.optional(pageSize(limits.top.max)),
+});
+/** A filtered, sorted page of spans. */
+export const SpansRequest = Schema.Struct({
+    op: Schema.Literal('spans'),
+    sessionId,
+    status: Schema.optional(StatusFilter),
+    /** Case-insensitive substring of the span name. */
+    name: Schema.optional(RequestText),
+    /** Only spans whose duration (or, while open, elapsed lower bound) is at least this. */
+    minDurationMs: Schema.optional(Millis.check(Schema.isGreaterThanOrEqualTo(0))),
+    /** Only spans overlapping `[fromMs, toMs]`. Timings are not clipped to it. */
+    fromMs: Schema.optional(Millis),
+    toMs: Schema.optional(Millis),
+    sort: Schema.optional(SpanSort),
+    limit: Schema.optional(pageSize(limits.spans.max)),
+    offset: Schema.optional(Schema.Natural),
+});
+/** One span with bounded ancestry, children, events and attributes. */
+export const SpanRequest = Schema.Struct({
+    op: Schema.Literal('span'),
+    sessionId,
+    spanId: RequestText,
+    children: Schema.optional(pageSize(limits.children.max)),
+    events: Schema.optional(pageSize(limits.events.max)),
+});
+/** A page of logs, optionally correlated with a span. */
+export const LogsRequest = Schema.Struct({
+    op: Schema.Literal('logs'),
+    sessionId,
+    spanId: Schema.optional(RequestText),
+    /** Requires `spanId`: that span's own logs, or its whole subtree's (default). */
+    scope: Schema.optional(LogScope),
+    minLevel: Schema.optional(MinLevel),
+    fromMs: Schema.optional(Millis),
+    toMs: Schema.optional(Millis),
+    limit: Schema.optional(pageSize(limits.logs.max)),
+    offset: Schema.optional(Schema.Natural),
+});
+export const QueryRequest = Schema.Union([
+    SessionsRequest,
+    SummaryRequest,
+    SpansRequest,
+    SpanRequest,
+    LogsRequest,
+]);
+const decodeQuery = Schema.decodeUnknownResult(QueryRequest, { onExcessProperty: 'error' });
+/**
+ * Validates an untrusted request. Unknown keys are rejected rather than
+ * ignored, so a misspelt filter can never silently widen a result.
+ */
+export const decodeRequest = (input) => {
+    const op = typeof input === 'object' &&
+        input !== null &&
+        typeof input.op === 'string'
+        ? input.op
+        : null;
+    const invalid = (message, hint) => Result.fail(failure(op, 'InvalidRequest', message, hint));
+    const decoded = decodeQuery(input);
+    if (Result.isFailure(decoded)) {
+        return invalid(decoded.failure.message, 'Fix the request; see the documented fields.');
+    }
+    const request = decoded.success;
+    if ('fromMs' in request &&
+        request.fromMs !== undefined &&
+        request.toMs !== undefined &&
+        request.fromMs > request.toMs) {
+        return invalid('fromMs must not be after toMs.', 'Swap or fix the range.');
+    }
+    if (request.op === 'logs' && request.scope !== undefined && request.spanId === undefined) {
+        return invalid('scope applies only with spanId; it was given without one.', 'Add spanId to correlate logs with a span, or drop scope to list all logs.');
+    }
+    return Result.succeed(request);
+};
+/** Operations a response may name; anything else is echoed as `null`. */
+const knownOps = new Set([
+    'sessions',
+    'summary',
+    'spans',
+    'span',
+    'logs',
+    'export',
+]);
+/**
+ * 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 const failure = (op, tag, message, hint, details) => {
+    const { text, truncated } = cut(message, limits.errorMessageChars);
+    return {
+        ok: false,
+        apiVersion,
+        op: op !== null && knownOps.has(op) ? op : null,
+        error: {
+            ...details,
+            _tag: tag,
+            message: text,
+            ...(truncated ? { messageTruncated: true } : {}),
+            hint,
+        },
+    };
+};
+const encoder = new TextEncoder();
+/**
+ * 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 const limitResponse = (response) => {
+    const bytes = encoder.encode(JSON.stringify(response)).length;
+    if (bytes <= limits.responseBytes)
+        return response;
+    return failure(response.op, 'ResponseTooLarge', `The response would be ${bytes} bytes of JSON, over the ${limits.responseBytes}-byte limit.`, 'Request fewer items (limit, top, children, events) or narrow the filters (status, name, minDurationMs, fromMs/toMs, minLevel, spanId/scope). Identifiers are never shortened, so extremely long IDs can make even a small page too large; export the trace and inspect the file directly.', {
+        bytes,
+        limitBytes: limits.responseBytes,
+        originalOutcome: response.ok ? 'ok' : response.error._tag,
+    });
+};
+// ---------------------------------------------------------------------------
+// Analysis
+// ---------------------------------------------------------------------------
+/** Microsecond resolution is plenty and keeps float noise out of the JSON. */
+const ms = (value) => Math.round(value * 1000) / 1000;
+/** Cuts to at most `max` UTF-16 units without splitting a surrogate pair. */
+function cut(text, max) {
+    if (text.length <= max)
+        return { text, truncated: false };
+    const code = text.charCodeAt(max - 1);
+    const end = code >= 0xd800 && code <= 0xdbff ? max - 1 : max;
+    return { text: text.slice(0, end), truncated: true };
+}
+const bound = (input) => {
+    const keys = Object.keys(input);
+    return {
+        entries: keys.slice(0, limits.attributeKeys).map((key) => {
+            const name = cut(key, limits.keyChars);
+            const value = input[key];
+            const encoded = cut(JSON.stringify(value), limits.valueChars);
+            return {
+                key: name.text,
+                keyTruncated: name.truncated,
+                value: encoded.truncated ? encoded.text : value,
+                valueTruncated: encoded.truncated,
+            };
+        }),
+        omittedKeys: Math.max(keys.length - limits.attributeKeys, 0),
+    };
+};
+const statusOf = (span) => {
+    if (span.end === undefined)
+        return 'open';
+    if (span.outcome?._tag !== 'Failure')
+        return 'ok';
+    if (span.outcome.kind === 'Fail')
+        return 'error';
+    if (span.outcome.kind === 'Die')
+        return 'defect';
+    return 'interrupted';
+};
+const matchesStatus = (status, filter) => {
+    if (filter === 'any')
+        return true;
+    if (filter === 'failed')
+        return status === 'error' || status === 'defect' || status === 'interrupted';
+    return status === filter;
+};
+/** A session's program and runtime, cut to `nameChars`. */
+const describe = (session) => {
+    const program = cut(session.program, limits.nameChars);
+    const runtime = cut(session.runtime, limits.nameChars);
+    return {
+        program: program.text,
+        programTruncated: program.truncated,
+        pid: session.pid,
+        runtime: runtime.text,
+        runtimeTruncated: runtime.truncated,
+    };
+};
+/** A source reconstructed once, plus the evidence gaps the renderer ignores. */
+class Analysis {
+    source;
+    store = new TraceStore();
+    /** Latest retained time (0 with none): open spans are measured up to here. */
+    now;
+    observedFrom;
+    observedUntil;
+    externalParents = new Map();
+    logCounts = new Map();
+    missingStarts;
+    outOfOrder;
+    clientDropped;
+    items = new Map();
+    /** Open spans: time so far not covered by a recorded child, a lower bound. */
+    openOutside = new Map();
+    constructor(source) {
+        this.source = source;
+        const store = this.store;
+        // Anchor at the session clock, not the first retained message, so times
+        // are identical across snapshots, evictions and exported files.
+        store.origin = source.session.clock.startTime;
+        store.epochOrigin = source.session.clock.wallClockEpochMillis;
+        const started = new Set();
+        const early = new Set();
+        let clientDropped = 0;
+        for (const message of source.messages) {
+            if (message._tag === 'SpanStart') {
+                started.add(message.spanId);
+                if (message.parent?._tag === 'ExternalParent') {
+                    this.externalParents.set(message.spanId, message.parent);
+                }
+            }
+            else if ((message._tag === 'SpanEnd' || message._tag === 'SpanEvent') &&
+                !started.has(message.spanId)) {
+                early.add(message.spanId);
+            }
+            else if (message._tag === 'Log') {
+                const dropped = message.annotations['effect_inspect.dropped'];
+                if (typeof dropped === 'number')
+                    clientDropped += dropped;
+            }
+        }
+        let outOfOrder = 0;
+        for (const id of early)
+            if (started.has(id))
+                outOfOrder++;
+        this.missingStarts = early.size - outOfOrder;
+        this.outOfOrder = outOfOrder;
+        this.clientDropped = clientDropped;
+        store.applyAll(source.messages);
+        // Computed here rather than read from the store's `duration`, which is
+        // floored at 0 for the renderer; times before the clock anchor are real.
+        let from = Number.POSITIVE_INFINITY;
+        let until = Number.NEGATIVE_INFINITY;
+        const observe = (time) => {
+            if (time < from)
+                from = time;
+            if (time > until)
+                until = time;
+        };
+        for (const span of store.spans.values()) {
+            observe(span.start);
+            if (span.end !== undefined)
+                observe(span.end);
+            for (const event of span.events)
+                observe(event.time);
+        }
+        for (const log of store.logs) {
+            observe(log.time);
+            if (log.spanId !== undefined) {
+                this.logCounts.set(log.spanId, (this.logCounts.get(log.spanId) ?? 0) + 1);
+            }
+        }
+        for (const sample of store.memory)
+            observe(sample.time);
+        this.observedFrom = from === Number.POSITIVE_INFINITY ? undefined : from;
+        this.observedUntil = until === Number.NEGATIVE_INFINITY ? undefined : until;
+        this.now = this.observedUntil ?? 0;
+    }
+    item(span) {
+        const cached = this.items.get(span.spanId);
+        if (cached !== undefined)
+            return cached;
+        const status = statusOf(span);
+        let openChildCount = 0;
+        for (const id of span.children) {
+            if (this.store.spans.get(id)?.end === undefined)
+                openChildCount++;
+        }
+        const closed = span.end !== undefined;
+        const { total, self } = timings(this.store, span, this.now);
+        if (!closed)
+            this.openOutside.set(span.spanId, ms(self));
+        const error = span.outcome?._tag === 'Failure'
+            ? (() => {
+                const { text, truncated } = cut(span.outcome.error, limits.errorChars);
+                return { kind: span.outcome.kind, message: text, messageTruncated: truncated };
+            })()
+            : null;
+        const name = cut(span.name, limits.nameChars);
+        const item = {
+            spanId: span.spanId,
+            traceId: span.traceId,
+            name: name.text,
+            nameTruncated: name.truncated,
+            kind: span.kind,
+            parentSpanId: span.parentId ?? null,
+            status,
+            startMs: ms(span.start),
+            endMs: closed ? ms(span.end) : null,
+            durationMs: closed ? ms(total) : null,
+            childCoveredMs: closed ? ms(total - self) : null,
+            outsideChildrenMs: closed ? ms(self) : null,
+            elapsedLowerBoundMs: closed ? null : ms(this.now - span.start),
+            childCount: span.children.length,
+            openChildCount,
+            eventCount: span.events.length,
+            logCount: this.logCounts.get(span.spanId) ?? 0,
+            error,
+        };
+        this.items.set(span.spanId, item);
+        return item;
+    }
+    context() {
+        const { source, store } = this;
+        const { session, capture } = source;
+        const counters = {
+            collectorDroppedMessages: capture?.droppedMessages ?? null,
+            collectorSkippedLines: capture?.skippedLines ?? null,
+            clientDroppedMessages: this.clientDropped,
+            fileTruncatedLines: source.truncatedLines,
+            spansMissingStart: this.missingStarts,
+            spansOutOfOrder: this.outOfOrder,
+            spansMissingParent: [...store.spans.values()].filter((span) => span.orphaned).length,
+        };
+        const lost = Object.values(counters).some((value) => value !== null && value > 0);
+        let status = 'noLossRecorded';
+        if (lost)
+            status = 'lossRecorded';
+        else if (capture === undefined)
+            status = 'unknown';
+        let detection = 'unknown';
+        if (capture !== undefined)
+            detection = capture.conflictDetection ? 'enforced' : 'unavailable';
+        const lastObservedMs = this.observedUntil === undefined ? null : ms(this.observedUntil);
+        const endedAtMs = session.endedAtEpochMillis === undefined
+            ? null
+            : ms(session.endedAtEpochMillis - session.clock.wallClockEpochMillis);
+        let state = 'unknown';
+        if (session.active)
+            state = 'active';
+        else if (endedAtMs !== null)
+            state = 'ended';
+        return {
+            source: {
+                kind: source.kind,
+                file: source.file ?? null,
+                sessionId: session.sessionId,
+                ...describe(session),
+                active: session.active,
+                startedAtEpochMillis: session.clock.wallClockEpochMillis,
+                endedAtEpochMillis: session.endedAtEpochMillis ?? null,
+                snapshotAtEpochMillis: source.snapshotAtEpochMillis,
+            },
+            time: {
+                unit: 'ms',
+                reference: 'sessionStart',
+                observedFromMs: this.observedFrom === undefined ? null : ms(this.observedFrom),
+                observedUntilMs: lastObservedMs,
+            },
+            termination: {
+                state,
+                lastObservedMs,
+                endedAtMs,
+                unobservedTailMs: endedAtMs === null || lastObservedMs === null ? null : ms(endedAtMs - lastObservedMs),
+            },
+            completeness: {
+                status,
+                ...counters,
+                openSpans: store.openSpans.size,
+                retainedMessages: source.messages.length,
+                messagesObserved: capture === undefined ? null : source.messages.length + capture.droppedMessages,
+            },
+            conflict: {
+                count: session.conflicts ?? (capture === undefined ? null : 0),
+                detection,
+            },
+        };
+    }
+}
+const page = (all, offset, limit) => ({
+    total: all.length,
+    offset,
+    limit,
+    nextOffset: offset + limit < all.length ? offset + limit : null,
+    items: all.slice(offset, offset + limit),
+});
+const byStart = (a, b) => a.startMs - b.startMs || (a.spanId < b.spanId ? -1 : Number(a.spanId > b.spanId));
+/** `measure` descending, ties by start. */
+const ranked = (measure) => (a, b) => measure(b) - measure(a) || byStart(a, b);
+/**
+ * Open spans interleave with completed ones by a lower bound of the measure:
+ * `elapsedLowerBoundMs` for duration, and for outside-children time the part
+ * of it no recorded child covered so far (open children counted up to now).
+ */
+const sorter = (sort, analysis) => {
+    if (sort === 'start')
+        return byStart;
+    if (sort === 'duration')
+        return ranked((item) => item.durationMs ?? item.elapsedLowerBoundMs);
+    return ranked((item) => item.outsideChildrenMs ?? analysis.openOutside.get(item.spanId));
+};
+/** Nearest `limits.ancestry` ancestors, root-most first; with `openOnly`, only the contiguous open ones. */
+const ancestry = (analysis, span, openOnly) => {
+    const { store } = analysis;
+    const items = [];
+    const seen = new Set([span.spanId]);
+    let parent = span.parentId === undefined ? undefined : store.spans.get(span.parentId);
+    let truncated = false;
+    while (parent !== undefined &&
+        !seen.has(parent.spanId) &&
+        !(openOnly && parent.end !== undefined)) {
+        if (items.length === limits.ancestry) {
+            truncated = true;
+            break;
+        }
+        seen.add(parent.spanId);
+        items.push(ref(analysis, parent));
+        parent = parent.parentId === undefined ? undefined : store.spans.get(parent.parentId);
+    }
+    return { items: items.reverse(), truncated };
+};
+const openAncestors = (analysis, span) => {
+    const { items, truncated } = ancestry(analysis, span, true);
+    return {
+        items: items.map((item) => ({
+            ...item,
+            elapsedLowerBoundMs: analysis.item(analysis.store.spans.get(item.spanId))
+                .elapsedLowerBoundMs,
+        })),
+        truncated,
+    };
+};
+const summarize = (analysis, top) => {
+    const items = [...analysis.store.spans.values()].map((span) => analysis.item(span));
+    const counts = { total: items.length, ok: 0, error: 0, defect: 0, interrupted: 0, open: 0 };
+    const groups = new Map();
+    for (const item of items) {
+        counts[item.status]++;
+        const fullName = analysis.store.spans.get(item.spanId).name;
+        let group = groups.get(fullName);
+        if (group === undefined) {
+            group = {
+                name: item.name,
+                nameTruncated: item.nameTruncated,
+                count: 0,
+                completed: 0,
+                open: 0,
+                failed: 0,
+                totalDurationMs: 0,
+                maxDurationMs: null,
+                totalOutsideChildrenMs: 0,
+            };
+            groups.set(fullName, group);
+        }
+        group.count++;
+        if (item.error !== null)
+            group.failed++;
+        if (item.durationMs === null)
+            group.open++;
+        else {
+            group.completed++;
+            group.totalDurationMs += item.durationMs;
+            group.totalOutsideChildrenMs += item.outsideChildrenMs;
+            group.maxDurationMs = Math.max(group.maxDurationMs ?? 0, item.durationMs);
+        }
+    }
+    const byLevel = {};
+    for (const log of analysis.store.logs)
+        byLevel[log.level] = (byLevel[log.level] ?? 0) + 1;
+    const completed = items.filter((item) => item.endMs !== null);
+    const open = items.filter((item) => item.endMs === null).sort(sorter('duration', analysis));
+    const innermost = open.filter((item) => item.openChildCount === 0);
+    const failures = items
+        .filter((item) => item.status === 'error' || item.status === 'defect')
+        .sort(byStart);
+    const { store } = analysis;
+    return {
+        spans: counts,
+        spanEvents: store.stats().events,
+        logs: { total: store.logs.length, byLevel },
+        memory: memorySummary(analysis, top),
+        failures: { total: failures.length, items: failures.slice(0, top) },
+        unfinished: {
+            open: open.length,
+            innermost: {
+                total: innermost.length,
+                items: innermost.slice(0, top).map((item) => ({
+                    ...item,
+                    openAncestors: openAncestors(analysis, store.spans.get(item.spanId)),
+                })),
+            },
+        },
+        longest: completed.toSorted(sorter('duration', analysis)).slice(0, top),
+        largestOutsideChildren: completed.toSorted(sorter('outsideChildren', analysis)).slice(0, top),
+        longestOpen: open.slice(0, top),
+        names: {
+            total: groups.size,
+            items: [...groups.values()]
+                .map((group) => ({
+                ...group,
+                totalDurationMs: ms(group.totalDurationMs),
+                totalOutsideChildrenMs: ms(group.totalOutsideChildrenMs),
+            }))
+                .sort((a, b) => b.totalDurationMs - a.totalDurationMs ||
+                (a.name < b.name ? -1 : Number(a.name > b.name)))
+                .slice(0, top),
+        },
+    };
+};
+const memorySummary = (analysis, top) => {
+    const { store } = analysis;
+    const samples = store.memory;
+    const first = samples[0];
+    const last = samples.at(-1);
+    if (first === undefined || last === undefined)
+        return null;
+    const peak = samples.find((sample) => sample.heapUsed === store.memoryPeak);
+    const gaps = samples.slice(1).map((sample, i) => sample.time - samples[i].time);
+    let gapAt = -1;
+    for (let i = 0; i < gaps.length; i++)
+        if (gapAt < 0 || gaps[i] > gaps[gapAt])
+            gapAt = i;
+    const sorted = gaps.toSorted((a, b) => a - b);
+    const mid = sorted.length >> 1;
+    const median = sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+    const active = [...store.spans.values()].filter((span) => span.start <= peak.time && (span.end ?? Number.POSITIVE_INFINITY) >= peak.time);
+    const ids = new Set(active.map((span) => span.spanId));
+    const innermost = active
+        .filter((span) => !span.children.some((id) => ids.has(id)))
+        .map((span) => ref(analysis, span))
+        .sort((a, b) => a.startMs - b.startMs || (a.spanId < b.spanId ? -1 : 1));
+    return {
+        samples: samples.length,
+        peakHeapUsedBytes: store.memoryPeak,
+        peakHeapAtMs: ms(peak.time),
+        peakRssBytes: store.memoryRssPeak,
+        lastHeapUsedBytes: last.heapUsed,
+        firstSampleMs: ms(first.time),
+        lastSampleMs: ms(last.time),
+        medianIntervalMs: gaps.length === 0 ? null : ms(median),
+        maxGapMs: gapAt < 0 ? null : ms(gaps[gapAt]),
+        maxGapFromMs: gapAt < 0 ? null : ms(samples[gapAt].time),
+        maxGapToMs: gapAt < 0 ? null : ms(samples[gapAt + 1].time),
+        spansActiveAtPeak: { total: innermost.length, items: innermost.slice(0, top) },
+    };
+};
+const processMemory = (analysis, span) => {
+    const until = span.end ?? analysis.now;
+    const inRange = analysis.store.memory.filter((sample) => sample.time >= span.start && sample.time <= until);
+    const first = inRange[0];
+    const last = inRange.at(-1);
+    if (first === undefined || last === undefined)
+        return null;
+    return {
+        samples: inRange.length,
+        firstSampleMs: ms(first.time),
+        lastSampleMs: ms(last.time),
+        firstHeapUsedBytes: first.heapUsed,
+        lastHeapUsedBytes: last.heapUsed,
+        maxHeapUsedBytes: Math.max(...inRange.map((sample) => sample.heapUsed)),
+    };
+};
+const ref = (analysis, span) => {
+    const item = analysis.item(span);
+    return {
+        spanId: item.spanId,
+        name: item.name,
+        nameTruncated: item.nameTruncated,
+        status: item.status,
+        startMs: item.startMs,
+        durationMs: item.durationMs,
+    };
+};
+const detail = (analysis, span, childLimit, eventLimit) => {
+    const { store } = analysis;
+    const external = analysis.externalParents.get(span.spanId);
+    let parentInfo = { kind: 'none' };
+    if (external !== undefined) {
+        parentInfo = { kind: 'external', spanId: external.spanId, traceId: external.traceId };
+    }
+    else if (span.parentId !== undefined) {
+        parentInfo = { kind: 'local', spanId: span.parentId, retained: !span.orphaned };
+    }
+    const children = span.children
+        .flatMap((id) => {
+        const child = store.spans.get(id);
+        return child === undefined ? [] : [analysis.item(child)];
+    })
+        .sort(byStart);
+    const events = span.events.toSorted((a, b) => a.time - b.time);
+    const stack = span.outcome?._tag === 'Failure' && span.outcome.stack !== undefined
+        ? cut(span.outcome.stack, limits.stackChars)
+        : undefined;
+    return {
+        ...analysis.item(span),
+        attributes: bound(span.attributes),
+        stack: stack?.text ?? null,
+        stackTruncated: stack?.truncated ?? false,
+        parent: parentInfo,
+        ancestry: ancestry(analysis, span, false),
+        children: { total: children.length, items: children.slice(0, childLimit) },
+        events: {
+            total: events.length,
+            items: events.slice(0, eventLimit).map((event) => {
+                const name = cut(event.name, limits.nameChars);
+                return {
+                    name: name.text,
+                    nameTruncated: name.truncated,
+                    timeMs: ms(event.time),
+                    attributes: bound(event.attributes),
+                };
+            }),
+        },
+        processMemory: processMemory(analysis, span),
+    };
+};
+/** Span ids of `root` and every retained descendant. */
+const subtree = (store, root) => {
+    const ids = new Set();
+    const stack = [root];
+    while (stack.length > 0) {
+        const span = stack.pop();
+        if (ids.has(span.spanId))
+            continue;
+        ids.add(span.spanId);
+        for (const id of span.children) {
+            const child = store.spans.get(id);
+            if (child !== undefined)
+                stack.push(child);
+        }
+    }
+    return ids;
+};
+const spanNotFound = (op, spanId, analysis) => failure(op, 'SpanNotFound', 'The requested span is not in the retained data of this session (see error.spanId).', 'List span ids with the spans query. A span evicted by capacity or never received cannot be recovered; check completeness.', {
+    spanId,
+    sessionId: analysis.source.session.sessionId,
+    completeness: analysis.context().completeness,
+});
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+/** Facts a reader of `summary` could otherwise miss, most important first. */
+const notices = (context, { unfinished, memory }) => {
+    const out = [];
+    const { termination, completeness, time } = context;
+    if (unfinished.open > 0) {
+        const spans = plural(unfinished.open, 'span');
+        const first = unfinished.innermost.items[0];
+        const outer = first?.openAncestors.items[0];
+        const within = outer === undefined
+            ? ''
+            : `, within "${outer.name}" (spanId ${outer.spanId}), open for at least ${outer.elapsedLowerBoundMs} ms`;
+        const position = first === undefined
+            ? ''
+            : ` Last recorded position: "${first.name}" (spanId ${first.spanId}), open for at least ${first.elapsedLowerBoundMs} ms${within}, innermost of ${plural(unfinished.innermost.total, 'open chain')}; see result.unfinished.`;
+        let message;
+        if (termination.state === 'active') {
+            message = `${spans} had no recorded end at snapshot time and the program is still connected; they may still end.${position}`;
+        }
+        else {
+            const ended = termination.state === 'ended'
+                ? `the collector recorded a disconnect at ${termination.endedAtMs} ms${termination.unobservedTailMs === null ? '' : `, ${termination.unobservedTailMs} ms after the last retained message, with nothing retained in between`}`
+                : 'no session end time is on record';
+            message = `${spans} had no recorded end; ${ended}.${position} The protocol has no end-of-session message, so a crash, a kill, an exit without closing spans and a dropped connection look the same; missing ends alone do not establish which, and an end may also have been sent but lost.`;
+        }
+        out.push({ code: 'openSpans', message });
+        out.push({
+            code: 'rankingsCompletedOnly',
+            message: `result.longest and result.largestOutsideChildren rank completed spans only; the ${spans} without an end are in result.unfinished and result.longestOpen.`,
+        });
+    }
+    const evicted = completeness.collectorDroppedMessages ?? 0;
+    if (evicted > 0) {
+        out.push({
+            code: 'collectorEvicted',
+            message: `The collector evicted the oldest ${plural(evicted, 'message')} of this session at its capacity: data before observedFromMs (${time.observedFromMs} ms) is missing, so earlier spans, logs and memory samples are absent and retained spans may lack their start or parent.`,
+        });
+    }
+    // ponytail: fixed 10x threshold; the sampling interval is not in the protocol.
+    if (memory?.maxGapMs != null && memory.maxGapMs > 10 * memory.medianIntervalMs) {
+        out.push({
+            code: 'memorySamplingGap',
+            message: `Memory samples are ${memory.medianIntervalMs} ms apart at the median, but no sample was retained for ${memory.maxGapMs} ms (from ${memory.maxGapFromMs} ms to ${memory.maxGapToMs} ms); process memory in that interval is unknown. The cause is not recorded. Possible explanations: synchronous work blocked the event loop so the sampling timer could not run, or the client's outbound queue was full and dropped samples (see completeness.clientDroppedMessages).`,
+        });
+    }
+    return out;
+};
+// ---------------------------------------------------------------------------
+// Entry points
+// ---------------------------------------------------------------------------
+/**
+ * Lists `sessions`, newest start first (ties by id). Discovery only: a caller
+ * that chose its session ID should query it directly instead.
+ */
+export const listSessions = (source, sessions, request) => {
+    const limit = request.limit ?? limits.sessions.default;
+    const offset = request.offset ?? 0;
+    const items = sessions
+        .map((session) => ({
+        sessionId: session.sessionId,
+        ...describe(session),
+        active: session.active,
+        startedAtEpochMillis: session.clock.wallClockEpochMillis,
+        endedAtEpochMillis: session.endedAtEpochMillis ?? null,
+        conflicts: session.conflicts ?? null,
+    }))
+        .sort((a, b) => b.startedAtEpochMillis - a.startedAtEpochMillis ||
+        (a.sessionId < b.sessionId ? -1 : Number(a.sessionId > b.sessionId)));
+    return limitResponse({
+        ok: true,
+        apiVersion,
+        op: 'sessions',
+        query: { op: 'sessions', limit, offset },
+        source,
+        result: page(items, offset, limit),
+    });
+};
+/**
+ * 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 const run = (source, request) => limitResponse(answer(source, request));
+/**
+ * The applied request: `op` and the selected `sessionId` first, then the
+ * caller's filters and the filled-in defaults, in a fixed key order so the
+ * same query serializes identically live and from a file.
+ */
+const echo = (request, sessionId, applied) => Object.assign({ op: request.op, sessionId }, request, applied, { sessionId });
+const answer = (source, request) => {
+    const { op } = request;
+    const sessionId = source.session.sessionId;
+    const conflicts = source.session.conflicts ?? 0;
+    if (conflicts > 0) {
+        return failure(op, 'SessionConflict', `This session ID was announced by ${conflicts} other run(s) besides the one recorded; the data cannot be attributed to your run.`, 'Relaunch with a new, unique EFFECT_INSPECT_SESSION_ID and query that ID.', { sessionId, conflicts });
+    }
+    const analysis = new Analysis(source);
+    const context = analysis.context();
+    const { store } = analysis;
+    switch (request.op) {
+        case 'summary': {
+            const top = request.top ?? limits.top.default;
+            const result = summarize(analysis, top);
+            return {
+                ok: true,
+                apiVersion,
+                op: 'summary',
+                query: { op, sessionId, top },
+                notices: notices(context, result),
+                ...context,
+                result,
+            };
+        }
+        case 'spans': {
+            const status = request.status ?? 'any';
+            const sort = request.sort ?? 'start';
+            const limit = request.limit ?? limits.spans.default;
+            const offset = request.offset ?? 0;
+            const needle = request.name?.toLowerCase();
+            const from = request.fromMs ?? Number.NEGATIVE_INFINITY;
+            const to = request.toMs ?? Number.POSITIVE_INFINITY;
+            const matched = [];
+            for (const span of store.spans.values()) {
+                const item = analysis.item(span);
+                if (!matchesStatus(item.status, status))
+                    continue;
+                // Matches the full name, not the shortened one in the response.
+                if (needle !== undefined && !span.name.toLowerCase().includes(needle))
+                    continue;
+                if (item.startMs > to || (item.endMs ?? analysis.now) < from)
+                    continue;
+                const measured = item.durationMs ?? item.elapsedLowerBoundMs;
+                if (request.minDurationMs !== undefined && measured < request.minDurationMs)
+                    continue;
+                matched.push(item);
+            }
+            matched.sort(sorter(sort, analysis));
+            return {
+                ok: true,
+                apiVersion,
+                op: 'spans',
+                query: echo(request, sessionId, { status, sort, limit, offset }),
+                ...context,
+                window: request.fromMs === undefined && request.toMs === undefined
+                    ? null
+                    : {
+                        fromMs: request.fromMs ?? null,
+                        toMs: request.toMs ?? null,
+                        match: 'overlap',
+                        inclusive: true,
+                        timings: 'fullSpan',
+                    },
+                result: page(matched, offset, limit),
+            };
+        }
+        case 'span': {
+            const span = store.spans.get(request.spanId);
+            if (span === undefined)
+                return spanNotFound(op, request.spanId, analysis);
+            const children = request.children ?? limits.children.default;
+            const events = request.events ?? limits.events.default;
+            return {
+                ok: true,
+                apiVersion,
+                op: 'span',
+                query: { op, sessionId, spanId: request.spanId, children, events },
+                ...context,
+                result: detail(analysis, span, children, events),
+            };
+        }
+        case 'logs': {
+            const limit = request.limit ?? limits.logs.default;
+            const offset = request.offset ?? 0;
+            const scope = request.spanId === undefined ? undefined : (request.scope ?? 'subtree');
+            let spans;
+            if (request.spanId !== undefined) {
+                const span = store.spans.get(request.spanId);
+                if (span === undefined)
+                    return spanNotFound(op, request.spanId, analysis);
+                spans = scope === 'span' ? new Set([span.spanId]) : subtree(store, span);
+            }
+            const minLevel = request.minLevel === undefined ? -1 : logLevels.indexOf(request.minLevel);
+            const from = request.fromMs ?? Number.NEGATIVE_INFINITY;
+            const to = request.toMs ?? Number.POSITIVE_INFINITY;
+            const matched = store.logs
+                .filter((log) => (spans === undefined || (log.spanId !== undefined && spans.has(log.spanId))) &&
+                (minLevel === -1 ||
+                    logLevels.indexOf(log.level) >= minLevel) &&
+                log.time >= from &&
+                log.time <= to)
+                // Stable: equal times keep arrival order.
+                .sort((a, b) => a.time - b.time);
+            const items = matched.slice(offset, offset + limit).map((log) => {
+                const { text, truncated } = cut(typeof log.message === 'string' ? log.message : JSON.stringify(log.message), limits.logMessageChars);
+                const spanName = log.spanId === undefined ? undefined : store.spans.get(log.spanId)?.name;
+                const shortName = spanName === undefined ? undefined : cut(spanName, limits.nameChars);
+                return {
+                    timeMs: ms(log.time),
+                    level: log.level,
+                    message: text,
+                    messageTruncated: truncated,
+                    spanId: log.spanId ?? null,
+                    spanName: shortName?.text ?? null,
+                    spanNameTruncated: shortName?.truncated ?? false,
+                    fiberId: log.fiberId ?? null,
+                    annotations: bound(log.annotations),
+                };
+            });
+            return {
+                ok: true,
+                apiVersion,
+                op: 'logs',
+                query: echo(request, sessionId, {
+                    ...(scope === undefined ? {} : { scope }),
+                    limit,
+                    offset,
+                }),
+                ...context,
+                window: request.fromMs === undefined && request.toMs === undefined
+                    ? null
+                    : {
+                        fromMs: request.fromMs ?? null,
+                        toMs: request.toMs ?? null,
+                        match: 'within',
+                        inclusive: true,
+                    },
+                result: { ...page(matched, offset, limit), items },
+            };
+        }
+    }
+};
+const sessionNotFound = (op, requested, where, details) => failure(op, 'SessionNotFound', `No session with the requested ID (error.sessionId) ${where}. No other session was substituted.`, 'Check the exact ID the program was launched with (EFFECT_INSPECT_SESSION_ID or the sessionId option), that it uses Inspect.layer() against this collector, and that it has started; or list sessions.', { ...details, sessionId: requested });
+/** Answers a request against trace-file text: the offline equivalent of a collector query. */
+export const queryFile = (text, file, input) => limitResponse(answerFile(text, file, input));
+const answerFile = (text, file, input) => {
+    const decoded = decodeRequest(input);
+    if (Result.isFailure(decoded))
+        return decoded.failure;
+    const request = decoded.success;
+    const loaded = fromTraceFile(text, file);
+    if (Result.isFailure(loaded))
+        return { ...loaded.failure, op: request.op };
+    const source = loaded.success;
+    if (request.op === 'sessions') {
+        return listSessions({ kind: 'file', file }, [source.session], request);
+    }
+    const saved = source.session.sessionId;
+    // A trace re-saved from the browser carries its `loaded:` display prefix.
+    if (request.sessionId !== undefined &&
+        request.sessionId !== saved &&
+        `loaded:${request.sessionId}` !== saved) {
+        return sessionNotFound(request.op, request.sessionId, 'is in this file', {
+            file,
+            fileSessionId: saved,
+        });
+    }
+    return run(source, request);
+};
+/** The live `SessionNotFound` failure, shared by the collector's handlers. */
+export const liveSessionNotFound = (op, sessionId) => sessionNotFound(op, sessionId, 'is known to this collector');
+/** The live failure for a per-session request without a `sessionId`. */
+export const sessionRequired = (op) => failure(op, 'InvalidRequest', 'Live queries must name a session: sessionId is required. The newest session is never assumed.', 'Pass the exact session ID the program was launched with, or list sessions to discover one.');