effect-inspect 0.1.0 → 0.2.0

package/dist/collector/QueryApi.js

@@ -0,0 +1,91 @@
+/**
+ * The collector's read-only query API over HTTP, on the collector's port.
+ *
+ * - `POST /api/v1/query` — body: a `Query.QueryRequest` JSON object. Reply:
+ *   a `Query.QueryResponse` JSON object. The body is authoritative; the
+ *   status mirrors it (200 ok, 400 InvalidRequest, 404 SessionNotFound or
+ *   SpanNotFound, 409 SessionConflict, 413 ResponseTooLarge). Every JSON
+ *   reply, errors included, is held to `Query.limits.responseBytes`.
+ * - `GET /api/v1/export?sessionId=ID` — the session's frozen snapshot as
+ *   `.eitrace` text with its loss counters in the header (200), or a
+ *   `QueryFailure` JSON body (400/404). A conflicted session still exports,
+ *   so the evidence is kept; queries against the file refuse it the same way.
+ *   Export is a lossless artifact transfer, so it is not held to the JSON
+ *   response bound: its size is the retained session (up to capacity).
+ *
+ * Each request answers from one atomic snapshot of one session. Two requests
+ * against an active session see different snapshots; compare
+ * `completeness.messagesObserved` to tell whether data changed between pages.
+ */
+import { Clock, Effect, Result } from 'effect';
+import { HttpServerRequest, HttpServerResponse } from 'effect/unstable/http';
+import * as Query from '../query/Query.js';
+import { Store } from './Store.js';
+/** Path prefix of the query API. */
+export const apiPath = '/api/v1/';
+const statusOf = (response) => {
+    if (response.ok)
+        return 200;
+    switch (response.error._tag) {
+        case 'InvalidRequest':
+            return 400;
+        case 'SessionNotFound':
+        case 'SpanNotFound':
+            return 404;
+        case 'SessionConflict':
+            return 409;
+        case 'ResponseTooLarge':
+            return 413;
+        default:
+            return 500;
+    }
+};
+/** Every JSON reply goes through the response byte bound, errors included. */
+const reply = (unbounded) => {
+    const response = Query.limitResponse(unbounded);
+    return HttpServerResponse.jsonUnsafe(response, { status: statusOf(response) });
+};
+/** Answers one decoded request from the store. */
+export const answer = (input) => Effect.gen(function* () {
+    const decoded = Query.decodeRequest(input);
+    if (Result.isFailure(decoded))
+        return decoded.failure;
+    const request = decoded.success;
+    const store = yield* Store;
+    if (request.op === 'sessions') {
+        return Query.listSessions({ kind: 'live', file: null }, yield* store.sessions, request);
+    }
+    if (request.sessionId === undefined)
+        return Query.sessionRequired(request.op);
+    const snapshot = yield* store.snapshot(request.sessionId);
+    if (snapshot === undefined)
+        return Query.liveSessionNotFound(request.op, request.sessionId);
+    // ponytail: rebuilds the trace model per request (~O(retained messages)),
+    // synchronously, which can delay ingest on this event loop meanwhile.
+    // Cache by `messagesObserved` if repeated queries on huge sessions show up.
+    return Query.run(Query.fromSnapshot(snapshot, yield* Clock.currentTimeMillis), request);
+});
+/** Handles a request under {@link apiPath}. */
+export const handle = (request, url) => Effect.gen(function* () {
+    if (url.pathname === `${apiPath}query` && request.method === 'POST') {
+        const body = yield* Effect.result(request.json);
+        if (Result.isFailure(body)) {
+            return reply(Query.failure(null, 'InvalidRequest', 'The request body is not JSON.', 'Send a JSON query object.'));
+        }
+        return reply(yield* answer(body.success));
+    }
+    if (url.pathname === `${apiPath}export` && request.method === 'GET') {
+        const sessionId = url.searchParams.get('sessionId');
+        if (sessionId === null)
+            return reply(Query.sessionRequired('export'));
+        const store = yield* Store;
+        const snapshot = yield* store.snapshot(sessionId);
+        if (snapshot === undefined)
+            return reply(Query.liveSessionNotFound('export', sessionId));
+        const source = Query.fromSnapshot(snapshot, yield* Clock.currentTimeMillis);
+        return HttpServerResponse.text(Query.toTraceFile(source), {
+            contentType: 'application/x-ndjson',
+        });
+    }
+    return reply(Query.failure(null, 'InvalidRequest', `Unknown endpoint ${request.method} ${url.pathname}.`, `Use POST ${apiPath}query or GET ${apiPath}export?sessionId=ID.`));
+});

package/dist/collector/Server.d.ts

@@ -20,5 +20,5 @@ export declare const webappPath = "/webapp";
  * released when that one connection ends, and nothing outlives it.
  */
 export declare const handleConnection: (socket: Socket.Socket, path: string) => Effect.Effect<void, never, Store>;
-/** Serves instrumented clients, webapp sockets, and the bundled web UI. */
+/** Serves instrumented clients, webapp sockets, the query API and the bundled web UI. */
 export declare const run: (fetch?: (request: Request) => Promise<Response>) => Effect.Effect<never, never, HttpServer.HttpServer | import("effect/Scope").Scope | Store>;

package/dist/collector/Server.js

@@ -11,6 +11,7 @@ import { Effect, Fiber, PubSub, Result } from 'effect';
 import { HttpServer, HttpServerRequest, HttpServerResponse } from 'effect/unstable/http';
 import { Socket } from 'effect/unstable/socket';
 import { clientCodec, collectorCodec, webappCodec, webappRequestCodec } from '../protocol/Codec.js';
+import * as QueryApi from './QueryApi.js';
 import { Store } from './Store.js';
 /** Path a webapp client connects on; anything else is an instrumented program. */
 export const webappPath = '/webapp';
@@ -71,26 +72,29 @@ const handleClient = Effect.fnUntraced(function* (socket) {
     const store = yield* Store;
     const pull = yield* readerFor(socket);
     const writer = yield* socket.writer;
+    /** This connection's identity, so the store can tell it from a collision. */
+    const connection = Symbol('connection');
     /** The session this connection belongs to, learned from its `Hello`. */
     let sessionId;
     const onMessage = (message) => Effect.gen(function* () {
         sessionId = message.sessionId;
         switch (message._tag) {
             case 'Hello':
-                yield* store.hello(message);
+                yield* store.hello(message, connection);
                 return;
             case 'Ping':
                 // A failed write means the client is gone; the read loop notices.
                 yield* Effect.ignore(writer.write(collectorCodec.encode({ _tag: 'Pong', sessionId: message.sessionId })));
                 return;
             default:
-                yield* store.append(message);
+                yield* store.append(message, connection);
         }
     });
-    yield* readLines(pull, clientCodec.decode, onMessage, () => Effect.suspend(() => store.skipLine(sessionId))).pipe(
+    yield* readLines(pull, clientCodec.decode, onMessage, () => Effect.suspend(() => store.skipLine(sessionId, connection))).pipe(
     // However the connection ends — clean close, crash, kill -9 — the session
-    // is marked ended. A reconnect with the same id resumes it.
-    Effect.ensuring(Effect.suspend(() => (sessionId === undefined ? Effect.void : store.end(sessionId)))));
+    // is marked ended, if this connection still owns it. A reconnect from the
+    // same client instance resumes it.
+    Effect.ensuring(Effect.suspend(() => sessionId === undefined ? Effect.void : store.end(sessionId, connection))));
 });
 /** Handles one webapp client's connection for its lifetime. */
 const handleWebapp = Effect.fnUntraced(function* (socket) {
@@ -146,12 +150,15 @@ const handleWebapp = Effect.fnUntraced(function* (socket) {
  * released when that one connection ends, and nothing outlives it.
  */
 export const handleConnection = (socket, path) => Effect.scoped(path === webappPath ? handleWebapp(socket) : handleClient(socket));
-/** Serves instrumented clients, webapp sockets, and the bundled web UI. */
+/** Serves instrumented clients, webapp sockets, the query API and the bundled web UI. */
 export const run = (fetch) => Effect.gen(function* () {
     const server = yield* HttpServer.HttpServer;
     yield* server.serve(Effect.gen(function* () {
         const request = yield* HttpServerRequest.HttpServerRequest;
-        const path = new URL(request.url, 'http://localhost').pathname;
+        const url = new URL(request.url, 'http://localhost');
+        const path = url.pathname;
+        if (path.startsWith(QueryApi.apiPath))
+            return yield* QueryApi.handle(request, url);
         if (request.headers.upgrade?.toLowerCase() === 'websocket') {
             const socket = yield* request.upgrade;
             yield* handleConnection(socket, path);
@@ -162,7 +169,7 @@ export const run = (fetch) => Effect.gen(function* () {
                 status: 426,
             });
         }
-        const response = yield* Effect.promise(() => fetch(new Request(new URL(request.url, 'http://localhost').href, {
+        const response = yield* Effect.promise(() => fetch(new Request(url.href, {
             method: request.method,
             headers: request.headers,
         })));

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. */