effect-inspect 0.1.1 → 0.2.0

package/dist/collector/Store.d.ts

@@ -8,6 +8,11 @@
  * Ingest never blocks on a consumer. The ring drops its oldest message when
  * full and the live `PubSub` is sliding, so neither a long-running program nor
  * a stalled webapp client can apply backpressure to the instrumented program.
+ *
+ * A session belongs to the first client instance that announced its ID. Only
+ * that instance's current connection may write to it or end it; a different
+ * instance reusing the ID is refused and counted in `Session.conflicts`, so a
+ * collision can never merge two runs or overwrite the original trace.
  */
 import { Context, Effect, Layer, PubSub } from 'effect';
 import * as Protocol from '../protocol/Schema.ts';
@@ -21,16 +26,40 @@ export interface SessionSnapshot {
     readonly droppedMessages: number;
     /** Lines received for this session that could not be decoded. */
     readonly skippedLines: number;
+    /**
+     * Whether the owner sent an instance ID, so a reused ID is refused and
+     * counted. `false` for an older client: a reused ID would have merged.
+     */
+    readonly conflictDetection: boolean;
 }
+/**
+ * One client connection, as the store knows it: an identity token only.
+ *
+ * Passed with every write so the store can tell the owning connection from a
+ * stale one (a reconnect already replaced it) or a refused one (an ID
+ * collision).
+ */
+export type Connection = symbol;
 declare const Store_base: Context.ServiceClass<Store, "effect-inspect/collector/Store", {
-    /** Opens a session, or resumes the existing one when a program reconnects. */
-    readonly hello: (message: Protocol.Hello) => Effect.Effect<void>;
-    /** Records one decoded message and fans it out to live subscribers. */
-    readonly append: (message: Protocol.ClientMessage) => Effect.Effect<void>;
-    /** Counts one line that could not be decoded. */
-    readonly skipLine: (sessionId: Protocol.SessionId | undefined) => Effect.Effect<void>;
-    /** Marks a session ended because its program disconnected. */
-    readonly end: (sessionId: Protocol.SessionId) => Effect.Effect<void>;
+    /**
+     * Opens a session for `connection`, or resumes it when the same client
+     * instance reconnects. A different instance announcing a known ID is a
+     * collision: it is refused and counted, and the session is left untouched.
+     */
+    readonly hello: (message: Protocol.Hello, connection: Connection) => Effect.Effect<void>;
+    /**
+     * Records one decoded message and fans it out to live subscribers — only
+     * when `connection` owns the message's session.
+     */
+    readonly append: (message: Protocol.ClientMessage, connection: Connection) => Effect.Effect<void>;
+    /** Counts one line that could not be decoded, if `connection` owns the session. */
+    readonly skipLine: (sessionId: Protocol.SessionId | undefined, connection: Connection) => Effect.Effect<void>;
+    /**
+     * Marks a session ended because `connection` closed. A no-op unless it is
+     * the owner's current connection, so neither a refused collision nor a
+     * connection a reconnect already replaced can end the owner's run.
+     */
+    readonly end: (sessionId: Protocol.SessionId, connection: Connection) => Effect.Effect<void>;
     /** Every known session, in the order they first said `Hello`. */
     readonly sessions: Effect.Effect<ReadonlyArray<Protocol.Session>>;
     /** One session's retained messages and loss counters. */
@@ -57,14 +86,25 @@ export declare class Store extends Store_base {
 export declare const make: (options?: {
     readonly capacity?: number;
 } | undefined) => Effect.Effect<{
-    /** Opens a session, or resumes the existing one when a program reconnects. */
-    readonly hello: (message: Protocol.Hello) => Effect.Effect<void>;
-    /** Records one decoded message and fans it out to live subscribers. */
-    readonly append: (message: Protocol.ClientMessage) => Effect.Effect<void>;
-    /** Counts one line that could not be decoded. */
-    readonly skipLine: (sessionId: Protocol.SessionId | undefined) => Effect.Effect<void>;
-    /** Marks a session ended because its program disconnected. */
-    readonly end: (sessionId: Protocol.SessionId) => Effect.Effect<void>;
+    /**
+     * Opens a session for `connection`, or resumes it when the same client
+     * instance reconnects. A different instance announcing a known ID is a
+     * collision: it is refused and counted, and the session is left untouched.
+     */
+    readonly hello: (message: Protocol.Hello, connection: Connection) => Effect.Effect<void>;
+    /**
+     * Records one decoded message and fans it out to live subscribers — only
+     * when `connection` owns the message's session.
+     */
+    readonly append: (message: Protocol.ClientMessage, connection: Connection) => Effect.Effect<void>;
+    /** Counts one line that could not be decoded, if `connection` owns the session. */
+    readonly skipLine: (sessionId: Protocol.SessionId | undefined, connection: Connection) => Effect.Effect<void>;
+    /**
+     * Marks a session ended because `connection` closed. A no-op unless it is
+     * the owner's current connection, so neither a refused collision nor a
+     * connection a reconnect already replaced can end the owner's run.
+     */
+    readonly end: (sessionId: Protocol.SessionId, connection: Connection) => Effect.Effect<void>;
     /** Every known session, in the order they first said `Hello`. */
     readonly sessions: Effect.Effect<ReadonlyArray<Protocol.Session>>;
     /** One session's retained messages and loss counters. */

package/dist/collector/Store.js

@@ -8,6 +8,11 @@
  * Ingest never blocks on a consumer. The ring drops its oldest message when
  * full and the live `PubSub` is sliding, so neither a long-running program nor
  * a stalled webapp client can apply backpressure to the instrumented program.
+ *
+ * A session belongs to the first client instance that announced its ID. Only
+ * that instance's current connection may write to it or end it; a different
+ * instance reusing the ID is refused and counted in `Session.conflicts`, so a
+ * collision can never merge two runs or overwrite the original trace.
  */
 import { Clock, Context, Effect, Layer, PubSub } from 'effect';
 import * as Protocol from '../protocol/Schema.js';
@@ -29,17 +34,31 @@ export const make = Effect.fnUntraced(function* (options) {
     const sessions = new Map();
     const changes = yield* PubSub.sliding(1);
     const notify = PubSub.publish(changes, undefined).pipe(Effect.asVoid);
-    const hello = (message) => Effect.gen(function* () {
+    const hello = (message, connection) => Effect.gen(function* () {
         const existing = sessions.get(message.sessionId);
         if (existing !== undefined) {
-            // A reconnect resumes the session rather than starting a new one, so a
-            // program that is killed and restarted keeps one continuous trace.
+            // Same instance means the client's socket dropped and it dialled back:
+            // resume, so one run keeps one continuous trace. Anything else is an
+            // independent run that chose the same ID. Refusing it keeps the
+            // original trace intact, and counting it lets a query report the
+            // collision rather than serve this run's data as the newcomer's.
+            if (existing.instanceId !== message.instanceId) {
+                existing.session = {
+                    ...existing.session,
+                    conflicts: (existing.session.conflicts ?? 0) + 1,
+                };
+                yield* notify;
+                return;
+            }
+            existing.connection = connection;
             existing.session = { ...existing.session, active: true };
             delete existing.session.endedAtEpochMillis;
             yield* notify;
             return;
         }
         sessions.set(message.sessionId, {
+            instanceId: message.instanceId,
+            connection,
             session: {
                 sessionId: message.sessionId,
                 program: message.program,
@@ -56,10 +75,16 @@ export const make = Effect.fnUntraced(function* (options) {
         });
         yield* notify;
     });
-    const append = (message) => Effect.suspend(() => {
-        const state = sessions.get(message.sessionId);
-        // A message for a session that never said Hello has nowhere to go. It is
-        // a client bug, not a reason to drop the connection.
+    /** The session `connection` currently owns under `sessionId`, if any. */
+    const owned = (sessionId, connection) => {
+        const state = sessionId === undefined ? undefined : sessions.get(sessionId);
+        return state?.connection === connection ? state : undefined;
+    };
+    const append = (message, connection) => Effect.suspend(() => {
+        const state = owned(message.sessionId, connection);
+        // A message for a session this connection does not own — it never said
+        // Hello, or it was refused as a collision — has nowhere to go. It is not
+        // a reason to drop the connection either.
         if (state === undefined)
             return Effect.void;
         if (state.ring.length < capacity) {
@@ -74,13 +99,13 @@ export const make = Effect.fnUntraced(function* (options) {
     });
     // A line from a connection that never sent a usable `Hello` has no session
     // to count it against, so it is skipped without a counter.
-    const skipLine = (sessionId) => Effect.sync(() => {
-        const state = sessionId === undefined ? undefined : sessions.get(sessionId);
+    const skipLine = (sessionId, connection) => Effect.sync(() => {
+        const state = owned(sessionId, connection);
         if (state !== undefined)
             state.skippedLines += 1;
     });
-    const end = (sessionId) => Effect.flatMap(Clock.currentTimeMillis, (now) => {
-        const state = sessions.get(sessionId);
+    const end = (sessionId, connection) => Effect.flatMap(Clock.currentTimeMillis, (now) => {
+        const state = owned(sessionId, connection);
         if (state === undefined || !state.session.active)
             return Effect.void;
         state.session = {
@@ -101,6 +126,7 @@ export const make = Effect.fnUntraced(function* (options) {
                 : state.ring.slice(state.head).concat(state.ring.slice(0, state.head)),
             droppedMessages: state.droppedMessages,
             skippedLines: state.skippedLines,
+            conflictDetection: state.instanceId !== undefined,
         };
     });
     const live = (sessionId) => Effect.sync(() => sessions.get(sessionId)?.live);

package/dist/protocol/Codec.d.ts

@@ -61,6 +61,7 @@ export declare const clientCodec: Codec<{
         readonly startTime: bigint;
         readonly wallClockEpochMillis: number;
     };
+    readonly instanceId?: string | undefined;
 } | {
     readonly sessionId: string;
     readonly _tag: "SpanStart";
@@ -225,6 +226,7 @@ export declare const webappCodec: Codec<{
         };
         readonly active: boolean;
         readonly endedAtEpochMillis?: number | undefined;
+        readonly conflicts?: number | undefined;
     }[];
 } | {
     readonly sessionId: string;
@@ -240,6 +242,7 @@ export declare const webappCodec: Codec<{
             readonly startTime: bigint;
             readonly wallClockEpochMillis: number;
         };
+        readonly instanceId?: string | undefined;
     } | {
         readonly sessionId: string;
         readonly _tag: "SpanStart";
@@ -397,6 +400,7 @@ export declare const webappCodec: Codec<{
             readonly startTime: bigint;
             readonly wallClockEpochMillis: number;
         };
+        readonly instanceId?: string | undefined;
     } | {
         readonly sessionId: string;
         readonly _tag: "SpanStart";
@@ -569,7 +573,13 @@ export declare const traceFileHeaderCodec: Codec<{
         };
         readonly active: boolean;
         readonly endedAtEpochMillis?: number | undefined;
+        readonly conflicts?: number | undefined;
     };
     readonly savedAtEpochMillis: number;
+    readonly capture?: {
+        readonly droppedMessages: number;
+        readonly skippedLines: number;
+        readonly conflictDetection: boolean;
+    } | undefined;
 }>;
 export {};

package/dist/protocol/Schema.d.ts

@@ -34,9 +34,25 @@ export declare const Json: Schema.Codec<Json>;
 /** Span attributes, log annotations, and metric/event attributes. */
 export declare const Attributes: Schema.$Record<Schema.String, Schema.Codec<Json, Json, never, never>>;
 export type Attributes = Schema.Schema.Type<typeof Attributes>;
-/** Identifies one run of an instrumented program. */
+/**
+ * Identifies one run of an instrumented program.
+ *
+ * Any string on the wire, so traces from older clients keep decoding. IDs a
+ * caller chooses are held to {@link isValidSessionId} by the client instead.
+ */
 export declare const SessionId: Schema.String;
 export type SessionId = Schema.Schema.Type<typeof SessionId>;
+/** What {@link isValidSessionId} accepts, phrased for diagnostics. */
+export declare const sessionIdRule = "1-128 ASCII letters, digits, \".\", \"_\" or \"-\", starting with a letter or digit";
+/**
+ * Whether a caller-chosen session ID is acceptable, such as `checkout-before-1`.
+ *
+ * Human-readable rather than UUID-shaped, and needs no quoting as a shell
+ * argument. No colon, so a chosen ID can never take the `loaded:` form the
+ * webapp gives sessions read from a saved file. A generated UUID also
+ * satisfies it.
+ */
+export declare const isValidSessionId: (id: string) => boolean;
 /** Mirrors `Tracer.SpanKind`. */
 export declare const SpanKind: Schema.Literals<readonly ["internal", "server", "client", "producer", "consumer"]>;
 export type SpanKind = Schema.Schema.Type<typeof SpanKind>;
@@ -67,6 +83,13 @@ export declare const Hello: Schema.Struct<{
         readonly startTime: Schema.BigIntFromString;
         readonly wallClockEpochMillis: Schema.Natural;
     }>;
+    /**
+     * Random per client instance, fixed for its lifetime and re-sent on every
+     * reconnect. Tells a genuine reconnect (same instance) from an independent
+     * run that chose the same `sessionId`. Absent from older clients, which are
+     * treated as one instance per `sessionId`.
+     */
+    readonly instanceId: Schema.optional<Schema.String>;
 }>;
 export type Hello = Schema.Schema.Type<typeof Hello>;
 /** The protocol version a `Hello` must carry. Bump on any breaking change. */
@@ -419,6 +442,13 @@ export declare const ClientMessage: Schema.Union<readonly [Schema.Struct<{
         readonly startTime: Schema.BigIntFromString;
         readonly wallClockEpochMillis: Schema.Natural;
     }>;
+    /**
+     * Random per client instance, fixed for its lifetime and re-sent on every
+     * reconnect. Tells a genuine reconnect (same instance) from an independent
+     * run that chose the same `sessionId`. Absent from older clients, which are
+     * treated as one instance per `sessionId`.
+     */
+    readonly instanceId: Schema.optional<Schema.String>;
 }>, Schema.Struct<{
     readonly sessionId: Schema.String;
     readonly _tag: Schema.tag<"SpanStart">;
@@ -563,6 +593,12 @@ export declare const Session: Schema.Struct<{
     }>;
     readonly active: Schema.Boolean;
     readonly endedAtEpochMillis: Schema.optional<Schema.Natural>;
+    /**
+     * Connections refused because a different client instance announced this
+     * `sessionId` — an ID collision. Their telemetry was discarded, so this
+     * session holds only the first instance's run. Absent when there were none.
+     */
+    readonly conflicts: Schema.optional<Schema.Natural>;
 }>;
 export type Session = Schema.Schema.Type<typeof Session>;
 /** Every session the collector holds. Sent on connect and on change. */
@@ -579,6 +615,12 @@ export declare const SessionList: Schema.Struct<{
         }>;
         readonly active: Schema.Boolean;
         readonly endedAtEpochMillis: Schema.optional<Schema.Natural>;
+        /**
+         * Connections refused because a different client instance announced this
+         * `sessionId` — an ID collision. Their telemetry was discarded, so this
+         * session holds only the first instance's run. Absent when there were none.
+         */
+        readonly conflicts: Schema.optional<Schema.Natural>;
     }>>;
 }>;
 export type SessionList = Schema.Schema.Type<typeof SessionList>;
@@ -603,6 +645,13 @@ export declare const Backlog: Schema.Struct<{
             readonly startTime: Schema.BigIntFromString;
             readonly wallClockEpochMillis: Schema.Natural;
         }>;
+        /**
+         * Random per client instance, fixed for its lifetime and re-sent on every
+         * reconnect. Tells a genuine reconnect (same instance) from an independent
+         * run that chose the same `sessionId`. Absent from older clients, which are
+         * treated as one instance per `sessionId`.
+         */
+        readonly instanceId: Schema.optional<Schema.String>;
     }>, Schema.Struct<{
         readonly sessionId: Schema.String;
         readonly _tag: Schema.tag<"SpanStart">;
@@ -743,6 +792,13 @@ export declare const Live: Schema.Struct<{
             readonly startTime: Schema.BigIntFromString;
             readonly wallClockEpochMillis: Schema.Natural;
         }>;
+        /**
+         * Random per client instance, fixed for its lifetime and re-sent on every
+         * reconnect. Tells a genuine reconnect (same instance) from an independent
+         * run that chose the same `sessionId`. Absent from older clients, which are
+         * treated as one instance per `sessionId`.
+         */
+        readonly instanceId: Schema.optional<Schema.String>;
     }>, Schema.Struct<{
         readonly sessionId: Schema.String;
         readonly _tag: Schema.tag<"SpanStart">;
@@ -898,6 +954,12 @@ export declare const WebappMessage: Schema.Union<readonly [Schema.Struct<{
         }>;
         readonly active: Schema.Boolean;
         readonly endedAtEpochMillis: Schema.optional<Schema.Natural>;
+        /**
+         * Connections refused because a different client instance announced this
+         * `sessionId` — an ID collision. Their telemetry was discarded, so this
+         * session holds only the first instance's run. Absent when there were none.
+         */
+        readonly conflicts: Schema.optional<Schema.Natural>;
     }>>;
 }>, Schema.Struct<{
     readonly sessionId: Schema.String;
@@ -913,6 +975,13 @@ export declare const WebappMessage: Schema.Union<readonly [Schema.Struct<{
             readonly startTime: Schema.BigIntFromString;
             readonly wallClockEpochMillis: Schema.Natural;
         }>;
+        /**
+         * Random per client instance, fixed for its lifetime and re-sent on every
+         * reconnect. Tells a genuine reconnect (same instance) from an independent
+         * run that chose the same `sessionId`. Absent from older clients, which are
+         * treated as one instance per `sessionId`.
+         */
+        readonly instanceId: Schema.optional<Schema.String>;
     }>, Schema.Struct<{
         readonly sessionId: Schema.String;
         readonly _tag: Schema.tag<"SpanStart">;
@@ -1050,6 +1119,13 @@ export declare const WebappMessage: Schema.Union<readonly [Schema.Struct<{
             readonly startTime: Schema.BigIntFromString;
             readonly wallClockEpochMillis: Schema.Natural;
         }>;
+        /**
+         * Random per client instance, fixed for its lifetime and re-sent on every
+         * reconnect. Tells a genuine reconnect (same instance) from an independent
+         * run that chose the same `sessionId`. Absent from older clients, which are
+         * treated as one instance per `sessionId`.
+         */
+        readonly instanceId: Schema.optional<Schema.String>;
     }>, Schema.Struct<{
         readonly sessionId: Schema.String;
         readonly _tag: Schema.tag<"SpanStart">;
@@ -1200,6 +1276,23 @@ export declare const WebappRequest: Schema.Union<readonly [Schema.Struct<{
     readonly _tag: Schema.tag<"Unsubscribe">;
 }>]>;
 export type WebappRequest = Schema.Schema.Type<typeof WebappRequest>;
+/**
+ * Collector-side loss counters for one session at snapshot time, carried in
+ * a trace file exported from the collector.
+ */
+export declare const TraceCapture: Schema.Struct<{
+    /** Messages evicted by the collector's per-session capacity bound. */
+    readonly droppedMessages: Schema.Natural;
+    /** Lines received for the session that could not be decoded. */
+    readonly skippedLines: Schema.Natural;
+    /**
+     * Whether the collector could refuse an independent run reusing this ID.
+     * `false` when the owning client predates instance IDs, so a reused ID
+     * would have merged silently and `session.conflicts` proves nothing.
+     */
+    readonly conflictDetection: Schema.Boolean;
+}>;
+export type TraceCapture = Schema.Schema.Type<typeof TraceCapture>;
 /**
  * Line 1 of a saved trace file.
  *
@@ -1229,8 +1322,32 @@ export declare const TraceFileHeader: Schema.Struct<{
         }>;
         readonly active: Schema.Boolean;
         readonly endedAtEpochMillis: Schema.optional<Schema.Natural>;
+        /**
+         * Connections refused because a different client instance announced this
+         * `sessionId` — an ID collision. Their telemetry was discarded, so this
+         * session holds only the first instance's run. Absent when there were none.
+         */
+        readonly conflicts: Schema.optional<Schema.Natural>;
     }>;
     readonly savedAtEpochMillis: Schema.Natural;
+    /**
+     * What the collector knew about loss when the file was exported from it.
+     * Absent from browser saves and older files: their capture completeness is
+     * unknown, not complete. Optional and additive, so older builds, which
+     * ignore unknown header keys, still read these files.
+     */
+    readonly capture: Schema.optional<Schema.Struct<{
+        /** Messages evicted by the collector's per-session capacity bound. */
+        readonly droppedMessages: Schema.Natural;
+        /** Lines received for the session that could not be decoded. */
+        readonly skippedLines: Schema.Natural;
+        /**
+         * Whether the collector could refuse an independent run reusing this ID.
+         * `false` when the owning client predates instance IDs, so a reused ID
+         * would have merged silently and `session.conflicts` proves nothing.
+         */
+        readonly conflictDetection: Schema.Boolean;
+    }>>;
 }>;
 export type TraceFileHeader = Schema.Schema.Type<typeof TraceFileHeader>;
 /** The trace file layout version. Bump only on a change to the header or the line layout. */

package/dist/protocol/Schema.js

@@ -28,8 +28,24 @@ export const Json = Schema.Union([
 ]);
 /** Span attributes, log annotations, and metric/event attributes. */
 export const Attributes = Schema.Record(Schema.String, Json);
-/** Identifies one run of an instrumented program. */
+/**
+ * Identifies one run of an instrumented program.
+ *
+ * Any string on the wire, so traces from older clients keep decoding. IDs a
+ * caller chooses are held to {@link isValidSessionId} by the client instead.
+ */
 export const SessionId = Schema.String;
+/** What {@link isValidSessionId} accepts, phrased for diagnostics. */
+export const sessionIdRule = '1-128 ASCII letters, digits, ".", "_" or "-", starting with a letter or digit';
+/**
+ * Whether a caller-chosen session ID is acceptable, such as `checkout-before-1`.
+ *
+ * Human-readable rather than UUID-shaped, and needs no quoting as a shell
+ * argument. No colon, so a chosen ID can never take the `loaded:` form the
+ * webapp gives sessions read from a saved file. A generated UUID also
+ * satisfies it.
+ */
+export const isValidSessionId = (id) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id);
 const sessionId = { sessionId: SessionId };
 /** Mirrors `Tracer.SpanKind`. */
 export const SpanKind = Schema.Literals(['internal', 'server', 'client', 'producer', 'consumer']);
@@ -64,6 +80,13 @@ export const Hello = Schema.Struct({
     runtime: Schema.String,
     protocolVersion: Schema.Natural,
     clock: Clock,
+    /**
+     * Random per client instance, fixed for its lifetime and re-sent on every
+     * reconnect. Tells a genuine reconnect (same instance) from an independent
+     * run that chose the same `sessionId`. Absent from older clients, which are
+     * treated as one instance per `sessionId`.
+     */
+    instanceId: Schema.optional(Schema.String),
 });
 /** The protocol version a `Hello` must carry. Bump on any breaking change. */
 export const protocolVersion = 1;
@@ -249,6 +272,12 @@ export const Session = Schema.Struct({
     clock: Clock,
     active: Schema.Boolean,
     endedAtEpochMillis: Schema.optional(Schema.Natural),
+    /**
+     * Connections refused because a different client instance announced this
+     * `sessionId` — an ID collision. Their telemetry was discarded, so this
+     * session holds only the first instance's run. Absent when there were none.
+     */
+    conflicts: Schema.optional(Schema.Natural),
 });
 /** Every session the collector holds. Sent on connect and on change. */
 export const SessionList = Schema.Struct({
@@ -302,6 +331,22 @@ export const Unsubscribe = Schema.Struct({
 });
 /** What the webapp sends to the collector. */
 export const WebappRequest = Schema.Union([Subscribe, Unsubscribe]);
+/**
+ * Collector-side loss counters for one session at snapshot time, carried in
+ * a trace file exported from the collector.
+ */
+export const TraceCapture = Schema.Struct({
+    /** Messages evicted by the collector's per-session capacity bound. */
+    droppedMessages: Schema.Natural,
+    /** Lines received for the session that could not be decoded. */
+    skippedLines: Schema.Natural,
+    /**
+     * Whether the collector could refuse an independent run reusing this ID.
+     * `false` when the owning client predates instance IDs, so a reused ID
+     * would have merged silently and `session.conflicts` proves nothing.
+     */
+    conflictDetection: Schema.Boolean,
+});
 /**
  * Line 1 of a saved trace file.
  *
@@ -322,6 +367,13 @@ export const TraceFileHeader = Schema.Struct({
     protocolVersion: Schema.Natural,
     session: Session,
     savedAtEpochMillis: Schema.Natural,
+    /**
+     * What the collector knew about loss when the file was exported from it.
+     * Absent from browser saves and older files: their capture completeness is
+     * unknown, not complete. Optional and additive, so older builds, which
+     * ignore unknown header keys, still read these files.
+     */
+    capture: Schema.optional(TraceCapture),
 });
 /** The trace file layout version. Bump only on a change to the header or the line layout. */
 export const traceFileFormatVersion = 1;

package/dist/query/Client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Calls a running collector's query API (see `collector/QueryApi.ts`).
+ *
+ * Never fails: transport problems become the same `QueryFailure` shape the
+ * collector returns, tagged `CollectorUnavailable` (nothing answered in time)
+ * or `CollectorError` (something answered, but not this API), so a caller
+ * prints one JSON contract whatever went wrong.
+ */
+import { Effect } from 'effect';
+import { HttpClient } from 'effect/unstable/http';
+import * as Query from './Query.ts';
+/** Where `effect-inspect start` listens by default. */
+export declare const defaultUrl = "http://localhost:34437";
+/** How long a call waits for the collector before `CollectorUnavailable`. */
+export declare const defaultTimeoutMs = 5000;
+export interface Options {
+    /** Collector base URL, e.g. {@link defaultUrl}. */
+    readonly url: string;
+    readonly timeoutMs?: number | undefined;
+}
+/** Sends one query request (validated by the collector) and returns its response. */
+export declare const query: (options: Options, request: unknown) => Effect.Effect<Query.QueryResponse, never, HttpClient.HttpClient>;
+/**
+ * Downloads one session's frozen snapshot as `.eitrace` text, loss counters
+ * included, for offline queries that answer exactly as the live one did.
+ */
+export declare const exportTrace: (options: Options, sessionId: string) => Effect.Effect<{
+    readonly ok: true;
+    readonly text: string;
+} | Query.QueryFailure, never, HttpClient.HttpClient>;

package/dist/query/Client.js

@@ -0,0 +1,74 @@
+/**
+ * Calls a running collector's query API (see `collector/QueryApi.ts`).
+ *
+ * Never fails: transport problems become the same `QueryFailure` shape the
+ * collector returns, tagged `CollectorUnavailable` (nothing answered in time)
+ * or `CollectorError` (something answered, but not this API), so a caller
+ * prints one JSON contract whatever went wrong.
+ */
+import { Duration, Effect } from 'effect';
+import { HttpClient, HttpClientRequest } from 'effect/unstable/http';
+import { defaultPort } from '../collector/Config.js';
+import * as Query from './Query.js';
+/** Where `effect-inspect start` listens by default. */
+export const defaultUrl = `http://localhost:${defaultPort}`;
+/** How long a call waits for the collector before `CollectorUnavailable`. */
+export const defaultTimeoutMs = 5000;
+const unavailable = (op, url, detail) => Query.failure(op, 'CollectorUnavailable', `No collector answered at ${url}: ${detail}`, 'Start one with `effect-inspect start` (EFFECT_INSPECT_PORT sets its port) or point at the right URL; for saved traces query the file instead.', { url });
+const foreign = (op, url, detail) => Query.failure(op, 'CollectorError', `${url} did not answer as an effect-inspect query API: ${detail}`, 'The collector may predate the query API, or another service owns that port. Upgrade and restart the collector, or check the URL.', { url });
+const isResponse = (body) => typeof body === 'object' &&
+    body !== null &&
+    body.apiVersion === Query.apiVersion &&
+    typeof body.ok === 'boolean';
+const opOf = (request) => typeof request === 'object' &&
+    request !== null &&
+    typeof request.op === 'string'
+    ? request.op
+    : null;
+const withTimeout = (options, op, effect) => {
+    const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+    return Effect.timeoutOrElse(effect, {
+        duration: Duration.millis(timeoutMs),
+        orElse: () => Effect.succeed(unavailable(op, options.url, `no answer within ${timeoutMs}ms`)),
+    });
+};
+/** Sends one query request (validated by the collector) and returns its response. */
+export const query = (options, request) => {
+    const op = opOf(request);
+    // Bounded here too: a failure built from a long URL, or an oversized body
+    // from a collector that does not enforce the bound, must not escape it.
+    return Effect.map(withTimeout(options, op, Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient;
+        const response = yield* client.execute(HttpClientRequest.post(new URL('/api/v1/query', options.url)).pipe(HttpClientRequest.bodyJsonUnsafe(request)));
+        const body = yield* response.json;
+        return isResponse(body)
+            ? body
+            : foreign(op, options.url, `unexpected body (HTTP ${response.status})`);
+    }).pipe(Effect.catchTag('HttpClientError', (error) => Effect.succeed(error.reason._tag === 'TransportError' || error.reason._tag === 'InvalidUrlError'
+        ? unavailable(op, options.url, error.message)
+        : foreign(op, options.url, error.message))))), Query.limitResponse);
+};
+/**
+ * Downloads one session's frozen snapshot as `.eitrace` text, loss counters
+ * included, for offline queries that answer exactly as the live one did.
+ */
+export const exportTrace = (options, sessionId) => Effect.map(withTimeout(options, 'export', Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const url = new URL('/api/v1/export', options.url);
+    url.searchParams.set('sessionId', sessionId);
+    const response = yield* client.execute(HttpClientRequest.get(url));
+    // An older collector hands unknown paths to the web UI, which may answer 200 HTML.
+    if (response.status === 200 &&
+        response.headers['content-type']?.startsWith('application/x-ndjson') === true) {
+        return { ok: true, text: yield* response.text };
+    }
+    const body = yield* response.json;
+    return isResponse(body) && !body.ok
+        ? body
+        : foreign('export', options.url, `unexpected body (HTTP ${response.status})`);
+}).pipe(Effect.catchTag('HttpClientError', (error) => Effect.succeed(error.reason._tag === 'TransportError' || error.reason._tag === 'InvalidUrlError'
+    ? unavailable('export', options.url, error.message)
+    : foreign('export', options.url, error.message))))), 
+// The trace text is a lossless artifact and deliberately unbounded;
+// only failures are held to the JSON response bound.
+(result) => (result.ok ? result : Query.limitResponse(result)));