@flighthq/socket 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.1047.858b9b6

package/README.md

@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/socket`. The `@fligh
 This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
 - [Flight project](https://github.com/flighthq/flight)
-- [Source for @flighthq/socket@0.5.0-next.1944.cd6b6e7](https://github.com/flighthq/flight/tree/cd6b6e71eb472b3a4249830a7743333f019fa7b7/packages/socket)
-- [License](https://github.com/flighthq/flight/blob/cd6b6e71eb472b3a4249830a7743333f019fa7b7/LICENSE.md)
+- [Source for @flighthq/socket@0.5.1-edge.1047.858b9b6](https://github.com/flighthq/flight/tree/858b9b601de814f6b6940cbb1ffff0916b903268/packages/socket)
+- [License](https://github.com/flighthq/flight/blob/858b9b601de814f6b6940cbb1ffff0916b903268/LICENSE.md)

package/dist/contract.d.ts

@@ -1,4 +1,5 @@
 export * from './enableSocketGuards';
 export * from './explainSocketSendFailure';
 export * from './socket';
+export { initializeWebSocketBackend } from './socket';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,UAAU,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC"}

package/dist/contract.js

@@ -1,4 +1,5 @@
 export * from './enableSocketGuards';
 export * from './explainSocketSendFailure';
 export * from './socket';
+export { initializeWebSocketBackend } from './socket';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,UAAU,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC"}

package/dist/enableSocketGuards.js

@@ -17,7 +17,7 @@ export function enableSocketGuards() {
 function warnOnSocketMisuse(notice) {
     const url = notice.socket.url;
     const message = notice.reason === 'no-connection'
-        ? 'createSocket: active backend returned no connection — call setSocketBackend(...) with a backend that supports this transport'
+        ? 'createSocket: the host carries no socket provider for this transport, or its provider returned no connection — pass a host whose net.socket supports it'
         : `${notice.operation}: socket is already disposed — call createSocket(...) to create a new socket`;
     logOnce(`socket:${notice.operation}:${notice.reason}`, LogLevel.Warn, { message, operation: notice.operation, reason: notice.reason, url }, 'socket');
 }

package/dist/enableSocketGuards.js.map

@@ -1 +1 @@
-{"version":3,"file":"enableSocketGuards.js","sourceRoot":"","sources":["../src/enableSocketGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C,MAAM,UAAU,sBAAsB;IACpC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,cAAc,CAAC,IAAI,CAAC,CAAC;IACrB,QAAQ,GAAG,KAAK,CAAC;AACnB,CAAC;AAED,qGAAqG;AACrG,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB;IAChC,cAAc,CAAC,kBAAkB,CAAC,CAAC;IACnC,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAmC;IAC7D,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;IAC9B,MAAM,OAAO,GACX,MAAM,CAAC,MAAM,KAAK,eAAe;QAC/B,CAAC,CAAC,8HAA8H;QAChI,CAAC,CAAC,GAAG,MAAM,CAAC,SAAS,8EAA8E,CAAC;IACxG,OAAO,CACL,UAAU,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,EAC7C,QAAQ,CAAC,IAAI,EACb,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,EACpE,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,IAAI,QAAQ,GAAG,KAAK,CAAC"}
+{"version":3,"file":"enableSocketGuards.js","sourceRoot":"","sources":["../src/enableSocketGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C,MAAM,UAAU,sBAAsB;IACpC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,cAAc,CAAC,IAAI,CAAC,CAAC;IACrB,QAAQ,GAAG,KAAK,CAAC;AACnB,CAAC;AAED,qGAAqG;AACrG,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB;IAChC,cAAc,CAAC,kBAAkB,CAAC,CAAC;IACnC,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAmC;IAC7D,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;IAC9B,MAAM,OAAO,GACX,MAAM,CAAC,MAAM,KAAK,eAAe;QAC/B,CAAC,CAAC,yJAAyJ;QAC3J,CAAC,CAAC,GAAG,MAAM,CAAC,SAAS,8EAA8E,CAAC;IACxG,OAAO,CACL,UAAU,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,EAC7C,QAAQ,CAAC,IAAI,EACb,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,EACpE,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,IAAI,QAAQ,GAAG,KAAK,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { areSocketGuardsEnabled, attachSocket, closeSocket, createSocket, detachSocket, disableSocketGuards, disposeSocket, enableSocketGuards, enableSocketSignals, explainSocketSendFailure, getSocketReadyState, sendSocketMessage, } from './contract';
+export { areSocketGuardsEnabled, attachSocket, closeSocket, createSocket, detachSocket, disableSocketGuards, disposeSocket, enableSocketGuards, enableSocketSignals, explainSocketSendFailure, getSocketReadyState, openTcpSocket, sendSocketMessage, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { areSocketGuardsEnabled, attachSocket, closeSocket, createSocket, detachSocket, disableSocketGuards, disposeSocket, enableSocketGuards, enableSocketSignals, explainSocketSendFailure, getSocketReadyState, sendSocketMessage, } from './contract';
+export { areSocketGuardsEnabled, attachSocket, closeSocket, createSocket, detachSocket, disableSocketGuards, disposeSocket, enableSocketGuards, enableSocketSignals, explainSocketSendFailure, getSocketReadyState, openTcpSocket, sendSocketMessage, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/socket.d.ts

@@ -1,14 +1,14 @@
-import type { Socket, SocketBackend, SocketGuard, SocketOptions, SocketReadyState, SocketSignals } from '@flighthq/types/contract';
+import type { Entity, EntityConstruction, HasNetSocket, Socket, SocketBackend, SocketGuard, SocketOptions, SocketReadyState, SocketSignals, TcpSocketConnection, TcpSocketOptions } from '@flighthq/types/contract';
 export declare function attachSocket(socket: Socket): void;
 export declare function closeSocket(socket: Socket, code?: number, reason?: string): void;
-export declare function createSocket(options: Readonly<SocketOptions>): Socket;
-export declare function createWebSocketBackend(): SocketBackend;
+export declare function createSocket(host: HasNetSocket, options: Readonly<SocketOptions>): Socket;
+export declare function createWebSocketBackend(): SocketBackend & Entity;
 export declare function detachSocket(socket: Socket): void;
 export declare function disposeSocket(socket: Socket): void;
 export declare function enableSocketSignals(socket: Socket): SocketSignals;
-export declare function getSocketBackend(): SocketBackend;
 export declare function getSocketReadyState(socket: Readonly<Socket>): SocketReadyState;
+export declare function initializeWebSocketBackend(out: EntityConstruction<SocketBackend & Entity>): void;
+export declare function openTcpSocket(host: HasNetSocket, options: Readonly<TcpSocketOptions>): TcpSocketConnection | null;
 export declare function sendSocketMessage(socket: Readonly<Socket>, data: string | ArrayBuffer): boolean;
-export declare function setSocketBackend(backend: SocketBackend | null): void;
 export declare function setSocketGuard(guard: SocketGuard | null): void;
 //# sourceMappingURL=socket.d.ts.map

package/dist/socket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,MAAM,EACN,aAAa,EAIb,WAAW,EAEX,aAAa,EACb,gBAAgB,EAEhB,aAAa,EACd,MAAM,0BAA0B,CAAC;AAKlC,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGjD;AAKD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAShF;AAOD,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAYrE;AAMD,wBAAgB,sBAAsB,IAAI,aAAa,CA0BtD;AAID,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjD;AAKD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CASlD;AAMD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAYjE;AAGD,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AAGD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,gBAAgB,CAE9E;AAKD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAQ/F;AAGD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEpE;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAE9D"}
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,MAAM,EACN,kBAAkB,EAClB,YAAY,EACZ,MAAM,EACN,aAAa,EAIb,WAAW,EAEX,aAAa,EACb,gBAAgB,EAEhB,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAKlC,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGjD;AAKD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAShF;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAkBzF;AAED,wBAAgB,sBAAsB,IAAI,aAAa,GAAG,MAAM,CAI/D;AAID,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjD;AAKD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CASlD;AAMD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAcjE;AAGD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,gBAAgB,CAE9E;AAMD,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,CAAC,aAAa,GAAG,MAAM,CAAC,GAAG,IAAI,CAwBhG;AAKD,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,mBAAmB,GAAG,IAAI,CAEjH;AAKD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAQ/F;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAE9D"}

package/dist/socket.js

@@ -1,3 +1,4 @@
+import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
 import { createSignal, emitSignal } from '@flighthq/signals/contract';
 // Resumes delivery of backend events to the socket's signals (idempotent). Pair with detachSocket.
 // createSocket leaves a new socket attached, so this is only needed to resume after detachSocket. A
@@ -21,12 +22,13 @@ export function closeSocket(socket, code, reason) {
     runtime.readyState = 'closing';
     runtime.connection?.closeSocketConnection(code, reason);
 }
-// Allocates a Socket entity plus its runtime and opens the connection through the active backend,
+// Allocates a Socket entity plus its runtime and opens the connection through the host's socket
+// provider,
 // wiring the backend's open/message/close/error into the socket's (still inert) signal group. The
 // socket starts in 'connecting' and is left attached (delivering). Enable signals with
 // enableSocketSignals to observe events. A backend that does not support the transport yields a null
 // connection and the socket stays in 'connecting' until closed.
-export function createSocket(options) {
+export function createSocket(host, options) {
     const runtime = {
         connection: null,
         signals: null,
@@ -34,42 +36,22 @@ export function createSocket(options) {
         delivering: true,
         disposed: false,
     };
-    const socket = { url: options.url, runtime };
-    runtime.connection = getSocketBackend().openSocket(options, makeSocketEventSink(runtime));
+    const socket = allocateEntity();
+    socket.url = options.url;
+    socket.runtime = runtime;
+    // The provider comes from the host the caller passed. A host that carries no socket transport
+    // yields no connection rather than reaching a process-global fallback: absence is an answer here,
+    // and the guard reports it.
+    const backend = host.net.socket;
+    runtime.connection = backend === undefined ? null : backend.openSocket(options, makeSocketEventSink(runtime));
     if (runtime.connection === null)
         _guard?.({ operation: 'createSocket', reason: 'no-connection', socket });
     return socket;
 }
-// Builds the default web backend over the DOM WebSocket. Created lazily by getSocketBackend — no
-// WebSocket is constructed at import time, so importing the package has no side effect. Returns a
-// null connection when WebSocket is unavailable (non-browser host) rather than throwing; raw TCP/UDP
-// is likewise unsupported here and only reachable through a native backend.
 export function createWebSocketBackend() {
-    return {
-        openSocket(options, events) {
-            if (typeof WebSocket === 'undefined')
-                return null;
-            const ws = options.protocols !== undefined
-                ? new WebSocket(options.url, options.protocols)
-                : new WebSocket(options.url);
-            ws.binaryType = options.binaryType ?? 'arraybuffer';
-            ws.onopen = () => events.handleSocketOpen();
-            ws.onmessage = (event) => events.handleSocketMessage(toSocketMessage(event.data));
-            ws.onclose = (event) => events.handleSocketClose({ code: event.code, reason: event.reason, wasClean: event.wasClean });
-            ws.onerror = () => events.handleSocketError();
-            return {
-                sendSocketFrame(data) {
-                    if (ws.readyState !== WebSocket.OPEN)
-                        return false;
-                    ws.send(data);
-                    return true;
-                },
-                closeSocketConnection(code, reason) {
-                    ws.close(code, reason);
-                },
-            };
-        },
-    };
+    const out = allocateEntity();
+    initializeWebSocketBackend(out);
+    return finishEntity(out);
 }
 // Stops delivery of backend events to the socket's signals. The live connection is untouched — use
 // closeSocket to close it. Safe to call repeatedly; resume with attachSocket.
@@ -99,25 +81,56 @@ export function enableSocketSignals(socket) {
     if (runtime.disposed)
         _guard?.({ operation: 'enableSocketSignals', reason: 'disposed', socket });
     if (runtime.signals === null) {
-        runtime.signals = {
-            onSocketOpen: createSignal(),
-            onSocketMessage: createSignal(),
-            onSocketClose: createSignal(),
-            onSocketError: createSignal(),
-        };
+        runtime.signals = (() => {
+            const out = allocateEntity();
+            out.onSocketOpen = createSignal();
+            out.onSocketMessage = createSignal();
+            out.onSocketClose = createSignal();
+            out.onSocketError = createSignal();
+            return finishEntity(out);
+        })();
     }
     return runtime.signals;
 }
-// The active socket backend, or a lazily-created web default. There is always a backend.
-export function getSocketBackend() {
-    if (_backend === null)
-        _backend = createWebSocketBackend();
-    return _backend;
-}
 // The socket's current connection phase, tracked on the runtime from backend events and closeSocket.
 export function getSocketReadyState(socket) {
     return socket.runtime.readyState;
 }
+// Builds the web backend over the DOM WebSocket. Nothing constructs one at import time, so importing
+// the package has no side effect; a host composes this value into its own net group. Returns a
+// null connection when WebSocket is unavailable (non-browser host) rather than throwing; raw TCP/UDP
+// is likewise unsupported here and only reachable through a native backend.
+export function initializeWebSocketBackend(out) {
+    out.openSocket = (options, events) => {
+        if (typeof WebSocket === 'undefined')
+            return null;
+        const ws = options.protocols !== undefined
+            ? new WebSocket(options.url, options.protocols)
+            : new WebSocket(options.url);
+        ws.binaryType = options.binaryType ?? 'arraybuffer';
+        ws.onopen = () => events.handleSocketOpen();
+        ws.onmessage = (event) => events.handleSocketMessage(toSocketMessage(event.data));
+        ws.onclose = (event) => events.handleSocketClose({ code: event.code, reason: event.reason, wasClean: event.wasClean });
+        ws.onerror = () => events.handleSocketError();
+        return {
+            sendSocketFrame(data) {
+                if (ws.readyState !== WebSocket.OPEN)
+                    return false;
+                ws.send(data);
+                return true;
+            },
+            closeSocketConnection(code, reason) {
+                ws.close(code, reason);
+            },
+        };
+    };
+}
+// Opens a raw TCP byte stream through the socket provider selected by the caller's host. Browser and
+// other framed-only providers omit openTcpSocket, so unsupported raw TCP returns null without trying
+// openSocket or interpreting the endpoint as a WebSocket URL.
+export function openTcpSocket(host, options) {
+    return host.net.socket?.openTcpSocket?.(options) ?? null;
+}
 // Sends a text or binary frame over the live connection without mutating or copying either argument.
 // Returns false — a sentinel, not a throw — when the socket is disposed, not open, has no connection,
 // or the backend rejects the send. explainSocketSendFailure diagnoses the deterministic preflight paths.
@@ -131,16 +144,11 @@ export function sendSocketMessage(socket, data) {
         return false;
     return runtime.connection.sendSocketFrame(data);
 }
-// Installs a native host socket backend (adding TCP/UDP); pass null to fall back to the web default.
-export function setSocketBackend(backend) {
-    _backend = backend;
-}
 // Installs the diagnostics hook used by the separately imported enableSocketGuards module. Null is
 // the production default and removes all guard-path work except the branch.
 export function setSocketGuard(guard) {
     _guard = guard;
 }
-let _backend = null;
 let _guard = null;
 // Builds the backend→entity sink bound to one socket's runtime: it updates readyState and emits the
 // opt-in signals. Every handler is a no-op once the runtime stops delivering (detach/dispose), so a

package/dist/socket.js.map

@@ -1 +1 @@
-{"version":3,"file":"socket.js","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAoBtE,mGAAmG;AACnG,oGAAoG;AACpG,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ;QAAE,OAAO;IACpC,MAAM,CAAC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;AACnC,CAAC;AAED,mGAAmG;AACnG,sGAAsG;AACtG,iGAAiG;AACjG,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAa,EAAE,MAAe;IACxE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;QACnE,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,OAAO,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO;IAChF,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAC/B,OAAO,CAAC,UAAU,EAAE,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED,gGAAgG;AAChG,YAAY;AACZ,kGAAkG;AAClG,uFAAuF;AACvF,qGAAqG;AACrG,gEAAgE;AAChE,MAAM,UAAU,YAAY,CAAC,IAAkB,EAAE,OAAgC;IAC/E,MAAM,OAAO,GAAkB;QAC7B,UAAU,EAAE,IAAI;QAChB,OAAO,EAAE,IAAI;QACb,UAAU,EAAE,YAAY;QACxB,UAAU,EAAE,IAAI;QAChB,QAAQ,EAAE,KAAK;KAChB,CAAC;IACF,MAAM,MAAM,GAAG,cAAc,EAAU,CAAC;IACxC,MAAM,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACzB,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,8FAA8F;IAC9F,kGAAkG;IAClG,4BAA4B;IAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;IAChC,OAAO,CAAC,UAAU,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9G,IAAI,OAAO,CAAC,UAAU,KAAK,IAAI;QAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1G,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,MAAM,GAAG,GAAG,cAAc,EAA0B,CAAC;IACrD,0BAA0B,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED,mGAAmG;AACnG,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,CAAC,OAAO,CAAC,UAAU,GAAG,KAAK,CAAC;AACpC,CAAC;AAED,mGAAmG;AACnG,sGAAsG;AACtG,yFAAyF;AACzF,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ;QAAE,OAAO;IACpC,WAAW,CAAC,MAAM,CAAC,CAAC;IACpB,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,UAAU,GAAG,QAAQ,CAAC;IAC9B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED,oGAAoG;AACpG,gGAAgG;AAChG,sGAAsG;AACtG,qGAAqG;AACrG,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,OAAO,CAAC,QAAQ;QAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IACjG,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC7B,OAAO,CAAC,OAAO,GAAG,CAAC,GAAG,EAAE;YACtB,MAAM,GAAG,GAAG,cAAc,EAAiB,CAAC;YAC5C,GAAG,CAAC,YAAY,GAAG,YAAY,EAAc,CAAC;YAC9C,GAAG,CAAC,eAAe,GAAG,YAAY,EAA8C,CAAC;YACjF,GAAG,CAAC,aAAa,GAAG,YAAY,EAA6C,CAAC;YAC9E,GAAG,CAAC,aAAa,GAAG,YAAY,EAAc,CAAC;YAC/C,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC;AACzB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,mBAAmB,CAAC,MAAwB;IAC1D,OAAO,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;AACnC,CAAC;AAED,qGAAqG;AACrG,+FAA+F;AAC/F,qGAAqG;AACrG,4EAA4E;AAC5E,MAAM,UAAU,0BAA0B,CAAC,GAA+C;IACxF,GAAG,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,EAA2B,EAAE;QAC5D,IAAI,OAAO,SAAS,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC;QAClD,MAAM,EAAE,GACN,OAAO,CAAC,SAAS,KAAK,SAAS;YAC7B,CAAC,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,SAAqB,CAAC;YAC3D,CAAC,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,EAAE,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,aAAa,CAAC;QACpD,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC5C,EAAE,CAAC,SAAS,GAAG,CAAC,KAAmB,EAAE,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAChG,EAAE,CAAC,OAAO,GAAG,CAAC,KAAiB,EAAE,EAAE,CACjC,MAAM,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjG,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC9C,OAAO;YACL,eAAe,CAAC,IAAI;gBAClB,IAAI,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI;oBAAE,OAAO,KAAK,CAAC;gBACnD,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO,IAAI,CAAC;YACd,CAAC;YACD,qBAAqB,CAAC,IAAI,EAAE,MAAM;gBAChC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzB,CAAC;SACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,qGAAqG;AACrG,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,IAAkB,EAAE,OAAmC;IACnF,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;AAC3D,CAAC;AAED,qGAAqG;AACrG,sGAAsG;AACtG,yGAAyG;AACzG,MAAM,UAAU,iBAAiB,CAAC,MAAwB,EAAE,IAA0B;IACpF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;QACzE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,KAAK,MAAM,IAAI,OAAO,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC/E,OAAO,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,mGAAmG;AACnG,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAAC,KAAyB;IACtD,MAAM,GAAG,KAAK,CAAC;AACjB,CAAC;AAED,IAAI,MAAM,GAAuB,IAAI,CAAC;AAEtC,oGAAoG;AACpG,oGAAoG;AACpG,mDAAmD;AACnD,SAAS,mBAAmB,CAAC,OAAsB;IACjD,OAAO;QACL,gBAAgB;YACd,IAAI,CAAC,OAAO,CAAC,UAAU;gBAAE,OAAO;YAChC,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC;YAC5B,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI;gBAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QACzE,CAAC;QACD,mBAAmB,CAAC,OAAO;YACzB,IAAI,CAAC,OAAO,CAAC,UAAU;gBAAE,OAAO;YAChC,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI;gBAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACrF,CAAC;QACD,iBAAiB,CAAC,IAAI;YACpB,IAAI,CAAC,OAAO,CAAC,UAAU;gBAAE,OAAO;YAChC,OAAO,CAAC,UAAU,GAAG,QAAQ,CAAC;YAC9B,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI;gBAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAChF,CAAC;QACD,iBAAiB;YACf,IAAI,CAAC,OAAO,CAAC,UAAU;gBAAE,OAAO;YAChC,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI;gBAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC1E,CAAC;KACF,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,qEAAqE;AACrE,SAAS,eAAe,CAAC,IAAa;IACpC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC7D,OAAO,EAAE,IAAI,EAAE,IAAmB,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACrD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/socket",
-  "version": "0.5.0-next.1944.cd6b6e7",
+  "version": "0.5.1-edge.1047.858b9b6",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,9 +38,10 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/log": "0.5.0-next.1944.cd6b6e7",
-    "@flighthq/signals": "0.5.0-next.1944.cd6b6e7",
-    "@flighthq/types": "0.5.0-next.1944.cd6b6e7"
+    "@flighthq/entity": "0.5.1-edge.1047.858b9b6",
+    "@flighthq/log": "0.5.1-edge.1047.858b9b6",
+    "@flighthq/signals": "0.5.1-edge.1047.858b9b6",
+    "@flighthq/types": "0.5.1-edge.1047.858b9b6"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enableSocketGuards.test.ts

@@ -1,15 +1,8 @@
 import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
-import type { LogEntry, SocketBackend } from '@flighthq/types/contract';
+import type { HasNetSocket, LogEntry, SocketBackend } from '@flighthq/types/contract';
 
 import { areSocketGuardsEnabled, disableSocketGuards, enableSocketGuards } from './enableSocketGuards';
-import {
-  closeSocket,
-  createSocket,
-  disposeSocket,
-  enableSocketSignals,
-  sendSocketMessage,
-  setSocketBackend,
-} from './socket';
+import { closeSocket, createSocket, disposeSocket, enableSocketSignals, sendSocketMessage } from './socket';
 
 function captureLog(run: () => void): readonly LogEntry[] {
   const sink = createMemoryLogSink(8);
@@ -33,9 +26,12 @@ function backend(hasConnection: boolean): SocketBackend {
 
 afterEach(() => {
   disableSocketGuards();
-  setSocketBackend(null);
 });
 
+function hostOf(backend: SocketBackend): HasNetSocket {
+  return { net: { socket: backend } } as HasNetSocket;
+}
+
 describe('areSocketGuardsEnabled', () => {
   it('reports whether the global guard hook is installed', () => {
     enableSocketGuards();
@@ -49,18 +45,18 @@ describe('disableSocketGuards', () => {
   it('restores silent core behavior', () => {
     enableSocketGuards();
     disableSocketGuards();
-    setSocketBackend(backend(false));
-    expect(captureLog(() => createSocket({ url: 'tcp://silent' }))).toEqual([]);
+    const host = hostOf(backend(false));
+    expect(captureLog(() => createSocket(host, { url: 'tcp://silent' }))).toEqual([]);
   });
 });
 
 describe('enableSocketGuards', () => {
   it('warns once when socket creation produces no connection', () => {
     enableSocketGuards();
-    setSocketBackend(backend(false));
+    const host = hostOf(backend(false));
     const entries = captureLog(() => {
-      createSocket({ url: 'tcp://unsupported' });
-      createSocket({ url: 'tcp://unsupported-again' });
+      createSocket(host, { url: 'tcp://unsupported' });
+      createSocket(host, { url: 'tcp://unsupported-again' });
     });
     expect(entries).toHaveLength(1);
     expect(entries[0]).toMatchObject({ channel: 'socket' });
@@ -69,13 +65,13 @@ describe('enableSocketGuards', () => {
       reason: 'no-connection',
       url: 'tcp://unsupported',
     });
-    expect(String((entries[0].data as Record<string, unknown>).message)).toContain('setSocketBackend');
+    expect(String((entries[0].data as Record<string, unknown>).message)).toContain('net.socket');
   });
 
   it('warns once per command issued after terminal disposal', () => {
     enableSocketGuards();
-    setSocketBackend(backend(true));
-    const socket = createSocket({ url: 'ws://disposed' });
+    const host = hostOf(backend(true));
+    const socket = createSocket(host, { url: 'ws://disposed' });
     disposeSocket(socket);
     const entries = captureLog(() => {
       closeSocket(socket);
@@ -97,8 +93,8 @@ describe('enableSocketGuards', () => {
 
   it('stays silent for ordinary pre-open sends and closes', () => {
     enableSocketGuards();
-    setSocketBackend(backend(true));
-    const socket = createSocket({ url: 'ws://connecting' });
+    const host = hostOf(backend(true));
+    const socket = createSocket(host, { url: 'ws://connecting' });
     const entries = captureLog(() => {
       sendSocketMessage(socket, 'early');
       closeSocket(socket);

package/src/explainSocketSendFailure.test.ts

@@ -1,9 +1,12 @@
-import type { SocketBackend, SocketEventSink } from '@flighthq/types/contract';
+import type { HasNetSocket, SocketBackend, SocketEventSink } from '@flighthq/types/contract';
 
 import { explainSocketSendFailure } from './explainSocketSendFailure';
-import { createSocket, disposeSocket, sendSocketMessage, setSocketBackend } from './socket';
+import { createSocket, disposeSocket, sendSocketMessage } from './socket';
 
-function installBackend(hasConnection: boolean, sendResult = true): () => SocketEventSink {
+function installBackend(
+  hasConnection: boolean,
+  sendResult = true,
+): { host: HasNetSocket; sink: () => SocketEventSink } {
   let sink!: SocketEventSink;
   const backend: SocketBackend = {
     openSocket(_options, events) {
@@ -15,16 +18,17 @@ function installBackend(hasConnection: boolean, sendResult = true): () => Socket
       };
     },
   };
-  setSocketBackend(backend);
-  return () => sink;
+  return { host: hostOf(backend), sink: () => sink };
 }
 
-afterEach(() => setSocketBackend(null));
+function hostOf(backend: SocketBackend): HasNetSocket {
+  return { net: { socket: backend } } as HasNetSocket;
+}
 
 describe('explainSocketSendFailure', () => {
   it('identifies an unsupported backend with no connection', () => {
-    installBackend(false);
-    const socket = createSocket({ url: 'tcp://host' });
+    const { host } = installBackend(false);
+    const socket = createSocket(host, { url: 'tcp://host' });
     expect(explainSocketSendFailure(socket)).toEqual({
       reason: 'no-connection',
       readyState: 'connecting',
@@ -33,8 +37,8 @@ describe('explainSocketSendFailure', () => {
   });
 
   it('reports the current non-open phase when a connection exists', () => {
-    installBackend(true);
-    const socket = createSocket({ url: 'ws://host' });
+    const { host } = installBackend(true);
+    const socket = createSocket(host, { url: 'ws://host' });
     expect(explainSocketSendFailure(socket)).toEqual({
       reason: 'not-open',
       readyState: 'connecting',
@@ -43,16 +47,16 @@ describe('explainSocketSendFailure', () => {
   });
 
   it('returns null once the socket can reach its backend, even when that backend returns false', () => {
-    const getSink = installBackend(true, false);
-    const socket = createSocket({ url: 'ws://host' });
+    const { host, sink: getSink } = installBackend(true, false);
+    const socket = createSocket(host, { url: 'ws://host' });
     getSink().handleSocketOpen();
     expect(sendSocketMessage(socket, 'frame')).toBe(false);
     expect(explainSocketSendFailure(socket)).toBeNull();
   });
 
   it('distinguishes terminal disposal from other closed or disconnected states', () => {
-    installBackend(true);
-    const socket = createSocket({ url: 'ws://host' });
+    const { host } = installBackend(true);
+    const socket = createSocket(host, { url: 'ws://host' });
     disposeSocket(socket);
     expect(explainSocketSendFailure(socket)).toEqual({
       reason: 'disposed',

package/src/socket.test.ts

@@ -1,12 +1,16 @@
 import { connectSignal } from '@flighthq/signals/contract';
 import type {
+  HasNetSocket,
   SocketBackend,
   SocketCloseInfo,
   SocketConnection,
   SocketEventSink,
   SocketMessage,
+  TcpSocketConnection,
+  TcpSocketOptions,
 } from '@flighthq/types/contract';
 
+import { openTcpSocket } from './index';
 import {
   attachSocket,
   closeSocket,
@@ -15,10 +19,9 @@ import {
   detachSocket,
   disposeSocket,
   enableSocketSignals,
-  getSocketBackend,
   getSocketReadyState,
+  initializeWebSocketBackend,
   sendSocketMessage,
-  setSocketBackend,
   setSocketGuard,
 } from './socket';
 
@@ -65,15 +68,26 @@ function fakeBackend(): FakeSocket {
 }
 
 afterEach(() => {
-  setSocketBackend(null);
   setSocketGuard(null);
 });
 
+function hostOf(backend: SocketBackend): HasNetSocket {
+  return { net: { socket: backend } } as HasNetSocket;
+}
+
+function tcpConnection(): TcpSocketConnection {
+  return {
+    readable: new ReadableStream<Uint8Array>(),
+    writable: new WritableStream<Uint8Array>(),
+    closeTcpSocketConnection(): void {},
+  };
+}
+
 describe('attachSocket', () => {
   it('resumes delivery after a detach', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     const signals = enableSocketSignals(socket);
     let opens = 0;
     connectSignal(signals.onSocketOpen, () => opens++);
@@ -85,8 +99,8 @@ describe('attachSocket', () => {
 
   it('cannot resume delivery after terminal disposal', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     const signals = enableSocketSignals(socket);
     let opens = 0;
     connectSignal(signals.onSocketOpen, () => opens++);
@@ -101,8 +115,8 @@ describe('attachSocket', () => {
 describe('closeSocket', () => {
   it('transitions to closing and forwards code/reason to the connection', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     fake.sink.handleSocketOpen();
     closeSocket(socket, 1000, 'bye');
     expect(getSocketReadyState(socket)).toBe('closing');
@@ -111,8 +125,8 @@ describe('closeSocket', () => {
 
   it('reaches closed once the backend close event arrives', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     fake.sink.handleSocketOpen();
     closeSocket(socket);
     fake.sink.handleSocketClose({ code: 1000, reason: '', wasClean: true });
@@ -121,8 +135,8 @@ describe('closeSocket', () => {
 
   it('is a no-op when already closed', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     fake.sink.handleSocketOpen();
     closeSocket(socket);
     fake.sink.handleSocketClose({ code: 1000, reason: '', wasClean: true });
@@ -132,8 +146,8 @@ describe('closeSocket', () => {
 
   it('stays closed and does not close the connection again after disposal', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     disposeSocket(socket);
     closeSocket(socket);
     expect(getSocketReadyState(socket)).toBe('closed');
@@ -144,8 +158,8 @@ describe('closeSocket', () => {
 describe('createSocket', () => {
   it('opens through the backend in the connecting state and records the url', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://host/path' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://host/path' });
     expect(socket.url).toBe('ws://host/path');
     expect(getSocketReadyState(socket)).toBe('connecting');
     expect(fake.lastOptions?.url).toBe('ws://host/path');
@@ -153,8 +167,8 @@ describe('createSocket', () => {
 
   it('passes protocols and binaryType through to the backend', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    createSocket({ url: 'ws://x', protocols: ['a', 'b'], binaryType: 'arraybuffer' });
+    const host = hostOf(fake.backend);
+    createSocket(host, { url: 'ws://x', protocols: ['a', 'b'], binaryType: 'arraybuffer' });
     expect(fake.lastOptions?.protocols).toEqual(['a', 'b']);
     expect(fake.lastOptions?.binaryType).toBe('arraybuffer');
   });
@@ -162,16 +176,16 @@ describe('createSocket', () => {
   it('tolerates a null connection from an unsupported transport', () => {
     const fake = fakeBackend();
     fake.openReturnsNull = true;
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'tcp://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'tcp://x' });
     expect(getSocketReadyState(socket)).toBe('connecting');
     expect(sendSocketMessage(socket, 'x')).toBe(false);
   });
 
   it('emits a text message with binary false and a binary message with binary true', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     const signals = enableSocketSignals(socket);
     const received: SocketMessage[] = [];
     connectSignal(signals.onSocketMessage, (m) => received.push(m));
@@ -187,8 +201,8 @@ describe('createSocket', () => {
 
   it('emits close info with code, reason, and wasClean', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     const signals = enableSocketSignals(socket);
     const infos: SocketCloseInfo[] = [];
     connectSignal(signals.onSocketClose, (i) => infos.push(i));
@@ -198,8 +212,8 @@ describe('createSocket', () => {
 
   it('emits onSocketError', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     const signals = enableSocketSignals(socket);
     let errors = 0;
     connectSignal(signals.onSocketError, () => errors++);
@@ -302,8 +316,8 @@ describe('createWebSocketBackend', () => {
 describe('detachSocket', () => {
   it('stops backend events from reaching the signals', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     const signals = enableSocketSignals(socket);
     let opens = 0;
     connectSignal(signals.onSocketOpen, () => opens++);
@@ -316,8 +330,8 @@ describe('detachSocket', () => {
 describe('disposeSocket', () => {
   it('closes an open connection and detaches so later events fire no signal', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     const signals = enableSocketSignals(socket);
     let messages = 0;
     connectSignal(signals.onSocketMessage, () => messages++);
@@ -332,8 +346,8 @@ describe('disposeSocket', () => {
 
   it('is safe to call on a fresh socket', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     expect(() => disposeSocket(socket)).not.toThrow();
   });
 });
@@ -341,22 +355,22 @@ describe('disposeSocket', () => {
 describe('enableSocketSignals', () => {
   it('returns the same group on repeated calls', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     expect(enableSocketSignals(socket)).toBe(enableSocketSignals(socket));
   });
 
   it('leaves a bare socket without signals', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     expect(socket.runtime.signals).toBeNull();
   });
 
   it('returns an inert stable group without reviving a disposed socket', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     disposeSocket(socket);
     const first = enableSocketSignals(socket);
     expect(enableSocketSignals(socket)).toBe(first);
@@ -365,23 +379,11 @@ describe('enableSocketSignals', () => {
   });
 });
 
-describe('getSocketBackend', () => {
-  it('lazily returns a web backend by default', () => {
-    expect(typeof getSocketBackend().openSocket).toBe('function');
-  });
-
-  it('returns the installed backend', () => {
-    const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    expect(getSocketBackend()).toBe(fake.backend);
-  });
-});
-
 describe('getSocketReadyState', () => {
   it('reflects connecting → open → closing → closed transitions', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     expect(getSocketReadyState(socket)).toBe('connecting');
     fake.sink.handleSocketOpen();
     expect(getSocketReadyState(socket)).toBe('open');
@@ -392,11 +394,54 @@ describe('getSocketReadyState', () => {
   });
 });
 
+describe('initializeWebSocketBackend', () => {
+  it('is the construction initializer of createWebSocketBackend', () => {
+    expect(typeof initializeWebSocketBackend).toBe('function');
+  });
+});
+
+describe('openTcpSocket', () => {
+  it('forwards the endpoint unchanged and returns the backend connection by identity', () => {
+    const expected = tcpConnection();
+    const options: TcpSocketOptions = { host: 'db.internal', port: 5432 };
+    const openTcpSocketBackend = vi.fn(() => expected);
+    const backend: SocketBackend = {
+      openSocket: vi.fn(() => null),
+      openTcpSocket: openTcpSocketBackend,
+    };
+
+    expect(openTcpSocket(hostOf(backend), options)).toBe(expected);
+    expect(openTcpSocketBackend).toHaveBeenCalledWith(options);
+  });
+
+  it('returns null when the host carries no socket backend', () => {
+    const host = { net: {} } as HasNetSocket;
+    expect(openTcpSocket(host, { host: 'localhost', port: 9000 })).toBeNull();
+  });
+
+  it('returns null for the web backend without attempting framed openSocket', () => {
+    const backend = createWebSocketBackend();
+    const openSocket = vi.spyOn(backend, 'openSocket');
+
+    expect(openTcpSocket(hostOf(backend), { host: 'localhost', port: 9000 })).toBeNull();
+    expect(openSocket).not.toHaveBeenCalled();
+  });
+
+  it('preserves an explicit null from a backend that cannot open the endpoint', () => {
+    const backend: SocketBackend = {
+      openSocket: vi.fn(() => null),
+      openTcpSocket: vi.fn(() => null),
+    };
+
+    expect(openTcpSocket(hostOf(backend), { host: 'unreachable.internal', port: 22 })).toBeNull();
+  });
+});
+
 describe('sendSocketMessage', () => {
   it('sends through the connection and returns true when open', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     fake.sink.handleSocketOpen();
     expect(sendSocketMessage(socket, 'ping')).toBe(true);
     expect(fake.sent).toEqual(['ping']);
@@ -404,16 +449,16 @@ describe('sendSocketMessage', () => {
 
   it('returns false without throwing when not open', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     expect(sendSocketMessage(socket, 'ping')).toBe(false);
     expect(fake.sent).toEqual([]);
   });
 
   it('returns false after disposal without reaching the released connection', () => {
     const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     fake.sink.handleSocketOpen();
     disposeSocket(socket);
     expect(sendSocketMessage(socket, 'ping')).toBe(false);
@@ -423,8 +468,8 @@ describe('sendSocketMessage', () => {
   it('returns false for an open state whose backend supplied no connection', () => {
     const fake = fakeBackend();
     fake.openReturnsNull = true;
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'tcp://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'tcp://x' });
     fake.sink.handleSocketOpen();
     expect(getSocketReadyState(socket)).toBe('open');
     expect(sendSocketMessage(socket, 'ping')).toBe(false);
@@ -433,8 +478,8 @@ describe('sendSocketMessage', () => {
   it('forwards binary data by identity and propagates false without mutating the readonly socket', () => {
     const fake = fakeBackend();
     fake.sendReturns = false;
-    setSocketBackend(fake.backend);
-    const socket = createSocket({ url: 'ws://x' });
+    const host = hostOf(fake.backend);
+    const socket = createSocket(host, { url: 'ws://x' });
     fake.sink.handleSocketOpen();
     Object.freeze(socket.runtime);
     Object.freeze(socket);
@@ -444,46 +489,6 @@ describe('sendSocketMessage', () => {
   });
 });
 
-describe('setSocketBackend', () => {
-  it('restores the lazy web default when passed null', () => {
-    const fake = fakeBackend();
-    setSocketBackend(fake.backend);
-    expect(getSocketBackend()).toBe(fake.backend);
-    setSocketBackend(null);
-    const web = getSocketBackend();
-    expect(web).not.toBe(fake.backend);
-    expect(typeof web.openSocket).toBe('function');
-  });
-});
-
-describe('setSocketGuard', () => {
-  it('installs and removes the core notice hook', () => {
-    const notices: string[] = [];
-    setSocketGuard((notice) => notices.push(`${notice.operation}:${notice.reason}`));
-    const unsupported = fakeBackend();
-    unsupported.openReturnsNull = true;
-    setSocketBackend(unsupported.backend);
-    createSocket({ url: 'tcp://x' });
-
-    const supported = fakeBackend();
-    setSocketBackend(supported.backend);
-    const socket = createSocket({ url: 'ws://x' });
-    disposeSocket(socket);
-    closeSocket(socket);
-    sendSocketMessage(socket, 'x');
-    enableSocketSignals(socket);
-    setSocketGuard(null);
-    closeSocket(socket);
-
-    expect(notices).toEqual([
-      'createSocket:no-connection',
-      'closeSocket:disposed',
-      'sendSocketMessage:disposed',
-      'enableSocketSignals:disposed',
-    ]);
-  });
-});
-
 function noopSink(): SocketEventSink {
   return {
     handleSocketOpen() {},
@@ -540,3 +545,29 @@ function installFakeWebSocket(): () => void {
     (globalThis as { WebSocket?: unknown }).WebSocket = original;
   };
 }
+describe('setSocketGuard', () => {
+  it('installs and removes the core notice hook', () => {
+    const notices: string[] = [];
+    setSocketGuard((notice) => notices.push(`${notice.operation}:${notice.reason}`));
+    const unsupported = fakeBackend();
+    unsupported.openReturnsNull = true;
+    const host = hostOf(unsupported.backend);
+    createSocket(host, { url: 'tcp://x' });
+
+    const supported = fakeBackend();
+    const socket = createSocket(hostOf(supported.backend), { url: 'ws://x' });
+    disposeSocket(socket);
+    closeSocket(socket);
+    sendSocketMessage(socket, 'x');
+    enableSocketSignals(socket);
+    setSocketGuard(null);
+    closeSocket(socket);
+
+    expect(notices).toEqual([
+      'createSocket:no-connection',
+      'closeSocket:disposed',
+      'sendSocketMessage:disposed',
+      'enableSocketSignals:disposed',
+    ]);
+  });
+});

package/src/socketHost.test.ts

@@ -0,0 +1,57 @@
+import type { HasNetSocket, SocketBackend, SocketConnection, SocketEventSink } from '@flighthq/types/contract';
+
+import { createSocket, getSocketReadyState } from './socket';
+
+function recordingBackend(label: string, opened: string[]): SocketBackend {
+  return {
+    openSocket(_options, events: SocketEventSink): SocketConnection | null {
+      opened.push(label);
+      return {
+        closeSocketConnection(): void {},
+        sendSocketFrame(): boolean {
+          events.handleSocketOpen();
+          return true;
+        },
+      };
+    },
+  };
+}
+
+function hostWith(backend: SocketBackend | undefined): HasNetSocket {
+  return { net: backend === undefined ? {} : { socket: backend } } as HasNetSocket;
+}
+
+describe('createSocket', () => {
+  it('opens through the provider carried by the host it is given', () => {
+    const opened: string[] = [];
+    createSocket(hostWith(recordingBackend('a', opened)), { url: 'wss://example.test' });
+    expect(opened).toEqual(['a']);
+  });
+
+  // ★ HOST ISOLATION. Two hosts, two providers, two answers. Under the ambient resolver one
+  // process-wide backend answered for every caller, so the second host was unreachable no matter what
+  // it carried — this is the property the migration exists to create.
+  it('keeps two hosts independent', () => {
+    const opened: string[] = [];
+    createSocket(hostWith(recordingBackend('first', opened)), { url: 'wss://one.test' });
+    createSocket(hostWith(recordingBackend('second', opened)), { url: 'wss://two.test' });
+    expect(opened).toEqual(['first', 'second']);
+  });
+
+  // ★ NO AMBIENT FALLBACK. A host that carries no socket provider must yield no connection rather than
+  // quietly reaching a process-global web backend. The socket stays 'connecting', which is the
+  // documented shape for a backend that cannot open the transport.
+  it('yields no connection when the host carries no socket provider', () => {
+    const socket = createSocket(hostWith(undefined), { url: 'wss://absent.test' });
+    expect(socket.runtime.connection).toBeNull();
+    expect(getSocketReadyState(socket)).toBe('connecting');
+  });
+
+  it('does not consult one host provider when another host is passed', () => {
+    const opened: string[] = [];
+    const unused = recordingBackend('unused', opened);
+    createSocket(hostWith(recordingBackend('used', opened)), { url: 'wss://x.test' });
+    expect(opened).not.toContain('unused');
+    expect(unused).toBeDefined();
+  });
+});