effect-inspect 0.1.0 → 0.2.0

package/dist/cli.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
-import { Command } from 'effect/unstable/cli';
-export declare const cli: Command.Command<"effect-inspect", {}, {}, import("effect/Config").ConfigError | import("effect/unstable/http/HttpServerError").ServeError, import("effect/Scope").Scope>;
+export {};

package/dist/cli.js

@@ -6,24 +6,166 @@ import * as NodeServices from '@effect/platform-node/NodeServices';
 // oxlint-disable-next-line effecttsgo/node-builtin-import
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
-import { Effect, Layer, Schema } from 'effect';
+import { Effect, Exit, Layer, Runtime, Schema } from 'effect';
 import { FileSystem } from 'effect/FileSystem';
-import { Command } from 'effect/unstable/cli';
-import { collectorConfig } from './collector/Config.js';
+import * as Stdio from 'effect/Stdio';
+import { CliConfig, Command, GlobalFlag } from 'effect/unstable/cli';
+import { queryCommands, runCli } from './cli/QueryCommands.js';
+import { collectorConfig, defaultPort } from './collector/Config.js';
 import { run } from './collector/Server.js';
-import { layer as storeLayer } from './collector/Store.js';
+import { defaultCapacity, layer as storeLayer } from './collector/Store.js';
 import { loadWebApp } from './collector/WebApp.js';
+/** Indents continuation lines under the help formatter's DESCRIPTION heading. */
+const text = (body) => body.trim().split('\n').join('\n  ');
 const start = Command.make('start', {}, () => Effect.gen(function* () {
     const { capacity, port } = yield* collectorConfig;
     const fetch = yield* loadWebApp;
     yield* Effect.logInfo(`effect-inspect listening at http://localhost:${port}`);
     return yield* Effect.provide(run(fetch), Layer.mergeAll(storeLayer({ capacity }), NodeHttpServer.layer(createServer, { port })));
-})).pipe(Command.withDescription('Start the collector and web UI (configured by EFFECT_INSPECT_PORT and EFFECT_INSPECT_CAPACITY)'));
-export const cli = Command.make('effect-inspect').pipe(Command.withDescription('Inspect Effect programs'), Command.withSubcommands([start]));
+})).pipe(Command.withShortDescription('Start the collector and web UI (configured by EFFECT_INSPECT_PORT and EFFECT_INSPECT_CAPACITY)'), Command.withDescription(text(`
+Start the collector and web UI (configured by EFFECT_INSPECT_PORT and EFFECT_INSPECT_CAPACITY).
+
+The collector receives telemetry from programs instrumented with Inspect.layer(),
+keeps it in memory per session, serves the web UI at http://localhost:PORT/ and
+answers the query commands (summary, spans, span, logs, export, sessions) on the same
+port. It runs in the foreground until stopped (Ctrl-C or SIGTERM); stopping it drops
+every trace it held, so \`export\` the sessions you want to keep first. Leave it
+running in its own terminal or as a background process while you query.
+
+ENVIRONMENT
+  EFFECT_INSPECT_PORT      Port to listen on (default ${defaultPort}). Query commands read
+                           the same variable to find the collector unless --url is given.
+  EFFECT_INSPECT_CAPACITY  Messages retained per session (default ${defaultCapacity}); older ones
+                           are evicted and reported as completeness.collectorDroppedMessages.
+
+CONNECTING PROGRAMS
+  Programs connect to ws://localhost:${defaultPort} by default. Inspect.layer() does not read
+  EFFECT_INSPECT_PORT: on another port pass Inspect.layer({ url: "ws://localhost:PORT" }).
+  (The examples in the effect-inspect repository do follow EFFECT_INSPECT_PORT.)
+  If no collector is listening, instrumented programs run normally but record nothing.
+
+OUTPUT AND EXIT
+  Logs "effect-inspect listening at http://localhost:PORT" on stdout once ready.
+  Exits 1 if the port is taken or the configuration is invalid; 130 on Ctrl-C.
+`)), Command.withExamples([
+    { command: 'effect-inspect start', description: 'Collector and UI on the default port' },
+    {
+        command: 'EFFECT_INSPECT_PORT=34500 effect-inspect start',
+        description: 'On another port; query it with EFFECT_INSPECT_PORT=34500 or --url',
+    },
+]));
+const rootHelp = text(`
+Inspect Effect programs: record their spans, span events, logs and memory samples,
+and query one exact run as JSON, live from a collector or offline from a saved
+.eitrace file. Written for coding agents: every query command prints one JSON
+document on stdout, diagnostics on stderr, and a distinct exit code per outcome.
+In this help, effect-inspect means however you run this CLI (npx effect-inspect,
+or node dist/cli.js in a built checkout of the repository).
+
+WHAT MUST BE TRUE
+  1. The program is instrumented: it provides Inspect.layer() from the effect-inspect
+     package (program.pipe(Effect.provide(Inspect.layer()))). Only Effect spans
+     (Effect.withSpan), span annotations/events, Effect logs and memory samples are
+     recorded. Nothing here instruments code for you, and no environment variable does.
+  2. For live queries a collector is running (\`effect-inspect start\`, leave it running)
+     and the program reaches it (ws://localhost:${defaultPort} by default). The collector
+     keeps sessions in memory until it stops, so a finished run can still be queried.
+  3. For offline queries you only need a .eitrace file (\`export\`); no collector.
+
+CHOOSE THE SESSION ID BEFORE LAUNCH
+  EFFECT_INSPECT_SESSION_ID=my-run-001 <command that runs the instrumented program>
+  then query exactly that run with --session my-run-001; no need to list sessions.
+  IDs: 1-128 ASCII letters, digits, ".", "_" or "-", starting with a letter or digit.
+  Use a new ID for every run, retry and instrumented child process. The program's
+  Inspect.layer({ sessionId }) option overrides the variable; with neither, the run
+  gets a random UUID (find it with \`sessions\`). An invalid or set-but-empty value
+  disables recording with a warning in the program's own logs; the program still
+  runs. A second run announcing an ID the collector holds is refused, the first run's
+  data is kept, and queries for that ID fail with SessionConflict instead of mixing.
+
+INVESTIGATION STEPS
+  1. summary --session ID                counts, failures, longest spans, completeness
+  2. spans   --session ID --status failed  find spans; --sort duration|outsideChildren
+  3. span    --session ID --span SPAN_ID   error, stack, attributes, ancestry, children
+  4. logs    --session ID --span SPAN_ID   logs in a span's subtree, or --from-ms/--to-ms
+  5. export  --session ID --out FILE       save the run; repeat 1-4 with --file FILE
+  sessions   lists sessions, only when you do not know the ID.
+
+SOURCES (every per-session query needs exactly one)
+  --session ID   live: the collector at --url, else http://localhost:$EFFECT_INSPECT_PORT,
+                 else http://localhost:${defaultPort}. Exact match; the newest session is never
+                 assumed and an unknown ID is SessionNotFound, never another run.
+  --file PATH    offline: a saved .eitrace; adding --session asserts the file's ID.
+
+OUTPUT AND EXIT CODES (all query commands)
+  stdout: one JSON document, pretty-printed; --json prints it compact on one line.
+    Success {"ok":true,"apiVersion":1,"op",...,"result"}; failure {"ok":false,
+    "apiVersion":1,"op","error":{"_tag","message","hint",...}}. The whole stdout,
+    newline included, is at most 1048576 bytes in either mode; pretty output is
+    larger, so a page that only fits compact gives ResponseTooLarge: add --json.
+  stderr: empty on success; a one-line diagnostic and a hint on failure.
+  0 ok (empty results too: result.total 0)   1 internal error
+  2 InvalidRequest          3 SessionNotFound         4 SpanNotFound
+  5 SessionConflict         6 ResponseTooLarge        7 TraceFileError
+  8 CollectorUnavailable    9 CollectorError          10 OutputError (export)
+  Each command's --help explains its errors and what to do next.
+
+EVIDENCE AND TIMING
+  Times are milliseconds since the session's clock origin (when its inspect client
+  started) and can be negative. durationMs is elapsed wall time; outsideChildrenMs is
+  elapsed time not covered by recorded child spans. Neither is CPU time or a verdict
+  that something is slow, and an open span (no end recorded) is not a deadlock.
+  Before concluding that something did not happen, read "completeness": lossRecorded
+  means evidence is missing, and noLossRecorded is not proof of completeness.
+
+Run \`effect-inspect <command> --help\` for the full flags, defaults, JSON fields and
+errors of each command.
+`);
+const cli = Command.make('effect-inspect').pipe(Command.withDescription(rootHelp), Command.withSubcommands([start, ...queryCommands]), Command.withExamples([
+    {
+        command: 'effect-inspect start',
+        description: 'Terminal 1: start the collector and leave it running',
+    },
+    {
+        command: 'EFFECT_INSPECT_SESSION_ID=failing-run-001 bun examples/failing.ts',
+        description: 'Terminal 2: run an instrumented program under a chosen ID (a repository example)',
+    },
+    {
+        command: 'effect-inspect summary --session failing-run-001 --json',
+        description: 'Overview of exactly that run',
+    },
+    {
+        command: 'effect-inspect spans --session failing-run-001 --status failed --json',
+        description: 'Its failed spans; copy a spanId and its parentSpanId',
+    },
+    { command: 'effect-inspect span --session failing-run-001 --span SPAN_ID --json' },
+    { command: 'effect-inspect logs --session failing-run-001 --span PARENT_SPAN_ID --json' },
+    {
+        command: 'effect-inspect export --session failing-run-001 --out failing-run-001.eitrace --json',
+        description: 'Save it, then query the file with no collector',
+    },
+    { command: 'effect-inspect summary --file failing-run-001.eitrace --json' },
+    { command: 'effect-inspect spans --file failing-run-001.eitrace --status failed --json' },
+]));
 const main = Effect.gen(function* () {
     const fs = yield* FileSystem;
     const packageJson = yield* fs.readFileString(fileURLToPath(new URL('../package.json', import.meta.url)));
     const { version } = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Struct({ version: Schema.String })))(packageJson);
-    return yield* Command.run(cli, { version });
+    const args = yield* (yield* Stdio.Stdio).args;
+    return yield* runCli(cli, version, args);
+});
+NodeRuntime.runMain(main.pipe(Effect.scoped, 
+// No interactive wizard: agents drive this CLI without a terminal.
+Effect.provide(Layer.mergeAll(NodeServices.layer, CliConfig.layer({
+    builtIns: [
+        GlobalFlag.Help,
+        GlobalFlag.Version,
+        GlobalFlag.Completions,
+        GlobalFlag.LogLevel,
+    ],
+})))), {
+    // `main` succeeds with the exit code; failures keep the default mapping.
+    teardown: (exit, onExit) => Exit.isSuccess(exit) && typeof exit.value === 'number'
+        ? onExit(exit.value)
+        : Runtime.defaultTeardown(exit, onExit),
 });
-NodeRuntime.runMain(main.pipe(Effect.scoped, Effect.provide(NodeServices.layer)));

package/dist/client/Client.d.ts

@@ -4,14 +4,27 @@
  *
  * The guarantee that shapes this module is that instrumenting a program must
  * never break or slow it. So the producer side is a synchronous, non-blocking
- * {@link InspectClient} `sendUnsafe` onto a sliding queue, and every transport
+ * {@link InspectClient} `sendUnsafe` onto a dropping queue, and every transport
  * concern — no collector listening, a mid-run disconnect, a consumer slower
  * than the program — is confined to a background fiber whose failures are
- * swallowed and retried. When the program outruns the socket the queue drops
- * its oldest messages and reports the count, rather than growing without bound
+ * swallowed and retried. When the program outruns the socket the queue refuses
+ * the newest messages and reports the count, rather than growing without bound
  * or pushing backpressure into the fibers being traced.
+ *
+ * Dropping rather than sliding, because *which* message is lost is the whole
+ * problem. A sliding queue evicts its oldest entries, so a burst threw away the
+ * `SpanEnd` of a span still running — and the session's `Hello`, the first
+ * message there is — while keeping the unrelated messages that caused the
+ * overrun. A span whose end was dropped renders as never-ending. Refusing at
+ * the tail instead keeps every message already accepted, so loss is a suffix of
+ * the burst rather than a hole punched through the session's history.
+ *
+ * The drain writes each dequeued batch as one newline-delimited frame rather
+ * than one frame per message, because a per-message write is what made the
+ * socket slow enough for a realistic burst to overrun the queue in the first
+ * place.
  */
-import { Context, Effect, type Scope } from 'effect';
+import { Context, Effect, Result, type Scope } from 'effect';
 import type { Socket } from 'effect/unstable/socket';
 import * as Protocol from '../protocol/Schema.ts';
 declare const InspectClient_base: Context.ServiceClass<InspectClient, "effect-inspect/client/InspectClient", {
@@ -26,11 +39,24 @@ declare const InspectClient_base: Context.ServiceClass<InspectClient, "effect-in
  */
 export declare class InspectClient extends InspectClient_base {
 }
+/** Environment variable a launcher sets to choose the session ID. */
+export declare const sessionIdEnv = "EFFECT_INSPECT_SESSION_ID";
 /** Options accepted by the inspect layers. */
 export interface Options {
+    /**
+     * The session ID this run reports under, e.g. `checkout-before-1`, so it can
+     * be queried by that exact name. Takes precedence over the
+     * `EFFECT_INSPECT_SESSION_ID` environment variable; a random UUID is used
+     * when neither is set. Must satisfy {@link Protocol.isValidSessionId}.
+     *
+     * Use one ID per run: a second client instance announcing an ID the
+     * collector already holds is refused as a collision, and its telemetry is
+     * discarded — by a collector from this release on; older ones merge them.
+     */
+    readonly sessionId?: string | undefined;
     /** Name shown for this program in the webapp. Defaults to the entry script's file name. */
     readonly programName?: string | undefined;
-    /** Outbound queue capacity, in messages. Defaults to 8192. */
+    /** Outbound queue capacity, in messages. Defaults to 131072 (~34 MB). */
     readonly bufferSize?: number | undefined;
     /**
      * How often to sample `process.memoryUsage()`, in milliseconds. Defaults to
@@ -41,12 +67,40 @@ export interface Options {
      */
     readonly memoryIntervalMillis?: number | undefined;
 }
+/**
+ * Picks this client's session ID: the `sessionId` option, else the exact
+ * `EFFECT_INSPECT_SESSION_ID` key of the environment, else a random UUID.
+ *
+ * | Input                                   | Result                   |
+ * | --------------------------------------- | ------------------------ |
+ * | option given (env never touched)        | the option, if valid     |
+ * | no environment, or exact key absent     | random UUID              |
+ * | exact key set, valid                    | that value               |
+ * | exact key set but empty, or invalid     | failure (diagnostic)     |
+ * | environment exists but cannot be read   | failure (diagnostic)     |
+ *
+ * `env` yields the raw record, read directly rather than through Effect's
+ * `ConfigProvider`: the env provider reports an empty value as missing, and
+ * this setting has to tell a set-but-empty variable (`ID=$UNSET_VAR`, a
+ * launcher mistake) from an absent one. So only the exact key counts —
+ * similarly prefixed variables are irrelevant. An unreadable environment is
+ * not treated as absence: the launcher may well have chosen an ID there.
+ *
+ * Never throws: a failure is a diagnostic, and the caller records nothing
+ * rather than report under a substituted ID nobody can find. Exported for
+ * tests only; not part of the public API.
+ */
+export declare const resolveSessionId: (options: Options | undefined, env?: () => Readonly<Record<string, string | undefined>> | undefined) => Result.Result<Protocol.SessionId, string>;
 /**
  * Builds the client service and forks the fiber that owns the connection.
  *
  * The returned effect never fails and never waits for the collector: if it is
  * unreachable the fiber retries in the background while `sendUnsafe` keeps
  * accepting (and dropping) messages, so the host program is unaffected.
+ *
+ * The session ID is resolved once, here, and re-announced unchanged on every
+ * reconnect. If the chosen ID is invalid the client logs a warning and records
+ * nothing, rather than reporting under an ID nobody asked for.
  */
 export declare const make: (options?: Options) => Effect.Effect<InspectClient['Service'], never, Scope.Scope | Socket.Socket>;
 export {};

package/dist/client/Client.js

@@ -4,19 +4,51 @@
  *
  * The guarantee that shapes this module is that instrumenting a program must
  * never break or slow it. So the producer side is a synchronous, non-blocking
- * {@link InspectClient} `sendUnsafe` onto a sliding queue, and every transport
+ * {@link InspectClient} `sendUnsafe` onto a dropping queue, and every transport
  * concern — no collector listening, a mid-run disconnect, a consumer slower
  * than the program — is confined to a background fiber whose failures are
- * swallowed and retried. When the program outruns the socket the queue drops
- * its oldest messages and reports the count, rather than growing without bound
+ * swallowed and retried. When the program outruns the socket the queue refuses
+ * the newest messages and reports the count, rather than growing without bound
  * or pushing backpressure into the fibers being traced.
+ *
+ * Dropping rather than sliding, because *which* message is lost is the whole
+ * problem. A sliding queue evicts its oldest entries, so a burst threw away the
+ * `SpanEnd` of a span still running — and the session's `Hello`, the first
+ * message there is — while keeping the unrelated messages that caused the
+ * overrun. A span whose end was dropped renders as never-ending. Refusing at
+ * the tail instead keeps every message already accepted, so loss is a suffix of
+ * the burst rather than a hole punched through the session's history.
+ *
+ * The drain writes each dequeued batch as one newline-delimited frame rather
+ * than one frame per message, because a per-message write is what made the
+ * socket slow enough for a realistic burst to overrun the queue in the first
+ * place.
  */
-import { Context, Duration, Effect, Latch, Queue, Schedule } from 'effect';
+import { Context, Duration, Effect, Latch, Queue, Result, Schedule } from 'effect';
 import { Socket as SocketService } from 'effect/unstable/socket';
 import { clientCodec } from '../protocol/Codec.js';
 import * as Protocol from '../protocol/Schema.js';
-/** How many messages may be buffered before the oldest are dropped. */
-const defaultBufferSize = 8192;
+/**
+ * How many messages may be buffered before new ones are refused.
+ *
+ * ponytail: the ceiling is counted in messages, not bytes. A message is a plain
+ * object held un-encoded, and the honest unit would be its retained size — but
+ * the only way to know that in `sendUnsafe` is to encode there, on the hot path
+ * of every traced span, duplicating work the drain already does. Measured
+ * instead: the reference workload's messages retain ~273 B each (and encode to
+ * ~275 B), so this bound is ~34 MB of queued telemetry. That is the documented
+ * ceiling — for *realistic* messages. Attribute values are user-supplied and
+ * unbounded, so a program annotating spans with megabyte strings can exceed it;
+ * the upgrade path is to track encoded bytes at the `writeBatch` boundary and
+ * feed that back as a byte budget, which costs a shared counter and is worth it
+ * only once someone actually hits it.
+ *
+ * 131,072 rather than the old 8,192 because batching the socket writes made the
+ * drain ~2.4x faster, so a deeper queue is cheap: it holds the entire 115,310
+ * message reference session at once, against a 31,563 msg/s peak that used to
+ * overrun 8,192 in a fifth of a second.
+ */
+const defaultBufferSize = 131072;
 /** How often a `Ping` is sent, so the collector can see a quiet program is alive. */
 const pingInterval = Duration.seconds(3);
 /** How often `process.memoryUsage()` is sampled, unless told otherwise. */
@@ -28,6 +60,28 @@ const defaultMemoryIntervalMillis = 100;
  * exit, and that is the worse failure.
  */
 const flushTimeout = Duration.millis(250);
+/**
+ * How many encoded bytes may ride in one socket frame.
+ *
+ * The drain writes a whole `takeAll` batch as one newline-delimited frame,
+ * which is the point — but a batch is unbounded, and the measured peak second
+ * is ~8.5 MB, so one write could otherwise hand the WebSocket a single
+ * multi-megabyte buffer to hold and copy. 256 KiB is roughly a thousand
+ * messages at the measured ~275 B mean: large enough that the per-write cost
+ * this change exists to remove is amortised away, small enough that the
+ * transient copy stays a normal allocation rather than a heap spike. The
+ * collector splits on newlines across chunk boundaries, so where a frame is
+ * cut has no effect on what it parses.
+ */
+const maxFrameBytes = 256 * 1024;
+/**
+ * How many messages may ride in one socket frame, whatever their size.
+ *
+ * A second bound for the pathological case the byte budget misses: a batch of
+ * very small messages would otherwise build one enormous array of strings
+ * before the join.
+ */
+const maxFrameMessages = 4096;
 /** Reconnect backoff: doubling from 250ms, capped so a late collector is still found. */
 const reconnectSchedule = Schedule.exponential(Duration.millis(250)).pipe(Schedule.modifyDelay(({ output }) => Effect.succeed(Duration.min(output, Duration.seconds(5)))));
 /**
@@ -38,6 +92,8 @@ const reconnectSchedule = Schedule.exponential(Duration.millis(250)).pipe(Schedu
  */
 export class InspectClient extends Context.Service()('effect-inspect/client/InspectClient') {
 }
+/** Environment variable a launcher sets to choose the session ID. */
+export const sessionIdEnv = 'EFFECT_INSPECT_SESSION_ID';
 /**
  * The name this program lists as.
  *
@@ -74,6 +130,77 @@ const memoryUsage = () => {
     const usage = globalThis.process?.memoryUsage;
     return typeof usage === 'function' ? usage.bind(globalThis.process) : undefined;
 };
+/**
+ * The raw process environment, or `undefined` when the runtime has none.
+ *
+ * Throws when an environment exists but may not be read. Deno is asked first,
+ * with `permissions.querySync`, which reports `granted` / `prompt` / `denied`
+ * without ever prompting: reading `process.env` there without permission
+ * either throws `NotCapable` or, in a terminal, stops the host program at an
+ * interactive prompt — and inspection must never block the program it
+ * watches.
+ */
+const processEnv = () => {
+    const process = globalThis.process;
+    if (process === undefined)
+        return undefined;
+    const deno = globalThis.Deno;
+    if (deno !== undefined) {
+        const state = deno.permissions?.querySync?.({ name: 'env', variable: sessionIdEnv }).state;
+        if (state !== 'granted') {
+            throw new Error(`env access is ${state ?? 'unknown'} (Deno: --allow-env=${sessionIdEnv})`);
+        }
+    }
+    return process.env;
+};
+/**
+ * Picks this client's session ID: the `sessionId` option, else the exact
+ * `EFFECT_INSPECT_SESSION_ID` key of the environment, else a random UUID.
+ *
+ * | Input                                   | Result                   |
+ * | --------------------------------------- | ------------------------ |
+ * | option given (env never touched)        | the option, if valid     |
+ * | no environment, or exact key absent     | random UUID              |
+ * | exact key set, valid                    | that value               |
+ * | exact key set but empty, or invalid     | failure (diagnostic)     |
+ * | environment exists but cannot be read   | failure (diagnostic)     |
+ *
+ * `env` yields the raw record, read directly rather than through Effect's
+ * `ConfigProvider`: the env provider reports an empty value as missing, and
+ * this setting has to tell a set-but-empty variable (`ID=$UNSET_VAR`, a
+ * launcher mistake) from an absent one. So only the exact key counts —
+ * similarly prefixed variables are irrelevant. An unreadable environment is
+ * not treated as absence: the launcher may well have chosen an ID there.
+ *
+ * Never throws: a failure is a diagnostic, and the caller records nothing
+ * rather than report under a substituted ID nobody can find. Exported for
+ * tests only; not part of the public API.
+ */
+export const resolveSessionId = (options, env = processEnv) => {
+    const fromOption = options?.sessionId;
+    const source = fromOption === undefined ? sessionIdEnv : 'the sessionId option';
+    let chosen = fromOption;
+    if (chosen === undefined) {
+        try {
+            chosen = env()?.[sessionIdEnv];
+        }
+        catch (error) {
+            return Result.fail(`${sessionIdEnv} could not be read: ${String(error)}`);
+        }
+    }
+    if (chosen === undefined) {
+        // Effect's `Crypto` can fail with a PlatformError and nothing on this path
+        // is allowed to fail; a session id needs uniqueness, not strength.
+        // oxlint-disable-next-line effecttsgo/crypto-random-uuid
+        return Result.succeed(crypto.randomUUID());
+    }
+    if (chosen === '')
+        return Result.fail(`${source} is set but empty: unset it or choose an ID`);
+    if (!Protocol.isValidSessionId(chosen)) {
+        return Result.fail(`${source} is not a valid session ID "${chosen}": use ${Protocol.sessionIdRule}`);
+    }
+    return Result.succeed(chosen);
+};
 /**
  * Forks the fiber that samples process memory into the outbound queue.
  *
@@ -112,28 +239,45 @@ const forkMemorySampler = (deps) => Effect.suspend(() => {
  * The returned effect never fails and never waits for the collector: if it is
  * unreachable the fiber retries in the background while `sendUnsafe` keeps
  * accepting (and dropping) messages, so the host program is unaffected.
+ *
+ * The session ID is resolved once, here, and re-announced unchanged on every
+ * reconnect. If the chosen ID is invalid the client logs a warning and records
+ * nothing, rather than reporting under an ID nobody asked for.
  */
 export const make = (options) => Effect.gen(function* () {
+    const resolved = resolveSessionId(options);
+    if (Result.isFailure(resolved)) {
+        yield* Effect.logWarning(`effect-inspect disabled: ${resolved.failure}`);
+        return InspectClient.of({ sessionId: '', sendUnsafe: () => { } });
+    }
+    const sessionId = resolved.success;
+    // Distinguishes this client from an independent run that chose the same
+    // session ID; fixed for the client's lifetime so a reconnect still matches.
+    // oxlint-disable-next-line effecttsgo/crypto-random-uuid-in-effect
+    const instanceId = crypto.randomUUID();
     const socket = yield* SocketService.Socket;
     const capacity = options?.bufferSize ?? defaultBufferSize;
-    const queue = yield* Queue.sliding(capacity);
-    // Effect's `Crypto` can fail with a PlatformError and nothing on this path
-    // is allowed to fail; a session id needs uniqueness, not strength.
-    // oxlint-disable-next-line effecttsgo/crypto-random-uuid-in-effect
-    const sessionId = crypto.randomUUID();
+    const queue = yield* Queue.dropping(capacity);
     // Tracked here rather than inside the queue so a drop survives a
     // reconnect: it is reported on the next `Hello`, which every reconnect
-    // re-sends. A sliding `offerUnsafe` always succeeds, so a full queue is
-    // the only drop signal there is.
+    // re-sends.
     // Open exactly while the queue is empty, so shutdown can ask "is everything
     // on the wire?" rather than guessing with a sleep.
     const flushed = Latch.makeUnsafe(true);
     let dropped = 0;
     let reported = 0;
+    // Total and non-blocking by construction, and it has to stay that way: this
+    // runs inside `Tracer.span`, `span.end` and a `Logger`, none of which can
+    // suspend or fail. A dropping `offerUnsafe` returns `false` when the queue
+    // is full instead of suspending, which is the entire reason the queue is
+    // dropping rather than a backpressuring `bounded` — refusing a message is a
+    // gap in a trace, whereas parking the fiber that emitted it is the traced
+    // program running slower because it is being watched.
     const sendUnsafe = (message) => {
-        if (Queue.sizeUnsafe(queue) >= capacity)
+        if (!Queue.offerUnsafe(queue, message)) {
             dropped += 1;
-        Queue.offerUnsafe(queue, message);
+            return;
+        }
         flushed.closeUnsafe();
     };
     const hello = Effect.clockWith((clock) => Effect.succeed({
@@ -143,6 +287,7 @@ export const make = (options) => Effect.gen(function* () {
         pid: globalThis.process?.pid ?? 0,
         runtime: runtimeName(),
         protocolVersion: Protocol.protocolVersion,
+        instanceId,
         clock: {
             startTime: clock.currentTimeNanosUnsafe(),
             // Deliberately the wall clock: this is the anchor that maps the
@@ -196,6 +341,41 @@ const connection = (deps) => Effect.gen(function* () {
     const reader = yield* deps.socket.reader;
     const writer = yield* deps.socket.writer;
     const write = (message) => Effect.suspend(() => writer.write(clientCodec.encode(message)));
+    /**
+     * Writes a batch as newline-delimited frames instead of one frame each.
+     *
+     * The codec already terminates every line with `\n`, so a frame is just
+     * the concatenation of its lines and the collector's line splitter carries
+     * an unterminated remainder across frames — batching needs no protocol
+     * change. Frames are cut at {@link maxFrameBytes} / {@link maxFrameMessages}
+     * so one huge batch cannot become one unbounded write.
+     *
+     * `encodeResult` rather than `encode`: `encode` throws, and a throw here
+     * would abandon the rest of an already-dequeued batch and tear down the
+     * connection over one out-of-domain field. A message that will not encode
+     * is dropped on its own and the batch carries on.
+     */
+    const writeBatch = (batch) => Effect.suspend(() => {
+        const frames = [];
+        let lines = [];
+        let bytes = 0;
+        for (const message of batch) {
+            const encoded = Result.getOrUndefined(clientCodec.encodeResult(message));
+            if (encoded === undefined)
+                continue;
+            if (lines.length > 0 &&
+                (bytes + encoded.length > maxFrameBytes || lines.length >= maxFrameMessages)) {
+                frames.push(lines.join(''));
+                lines = [];
+                bytes = 0;
+            }
+            lines.push(encoded);
+            bytes += encoded.length;
+        }
+        if (lines.length > 0)
+            frames.push(lines.join(''));
+        return Effect.forEach(frames, (frame) => writer.write(frame), { discard: true });
+    });
     yield* Effect.flatMap(deps.hello, write);
     // Keeps the connection warm and surfaces a half-open socket as a write
     // failure, which is what triggers the reconnect.
@@ -206,7 +386,7 @@ const connection = (deps) => Effect.gen(function* () {
         const gap = yield* deps.reportDropped;
         if (gap !== undefined)
             yield* write(gap);
-        yield* Effect.forEach(batch, write);
+        yield* writeBatch(batch);
         // Everything offered so far is on the wire. `sendUnsafe` closes the latch
         // again on the next message, so this tracks the queue rather than latching
         // permanently on the first quiet moment.

package/dist/collector/QueryApi.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 { Effect } from 'effect';
+import { HttpServerRequest, HttpServerResponse } from 'effect/unstable/http';
+import * as Query from '../query/Query.ts';
+import { Store } from './Store.ts';
+/** Path prefix of the query API. */
+export declare const apiPath = "/api/v1/";
+/** Answers one decoded request from the store. */
+export declare const answer: (input: unknown) => Effect.Effect<Query.QueryResponse, never, Store>;
+/** Handles a request under {@link apiPath}. */
+export declare const handle: (request: HttpServerRequest.HttpServerRequest, url: URL) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, Store>;