keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/app/transport/tcp-egress.js

@@ -0,0 +1,377 @@
+/** Concrete TCP connections and pull-driven writers; applications compose receive work. */
+import { framePayload } from "cesr-ts";
+import { createConnection } from "node:net";
+import { call, resource } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { abortable, rethrowCleanupFailure } from "../runtime/abortable.js";
+import { chunkBytes } from "./byte-source.js";
+import { TransportError } from "./transport-error.js";
+/**
+ * Validate actual chunk sizes and deadlines before acquiring a socket.
+ *
+ * @param value Requested byte count or duration.
+ * @param name Option name used in the validation error.
+ * @returns The unchanged validated value.
+ * @throws RangeError for nonpositive or unsafe integers.
+ */
+function positive(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError(`${name} must be a positive safe integer`);
+    return value;
+}
+/**
+ * Open a socket and lend it to application-owned receive/transmit operations.
+ * This resource does not parse incoming data. Its scope destroys the socket and
+ * joins native close after child operations stop. Receive EOF can leave output
+ * open; the borrower must complete or cancel both directions before releasing it.
+ *
+ * @param url TCP endpoint with an explicit port in the range 1–65535.
+ * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+ * @param options Connection timeout in milliseconds and optional upstream cancellation; default timeout is 30000.
+ * @returns A paused half-open-capable connection borrowed until the enclosing scope ends.
+ * @throws URL/option validation failures precede connection acquisition; connection errors retain their causes as TransportError.
+ */
+export function openTcpConnection(url, clock, options = {}) {
+    return resource(function* (provide) {
+        const parsed = new URL(url), port = Number(parsed.port);
+        if (parsed.protocol !== "tcp:" || !Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new ValidationError(`TCP output requires tcp: with a valid port: ${url}`);
+        }
+        const timeout = positive(options.connectTimeoutMs ?? 30000, "connectTimeoutMs");
+        const controller = new AbortController();
+        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+        signal.throwIfAborted();
+        const socket = createConnection({ host: parsed.hostname, port, allowHalfOpen: true });
+        socket.pause();
+        const closed = new Promise((resolve) => socket.once("close", resolve));
+        /** Cancellation destroys the handle; the enclosing resource joins native close. */
+        const destroy = () => socket.destroy();
+        /**
+         * Stop both directions with the original owner failure or cancellation.
+         * @param reason Failure to expose through the connection signal; omitted for ordinary teardown.
+         */
+        const close = (reason) => {
+            controller.abort(reason);
+            socket.destroy();
+        };
+        /** Detect premature directional closure even when no parser currently holds the readable side. */
+        const disconnected = () => {
+            if (!socket.writableFinished)
+                close(new TransportError(`TCP ${url} closed before output completed`));
+            else if (!socket.readableEnded)
+                close(new TransportError(`TCP ${url} closed before receive EOF`));
+        };
+        /**
+         * Classify a native socket error at its actual connection boundary.
+         * @param cause Native socket failure retained as the TransportError cause.
+         */
+        const failed = (cause) => close(new TransportError(`TCP connection to ${url} failed`, { cause }));
+        socket.on("error", failed);
+        socket.on("close", disconnected);
+        signal.addEventListener("abort", destroy, { once: true });
+        let timer;
+        try {
+            yield* abortable(async (signal) => {
+                timer = clock.setTimeout(() => close(new TransportError(`TCP connect deadline exceeded for ${url}`)), timeout);
+                try {
+                    await interrupted(new Promise((resolve) => socket.once("connect", resolve)), signal);
+                }
+                finally {
+                    clock.clearTimeout(timer);
+                    timer = undefined;
+                }
+            }, signal);
+            yield* provide({ socket, closed, signal, close });
+        }
+        finally {
+            close();
+            yield* call(() => closed);
+            signal.removeEventListener("abort", destroy);
+            socket.off("error", failed);
+            socket.off("close", disconnected);
+        }
+    });
+}
+/**
+ * Send a resident value over the same concrete connection/source owner as streaming output.
+ *
+ * @param url TCP endpoint with an explicit port in the range 1–65535.
+ * @param bytes Resident signed wire bytes; chunking copies each outgoing segment.
+ * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+ * @param options Chunk size, connection/drain deadlines and optional cancellation; defaults are 64 KiB and 30-second deadlines.
+ * @returns Local output completion after owned socket cleanup joins; no receive-EOF or protocol-acceptance guarantee.
+ * @throws Source/serialization, transport, cancellation and cleanup errors propagate.
+ */
+export function sendCesrTcp(url, bytes, clock, options = {}) {
+    const cap = positive(options.maxChunkBytes ?? 65536, "maxChunkBytes");
+    return streamCesrTcp(url, (signal) => chunkBytes(bytes, { signal, maxChunkBytes: cap }), clock, options);
+}
+/**
+ * Transmit-only flow completes local drain, then its connection owner joins close without awaiting peer EOF.
+ *
+ * @param url TCP endpoint with an explicit port in the range 1–65535.
+ * @param source Creates a finite binary source with the owner's cancellation signal; must interrupt reads and finish cleanup when aborted.
+ * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+ * @param options Chunk size, connection/drain deadlines and optional cancellation; defaults are 64 KiB and 30-second deadlines.
+ * @returns Local output completion after owned socket cleanup joins; no receive-EOF or protocol-acceptance guarantee.
+ * @throws Source/serialization, transport, cancellation and cleanup errors propagate.
+ */
+export function streamCesrTcp(url, source, clock, options = {}) {
+    return call(function* () {
+        const connection = yield* openTcpConnection(url, clock, options);
+        connection.socket.resume();
+        return yield* finishTcpOutput(connection, source, clock, options, false);
+    });
+}
+/**
+ * Borrow an already hydrated frame through serializer completion, without reparsing.
+ *
+ * @param url TCP endpoint with an explicit port in the range 1–65535.
+ * @param frame Borrowed parsed frame; serialization preserves its body and attachments without reparsing.
+ * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+ * @param options Chunk size, connection/drain deadlines and optional cancellation; defaults are 64 KiB and 30-second deadlines.
+ * @returns Local output completion after owned socket cleanup joins; no receive-EOF or protocol-acceptance guarantee.
+ * @throws Source/serialization, transport, cancellation and cleanup errors propagate.
+ */
+export function sendCesrTcpFrame(url, frame, clock, options = {}) {
+    const cap = positive(options.maxChunkBytes ?? 65536, "maxChunkBytes");
+    return streamCesrTcp(url, async function* (signal) {
+        for await (const chunk of framePayload(frame).open(signal)) {
+            yield* chunkBytes(chunk, { signal, maxChunkBytes: cap });
+        }
+    }, clock, options);
+}
+/**
+ * Pull/write/drain one chunk at a time and join source cleanup before returning.
+ *
+ * @param socket Borrowed writable socket; this operation never calls end on successful completion.
+ * @param factory Creates a finite binary source with the owner's cancellation signal; must interrupt reads and finish cleanup when aborted.
+ * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+ * @param options Optional cancellation for this write/source lifetime.
+ * @returns Local output completion after source cleanup; caller still owns final socket close.
+ * @throws Source and write errors propagate; abort destroys the socket to interrupt pending output.
+ */
+export function writeCesrTcpSocket(socket, factory, clock, { signal } = {}) {
+    return abortable(async (signal) => {
+        /** Cancellation destroys the handle; the enclosing resource joins native close. */
+        const destroy = () => socket.destroy();
+        signal.addEventListener("abort", destroy, { once: true });
+        try {
+            await writeBorrowedSource(socket, factory, signal, clock, { fail: destroy });
+        }
+        finally {
+            signal.removeEventListener("abort", destroy);
+        }
+    }, signal);
+}
+/**
+ * Finish output on a duplex connection and wait for native connection close.
+ * The receiver must run concurrently and consume the peer's readable half. The
+ * messenger separately joins receive processing before reporting duplex success.
+ *
+ * @param connection Borrowed connection with an application-owned concurrent receive operation.
+ * @param factory Creates a finite binary source with the owner's cancellation signal; must interrupt reads and finish cleanup when aborted.
+ * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+ * @param options Absolute drain timeout starting at source EOF; default 30000 milliseconds.
+ * @returns Completion after local end and peer close, within the same drain deadline.
+ */
+export function sendCesrTcpSocket(connection, factory, clock, options = {}) {
+    return finishTcpOutput(connection, factory, clock, options, true);
+}
+/**
+ * Write the source, end the writable half, and apply the selected close boundary.
+ * One deadline starts at source EOF and is never refreshed by activity. Transmit-only
+ * completion does not wait for arbitrary peer EOF. Its enclosing connection resource
+ * subsequently joins close; a later receive reset does not revise completed local output.
+ *
+ * @param connection Connection whose signal and close operation own both directions.
+ * @param factory Creates a finite binary source with the owner's cancellation signal; must interrupt reads and finish cleanup when aborted.
+ * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+ * @param options Absolute post-source-EOF drain timeout in milliseconds.
+ * @param waitForPeer True for duplex: also await native close. False completes after local end.
+ * @returns Completion at the selected output boundary.
+ */
+function finishTcpOutput(connection, factory, clock, options, waitForPeer) {
+    const timeout = positive(options.drainTimeoutMs ?? 30000, "drainTimeoutMs");
+    return abortable(async (signal) => {
+        let timer;
+        let ending;
+        let endClosed;
+        /** Abort pending output before joining its end callback/close promise. */
+        const stop = () => connection.close(signal.reason);
+        signal.addEventListener("abort", stop, { once: true });
+        try {
+            await writeBorrowedSource(connection.socket, factory, signal, clock, {
+                fail: connection.close,
+                /**
+                 * Start the absolute output-drain deadline only after the source reports EOF.
+                 */
+                eof() {
+                    timer = clock.setTimeout(() => connection.close(new TransportError("TCP drain deadline exceeded")), timeout);
+                },
+            });
+            signal.throwIfAborted();
+            ending = new Promise((resolve, reject) => {
+                // Some runtimes omit end's callback after destroy; actual socket close still settles this I/O.
+                endClosed = () => reject(signal.aborted ? signal.reason : new TransportError("TCP closed before output ended"));
+                connection.socket.once("close", endClosed);
+                connection.socket.end((cause) => cause
+                    ? reject(signal.aborted ? signal.reason : new TransportError("TCP output end failed", { cause }))
+                    : resolve());
+            });
+            await interrupted(ending, signal);
+            ending = undefined;
+            if (waitForPeer)
+                await interrupted(connection.closed, signal);
+        }
+        finally {
+            if (signal.aborted)
+                connection.close(signal.reason);
+            await ending?.catch(() => undefined);
+            if (endClosed)
+                connection.socket.off("close", endClosed);
+            if (timer !== undefined)
+                clock.clearTimeout(timer);
+            signal.removeEventListener("abort", stop);
+        }
+    }, connection.signal);
+}
+/**
+ * Interrupt waiting without claiming to cancel or join the underlying I/O.
+ * The attached rejection observer avoids an unhandled late rejection; ownership
+ * and cleanup of the pending operation remain with the caller.
+ *
+ * @param pending Actual I/O promise; its owner must still join it after cancellation.
+ * @param signal Signal whose exact reason rejects the wait.
+ * @returns The I/O result if it wins the cancellation race.
+ */
+async function interrupted(pending, signal) {
+    signal.throwIfAborted();
+    let abort;
+    try {
+        return await Promise.race([
+            pending,
+            new Promise((_, reject) => {
+                abort = () => reject(signal.reason);
+                signal.addEventListener("abort", abort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
+/**
+ * Pull and flush one source chunk before requesting the next.
+ * Source EOF is distinct from socket.end. The owner receives failure before this
+ * helper joins pending reads/writes and returns the iterator, allowing it to unblock
+ * connection I/O. Distinct late cleanup failures remain visible.
+ *
+ * @param socket Borrowed socket; the connection owner handles final destruction and close.
+ * @param factory Creates a finite binary source with the owner's cancellation signal; must interrupt reads and finish cleanup when aborted.
+ * @param signal Owner cancellation, checked between pulls and native writes.
+ * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+ * @param hooks Optional owner notifications: eof runs on source exhaustion; fail interrupts the connection before cleanup joins.
+ * @returns Completion after write callbacks, backpressure drains and source cleanup.
+ */
+async function writeBorrowedSource(socket, factory, signal, clock, hooks = {}) {
+    let iterator;
+    let pendingRead;
+    let pendingWrite;
+    let timer;
+    let failure;
+    let work = 0;
+    /**
+     * Join late failures without reporting the same read/write rejection twice.
+     * @param error Rejection from outstanding source, iterator-return or native write cleanup.
+     */
+    const noteCleanup = (error) => {
+        if (failure && error === failure.error)
+            return;
+        try {
+            if (signal.aborted)
+                rethrowCleanupFailure(error, signal);
+            else
+                throw error;
+        }
+        catch (remaining) {
+            failure = {
+                error: failure ? new AggregateError([failure.error, remaining], "TCP source cleanup failed") : remaining,
+            };
+        }
+    };
+    try {
+        const source = await factory(signal);
+        iterator = source[Symbol.asyncIterator]();
+        signal.throwIfAborted();
+        while (true) {
+            // Empty/immediately resolved producers must not starve socket events or scope cancellation.
+            if (++work === 4096) {
+                work = 0;
+                await interrupted(new Promise((resolve) => {
+                    timer = clock.setTimeout(resolve, 0);
+                }), signal);
+                clock.clearTimeout(timer);
+                timer = undefined;
+            }
+            pendingRead = Promise.resolve(iterator.next());
+            const part = await interrupted(pendingRead, signal);
+            pendingRead = undefined;
+            signal.throwIfAborted();
+            if (part.done) {
+                hooks.eof?.();
+                break;
+            }
+            if (!(part.value instanceof Uint8Array))
+                throw new TypeError("TCP source must yield binary chunks");
+            if (!part.value.length)
+                continue;
+            let drain;
+            const drained = new Promise((resolve) => drain = resolve);
+            socket.once("drain", drain);
+            try {
+                let writable = false;
+                pendingWrite = new Promise((resolve, reject) => {
+                    writable = socket.write(part.value, (error) => {
+                        // Destroying our socket cancels its queued write; preserve that owner's abort reason.
+                        if (signal.aborted && (error?.code === "ECANCELED"
+                            || (signal.reason instanceof TransportError && signal.reason.cause === error))) {
+                            reject(signal.reason);
+                        }
+                        else if (error)
+                            reject(new TransportError("TCP output write failed", { cause: error }));
+                        else
+                            resolve();
+                    });
+                });
+                await interrupted(pendingWrite, signal);
+                pendingWrite = undefined;
+                if (!writable)
+                    await interrupted(drained, signal);
+            }
+            finally {
+                socket.removeListener("drain", drain);
+            }
+        }
+    }
+    catch (error) {
+        failure = { error };
+        hooks.fail?.(error);
+    }
+    finally {
+        try {
+            await pendingRead?.catch(noteCleanup);
+            await iterator?.return?.();
+        }
+        catch (error) {
+            noteCleanup(error);
+        }
+        finally {
+            await pendingWrite?.catch(noteCleanup);
+            if (timer !== undefined)
+                clock.clearTimeout(timer);
+        }
+    }
+    if (failure)
+        throw failure.error;
+}

package/esm/keri/npm/src/app/transport/tcp-messenger.js

@@ -0,0 +1,162 @@
+/** TCP attempt ownership: source transmission, optional signed replies and joined cleanup. */
+import { parse } from "cesr-ts";
+import { call, ensure, on, race, spawn } from "effection";
+import { rethrowCleanupFailure } from "../runtime/abortable.js";
+import { chunkBytes } from "./byte-source.js";
+import { socketBytes } from "./socket-source.js";
+import { openTcpConnection, sendCesrTcpSocket, streamCesrTcp, } from "./tcp-egress.js";
+/**
+ * Own one TCP delivery attempt and its parser/Kevery, following KERIpy TCPMessenger.
+ *
+ * Poster or WitnessInquisitor owns queued source work and delivery policy. This messenger runs
+ * directly in that owner's scope, keeps no message queue or sent history, and joins
+ * TX, optional RX, parser/source cleanup and connection close before returning.
+ * Finite bytes and pull sources share the same socket implementation.
+ *
+ * Transmit-only is the default. Reply mode starts RX before TX so the peer may
+ * answer during upload, then waits for receive EOF and dispatch completion.
+ * Those are socket/protocol-processing facts, not the calling workflow's
+ * accepted-state predicate or an application acknowledgement from the peer.
+ */
+export class TCPMessenger {
+    /**
+     * Bind the actual receiver and clock without opening a socket or acquiring stores.
+     *
+     * @param url TCP endpoint bound to this messenger.
+     * @param clock Borrowed clock for connection/drain deadlines and scheduler yields; durations are milliseconds.
+     * @param protocol Optional borrowed receiver; omitted means transmit-only.
+     */
+    constructor(url, clock, protocol = null) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: url
+        });
+        Object.defineProperty(this, "clock", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: clock
+        });
+        Object.defineProperty(this, "protocol", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: protocol
+        });
+        /** Input-owned Kevery (kvy); null when no protocol receive capability was supplied. */
+        Object.defineProperty(this, "kvy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.kvy = protocol?.makeKevery() ?? null;
+    }
+    /**
+     * Adapt resident signed wire to the same pull-source lifetime as streamed output.
+     *
+     * @param msg Resident signed CESR bytes; copied into chunks as transmitted.
+     * @param options Chunk size, connection/drain deadlines and optional cancellation; defaults are 64 KiB and 30-second deadlines. Set replies to process same-socket input through EOF; local controls KEL intake policy.
+     * @returns Completion after local output; reply mode also joins receive EOF and protocol processing.
+     * @throws Reply mode requires a protocol processor. Source/parser, dispatch, transport and cleanup failures propagate.
+     */
+    send(msg, options = {}) {
+        return this.sendSource((signal) => chunkBytes(msg, { signal, maxChunkBytes: options.maxChunkBytes }), options);
+    }
+    /**
+     * Send one source; duplex processing is explicit and never changes the local-only success contract.
+     *
+     * @param source Creates a finite binary source with the owner's cancellation signal; must interrupt reads and finish cleanup when aborted.
+     * @param options Chunk size, connection/drain deadlines and optional cancellation; defaults are 64 KiB and 30-second deadlines. Set replies to process same-socket input through EOF; local controls KEL intake policy.
+     * @returns Completion after local output; reply mode also joins receive EOF and protocol processing.
+     * @throws Reply mode requires a protocol processor. Source/parser, dispatch, transport and cleanup failures propagate.
+     */
+    sendSource(source, options = {}) {
+        if (options.replies)
+            return this.receiptDo(source, options);
+        return streamCesrTcp(this.url, source, this.clock, { ...options });
+    }
+    /**
+     * Send while processing replies, corresponding to KERIpy TCPMessenger.receiptDo/msgDo.
+     * Cancel and join concurrent RX/TX children before releasing the borrowed socket.
+     *
+     * @param source Creates a finite binary source with the owner's cancellation signal; must interrupt reads and finish cleanup when aborted.
+     * @param options Chunk size, connection/drain deadlines and optional cancellation; defaults are 64 KiB and 30-second deadlines. Set replies to process same-socket input through EOF; local controls KEL intake policy.
+     * @returns Completion after output, processed receive EOF and joined connection cleanup.
+     * @throws Missing receive capability, source/parser, dispatch, transport and cleanup failures propagate.
+     */
+    receiptDo(source, options) {
+        const protocol = this.protocol, kvy = this.kvy, clock = this.clock, url = this.url;
+        if (!protocol || !kvy)
+            throw new Error("TCP reply delivery requires a protocol processor");
+        return call(function* () {
+            const { replies: _replies, local = true, ...send } = options;
+            const connection = yield* openTcpConnection(url, clock, send);
+            // Register RX before TX so a peer can reply while the outbound source is still open.
+            const receive = yield* spawn(function* () {
+                yield* race([
+                    call(function* () {
+                        const controller = new AbortController();
+                        const signal = AbortSignal.any([controller.signal, connection.signal]);
+                        const frames = parse(socketBytes(connection.socket, { signal }));
+                        let pending;
+                        // Join the outstanding read before returning the parser/source iterator.
+                        yield* ensure(function* () {
+                            try {
+                                if (pending) {
+                                    try {
+                                        yield* call(() => pending);
+                                    }
+                                    catch (error) {
+                                        rethrowCleanupFailure(error, signal);
+                                    }
+                                }
+                            }
+                            finally {
+                                yield* call(() => frames.return());
+                            }
+                        });
+                        try {
+                            while (true) {
+                                signal.throwIfAborted();
+                                pending = frames.next();
+                                let next;
+                                try {
+                                    next = yield* call(() => pending);
+                                }
+                                catch (error) {
+                                    pending = undefined;
+                                    throw error;
+                                }
+                                pending = undefined;
+                                signal.throwIfAborted();
+                                if (next.done)
+                                    return;
+                                yield* protocol.dispatch(next.value, { local, escrows: true }, kvy);
+                            }
+                        }
+                        catch (error) {
+                            // Stop TX before parser/source cleanup can suspend on the failed direction.
+                            connection.close(error);
+                        }
+                        finally {
+                            controller.abort();
+                        }
+                    }),
+                    call(function* () {
+                        const abort = yield* on(connection.signal, "abort");
+                        connection.signal.throwIfAborted();
+                        yield* abort.next();
+                        throw connection.signal.reason;
+                    }),
+                ]);
+            });
+            yield* sendCesrTcpSocket(connection, source, clock, send);
+            // Duplex completion requires processed receive EOF; transmit-only never enters this path.
+            yield* receive;
+            connection.signal.throwIfAborted();
+        });
+    }
+}

package/esm/keri/npm/src/app/transport/tcp-stream-messenger.js

@@ -0,0 +1,40 @@
+import { chunkBytes } from "./byte-source.js";
+import { streamCesrTcp } from "./tcp-egress.js";
+/**
+ * KERIpy-style TCPStreamMessenger over one already prepared opaque payload.
+ * Borrow bytes until send finishes, with no CESR parsing, receive processor or
+ * private queue. Reuse the ordinary socket owner for connection, local drain and
+ * joined cancellation; producers retain preparation and any delivery policy.
+ */
+export class TCPStreamMessenger {
+    /** Construction borrows prepared bytes and opens no connection. */
+    constructor(url, clock, payload) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: url
+        });
+        Object.defineProperty(this, "clock", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: clock
+        });
+        Object.defineProperty(this, "payload", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: payload
+        });
+    }
+    /**
+     * Send all bytes and join local drain/cleanup without awaiting remote EOF.
+     * Completion does not prove the peer parsed, accepted or durably stored them.
+     * Connection/drain deadlines use the borrowed clock; source, transport and
+     * genuine cleanup failures propagate to this operation's caller.
+     */
+    send(options = {}) {
+        return streamCesrTcp(this.url, signal => chunkBytes(this.payload, { signal, maxChunkBytes: options.maxChunkBytes }), this.clock, options);
+    }
+}

package/esm/keri/npm/src/app/transport/transport-error.js

@@ -0,0 +1,14 @@
+/** A failure observed at a concrete network I/O boundary, retaining its original cause. */
+export class TransportError extends Error {
+    /**
+     * Preserve a concrete I/O failure for transport owners to classify.
+     * Protocol refusals and arbitrary parser/storage failures must not be wrapped here.
+     *
+     * @param message Description of the actual failing network boundary.
+     * @param options Native Error options, normally containing the original I/O cause.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = "TransportError";
+    }
+}