@flighthq/socket 0.3.0-next.906.07cea63 → 0.3.0

package/dist/contract.d.ts

@@ -1,2 +1,4 @@
+export * from './enableSocketGuards';
+export * from './explainSocketSendFailure';
 export * 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,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"}

package/dist/contract.js

@@ -1,2 +1,4 @@
+export * from './enableSocketGuards';
+export * from './explainSocketSendFailure';
 export * 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,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"}

package/dist/enableSocketGuards.d.ts

@@ -0,0 +1,4 @@
+export declare function areSocketGuardsEnabled(): boolean;
+export declare function disableSocketGuards(): void;
+export declare function enableSocketGuards(): void;
+//# sourceMappingURL=enableSocketGuards.d.ts.map

package/dist/enableSocketGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableSocketGuards.d.ts","sourceRoot":"","sources":["../src/enableSocketGuards.ts"],"names":[],"mappings":"AAMA,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAID,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/enableSocketGuards.js

@@ -0,0 +1,25 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setSocketGuard } from './socket';
+export function areSocketGuardsEnabled() {
+    return _enabled;
+}
+export function disableSocketGuards() {
+    setSocketGuard(null);
+    _enabled = false;
+}
+// Installs opt-in warnings for unsupported socket creation and commands issued after terminal entity
+// disposal. Omitting this module sheds the guidance strings and @flighthq/log dependency.
+export function enableSocketGuards() {
+    setSocketGuard(warnOnSocketMisuse);
+    _enabled = true;
+}
+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'
+        : `${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');
+}
+let _enabled = false;
+//# sourceMappingURL=enableSocketGuards.js.map

package/dist/enableSocketGuards.js.map

@@ -0,0 +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"}

package/dist/explainSocketSendFailure.d.ts

@@ -0,0 +1,3 @@
+import type { Socket, SocketSendFailureExplanation } from '@flighthq/types/contract';
+export declare function explainSocketSendFailure(socket: Readonly<Socket>): SocketSendFailureExplanation | null;
+//# sourceMappingURL=explainSocketSendFailure.d.ts.map

package/dist/explainSocketSendFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainSocketSendFailure.d.ts","sourceRoot":"","sources":["../src/explainSocketSendFailure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAIrF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,4BAA4B,GAAG,IAAI,CAUtG"}

package/dist/explainSocketSendFailure.js

@@ -0,0 +1,15 @@
+// Explains the deterministic preflight reasons sendSocketMessage returns false without invoking its
+// backend. Returns null when the socket can reach the backend; the backend may still return false.
+export function explainSocketSendFailure(socket) {
+    const runtime = socket.runtime;
+    if (runtime.disposed)
+        return { reason: 'disposed', readyState: 'closed', url: socket.url };
+    if (runtime.connection === null) {
+        return { reason: 'no-connection', readyState: runtime.readyState, url: socket.url };
+    }
+    if (runtime.readyState !== 'open') {
+        return { reason: 'not-open', readyState: runtime.readyState, url: socket.url };
+    }
+    return null;
+}
+//# sourceMappingURL=explainSocketSendFailure.js.map

package/dist/explainSocketSendFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainSocketSendFailure.js","sourceRoot":"","sources":["../src/explainSocketSendFailure.ts"],"names":[],"mappings":"AAEA,oGAAoG;AACpG,mGAAmG;AACnG,MAAM,UAAU,wBAAwB,CAAC,MAAwB;IAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,OAAO,CAAC,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;IAC3F,IAAI,OAAO,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;IACtF,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;IACjF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { attachSocket, closeSocket, createSocket, detachSocket, disposeSocket, enableSocketSignals, getSocketReadyState, sendSocketMessage, } from './contract';
+export { areSocketGuardsEnabled, attachSocket, closeSocket, createSocket, detachSocket, disableSocketGuards, disposeSocket, enableSocketGuards, enableSocketSignals, explainSocketSendFailure, getSocketReadyState, 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,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,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,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { attachSocket, closeSocket, createSocket, detachSocket, disposeSocket, enableSocketSignals, getSocketReadyState, sendSocketMessage, } from './contract';
+export { areSocketGuardsEnabled, attachSocket, closeSocket, createSocket, detachSocket, disableSocketGuards, disposeSocket, enableSocketGuards, enableSocketSignals, explainSocketSendFailure, getSocketReadyState, 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,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,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,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/socket.d.ts

@@ -1,4 +1,4 @@
-import type { Socket, SocketBackend, SocketOptions, SocketReadyState, SocketSignals } from '@flighthq/types/contract';
+import type { Socket, SocketBackend, SocketGuard, SocketOptions, SocketReadyState, SocketSignals } 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;
@@ -10,4 +10,5 @@ export declare function getSocketBackend(): SocketBackend;
 export declare function getSocketReadyState(socket: Readonly<Socket>): SocketReadyState;
 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,EAKb,aAAa,EACb,gBAAgB,EAEhB,aAAa,EACd,MAAM,0BAA0B,CAAC;AAIlC,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjD;AAKD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAKhF;AAOD,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAUrE;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,CAIlD;AAKD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAWjE;AAGD,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AAGD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,gBAAgB,CAE9E;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAI/F;AAGD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEpE"}
+{"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"}

package/dist/socket.js

@@ -1,7 +1,10 @@
 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.
+// createSocket leaves a new socket attached, so this is only needed to resume after detachSocket. A
+// disposed socket is terminal and cannot be reattached.
 export function attachSocket(socket) {
+    if (socket.runtime.disposed)
+        return;
     socket.runtime.delivering = true;
 }
 // Begins a clean close of the live connection. Transitions readyState connecting/open → 'closing';
@@ -9,6 +12,10 @@ export function attachSocket(socket) {
 // This is the connection command, distinct from disposeSocket (which releases the entity to GC).
 export function closeSocket(socket, code, reason) {
     const runtime = socket.runtime;
+    if (runtime.disposed) {
+        _guard?.({ operation: 'closeSocket', reason: 'disposed', socket });
+        return;
+    }
     if (runtime.readyState === 'closing' || runtime.readyState === 'closed')
         return;
     runtime.readyState = 'closing';
@@ -25,9 +32,12 @@ export function createSocket(options) {
         signals: null,
         readyState: 'connecting',
         delivering: true,
+        disposed: false,
     };
     const socket = { url: options.url, runtime };
     runtime.connection = getSocketBackend().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
@@ -70,15 +80,24 @@ export function detachSocket(socket) {
 // delivery, and drops the signal group. Distinct from closeSocket — dispose is entity teardown, close
 // is the connection command. After dispose the socket is inert and should not be reused.
 export function disposeSocket(socket) {
+    if (socket.runtime.disposed)
+        return;
     closeSocket(socket);
     detachSocket(socket);
-    socket.runtime.signals = null;
+    const runtime = socket.runtime;
+    runtime.connection = null;
+    runtime.signals = null;
+    runtime.readyState = 'closed';
+    runtime.disposed = true;
 }
 // Opts the socket into its typed event signals, allocating the group on first call and returning it
 // (idempotent — a later call returns the same group). A bare socket that never calls this keeps
-// runtime.signals null and pays no signal allocation or dispatch cost.
+// runtime.signals null and pays no signal allocation or dispatch cost. On a disposed socket the group
+// remains inert; the optional guard reports the misuse while retaining this function's return shape.
 export function enableSocketSignals(socket) {
     const runtime = socket.runtime;
+    if (runtime.disposed)
+        _guard?.({ operation: 'enableSocketSignals', reason: 'disposed', socket });
     if (runtime.signals === null) {
         runtime.signals = {
             onSocketOpen: createSignal(),
@@ -99,10 +118,15 @@ export function getSocketBackend() {
 export function getSocketReadyState(socket) {
     return socket.runtime.readyState;
 }
-// Sends a text or binary frame over the live connection. Returns false — a sentinel, not a throw —
-// when the socket is not open or has no connection.
+// 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.
 export function sendSocketMessage(socket, data) {
     const runtime = socket.runtime;
+    if (runtime.disposed) {
+        _guard?.({ operation: 'sendSocketMessage', reason: 'disposed', socket });
+        return false;
+    }
     if (runtime.readyState !== 'open' || runtime.connection === null)
         return false;
     return runtime.connection.sendSocketFrame(data);
@@ -111,7 +135,13 @@ export function sendSocketMessage(socket, data) {
 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
 // late backend event after teardown fires nothing.

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":"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"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/socket",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.0",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,8 +38,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/signals": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/log": "0.3.0",
+    "@flighthq/signals": "0.3.0",
+    "@flighthq/types": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enableSocketGuards.test.ts

@@ -0,0 +1,108 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import type { LogEntry, SocketBackend } from '@flighthq/types/contract';
+
+import { areSocketGuardsEnabled, disableSocketGuards, enableSocketGuards } from './enableSocketGuards';
+import {
+  closeSocket,
+  createSocket,
+  disposeSocket,
+  enableSocketSignals,
+  sendSocketMessage,
+  setSocketBackend,
+} from './socket';
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+function backend(hasConnection: boolean): SocketBackend {
+  return {
+    openSocket() {
+      if (!hasConnection) return null;
+      return { closeSocketConnection() {}, sendSocketFrame: () => true };
+    },
+  };
+}
+
+afterEach(() => {
+  disableSocketGuards();
+  setSocketBackend(null);
+});
+
+describe('areSocketGuardsEnabled', () => {
+  it('reports whether the global guard hook is installed', () => {
+    enableSocketGuards();
+    expect(areSocketGuardsEnabled()).toBe(true);
+    disableSocketGuards();
+    expect(areSocketGuardsEnabled()).toBe(false);
+  });
+});
+
+describe('disableSocketGuards', () => {
+  it('restores silent core behavior', () => {
+    enableSocketGuards();
+    disableSocketGuards();
+    setSocketBackend(backend(false));
+    expect(captureLog(() => createSocket({ url: 'tcp://silent' }))).toEqual([]);
+  });
+});
+
+describe('enableSocketGuards', () => {
+  it('warns once when socket creation produces no connection', () => {
+    enableSocketGuards();
+    setSocketBackend(backend(false));
+    const entries = captureLog(() => {
+      createSocket({ url: 'tcp://unsupported' });
+      createSocket({ url: 'tcp://unsupported-again' });
+    });
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({ channel: 'socket' });
+    expect(entries[0].data).toMatchObject({
+      operation: 'createSocket',
+      reason: 'no-connection',
+      url: 'tcp://unsupported',
+    });
+    expect(String((entries[0].data as Record<string, unknown>).message)).toContain('setSocketBackend');
+  });
+
+  it('warns once per command issued after terminal disposal', () => {
+    enableSocketGuards();
+    setSocketBackend(backend(true));
+    const socket = createSocket({ url: 'ws://disposed' });
+    disposeSocket(socket);
+    const entries = captureLog(() => {
+      closeSocket(socket);
+      closeSocket(socket);
+      sendSocketMessage(socket, 'frame');
+      enableSocketSignals(socket);
+    });
+    expect(entries).toHaveLength(3);
+    expect(entries.map((entry) => (entry.data as Record<string, unknown>).operation)).toEqual([
+      'closeSocket',
+      'sendSocketMessage',
+      'enableSocketSignals',
+    ]);
+    for (const entry of entries) {
+      expect(entry.data).toMatchObject({ reason: 'disposed', url: 'ws://disposed' });
+      expect(String((entry.data as Record<string, unknown>).message)).toContain('createSocket');
+    }
+  });
+
+  it('stays silent for ordinary pre-open sends and closes', () => {
+    enableSocketGuards();
+    setSocketBackend(backend(true));
+    const socket = createSocket({ url: 'ws://connecting' });
+    const entries = captureLog(() => {
+      sendSocketMessage(socket, 'early');
+      closeSocket(socket);
+    });
+    expect(entries).toEqual([]);
+  });
+});

package/src/explainSocketSendFailure.test.ts

@@ -0,0 +1,63 @@
+import type { SocketBackend, SocketEventSink } from '@flighthq/types/contract';
+
+import { explainSocketSendFailure } from './explainSocketSendFailure';
+import { createSocket, disposeSocket, sendSocketMessage, setSocketBackend } from './socket';
+
+function installBackend(hasConnection: boolean, sendResult = true): () => SocketEventSink {
+  let sink!: SocketEventSink;
+  const backend: SocketBackend = {
+    openSocket(_options, events) {
+      sink = events;
+      if (!hasConnection) return null;
+      return {
+        closeSocketConnection() {},
+        sendSocketFrame: () => sendResult,
+      };
+    },
+  };
+  setSocketBackend(backend);
+  return () => sink;
+}
+
+afterEach(() => setSocketBackend(null));
+
+describe('explainSocketSendFailure', () => {
+  it('identifies an unsupported backend with no connection', () => {
+    installBackend(false);
+    const socket = createSocket({ url: 'tcp://host' });
+    expect(explainSocketSendFailure(socket)).toEqual({
+      reason: 'no-connection',
+      readyState: 'connecting',
+      url: 'tcp://host',
+    });
+  });
+
+  it('reports the current non-open phase when a connection exists', () => {
+    installBackend(true);
+    const socket = createSocket({ url: 'ws://host' });
+    expect(explainSocketSendFailure(socket)).toEqual({
+      reason: 'not-open',
+      readyState: 'connecting',
+      url: 'ws://host',
+    });
+  });
+
+  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' });
+    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' });
+    disposeSocket(socket);
+    expect(explainSocketSendFailure(socket)).toEqual({
+      reason: 'disposed',
+      readyState: 'closed',
+      url: 'ws://host',
+    });
+  });
+});

package/src/socket.test.ts

@@ -19,6 +19,7 @@ import {
   getSocketReadyState,
   sendSocketMessage,
   setSocketBackend,
+  setSocketGuard,
 } from './socket';
 
 interface FakeSocket {
@@ -63,7 +64,10 @@ function fakeBackend(): FakeSocket {
   return state;
 }
 
-afterEach(() => setSocketBackend(null));
+afterEach(() => {
+  setSocketBackend(null);
+  setSocketGuard(null);
+});
 
 describe('attachSocket', () => {
   it('resumes delivery after a detach', () => {
@@ -78,6 +82,20 @@ describe('attachSocket', () => {
     fake.sink.handleSocketOpen();
     expect(opens).toBe(1);
   });
+
+  it('cannot resume delivery after terminal disposal', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    const signals = enableSocketSignals(socket);
+    let opens = 0;
+    connectSignal(signals.onSocketOpen, () => opens++);
+    disposeSocket(socket);
+    attachSocket(socket);
+    fake.sink.handleSocketOpen();
+    expect(opens).toBe(0);
+    expect(socket.runtime.delivering).toBe(false);
+  });
 });
 
 describe('closeSocket', () => {
@@ -111,6 +129,16 @@ describe('closeSocket', () => {
     closeSocket(socket);
     expect(fake.closes).toHaveLength(1);
   });
+
+  it('stays closed and does not close the connection again after disposal', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    disposeSocket(socket);
+    closeSocket(socket);
+    expect(getSocketReadyState(socket)).toBe('closed');
+    expect(fake.closes).toHaveLength(1);
+  });
 });
 
 describe('createSocket', () => {
@@ -296,6 +324,8 @@ describe('disposeSocket', () => {
     fake.sink.handleSocketOpen();
     disposeSocket(socket);
     expect(fake.closes).toHaveLength(1);
+    expect(socket.runtime.connection).toBeNull();
+    expect(getSocketReadyState(socket)).toBe('closed');
     fake.sink.handleSocketMessage({ data: 'x', binary: false });
     expect(messages).toBe(0);
   });
@@ -322,6 +352,17 @@ describe('enableSocketSignals', () => {
     const socket = createSocket({ 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' });
+    disposeSocket(socket);
+    const first = enableSocketSignals(socket);
+    expect(enableSocketSignals(socket)).toBe(first);
+    expect(socket.runtime.delivering).toBe(false);
+    expect(getSocketReadyState(socket)).toBe('closed');
+  });
 });
 
 describe('getSocketBackend', () => {
@@ -369,13 +410,37 @@ describe('sendSocketMessage', () => {
     expect(fake.sent).toEqual([]);
   });
 
-  it('propagates a false send result from the connection', () => {
+  it('returns false after disposal without reaching the released connection', () => {
     const fake = fakeBackend();
-    fake.sendReturns = false;
     setSocketBackend(fake.backend);
     const socket = createSocket({ url: 'ws://x' });
     fake.sink.handleSocketOpen();
+    disposeSocket(socket);
     expect(sendSocketMessage(socket, 'ping')).toBe(false);
+    expect(fake.sent).toEqual([]);
+  });
+
+  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' });
+    fake.sink.handleSocketOpen();
+    expect(getSocketReadyState(socket)).toBe('open');
+    expect(sendSocketMessage(socket, 'ping')).toBe(false);
+  });
+
+  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' });
+    fake.sink.handleSocketOpen();
+    Object.freeze(socket.runtime);
+    Object.freeze(socket);
+    const frame = new Uint8Array([1, 2, 3]).buffer;
+    expect(sendSocketMessage(socket, frame)).toBe(false);
+    expect(fake.sent[0]).toBe(frame);
   });
 });
 
@@ -391,6 +456,34 @@ describe('setSocketBackend', () => {
   });
 });
 
+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() {},