reactor-effect-client 0.2.0 → 0.3.0

package/dist/session.js

@@ -6,10 +6,12 @@ import * as Exit from "effect/Exit";
 import * as Queue from "effect/Queue";
 import * as Cause from "effect/Cause";
 import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
 import * as Stream from "effect/Stream";
-import { errorOf, positiveLimit, ReactorError } from "./errors.js";
+import { duration } from "./duration.js";
+import { parsed, parsedInput, positiveLimit, ReactorError, Remote } from "./errors.js";
 import { nonempty, uint32, structFromObject, objectFromStruct } from "./json.js";
-import { CoordinatorClient } from "./coordinator/_internal/client.js";
+import { CoordinatorClient, terminationAttributes } from "./coordinator/_internal/client.js";
 import { Correlator } from "./correlation.js";
 import { Observations } from "./observation.js";
 import * as W from "./wire.generated.js";
@@ -19,10 +21,24 @@ import { captureUploads } from "./session/_internal/uploads.js";
 import { SessionLifecycle } from "./session/_internal/lifecycle.js";
 import { isKnownRemote, RemoteSession } from "./session/_internal/remote.js";
 import { cleanupSession } from "./session/_internal/cleanup.js";
-const pure = (body) => Effect.try({ try: body, catch: errorOf });
-const withDeadline = (effect, ms, operation) => effect.pipe(Effect.timeoutOrElse({
-    duration: ms,
-    orElse: () => Effect.fail(new ReactorError("Timeout", `${operation}: deadline`)),
+/** A provider error reply: its code routes, its text stays in `body` for inspection. */
+const remoteError = (value, context) => new ReactorError({
+    reason: new Remote({
+        _tag: "Remote",
+        message: `remote command error ${value.code}`,
+        remoteCode: value.code,
+        body: value.message,
+    }),
+    context,
+});
+const pure = (body) => parsed(body);
+/** Mark a connect phase on the current span, as SqlClient marks a transaction's. */
+const phase = (name) => Effect.currentSpan.pipe(Effect.flatMap((span) => Clock.currentTimeNanos.pipe(Effect.map((now) => span.event(`reactor.connect.${name}`, now)))), Effect.ignore);
+const replyTimeout = (input) => duration(input, "reply timeout", { maximum: "10 minutes" });
+const uploadTimeout = (input) => duration(input, "upload timeout", { maximum: "10 minutes" });
+const withDeadline = (effect, deadline, operation) => effect.pipe(Effect.timeoutOrElse({
+    duration: deadline,
+    orElse: () => Effect.fail(ReactorError.fromCode("Timeout", `${operation}: deadline`)),
 }));
 /** The canonical Reactor state and wire engine for both public host exports.
  * Platform and peer dependencies are supplied by the configured client factory. */
@@ -40,7 +56,8 @@ export class Session {
     closeReport;
     received = new Set();
     bitrates = new Map();
-    commandTimeout;
+    replyTimeout;
+    uploadTimeout;
     connectTimeout;
     readyTimeout;
     heartbeat;
@@ -57,12 +74,18 @@ export class Session {
         else
             nonempty(options.intent.model.name, "model name");
         this.http = http;
-        this.commandTimeout = positiveLimit(options.commandTimeoutMs ?? 10_000, "command timeout", 600_000);
-        this.connectTimeout = positiveLimit(options.connectTimeoutMs ?? 180_000, "connect timeout", 600_000);
-        this.readyTimeout = positiveLimit(options.readyTimeoutMs ?? 30_000, "ready timeout", 600_000);
-        this.heartbeat = options.heartbeatMs ?? 10_000;
-        if (this.heartbeat !== 0)
-            positiveLimit(this.heartbeat, "heartbeat interval", 600_000);
+        this.replyTimeout = replyTimeout(options.replyTimeout ?? "10 seconds");
+        this.uploadTimeout = uploadTimeout(options.uploadTimeout ?? "60 seconds");
+        this.connectTimeout = duration(options.connectTimeout ?? "3 minutes", "connect timeout", {
+            maximum: "10 minutes",
+        });
+        this.readyTimeout = duration(options.readyTimeout ?? "30 seconds", "ready timeout", {
+            maximum: "10 minutes",
+        });
+        this.heartbeat = duration(options.heartbeatInterval ?? "10 seconds", "heartbeat interval", {
+            maximum: "10 minutes",
+            allowInfinite: true,
+        });
         this.uploadBound = positiveLimit(options.maxUploadBytes ?? 16_777_216, "upload byte bound", 64 * 1024 * 1024);
         this.data = new Correlator("data", options.maxPending ?? 128, options.requestNamespace);
         this.control = new Correlator("ctrl", options.maxPending ?? 128, options.requestNamespace);
@@ -162,7 +185,7 @@ export class Session {
         switch (event.type) {
             case "state":
                 if (event.state === "failed" || event.state === "disconnected" || event.state === "closed")
-                    this.fail(c, new ReactorError("Disconnected", `peer state ${event.state}`, {
+                    this.fail(c, ReactorError.fromCode("Disconnected", `peer state ${event.state}`, {
                         generation: c.generation,
                     }));
                 else {
@@ -172,7 +195,10 @@ export class Session {
                 break;
             case "channel":
                 if (!event.open) {
-                    this.fail(c, new ReactorError("Disconnected", `${event.channel} channel closed`));
+                    this.fail(c, ReactorError.fromCode("ChannelClosed", `${event.channel} channel closed`, {
+                        generation: c.generation,
+                        detail: { channel: event.channel },
+                    }));
                     break;
                 }
                 if (event.channel === "control")
@@ -187,7 +213,7 @@ export class Session {
                 else {
                     c.iceBytes += event.candidate.candidate.length * 2;
                     if (c.iceBuffer.length >= 256 || c.iceBytes > 262_144 || c.finalSent) {
-                        this.fail(c, new ReactorError("Overflow", "ICE buffer bound or candidate after final batch"));
+                        this.fail(c, ReactorError.fromCode("Overflow", "ICE buffer bound or candidate after final batch"));
                         break;
                     }
                     c.iceBuffer.push(event.candidate);
@@ -215,8 +241,7 @@ export class Session {
             if (channel === "data") {
                 const message = W.DataServerMessage.decode(bytes), payload = message.payload;
                 if (payload?.case === "error") {
-                    const error = new ReactorError("Remote", payload.value.message, {
-                        remoteCode: payload.value.code,
+                    const error = remoteError(payload.value, {
                         requestId: message.request_id,
                         generation: c.generation,
                         outcome: "replied",
@@ -260,13 +285,12 @@ export class Session {
                 if (payload === undefined) {
                     this.emit({
                         _tag: "Diagnostic",
-                        error: new ReactorError("Protocol", "bodyless control response does not resolve a request", { requestId: message.request_id }),
+                        error: ReactorError.fromCode("Protocol", "bodyless control response does not resolve a request", { requestId: message.request_id }),
                     }, bytes.length);
                     return;
                 }
                 const result = payload.case === "error"
-                    ? Effect.fail(new ReactorError("Remote", payload.value.message, {
-                        remoteCode: payload.value.code,
+                    ? Effect.fail(remoteError(payload.value, {
                         requestId: message.request_id,
                         outcome: "replied",
                         detail: message,
@@ -283,7 +307,7 @@ export class Session {
                     else if (payload.case === "error")
                         c.pendingClaims.delete(message.request_id);
                     else {
-                        this.fail(c, new ReactorError("UnexpectedReply", "publisher claim reply did not identify the requested track", {
+                        this.fail(c, ReactorError.fromCode("UnexpectedReply", "publisher claim reply did not identify the requested track", {
                             operation: "publish_track",
                             requestId: message.request_id,
                             outcome: "unknown",
@@ -297,7 +321,11 @@ export class Session {
             }
         }
         catch (cause) {
-            this.emit({ _tag: "Diagnostic", error: errorOf(cause, "Protocol") }, bytes.length);
+            // Decoding rejects a malformed reply with a ReactorError; anything else it
+            // throws is a bug and propagates to the peer rather than becoming typed.
+            if (!ReactorError.is(cause))
+                throw cause;
+            this.emit({ _tag: "Diagnostic", error: cause }, bytes.length);
         }
     }
     flushIce(c) {
@@ -319,9 +347,9 @@ export class Session {
     background(c, body) {
         return Effect.forkIn(body.pipe(Effect.raceFirst(Deferred.await(c.failed)), Effect.catchCause((cause) => Effect.sync(() => {
             const failure = Cause.findError(cause);
-            this.fail(c, failure._tag === "Success" && failure.success instanceof ReactorError
+            this.fail(c, failure._tag === "Success" && ReactorError.is(failure.success)
                 ? failure.success
-                : new ReactorError("Protocol", "session task failed", {
+                : ReactorError.fromCode("Protocol", "session task failed", {
                     detail: cause,
                     generation: c.generation,
                 }));
@@ -340,12 +368,14 @@ export class Session {
             });
             yield* Scope.addFinalizer(c.scope, Effect.gen(function* () {
                 if (c.failure === undefined)
-                    self.fail(c, new ReactorError("Aborted", "connection scope closed", { generation: c.generation }));
+                    self.fail(c, ReactorError.fromCode("Aborted", "connection scope closed", {
+                        generation: c.generation,
+                    }));
                 if (c.peer.shutdown !== undefined)
-                    yield* c.peer.shutdown().pipe(Effect.orDie);
+                    yield* c.peer.shutdown.pipe(Effect.orDie);
             }));
             if (previous !== undefined) {
-                self.fail(previous, new ReactorError("Disconnected", "connection retired for reconnect"));
+                self.fail(previous, ReactorError.fromCode("Disconnected", "connection retired for reconnect"));
                 yield* Scope.close(previous.scope, Exit.void);
             }
             return c;
@@ -376,9 +406,7 @@ export class Session {
             const connection = this.currentReady();
             const media = connection.peer.rawMedia;
             if (media === undefined)
-                throw new ReactorError("UnsupportedCapability", "peer has no decoded media capability", {
-                    outcome: "not-submitted",
-                });
+                throw ReactorError.fromCode("UnsupportedCapability", "peer has no decoded media capability", { outcome: "not-submitted" });
             const owned = (source) => Stream.transformPull(source, (pull) => Effect.succeed(pure(() => this.assertCurrent(connection)).pipe(Effect.andThen(pull), Effect.raceFirst(Deferred.await(connection.failed)), Effect.tap(() => pure(() => this.assertCurrent(connection))))));
             return Object.freeze({
                 generation: connection.generation,
@@ -394,9 +422,7 @@ export class Session {
         return pure(() => {
             const connection = this.currentReady();
             if (connection.peer.nativeTracks !== true) {
-                throw new ReactorError("UnsupportedCapability", "peer has no browser track capability", {
-                    outcome: "not-submitted",
-                });
+                throw ReactorError.fromCode("UnsupportedCapability", "peer has no browser track capability", { outcome: "not-submitted" });
             }
             return Object.freeze({
                 generation: connection.generation,
@@ -421,19 +447,22 @@ export class Session {
         const self = this;
         return Effect.gen(function* () {
             const c = yield* self.begin(reconnect);
+            yield* Effect.annotateCurrentSpan("reactor.connection.generation", c.generation);
             const work = Effect.gen(function* () {
                 if (!reconnect)
                     yield* self.guard(c, self.allocate());
                 self.assertCurrent(c);
                 self.lifecycle.transition("waiting");
                 const remote = self.currentRemote();
+                yield* Effect.annotateCurrentSpan("reactor.session.id", remote.id);
                 const descriptor = yield* self.guard(c, self.http.ready(remote.id, reconnect ? undefined : remote.descriptor));
                 remote.descriptor = descriptor;
+                yield* phase("described");
                 const capabilities = descriptor.capabilities, transport = descriptor.selected_transport;
                 if (capabilities === undefined || transport === undefined)
-                    return yield* Effect.fail(new ReactorError("Protocol", "missing ready capabilities/transport"));
+                    return yield* ReactorError.fromCode("Protocol", "missing ready capabilities/transport");
                 if (transport.protocol !== "webrtc" || transport.version !== "1.0")
-                    return yield* Effect.fail(new ReactorError("VersionMismatch", `unsupported transport ${transport.protocol}/${transport.version}`));
+                    return yield* ReactorError.fromCode("VersionMismatch", `unsupported transport ${transport.protocol}/${transport.version}`);
                 const readyDescriptor = Object.freeze({
                     ...descriptor,
                     capabilities,
@@ -442,10 +471,12 @@ export class Session {
                 const servers = yield* self.guard(c, self.http.iceServers(remote.id));
                 const prepared = yield* self.guard(c, Scope.provide(c.peer.prepare(servers, capabilities.tracks, (event) => self.onPeer(c, event)), c.scope));
                 c.mapping = prepared.mapping;
+                yield* phase("prepared");
                 const previousId = remote.connectionId;
                 const cid = previousId ?? (yield* self.guard(c, self.http.register(remote.id)));
                 c.connectionId = cid;
                 remote.connectionId = cid;
+                yield* phase("registered");
                 // Source order: registration -> buffered ICE (including empty final) -> offer -> poll answer.
                 yield* self.flushIce(c);
                 yield* self.background(c, Effect.gen(function* () {
@@ -455,22 +486,28 @@ export class Session {
                     }
                 }));
                 yield* self.guard(c, self.http.offer(remote.id, cid, prepared.sdp, prepared.mapping, reconnect && previousId !== undefined));
+                yield* phase("offered");
                 const answer = yield* self.guard(c, self.http.answer(remote.id, cid));
                 if (answer.connection_id !== undefined) {
                     c.connectionId = answer.connection_id;
                     remote.connectionId = answer.connection_id;
                 }
                 yield* self.guard(c, c.peer.answer(answer.sdp_answer));
+                yield* phase("answered");
                 yield* withDeadline(self.guard(c, Deferred.await(c.ready)), self.readyTimeout, "peer and both channels ready");
                 self.assertCurrent(c);
-                c.negotiated = Object.freeze({
+                yield* phase("ready");
+                self.lifecycle.ready(c, Object.freeze({
                     ownership: remote.ownership,
                     sessionId: remote.id,
                     descriptor: readyDescriptor,
                     connectionId: c.connectionId,
-                });
-                self.lifecycle.transition("ready");
-                if (self.options.autoResumeTracks ?? self.options.intent._tag === "Create")
+                }));
+                // Each connection subscribes to its own receive-only tracks, an attached
+                // one as much as the one that created the session: hosted Reactor holds
+                // a connection's media until that connection resumes them. A data-only
+                // peer has no tracks to resume.
+                if ((self.options.autoResumeTracks ?? true) && c.peer.mediaSupported !== false)
                     for (const track of capabilities.tracks)
                         if (track.direction === "recvonly") {
                             const outcome = yield* Effect.result(self.setTrackActive(track.name, true));
@@ -482,7 +519,7 @@ export class Session {
                     if (outcome._tag === "Failure")
                         self.emit({ _tag: "Diagnostic", error: outcome.failure });
                 }
-                if (self.heartbeat !== 0)
+                if (Duration.isFinite(self.heartbeat))
                     yield* self.background(c, Effect.gen(function* () {
                         while (true) {
                             yield* self.ping();
@@ -494,15 +531,17 @@ export class Session {
                 ? Effect.gen(function* () {
                     self.remote.allocationLost();
                     const error = Cause.findError(exit.cause);
-                    self.fail(c, error._tag === "Success" && error.success instanceof ReactorError
+                    self.fail(c, error._tag === "Success" && ReactorError.is(error.success)
                         ? error.success
-                        : new ReactorError("Aborted", "connection attempt interrupted"));
+                        : ReactorError.fromCode("Aborted", "connection attempt interrupted"));
                     yield* Scope.close(c.scope, Exit.void);
                 })
                 : Effect.void));
-        });
+        }).pipe(
+        // A caller-boundary span with an event per phase; the caller can cancel it.
+        Effect.withSpan(reconnect ? "reactor.session.reconnect" : "reactor.session.connect", { kind: "client" }, { captureStackTrace: false }));
     }
-    request(c, correlator, operation, encode, channel, timeoutMs, publication) {
+    request(c, correlator, operation, encode, channel, deadline, publication) {
         const self = this;
         return Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
             const pending = yield* pure(() => {
@@ -515,20 +554,26 @@ export class Session {
             if (encoded._tag === "Failure") {
                 correlator.cancel(pending);
                 c.pendingClaims.delete(pending.id);
-                return yield* Effect.fail(new ReactorError(encoded.failure.code, encoded.failure.message, {
-                    ...encoded.failure.context,
+                return yield* new ReactorError({
+                    reason: encoded.failure.reason,
+                    context: {
+                        ...encoded.failure.context,
+                        operation,
+                        requestId: pending.id,
+                        generation: c.generation,
+                        outcome: "not-submitted",
+                    },
+                });
+            }
+            const failure = (error) => new ReactorError({
+                reason: error.reason,
+                context: {
+                    ...error.context,
                     operation,
                     requestId: pending.id,
                     generation: c.generation,
-                    outcome: "not-submitted",
-                }));
-            }
-            const failure = (error) => new ReactorError(error.code, error.message, {
-                ...error.context,
-                operation,
-                requestId: pending.id,
-                generation: c.generation,
-                outcome: error.context.outcome ?? (pending.submitted ? "unknown" : "not-submitted"),
+                    outcome: error.context.outcome ?? (pending.submitted ? "unknown" : "not-submitted"),
+                },
             });
             const sending = pure(() => {
                 self.assertCurrent(c);
@@ -549,7 +594,7 @@ export class Session {
                 // native backend remains responsible for any foreign operation slot.
                 yield* Effect.forkIn(sending, yield* Effect.scope, { startImmediately: true });
                 return yield* Deferred.await(pending.deferred);
-            })).pipe(Effect.interruptible, (effect) => withDeadline(effect, timeoutMs, operation), Effect.mapError(failure), Effect.onExit((exit) => Effect.sync(() => {
+            })).pipe(Effect.interruptible, (effect) => withDeadline(effect, deadline, operation), Effect.mapError(failure), Effect.onExit((exit) => Effect.sync(() => {
                 if (!pending.submitted) {
                     correlator.cancel(pending);
                     c.pendingClaims.delete(pending.id);
@@ -558,29 +603,56 @@ export class Session {
                     pending.waiting = false;
                 // Unresolved submitted records remain bounded by maxPending. A late
                 // reply or retiring this generation releases the slot; a timeout does not.
-            })));
+            })), 
+            // The span covers the owned execution, not the caller's wait: the wire has no
+            // cancel, so it ends with the request's own outcome even after the caller stops
+            // waiting. It records identity and dispatch evidence only; failure messages are
+            // library-written, so its Exit carries no input, reply or provider text.
+            Effect.onExit((exit) => {
+                const error = Exit.findError(exit);
+                return Effect.annotateCurrentSpan(Exit.isSuccess(exit)
+                    ? { "reactor.command.outcome": "replied" }
+                    : error._tag === "Success"
+                        ? {
+                            "reactor.command.outcome": error.success.context.outcome,
+                            "error.type": error.success.reason._tag,
+                        }
+                        : // No typed failure: the connection scope closed, or a defect.
+                            { "reactor.command.outcome": pending.submitted ? "unknown" : "not-submitted" });
+            }), Effect.withSpan(channel === "data" ? "reactor.session.command" : "reactor.session.control", {
+                kind: "client",
+                attributes: {
+                    "reactor.operation": operation,
+                    "reactor.request.id": pending.id,
+                    "reactor.connection.generation": c.generation,
+                },
+            }, { captureStackTrace: false }));
             const owner = yield* Effect.forkIn(execution, c.scope, { startImmediately: true });
             return yield* restore(Fiber.join(owner));
         }));
     }
-    command(type, data, uploads = new Map(), timeoutMs = this.commandTimeout) {
-        return pure(() => {
-            const c = this.currentReady(), payload = {
+    command(type, data, options = {}) {
+        return pure(() => this.currentReady()).pipe(
+        // The caller's name, data, uploads and deadline: a rejection is InvalidInput.
+        Effect.flatMap((c) => parsedInput(() => ({
+            c,
+            deadline: options.replyTimeout === undefined
+                ? this.replyTimeout
+                : replyTimeout(options.replyTimeout),
+            payload: {
                 type: nonempty(type, "command type"),
                 data: structFromObject(data),
-                uploads: captureUploads(uploads),
-            };
-            positiveLimit(timeoutMs, "command timeout", 600_000);
-            return { c, payload };
-        }).pipe(Effect.mapError((error) => new CommandFailure(error, {
+                uploads: captureUploads(options.uploads ?? new Map()),
+            },
+        }), type)), Effect.mapError((error) => CommandFailure.from(error, {
             ...error.context,
             operation: type,
             outcome: "not-submitted",
-        })), Effect.flatMap(({ c, payload }) => this.request(c, this.data, type, (id) => W.DataClientMessage.encode({
+        })), Effect.flatMap(({ c, deadline, payload }) => this.request(c, this.data, type, (id) => W.DataClientMessage.encode({
             request_id: id,
             kind: 1,
             payload: { case: "command", value: payload },
-        }), "data", timeoutMs).pipe(Effect.mapError((error) => {
+        }), "data", deadline).pipe(Effect.mapError((error) => {
             const { outcome, requestId, generation } = error.context;
             if (outcome === "unknown" || outcome === "replied") {
                 if (requestId === undefined || generation === undefined)
@@ -592,9 +664,9 @@ export class Session {
                     requestId,
                     generation,
                 };
-                return new CommandFailure(error, context);
+                return CommandFailure.from(error, context);
             }
-            return new CommandFailure(error, {
+            return CommandFailure.from(error, {
                 ...error.context,
                 operation: type,
                 outcome: "not-submitted",
@@ -606,13 +678,13 @@ export class Session {
             const connection = expected ?? this.currentReady();
             this.assertCurrent(connection);
             return connection;
-        }).pipe(Effect.flatMap((c) => this.request(c, this.control, operation, (id) => W.ControlClientMessage.encode({ request_id: id, kind: 1, payload }), "control", this.commandTimeout, payload.case === "publish_track" ? payload.value.name : undefined)));
+        }).pipe(Effect.flatMap((c) => this.request(c, this.control, operation, (id) => W.ControlClientMessage.encode({ request_id: id, kind: 1, payload }), "control", this.replyTimeout, payload.case === "publish_track" ? payload.value.name : undefined)));
     }
     notification(c, payload) {
         return pure(() => {
             this.assertCurrent(c);
             return W.ControlClientMessage.encode({ request_id: "", kind: 3, payload });
-        }).pipe(Effect.flatMap((bytes) => this.guard(c, c.peer.send("control", bytes))), (effect) => withDeadline(effect, this.commandTimeout, "control notification"));
+        }).pipe(Effect.flatMap((bytes) => this.guard(c, c.peer.send("control", bytes))), (effect) => withDeadline(effect, this.replyTimeout, "control notification"));
     }
     ping() {
         return pure(() => this.currentReady()).pipe(Effect.flatMap((c) => this.notification(c, { case: "ping", value: {} })));
@@ -620,7 +692,7 @@ export class Session {
     schema() {
         return this.controlRequest("request_schema", { case: "request_schema", value: {} }).pipe(Effect.flatMap((reply) => pure(() => {
             if (reply.case !== "model_schema")
-                throw new ReactorError("UnexpectedReply", `schema reply was ${reply.case}`, {
+                throw ReactorError.fromCode("UnexpectedReply", `schema reply was ${reply.case}`, {
                     outcome: "replied",
                 });
             return {
@@ -634,23 +706,41 @@ export class Session {
     clip(payload) {
         return this.controlRequest(payload.case, payload).pipe(Effect.flatMap((reply) => pure(() => {
             if (reply.case === "clip_failed")
-                throw new ReactorError(/recorder disabled|encoder crashed/i.test(reply.value.reason)
-                    ? "RecorderDisabled"
-                    : "Remote", reply.value.reason, { outcome: "replied" });
+                throw new ReactorError({
+                    reason: new Remote({
+                        // The one regex classification of provider free text, a deliberate exception:
+                        // ClipFailed carries only a reason string, and a caller must tell a disabled
+                        // recorder from other clip failures. Add no others; drop this once the wire
+                        // carries a code.
+                        _tag: /recorder disabled|encoder crashed/i.test(reply.value.reason)
+                            ? "RecorderDisabled"
+                            : "Remote",
+                        message: "clip failed",
+                        body: reply.value.reason,
+                    }),
+                    context: { outcome: "replied" },
+                });
             if (reply.case !== "clip_ready")
-                throw new ReactorError("UnexpectedReply", `clip reply was ${reply.case}`, {
+                throw ReactorError.fromCode("UnexpectedReply", `clip reply was ${reply.case}`, {
                     outcome: "replied",
                 });
-            return {
-                ...reply.value,
-                playlist_url: new URL(reply.value.playlist_url, `${this.http.apiUrl}/`).href,
-            };
+            let playlist;
+            try {
+                playlist = new URL(reply.value.playlist_url, `${this.http.apiUrl}/`);
+            }
+            catch (cause) {
+                throw ReactorError.fromCode("Protocol", "clip playlist URL is malformed", {
+                    outcome: "replied",
+                    detail: cause,
+                });
+            }
+            return { ...reply.value, playlist_url: playlist.href };
         })));
     }
     requestClip(seconds) {
         return pure(() => {
             if (!Number.isFinite(seconds) || seconds <= 0)
-                throw new ReactorError("Protocol", "clip duration must be finite and positive");
+                throw ReactorError.fromCode("Protocol", "clip duration must be finite and positive");
         }).pipe(Effect.andThen(this.clip({ case: "request_clip", value: { duration_seconds: seconds } })));
     }
     recording() {
@@ -658,10 +748,10 @@ export class Session {
     }
     namedTrack(name, connection) {
         if (connection.peer.mediaSupported === false)
-            throw new ReactorError("UnsupportedCapability", "This peer is data-only; track/media operations are unavailable", { outcome: "not-submitted" });
+            throw ReactorError.fromCode("UnsupportedCapability", "This peer is data-only; track/media operations are unavailable", { outcome: "not-submitted" });
         const track = connection.negotiated.descriptor.capabilities.tracks.find((t) => t.name === name);
         if (track === undefined)
-            throw new ReactorError("InvalidState", `unknown track: ${name}`);
+            throw ReactorError.fromCode("InvalidState", `unknown track: ${name}`);
         return track;
     }
     trackOperation(name, body, expected) {
@@ -670,7 +760,7 @@ export class Session {
             this.assertCurrent(c);
             const track = this.namedTrack(name, c);
             if (c.trackBusy.has(name))
-                throw new ReactorError("InvalidState", `another track operation is in flight: ${name}`);
+                throw ReactorError.fromCode("InvalidState", `another track operation is in flight: ${name}`);
             c.trackBusy.add(name);
             return { c, track };
         }), ({ c, track }) => this.guard(c, body(c, track)), ({ c }) => Effect.sync(() => {
@@ -702,17 +792,17 @@ export class Session {
                 self.assertCurrent(c);
                 invoked = true;
             }).pipe(Effect.andThen(Effect.suspend(() => c.peer.replace(name, clone))), Effect.timeoutOrElse({
-                duration: self.commandTimeout,
+                duration: self.replyTimeout,
                 orElse: () => {
                     deadline = true;
-                    return Effect.fail(new ReactorError("Timeout", "sender replacement deadline; local generation retired", { operation: name, outcome: "unknown" }));
+                    return Effect.fail(ReactorError.fromCode("Timeout", "sender replacement deadline; local generation retired", { operation: name, outcome: "unknown" }));
                 },
             }));
             yield* restore(mutation).pipe(Effect.onExit((exit) => Exit.isFailure(exit)
                 ? Effect.sync(() => {
                     clone?.stop();
                     if (invoked && (deadline || Cause.hasInterrupts(exit.cause)))
-                        self.fail(c, new ReactorError(deadline ? "Timeout" : "Disconnected", "native sender replacement abandoned; reconnect explicitly before reusing publication", { operation: name, outcome: "unknown" }));
+                        self.fail(c, ReactorError.fromCode(deadline ? "Timeout" : "Disconnected", "native sender replacement abandoned; reconnect explicitly before reusing publication", { operation: name, outcome: "unknown" }));
                 })
                 : Effect.void));
             // No interruptible boundary between successful mutation and recording its owner.
@@ -738,17 +828,15 @@ export class Session {
         const self = this;
         return this.trackOperation(name, (c, track) => Effect.gen(function* () {
             if (c.peer.nativeTracks === false)
-                return yield* Effect.fail(new ReactorError("UnsupportedCapability", "this peer does not accept browser media tracks", { outcome: "not-submitted" }));
+                return yield* ReactorError.fromCode("UnsupportedCapability", "this peer does not accept browser media tracks", { outcome: "not-submitted" });
             if (track.direction !== "sendonly" ||
                 source.kind !== track.kind ||
                 source.readyState !== "live")
-                return yield* Effect.fail(new ReactorError("InvalidState", "publish requires a live matching input track"));
+                return yield* ReactorError.fromCode("InvalidState", "publish requires a live matching input track");
             if (!c.claimed.has(name)) {
                 const reply = yield* self.controlRequest("publish_track", { case: "publish_track", value: { name } }, c);
                 if (reply.case !== "publish_track" || reply.value.name !== name)
-                    return yield* Effect.fail(new ReactorError("UnexpectedReply", "publisher claim reply mismatch", {
-                        outcome: "replied",
-                    }));
+                    return yield* ReactorError.fromCode("UnexpectedReply", "publisher claim reply mismatch", { outcome: "replied" });
                 c.claimed.add(name);
             }
             yield* self.replaceSender(c, name, source);
@@ -756,7 +844,7 @@ export class Session {
     }
     unpublish(name, expected) {
         return this.trackOperation(name, (c) => c.peer.nativeTracks === false
-            ? Effect.fail(new ReactorError("UnsupportedCapability", "this peer does not expose browser track publication", { outcome: "not-submitted" }))
+            ? Effect.fail(ReactorError.fromCode("UnsupportedCapability", "this peer does not expose browser track publication", { outcome: "not-submitted" }))
             : this.replaceSender(c, name, null).pipe(Effect.andThen(this.notification(c, { case: "unpublish_track", value: { name } })), Effect.tap(() => Effect.sync(() => {
                 c.claimed.delete(name);
             }))), expected);
@@ -766,7 +854,7 @@ export class Session {
             const c = expected ?? this.currentReady();
             this.assertCurrent(c);
             if (c.peer.nativeTracks === false)
-                throw new ReactorError("UnsupportedCapability", "this peer exposes owned decoded frames instead of browser tracks", { outcome: "not-submitted" });
+                throw ReactorError.fromCode("UnsupportedCapability", "this peer exposes owned decoded frames instead of browser tracks", { outcome: "not-submitted" });
             return { peer: c.peer, track: c.peer.lease(name) };
         }), ({ peer, track }) => Effect.sync(() => peer.release(track))).pipe(Effect.map(({ track }) => track));
     }
@@ -779,7 +867,7 @@ export class Session {
         const self = this;
         return Effect.gen(function* () {
             const connection = yield* pure(() => self.currentReady());
-            const raw = yield* self.guard(connection, connection.peer.stats());
+            const raw = yield* self.guard(connection, connection.peer.stats);
             // Elapsed sampling time belongs to this Effect boundary, not the pure sampler.
             const atNanos = yield* Clock.monotonicTimeNanos;
             const atMs = Number(atNanos) / 1_000_000;
@@ -787,9 +875,9 @@ export class Session {
         });
     }
     rawStats() {
-        return pure(() => this.currentReady()).pipe(Effect.flatMap((c) => this.guard(c, c.peer.stats())));
+        return pure(() => this.currentReady()).pipe(Effect.flatMap((c) => this.guard(c, c.peer.stats)));
     }
-    upload(name, mimeType, bytes, timeoutMs = 60_000) {
+    upload(name, mimeType, bytes, options = {}) {
         const self = this;
         return Effect.suspend(() => {
             let progress = {
@@ -803,7 +891,6 @@ export class Session {
                     nonempty(name, "upload name");
                     nonempty(mimeType, "upload MIME type");
                     positiveLimit(bytes.byteLength, "upload size", self.uploadBound);
-                    positiveLimit(timeoutMs, "upload timeout", 600_000);
                     return { c, remote, copy: new Uint8Array(bytes) };
                 });
                 progress = { ...progress, allocation: "unknown" };
@@ -825,12 +912,22 @@ export class Session {
                 progress = { ...progress, notification: "submitted" };
                 return { file, transfer: "confirmed", notification: "submitted" };
             });
-            return withDeadline(operation, timeoutMs, "upload").pipe(Effect.mapError((e) => new ReactorError("Upload", e.message, {
+            return pure(() => options.uploadTimeout === undefined
+                ? self.uploadTimeout
+                : uploadTimeout(options.uploadTimeout)).pipe(Effect.flatMap((deadline) => withDeadline(operation, deadline, "upload")), Effect.mapError((e) => ReactorError.fromCode("Upload", e.message, {
                 ...e.context,
                 operation: "upload",
                 detail: { cause: e, progress: { ...progress } },
             })), Effect.ensuring(Effect.sync(() => self.emit({ _tag: "Upload", progress: Object.freeze({ ...progress }) }))));
-        });
+        }).pipe(
+        // The MIME type and size only: never the name or the bytes.
+        Effect.withSpan("reactor.session.upload", {
+            kind: "client",
+            attributes: {
+                "reactor.upload.mime_type": mimeType,
+                "reactor.upload.size": bytes.byteLength,
+            },
+        }, { captureStackTrace: false }));
     }
     /** Idempotent close. Owned-session termination is attempted once; response is not terminal proof. */
     close() {
@@ -842,27 +939,33 @@ export class Session {
             self.closeGate = gate;
             return Effect.gen(function* () {
                 self.lifecycle.transition("closing");
-                Deferred.doneUnsafe(self.lifecycle.closing, Effect.fail(new ReactorError("Closed", "session closing")));
+                Deferred.doneUnsafe(self.lifecycle.closing, Effect.fail(ReactorError.fromCode("Closed", "session closing")));
                 const report = yield* cleanupSession({
                     connection: self.lifecycle.connection,
                     scope: self.lifecycle.scope,
                     remote: self.remote,
                     http: self.http,
-                    commandTimeout: self.commandTimeout,
+                    replyTimeout: self.replyTimeout,
                     retire: (connection, error) => self.fail(connection, error),
                 });
                 self.closeReport = report;
                 self.lifecycle.transition("closed");
                 self.observations.end();
                 Deferred.doneUnsafe(gate, Effect.succeed(report));
-                try {
-                    self.options.onClose?.(report);
-                }
-                catch {
-                    /* Consumer callbacks cannot undo or stall cleanup. */
-                }
+                // Consumer callbacks cannot undo or stall cleanup.
+                yield* Effect.ignore(Effect.try(() => self.options.onClose?.(report)));
+                yield* Effect.annotateCurrentSpan({
+                    "reactor.close.local_closed": report.localClosed,
+                    "reactor.close.allocation": report.allocation,
+                    ...terminationAttributes(report.remote),
+                });
                 return report;
-            });
+            }).pipe(
+            // Only the close that runs cleanup is traced; a later close awaits its report.
+            Effect.withSpan("reactor.session.close", {
+                kind: "client",
+                attributes: self.remote.id === undefined ? {} : { "reactor.session.id": self.remote.id },
+            }, { captureStackTrace: false }));
         }));
     }
     isKnownTerminal() {