transport-io 0.0.1

package/dist/datagram.d.ts

@@ -0,0 +1,29 @@
+export interface Datagram {
+    readonly eventId: number;
+    readonly origin: number;
+    readonly sequence: number;
+    readonly payload: Uint8Array;
+}
+/**
+ * The usable size is a property of the path, not a constant, so it is queried at send
+ * time. The floor is used only when the transport reports nothing usable.
+ */
+export declare function maxDatagramPayload(reportedMax: number): number;
+export declare function encodeDatagram(dg: Datagram, reportedMax: number): Uint8Array;
+export declare function decodeDatagram(bytes: Uint8Array): Datagram;
+/**
+ * Last-write-wins keyed on (origin, event). PROTOCOL.md §7.3.
+ *
+ * Wrap is treated as circular over the 32-bit space: a difference greater than 2^31 reads
+ * as wrap rather than regression.
+ */
+export declare class SequenceGate {
+    #private;
+    get staleReceived(): number;
+    /** Returns true when the datagram is fresh and should be delivered. */
+    accept(origin: number, eventId: number, sequence: number, now: number): boolean;
+    /** A receiver discards (origin, event) state after this idle, so origins can be reused. */
+    sweep(now: number, retentionMs: number): void;
+    get tracked(): number;
+}
+//# sourceMappingURL=datagram.d.ts.map

package/dist/datagram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datagram.d.ts","sourceRoot":"","sources":["../src/datagram.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAkC5E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,CA+B1D;AAED;;;;;GAKG;AACH,qBAAa,YAAY;;IAIvB,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,uEAAuE;IACvE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAa9E;IAED,2FAA2F;IAC3F,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAI5C;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF"}

package/dist/datagram.js

@@ -0,0 +1,92 @@
+/** Datagram header. PROTOCOL.md §7.1 — codec, event id, origin, sequence, then payload. */
+import { TransportError } from './errors.js';
+import { Codec, DATAGRAM_CONSERVATIVE_FLOOR, DATAGRAM_HEADER_BYTES, EVENT_ID_NOT_APPLICABLE, } from './protocol.js';
+/**
+ * The usable size is a property of the path, not a constant, so it is queried at send
+ * time. The floor is used only when the transport reports nothing usable.
+ */
+export function maxDatagramPayload(reportedMax) {
+    const effective = reportedMax > 0 ? reportedMax : DATAGRAM_CONSERVATIVE_FLOOR;
+    return Math.max(0, effective - DATAGRAM_HEADER_BYTES);
+}
+export function encodeDatagram(dg, reportedMax) {
+    if (dg.payload.byteLength === 0) {
+        throw new TransportError('WT_PROTOCOL_ERROR', 'a datagram payload of zero bytes is not representable', 'Send at least one byte. A zero-length write freezes some transports.');
+    }
+    if (dg.eventId === EVENT_ID_NOT_APPLICABLE) {
+        throw new TransportError('WT_PROTOCOL_ERROR', 'event id 0 is not valid on the datagram lane', 'Datagrams always carry a contract event. Check the event table.');
+    }
+    const limit = maxDatagramPayload(reportedMax);
+    if (dg.payload.byteLength > limit) {
+        // The transport accepts an oversized datagram, discards it, and reports success, so
+        // this check is the only thing standing between a user and a silent drop.
+        throw new TransportError('WT_DATAGRAM_TOO_LARGE', `payload is ${dg.payload.byteLength} bytes and the path allows ${limit}`, 'Shorten the payload, or declare this event on the stream lane where size is not capped this tightly.');
+    }
+    const out = new Uint8Array(DATAGRAM_HEADER_BYTES + dg.payload.byteLength);
+    const view = new DataView(out.buffer);
+    view.setUint8(0, Codec.JSON);
+    view.setUint32(1, dg.eventId, false);
+    view.setUint32(5, dg.origin, false);
+    view.setUint32(9, dg.sequence, false);
+    out.set(dg.payload, DATAGRAM_HEADER_BYTES);
+    return out;
+}
+export function decodeDatagram(bytes) {
+    if (bytes.byteLength <= DATAGRAM_HEADER_BYTES) {
+        throw new TransportError('WT_PROTOCOL_ERROR', `datagram is ${bytes.byteLength} bytes, at or below the ${DATAGRAM_HEADER_BYTES}-byte header`, 'A datagram must carry at least one payload byte. See PROTOCOL.md §7.2.');
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const codec = view.getUint8(0);
+    if (codec !== Codec.JSON) {
+        throw new TransportError('WT_UNSUPPORTED_CODEC', `codec 0x${codec.toString(16).padStart(2, '0')} is not supported`, 'This version speaks JSON only. Send codec 0x01.');
+    }
+    const eventId = view.getUint32(1, false);
+    if (eventId === EVENT_ID_NOT_APPLICABLE) {
+        throw new TransportError('WT_PROTOCOL_ERROR', 'event id 0 is not valid on the datagram lane', 'Check the sender against PROTOCOL.md §7.2.');
+    }
+    return {
+        eventId,
+        origin: view.getUint32(5, false),
+        sequence: view.getUint32(9, false),
+        payload: bytes.slice(DATAGRAM_HEADER_BYTES),
+    };
+}
+/**
+ * Last-write-wins keyed on (origin, event). PROTOCOL.md §7.3.
+ *
+ * Wrap is treated as circular over the 32-bit space: a difference greater than 2^31 reads
+ * as wrap rather than regression.
+ */
+export class SequenceGate {
+    #seen = new Map();
+    #staleReceived = 0;
+    get staleReceived() {
+        return this.#staleReceived;
+    }
+    /** Returns true when the datagram is fresh and should be delivered. */
+    accept(origin, eventId, sequence, now) {
+        const key = `${origin}:${eventId}`;
+        const prev = this.#seen.get(key);
+        if (prev !== undefined) {
+            const delta = (sequence - prev.seq) >>> 0;
+            const isNewer = delta !== 0 && delta < 0x80000000;
+            if (!isNewer) {
+                this.#staleReceived++;
+                return false;
+            }
+        }
+        this.#seen.set(key, { seq: sequence, at: now });
+        return true;
+    }
+    /** A receiver discards (origin, event) state after this idle, so origins can be reused. */
+    sweep(now, retentionMs) {
+        for (const [key, v] of this.#seen) {
+            if (now - v.at >= retentionMs)
+                this.#seen.delete(key);
+        }
+    }
+    get tracked() {
+        return this.#seen.size;
+    }
+}
+//# sourceMappingURL=datagram.js.map

package/dist/datagram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datagram.js","sourceRoot":"","sources":["../src/datagram.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/** Every error carries a stable code and a sentence saying what to do about it. */
+export type TransportErrorCode = 'WT_NO_SUPPORT' | 'WT_DATAGRAM_TOO_LARGE' | 'WT_ROOM_NOT_JOINED' | 'WT_SESSION_CLOSED' | 'WT_ABORTED' | 'WT_HANDLER_ERROR' | 'WT_PROTOCOL_ERROR' | 'WT_UNSUPPORTED_CODEC' | 'WT_PAYLOAD_TOO_LARGE' | 'WT_HANDSHAKE_INCOMPLETE' | 'WT_UNKNOWN_EVENT' | 'WT_VALIDATION_FAILED' | 'WT_PROTOCOL_VERSION_MISMATCH' | 'WT_CONTRACT_MISMATCH' | 'WT_HANDSHAKE_TIMEOUT' | 'WT_PEER_TOO_SLOW' | 'WT_TOO_MANY_STREAMS' | 'WT_RELIABILITY_REFUSED';
+export declare class TransportError extends Error {
+    readonly code: TransportErrorCode;
+    readonly remedy: string;
+    constructor(code: TransportErrorCode, message: string, remedy: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,uBAAuB,GACvB,oBAAoB,GACpB,mBAAmB,GACnB,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,sBAAsB,GACtB,sBAAsB,GACtB,yBAAyB,GACzB,kBAAkB,GAClB,sBAAsB,GACtB,8BAA8B,GAC9B,sBAAsB,GACtB,sBAAsB,GACtB,kBAAkB,GAClB,qBAAqB,GACrB,wBAAwB,CAAA;AAE5B,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB,YAAY,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAKpE;CACF"}

package/dist/errors.js

@@ -0,0 +1,11 @@
+export class TransportError extends Error {
+    code;
+    remedy;
+    constructor(code, message, remedy) {
+        super(`${code}: ${message} — ${remedy}`);
+        this.name = 'TransportError';
+        this.code = code;
+        this.remedy = remedy;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAqBA,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAoB;IACxB,MAAM,CAAQ;IAEvB,YAAY,IAAwB,EAAE,OAAe,EAAE,MAAc;QACnE,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,MAAM,MAAM,EAAE,CAAC,CAAA;QACxC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF"}

package/dist/framer.d.ts

@@ -0,0 +1,21 @@
+import { FrameType } from './protocol.ts';
+export interface Frame {
+    readonly type: FrameType;
+    readonly codec: number;
+    readonly eventId: number;
+    readonly payload: Uint8Array;
+}
+/** §5.1 — the cap is per frame type: a call is the documented home for a large payload. */
+export declare function maxPayloadFor(type: FrameType): number;
+export declare function encodeFrame(frame: Frame): Uint8Array;
+/**
+ * Incremental decoder. Feed it whatever the transport hands you — a fragment, several
+ * frames, or a frame split across many reads — and it yields whole frames only.
+ */
+export declare class FrameDecoder {
+    #private;
+    /** Bytes held pending a complete frame. Exposed so tests can assert nothing leaks. */
+    get buffered(): number;
+    push(chunk: Uint8Array): Frame[];
+}
+//# sourceMappingURL=framer.d.ts.map

package/dist/framer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framer.d.ts","sourceRoot":"","sources":["../src/framer.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,SAAS,EAOV,MAAM,eAAe,CAAA;AAEtB,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAC7B;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAIrD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,UAAU,CA2BpD;AAED;;;GAGG;AACH,qBAAa,YAAY;;IAGvB,sFAAsF;IACtF,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,EAAE,CAmF/B;CACF"}

package/dist/framer.js

@@ -0,0 +1,110 @@
+/**
+ * Stream framing, implemented to PROTOCOL.md §5.
+ *
+ * QUIC streams are byte streams and do not preserve write boundaries. Measured on the
+ * reference transport, 51 writes arrived as 217 reads, and the large write fragmented
+ * while the small ones happened to survive — which is the worst case, because naive
+ * boundary-trusting code passes in development and fails under load. The length prefix
+ * is the only thing that recovers frame boundaries, and nobody using this library should
+ * ever have to think about it.
+ */
+import { TransportError } from './errors.js';
+import { Codec, FrameType, isFrameType, LENGTH_PREFIX_BYTES, MAX_CALL_PAYLOAD_BYTES, MAX_EMIT_PAYLOAD_BYTES, MIN_LENGTH, STREAM_HEADER_BYTES, } from './protocol.js';
+/** §5.1 — the cap is per frame type: a call is the documented home for a large payload. */
+export function maxPayloadFor(type) {
+    return type === FrameType.CALL_REQUEST || type === FrameType.CALL_RESPONSE
+        ? MAX_CALL_PAYLOAD_BYTES
+        : MAX_EMIT_PAYLOAD_BYTES;
+}
+export function encodeFrame(frame) {
+    const payloadLength = frame.payload.byteLength;
+    if (payloadLength === 0) {
+        throw new TransportError('WT_PROTOCOL_ERROR', 'a frame payload of zero bytes is not representable', 'Stream close terminates a response, so no zero-length sentinel is needed. Send at least one byte.');
+    }
+    const cap = maxPayloadFor(frame.type);
+    if (payloadLength > cap) {
+        throw new TransportError('WT_PAYLOAD_TOO_LARGE', `payload is ${payloadLength} bytes and the cap for this frame type is ${cap}`, 'Use a call rather than an emit, or split the payload.');
+    }
+    const out = new Uint8Array(LENGTH_PREFIX_BYTES + STREAM_HEADER_BYTES + payloadLength);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, STREAM_HEADER_BYTES + payloadLength, false);
+    view.setUint8(4, frame.type);
+    view.setUint8(5, frame.codec);
+    view.setUint16(6, 0, false); // Reserved, MUST be zero
+    view.setUint32(8, frame.eventId, false);
+    out.set(frame.payload, LENGTH_PREFIX_BYTES + STREAM_HEADER_BYTES);
+    return out;
+}
+/**
+ * Incremental decoder. Feed it whatever the transport hands you — a fragment, several
+ * frames, or a frame split across many reads — and it yields whole frames only.
+ */
+export class FrameDecoder {
+    #buf = new Uint8Array(0);
+    /** Bytes held pending a complete frame. Exposed so tests can assert nothing leaks. */
+    get buffered() {
+        return this.#buf.byteLength;
+    }
+    push(chunk) {
+        if (chunk.byteLength > 0) {
+            const merged = new Uint8Array(this.#buf.byteLength + chunk.byteLength);
+            merged.set(this.#buf, 0);
+            merged.set(chunk, this.#buf.byteLength);
+            this.#buf = merged;
+        }
+        const frames = [];
+        for (;;) {
+            if (this.#buf.byteLength < LENGTH_PREFIX_BYTES)
+                break;
+            const view = new DataView(this.#buf.buffer, this.#buf.byteOffset, this.#buf.byteLength);
+            const length = view.getUint32(0, false);
+            if (length < MIN_LENGTH) {
+                throw new TransportError('WT_PROTOCOL_ERROR', `frame length ${length} is below the minimum of ${MIN_LENGTH}`, 'A length of 0 or a header-only frame is a protocol error. Check the sender against PROTOCOL.md §5.1.');
+            }
+            const payloadLength = length - STREAM_HEADER_BYTES;
+            // §5.3 gives calls 16 MiB and everything else 1 MiB. This enforced the call cap for
+            // every frame type, so a peer could declare 16 MiB on the emit lane — sixteen times
+            // its documented cap — and the decoder would buffer toward it.
+            //
+            // The type byte is at offset 4, so it is readable as soon as five bytes are, which is
+            // before any payload has to be held. Until then the universal cap applies, which
+            // bounds the wait rather than assuming the generous case.
+            const type_ = this.#buf.byteLength > 4 ? view.getUint8(4) : undefined;
+            const cap = type_ === undefined ||
+                type_ === FrameType.CALL_REQUEST ||
+                type_ === FrameType.CALL_RESPONSE ||
+                type_ === FrameType.CALL_ERROR
+                ? MAX_CALL_PAYLOAD_BYTES
+                : MAX_EMIT_PAYLOAD_BYTES;
+            if (payloadLength > cap) {
+                throw new TransportError('WT_PAYLOAD_TOO_LARGE', `frame declares a ${payloadLength}-byte payload, above the ${cap}-byte cap for its type`, 'Split the payload, or use a call. See PROTOCOL.md §5.3.');
+            }
+            const total = LENGTH_PREFIX_BYTES + length;
+            if (this.#buf.byteLength < total)
+                break; // partial frame: wait for more bytes
+            const type = view.getUint8(4);
+            if (!isFrameType(type)) {
+                throw new TransportError('WT_PROTOCOL_ERROR', `frame type 0x${type.toString(16).padStart(2, '0')} is reserved or unknown`, 'Check the sender against the frame type table in PROTOCOL.md §5.2.');
+            }
+            const codec = view.getUint8(5);
+            if (codec !== Codec.JSON) {
+                throw new TransportError('WT_UNSUPPORTED_CODEC', `codec 0x${codec.toString(16).padStart(2, '0')} is not supported`, 'This version speaks JSON only. Send codec 0x01.');
+            }
+            if (view.getUint16(6, false) !== 0) {
+                throw new TransportError('WT_PROTOCOL_ERROR', 'the reserved header field is not zero', 'Zero bytes 6 and 7 of the frame header. See PROTOCOL.md §5.1.');
+            }
+            const eventId = view.getUint32(8, false);
+            const payloadStart = LENGTH_PREFIX_BYTES + STREAM_HEADER_BYTES;
+            // Copy rather than subarray: the caller keeps this past the next push().
+            frames.push({
+                type,
+                codec,
+                eventId,
+                payload: this.#buf.slice(payloadStart, total),
+            });
+            this.#buf = this.#buf.slice(total);
+        }
+        return frames;
+    }
+}
+//# sourceMappingURL=framer.js.map

package/dist/framer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framer.js","sourceRoot":"","sources":["../src/framer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EACL,KAAK,EACL,SAAS,EACT,WAAW,EACX,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,UAAU,EACV,mBAAmB,GACpB,MAAM,eAAe,CAAA;AAStB,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAAC,IAAe;IAC3C,OAAO,IAAI,KAAK,SAAS,CAAC,YAAY,IAAI,IAAI,KAAK,SAAS,CAAC,aAAa;QACxE,CAAC,CAAC,sBAAsB;QACxB,CAAC,CAAC,sBAAsB,CAAA;AAC5B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAA;IAC9C,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,cAAc,CACtB,mBAAmB,EACnB,oDAAoD,EACpD,mGAAmG,CACpG,CAAA;IACH,CAAC;IACD,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACrC,IAAI,aAAa,GAAG,GAAG,EAAE,CAAC;QACxB,MAAM,IAAI,cAAc,CACtB,sBAAsB,EACtB,cAAc,aAAa,6CAA6C,GAAG,EAAE,EAC7E,uDAAuD,CACxD,CAAA;IACH,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,mBAAmB,GAAG,mBAAmB,GAAG,aAAa,CAAC,CAAA;IACrF,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACrC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,mBAAmB,GAAG,aAAa,EAAE,KAAK,CAAC,CAAA;IAC7D,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;IAC5B,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IAC7B,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA,CAAC,yBAAyB;IACrD,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACvC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CAAC,CAAA;IACjE,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,YAAY;IACvB,IAAI,GAAe,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;IAEpC,sFAAsF;IACtF,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAA;IAC7B,CAAC;IAED,IAAI,CAAC,KAAiB;QACpB,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,CAAA;YACtE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;YACxB,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;YACvC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAA;QACpB,CAAC;QAED,MAAM,MAAM,GAAY,EAAE,CAAA;QAC1B,SAAS,CAAC;YACR,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,mBAAmB;gBAAE,MAAK;YACrD,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;YACvF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;YAEvC,IAAI,MAAM,GAAG,UAAU,EAAE,CAAC;gBACxB,MAAM,IAAI,cAAc,CACtB,mBAAmB,EACnB,gBAAgB,MAAM,4BAA4B,UAAU,EAAE,EAC9D,sGAAsG,CACvG,CAAA;YACH,CAAC;YACD,MAAM,aAAa,GAAG,MAAM,GAAG,mBAAmB,CAAA;YAClD,oFAAoF;YACpF,oFAAoF;YACpF,+DAA+D;YAC/D,EAAE;YACF,sFAAsF;YACtF,iFAAiF;YACjF,0DAA0D;YAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;YACrE,MAAM,GAAG,GACP,KAAK,KAAK,SAAS;gBACnB,KAAK,KAAK,SAAS,CAAC,YAAY;gBAChC,KAAK,KAAK,SAAS,CAAC,aAAa;gBACjC,KAAK,KAAK,SAAS,CAAC,UAAU;gBAC5B,CAAC,CAAC,sBAAsB;gBACxB,CAAC,CAAC,sBAAsB,CAAA;YAC5B,IAAI,aAAa,GAAG,GAAG,EAAE,CAAC;gBACxB,MAAM,IAAI,cAAc,CACtB,sBAAsB,EACtB,oBAAoB,aAAa,4BAA4B,GAAG,wBAAwB,EACxF,yDAAyD,CAC1D,CAAA;YACH,CAAC;YAED,MAAM,KAAK,GAAG,mBAAmB,GAAG,MAAM,CAAA;YAC1C,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,KAAK;gBAAE,MAAK,CAAC,qCAAqC;YAE7E,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAC7B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvB,MAAM,IAAI,cAAc,CACtB,mBAAmB,EACnB,gBAAgB,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,yBAAyB,EAC3E,oEAAoE,CACrE,CAAA;YACH,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAC9B,IAAI,KAAK,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;gBACzB,MAAM,IAAI,cAAc,CACtB,sBAAsB,EACtB,WAAW,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,mBAAmB,EACjE,iDAAiD,CAClD,CAAA;YACH,CAAC;YACD,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,cAAc,CACtB,mBAAmB,EACnB,uCAAuC,EACvC,+DAA+D,CAChE,CAAA;YACH,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;YACxC,MAAM,YAAY,GAAG,mBAAmB,GAAG,mBAAmB,CAAA;YAC9D,yEAAyE;YACzE,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI;gBACJ,KAAK;gBACL,OAAO;gBACP,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC;aAC9C,CAAC,CAAA;YACF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACpC,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

package/dist/handshake.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Handshake. PROTOCOL.md §4 — frame 0 of the emit stream.
+ *
+ * Being frame 0 of a stream that already exists is what removes the early-traffic race:
+ * in-order delivery within a stream means nothing can arrive before it. There is no
+ * separate handshake stream and no rule guarding one.
+ */
+import type { EventTable, Lane } from './contract.ts';
+export type WireEvent = readonly [name: string, id: number, lane: Lane];
+export interface HandshakePayload {
+    readonly v: number;
+    readonly feat: readonly string[];
+    readonly events: readonly WireEvent[];
+}
+/** Reserved and unimplemented in this version. PROTOCOL.md §4.2. */
+export declare const RESERVED_FEATURES: readonly string[];
+export declare function buildHandshake(table: EventTable, feat?: readonly string[]): HandshakePayload;
+export interface Negotiated {
+    readonly feat: readonly string[];
+    /** Events the peer knows that we do not. Sending one yields WT_UNKNOWN_EVENT, not a fault. */
+    readonly peerOnly: readonly string[];
+    /** Events we know that the peer does not. */
+    readonly localOnly: readonly string[];
+}
+export declare function parseHandshake(value: unknown): HandshakePayload;
+/**
+ * PROTOCOL.md §4.3 and §4.4. The event table is validated first and conflicts are fatal;
+ * `feat` is negotiated second and is never fatal.
+ *
+ * Comparison is per event. A whole-contract equality check would refuse a session over an
+ * added event, which turns every additive change into a fleet-wide cutover.
+ */
+export declare function negotiate(local: HandshakePayload, peer: HandshakePayload): Negotiated;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAIrD,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;CACtC;AAED,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAI9C,CAAA;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE,SAAS,MAAM,EAAO,GAC3B,gBAAgB,CAElB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CACtC;AAYD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAkB/D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,GAAG,UAAU,CA+CrF"}

package/dist/handshake.js

@@ -0,0 +1,79 @@
+/**
+ * Handshake. PROTOCOL.md §4 — frame 0 of the emit stream.
+ *
+ * Being frame 0 of a stream that already exists is what removes the early-traffic race:
+ * in-order delivery within a stream means nothing can arrive before it. There is no
+ * separate handshake stream and no rule guarding one.
+ */
+import { TransportError } from './errors.js';
+import { PROTOCOL_VERSION } from './protocol.js';
+/** Reserved and unimplemented in this version. PROTOCOL.md §4.2. */
+export const RESERVED_FEATURES = [
+    'emit-per-room',
+    'codec-msgpack',
+    'session-resume',
+];
+export function buildHandshake(table, feat = []) {
+    return { v: PROTOCOL_VERSION, feat, events: table.wire() };
+}
+function isWireEvent(v) {
+    return (Array.isArray(v) &&
+        v.length === 3 &&
+        typeof v[0] === 'string' &&
+        typeof v[1] === 'number' &&
+        (v[2] === 'stream' || v[2] === 'datagram'));
+}
+export function parseHandshake(value) {
+    const bad = (why) => {
+        throw new TransportError('WT_PROTOCOL_ERROR', `malformed handshake: ${why}`, 'Check the sender against PROTOCOL.md §4.1.');
+    };
+    if (typeof value !== 'object' || value === null)
+        return bad('not an object');
+    const { v, feat, events } = value;
+    if (typeof v !== 'number')
+        return bad('`v` is not a number');
+    if (!Array.isArray(feat) || feat.some((f) => typeof f !== 'string')) {
+        return bad('`feat` is not an array of strings');
+    }
+    if (!Array.isArray(events) || !events.every(isWireEvent)) {
+        return bad('`events` is not an array of [name, id, lane] triples');
+    }
+    return { v, feat: feat, events: events };
+}
+/**
+ * PROTOCOL.md §4.3 and §4.4. The event table is validated first and conflicts are fatal;
+ * `feat` is negotiated second and is never fatal.
+ *
+ * Comparison is per event. A whole-contract equality check would refuse a session over an
+ * added event, which turns every additive change into a fleet-wide cutover.
+ */
+export function negotiate(local, peer) {
+    if (peer.v !== local.v) {
+        throw new TransportError('WT_PROTOCOL_VERSION_MISMATCH', `peer speaks protocol v${peer.v} and this is v${local.v}`, 'Protocol v0 is unstable and requires an exact match. Deploy both sides together.');
+    }
+    const localByName = new Map(local.events.map((e) => [e[0], e]));
+    const localById = new Map(local.events.map((e) => [e[1], e]));
+    const peerByName = new Map(peer.events.map((e) => [e[0], e]));
+    for (const [name, id, lane] of peer.events) {
+        const mine = localByName.get(name);
+        if (mine !== undefined) {
+            if (mine[2] !== lane) {
+                throw new TransportError('WT_CONTRACT_MISMATCH', `event '${name}' is '${mine[2]}' here and '${lane}' at the peer`, 'The two sides disagree about a delivery guarantee. Deploy the same contract on both.');
+            }
+            if (mine[1] !== id) {
+                throw new TransportError('WT_CONTRACT_MISMATCH', `event '${name}' is id ${mine[1]} here and ${id} at the peer`, 'One side has an explicit `id` override the other lacks. Align the contract.');
+            }
+            continue;
+        }
+        const collides = localById.get(id);
+        if (collides !== undefined) {
+            throw new TransportError('WT_CONTRACT_MISMATCH', `peer event '${name}' has id ${id}, which is '${collides[0]}' here`, 'Two different events share an id across the two sides. Align the contract.');
+        }
+    }
+    return {
+        feat: local.feat.filter((f) => peer.feat.includes(f)),
+        peerOnly: peer.events.filter((e) => !localByName.has(e[0])).map((e) => e[0]),
+        localOnly: local.events.filter((e) => !peerByName.has(e[0])).map((e) => e[0]),
+    };
+}
+//# sourceMappingURL=handshake.js.map

package/dist/handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"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"}

package/dist/hub.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Rooms and fan-out. Server-side.
+ *
+ * A frame is encoded ONCE and the same bytes go to every local member and onto the bus.
+ * That is what makes origin-scoped datagram sequencing correct: a per-recipient re-encode
+ * would be needed if the sequence belonged to the receiving session, and the adapter
+ * boundary forbids it anyway.
+ *
+ * Local peers are delivered directly rather than via a bus round-trip: lower latency and
+ * no dependency on the adapter echoing. The documented consequence is that local peers
+ * observe a message slightly before remote ones.
+ */
+import type { Adapter, PeerId } from './adapter.ts';
+import type { EventTable } from './contract.ts';
+import type { Session } from './session.ts';
+export interface BroadcastArgs {
+    readonly origin: number;
+    readonly except?: readonly PeerId[];
+}
+export declare class Hub {
+    #private;
+    constructor(adapter: Adapter, table: EventTable);
+    join(room: string, id: PeerId, session: Session): Promise<void>;
+    leave(room: string, id: PeerId): Promise<void>;
+    /**
+     * Teardown runs to completion whatever the bus does.
+     *
+     * `broadcast` already wrapped its adapter call; this did not, so a rejection on the
+     * first room threw straight out of the loop — rooms 2..N kept their `Member` record,
+     * each holding a live Session, and `#peerRooms.delete(id)` never ran. Nothing retries,
+     * because `conn.closed` resolves exactly once. A later `to(room).emit()` then fanned
+     * frames into a session that was already gone.
+     *
+     * The local half is what this node's correctness depends on, so it is unconditional.
+     * The bus half is best-effort by nature: the peer's connection is already gone, and a
+     * bus that cannot be told now will not be told by us failing here.
+     */
+    removePeer(id: PeerId): Promise<void>;
+    rooms(id: PeerId): readonly string[];
+    memberCount(room: string): number;
+    broadcast(room: string, event: string, payload: unknown, args: BroadcastArgs): Promise<void>;
+}
+//# sourceMappingURL=hub.d.ts.map

package/dist/hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.d.ts","sourceRoot":"","sources":["../src/hub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,EAAE,MAAM,cAAc,CAAA;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAK/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAO3C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAED,qBAAa,GAAG;;IAOd,YAAY,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAY9C;IAEK,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCpE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnD;IAED;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS1C;IAED,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEnC;IAED,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhC;IAEK,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAqCf;CAyBF"}

package/dist/hub.js

@@ -0,0 +1,149 @@
+import { encodePayload } from './codec.js';
+import { encodeDatagram } from './datagram.js';
+import { TransportError } from './errors.js';
+import { encodeFrame } from './framer.js';
+import { Codec, DATAGRAM_CONSERVATIVE_FLOOR, FrameType } from './protocol.js';
+export class Hub {
+    #adapter;
+    #table;
+    #rooms = new Map();
+    #peerRooms = new Map();
+    #seqs = new Map();
+    constructor(adapter, table) {
+        this.#adapter = adapter;
+        this.#table = table;
+        // A node receiving its own publish back is normal, so core dedupes by origin node
+        // rather than relying on the adapter to suppress it — and dedupes against the
+        // *adapter's* id, which is the one stamped into the envelope. It used to compare
+        // against the Server's separate `nodeId`, so any deployment where those differed
+        // delivered every local broadcast twice, in silence.
+        this.#adapter.onRemote((e) => {
+            if (e.nodeId === this.#adapter.nodeId)
+                return;
+            this.#deliverLocal(e.room, e.frame, e.lane, e.except ?? []);
+        });
+    }
+    async join(room, id, session) {
+        // `onSession(async peer => { await lookup(); await peer.join(room) })` is the pattern
+        // the README teaches, so a client dropping during the lookup lands here routinely.
+        // Such a join used to succeed and be retained for ever: the JOIN notify write died in
+        // the emit path's swallowing catch, so nothing surfaced, and the teardown that would
+        // have removed it had already run.
+        if (session.disposed) {
+            throw new TransportError('WT_SESSION_CLOSED', `peer ${id} disconnected before it could join '${room}'`, 'Check the peer is still connected after any await, or ignore this — it is routine.');
+        }
+        let members = this.#rooms.get(room);
+        if (members === undefined) {
+            members = new Map();
+            this.#rooms.set(room, members);
+        }
+        // The bus first, local state second. Mutating before the await left a rejected join
+        // half-applied: the hub fanned broadcasts to a peer the bus had no record of, and the
+        // client was never notified it had joined. For a room whose join is gated on
+        // authorization, that is traffic reaching someone who was refused — permanently,
+        // because nothing rolls it back and nothing retries.
+        await this.#adapter.join(room, id);
+        members.set(id, { id, session });
+        let rooms = this.#peerRooms.get(id);
+        if (rooms === undefined) {
+            rooms = new Set();
+            this.#peerRooms.set(id, rooms);
+        }
+        rooms.add(room);
+        this.#notify(session, FrameType.JOIN, room);
+    }
+    async leave(room, id) {
+        const members = this.#rooms.get(room);
+        const member = members?.get(id);
+        members?.delete(id);
+        if (members !== undefined && members.size === 0)
+            this.#rooms.delete(room);
+        this.#peerRooms.get(id)?.delete(room);
+        // Local state and the peer are settled before the bus is told, so a bus that rejects
+        // leaves this node consistent. The rejection still reaches the caller, who asked.
+        if (member !== undefined)
+            this.#notify(member.session, FrameType.LEAVE, room);
+        await this.#adapter.leave(room, id);
+    }
+    /**
+     * Teardown runs to completion whatever the bus does.
+     *
+     * `broadcast` already wrapped its adapter call; this did not, so a rejection on the
+     * first room threw straight out of the loop — rooms 2..N kept their `Member` record,
+     * each holding a live Session, and `#peerRooms.delete(id)` never ran. Nothing retries,
+     * because `conn.closed` resolves exactly once. A later `to(room).emit()` then fanned
+     * frames into a session that was already gone.
+     *
+     * The local half is what this node's correctness depends on, so it is unconditional.
+     * The bus half is best-effort by nature: the peer's connection is already gone, and a
+     * bus that cannot be told now will not be told by us failing here.
+     */
+    async removePeer(id) {
+        const rooms = [...(this.#peerRooms.get(id) ?? [])];
+        this.#peerRooms.delete(id);
+        for (const room of rooms) {
+            const members = this.#rooms.get(room);
+            members?.delete(id);
+            if (members !== undefined && members.size === 0)
+                this.#rooms.delete(room);
+        }
+        await Promise.allSettled(rooms.map((room) => this.#adapter.leave(room, id)));
+    }
+    rooms(id) {
+        return [...(this.#peerRooms.get(id) ?? [])];
+    }
+    memberCount(room) {
+        return this.#rooms.get(room)?.size ?? 0;
+    }
+    async broadcast(room, event, payload, args) {
+        const entry = this.#table.byName(event);
+        if (entry === undefined) {
+            throw new TransportError('WT_UNKNOWN_EVENT', `'${event}' is not in the contract`, 'Add it to the contract, or check the spelling.');
+        }
+        const body = encodePayload(payload);
+        const except = args.except ?? [];
+        const bytes = entry.lane === 'datagram'
+            ? encodeDatagram({
+                eventId: entry.id,
+                origin: args.origin,
+                sequence: this.#nextSeq(entry.id),
+                payload: body,
+            }, DATAGRAM_CONSERVATIVE_FLOOR)
+            : encodeFrame({
+                type: FrameType.EMIT,
+                codec: Codec.JSON,
+                eventId: entry.id,
+                payload: body,
+            });
+        this.#deliverLocal(room, bytes, entry.lane, except);
+        try {
+            await this.#adapter.broadcast(room, bytes, { lane: entry.lane, except });
+        }
+        catch {
+            // Any adapter method may reject. Core degrades rather than crashing: local members
+            // already have the message and every session stays up.
+        }
+    }
+    #nextSeq(eventId) {
+        const n = ((this.#seqs.get(eventId) ?? 0) + 1) >>> 0 || 1;
+        this.#seqs.set(eventId, n);
+        return n;
+    }
+    #notify(session, type, room) {
+        session.sendFrame({ type, codec: Codec.JSON, eventId: 0, payload: encodePayload({ room }) });
+    }
+    #deliverLocal(room, bytes, lane, except) {
+        const members = this.#rooms.get(room);
+        if (members === undefined)
+            return; // no local members is not an error
+        for (const m of members.values()) {
+            if (except.includes(m.id))
+                continue;
+            if (lane === 'datagram')
+                m.session.sendDatagramBytes(bytes);
+            else
+                m.session.sendEncodedFrame(bytes);
+        }
+    }
+}
+//# sourceMappingURL=hub.js.map