@flighthq/ipc 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.638.d4dbd4e

package/README.md

@@ -1,6 +1,6 @@
 # @flighthq/ipc
 
-Inter-process messaging (send, invoke, per-channel subscribe) over a swappable web/native backend
+Inter-process message reception over an explicit host capability
 
 ## Install
 
@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/ipc`. The `@flighthq
 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/ipc@0.5.0-next.1944.cd6b6e7](https://github.com/flighthq/flight/tree/cd6b6e71eb472b3a4249830a7743333f019fa7b7/packages/ipc)
-- [License](https://github.com/flighthq/flight/blob/cd6b6e71eb472b3a4249830a7743333f019fa7b7/LICENSE.md)
+- [Source for @flighthq/ipc@0.5.1-edge.638.d4dbd4e](https://github.com/flighthq/flight/tree/d4dbd4e347dc8be10b180c85a766ab50333dcb51/packages/ipc)
+- [License](https://github.com/flighthq/flight/blob/d4dbd4e347dc8be10b180c85a766ab50333dcb51/LICENSE.md)

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createIpcChannel, enableIpcSignals, explainIpcBackend, getIpcListenerCount, getIpcSignals, invokeIpc, invokeIpcWithTimeout, onIpcInvoke, onIpcMessage, onIpcMessageEvent, onceIpcMessage, removeAllIpcListeners, sendIpcMessage, sendIpcMessageTo, } from './contract';
+export { onIpcMessage, onceIpcMessage } 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,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createIpcChannel, enableIpcSignals, explainIpcBackend, getIpcListenerCount, getIpcSignals, invokeIpc, invokeIpcWithTimeout, onIpcInvoke, onIpcMessage, onIpcMessageEvent, onceIpcMessage, removeAllIpcListeners, sendIpcMessage, sendIpcMessageTo, } from './contract';
+export { onIpcMessage, onceIpcMessage } 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,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/ipc.d.ts

@@ -1,23 +1,4 @@
-import type { BackendExplanation } from '@flighthq/types/contract';
-import type { IpcBackend, IpcChannel, IpcMessageEvent, IpcSignals, IpcTarget } from '@flighthq/types/contract';
-export declare function createIpcChannel(name: string): IpcChannel;
-export declare function enableIpcSignals(): IpcSignals;
-export declare function explainIpcBackend(): BackendExplanation;
-export declare function getIpcBackend(): IpcBackend;
-export declare function getIpcListenerCount(channel: string | Readonly<IpcChannel>): number;
-export declare function getIpcSignals(): Readonly<IpcSignals> | null;
-export declare function hasIpcBackend(): boolean;
-export declare function installIpcHostBackend(backend: IpcBackend): void;
-export declare function invokeIpc(channel: string | Readonly<IpcChannel>, ...args: readonly unknown[]): Promise<unknown>;
-export declare function invokeIpcWithTimeout(channel: string | Readonly<IpcChannel>, timeoutMs: number, ...args: readonly unknown[]): Promise<unknown>;
-export declare function observeIpcHostResult(operation: string, succeeded: boolean): void;
-export declare function onceIpcMessage(channel: string | Readonly<IpcChannel>, listener: (...args: readonly unknown[]) => void): () => void;
-export declare function onIpcInvoke(channel: string | Readonly<IpcChannel>, handler: (...args: readonly unknown[]) => unknown | Promise<unknown>): () => void;
-export declare function onIpcMessage(channel: string | Readonly<IpcChannel>, listener: (...args: readonly unknown[]) => void): () => void;
-export declare function onIpcMessageEvent(channel: string | Readonly<IpcChannel>, listener: (event: Readonly<IpcMessageEvent>) => void): () => void;
-export declare function removeAllIpcListeners(channel?: string | Readonly<IpcChannel>): void;
-export declare function resetIpcBackendForTest(): void;
-export declare function sendIpcMessage(channel: string | Readonly<IpcChannel>, ...args: readonly unknown[]): void;
-export declare function sendIpcMessageTo(target: Readonly<IpcTarget>, channel: string | Readonly<IpcChannel>, ...args: readonly unknown[]): void;
-export declare function setIpcBackend(backend: IpcBackend | null): void;
+import type { HasIpcMessage } from '@flighthq/types/contract';
+export declare function onceIpcMessage(host: HasIpcMessage, channel: string, listener: (...args: readonly unknown[]) => void): () => void;
+export declare function onIpcMessage(host: HasIpcMessage, channel: string, listener: (...args: readonly unknown[]) => void): () => void;
 //# sourceMappingURL=ipc.d.ts.map

package/dist/ipc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ipc.d.ts","sourceRoot":"","sources":["../src/ipc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EACV,UAAU,EAEV,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACV,MAAM,0BAA0B,CAAC;AAkClC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAEzD;AAKD,wBAAgB,gBAAgB,IAAI,UAAU,CAQ7C;AAGD,wBAAgB,iBAAiB,IAAI,kBAAkB,CAatD;AAGD,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAGD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,CAGlF;AAGD,wBAAgB,aAAa,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAE3D;AAGD,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAID,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAM/D;AAID,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/G;AAID,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAC1B,OAAO,CAAC,OAAO,CAAC,CAYlB;AAGD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAKhF;AAID,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,GAC9C,MAAM,IAAI,CAOZ;AAKD,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACnE,MAAM,IAAI,CAIZ;AAID,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,GAC9C,MAAM,IAAI,CAgBZ;AAID,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,eAAe,CAAC,KAAK,IAAI,GACnD,MAAM,IAAI,CAyBZ;AAGD,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAYnF;AAGD,wBAAgB,sBAAsB,IAAI,IAAI,CAK7C;AAGD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAExG;AAID,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,EAC3B,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAC1B,IAAI,CAEN;AAGD,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAG9D"}
+{"version":3,"file":"ipc.d.ts","sourceRoot":"","sources":["../src/ipc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAkB9D,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,GAC9C,MAAM,IAAI,CAiBZ;AAID,wBAAgB,YAAY,CAC1B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,GAC9C,MAAM,IAAI,CAEZ"}

package/dist/ipc.js

@@ -1,231 +1,42 @@
-import { createSignal, emitSignal } from '@flighthq/signals/contract';
-import { IpcTimeoutError } from '@flighthq/types/contract';
-// Resolves a channel argument that may be either a string or an IpcChannel descriptor.
-function resolveChannel(channel) {
-    return typeof channel === 'string' ? channel : channel.name;
-}
-// Package-local listener tracking, keyed by channel name. Used by onceIpcMessage,
-// removeAllIpcListeners, and getIpcListenerCount. Each entry is the unsubscribe thunk
-// returned by the backend, associated with a channel string.
-const _listeners = new Map();
-function _trackListener(channel, unsubscribe) {
-    let set = _listeners.get(channel);
-    if (set === undefined) {
-        set = new Set();
-        _listeners.set(channel, set);
-    }
-    set.add(unsubscribe);
-}
-function _untrackListener(channel, unsubscribe) {
-    const set = _listeners.get(channel);
-    if (set !== undefined) {
-        set.delete(unsubscribe);
-        if (set.size === 0)
-            _listeners.delete(channel);
-    }
-}
-let _ipcSignals = null;
-// Creates a typed channel descriptor. Functions that accept a channel string also accept an
-// IpcChannel, so a feature can publish its channel constants once and get a single grep target.
-export function createIpcChannel(name) {
-    return { name };
-}
-// Activates the optional IpcSignals group and returns it. Calling this is when the cost is assumed.
-// The returned object is shared for the lifetime of the package; calling enableIpcSignals multiple
-// times returns the same instance.
-export function enableIpcSignals() {
-    if (_ipcSignals === null) {
-        _ipcSignals = {
-            onBackendChanged: createSignal(),
-            onChannelMessage: createSignal(),
-        };
-    }
-    return _ipcSignals;
-}
-// Returns a BackendExplanation describing the active backend layer, conflict state, and viability.
-export function explainIpcBackend() {
-    if (_custom !== null) {
-        return { conflict: _hostConflict, layer: 'custom', operation: null, viability: 'unobserved' };
-    }
-    if (_host !== null) {
-        return {
-            conflict: _hostConflict,
-            layer: 'host',
-            operation: _hostObservation !== null ? _hostObservation.operation : null,
-            viability: _hostObservation !== null ? _hostObservation.viability : 'unobserved',
-        };
-    }
-    return { conflict: false, layer: 'host-not-enabled', operation: null, viability: 'unobserved' };
-}
-// Returns the active IpcBackend. Precedence: custom > host > sentinel.
-export function getIpcBackend() {
-    return _custom ?? _host ?? _sentinel;
-}
-// Returns the count of active in-package listeners on a channel. Returns 0 for an unknown channel.
-export function getIpcListenerCount(channel) {
-    const name = resolveChannel(channel);
-    return _listeners.get(name)?.size ?? 0;
-}
-// Returns the active IpcSignals group, or null if enableIpcSignals has not been called.
-export function getIpcSignals() {
-    return _ipcSignals;
-}
-// Returns true when a custom or host backend is installed, false when only the sentinel is active.
-export function hasIpcBackend() {
-    return _custom !== null || _host !== null;
-}
-// Installs the host-layer IPC backend. Idempotent: a second call with the same backend is a no-op;
-// a second call with a different backend sets the conflict flag and keeps the first.
-export function installIpcHostBackend(backend) {
-    if (_host !== null) {
-        if (_host !== backend)
-            _hostConflict = true;
-        return;
-    }
-    _host = backend;
-}
-// Sends a request on `channel` and resolves with the host's response, or undefined on web.
-// Rejects with a plain Error if the host handler throws.
-export function invokeIpc(channel, ...args) {
-    return getIpcBackend().invoke(resolveChannel(channel), args);
-}
-// Sends a request on `channel` and resolves with the host's response, or rejects with
-// IpcTimeoutError if the invoke does not complete within timeoutMs milliseconds.
-export function invokeIpcWithTimeout(channel, timeoutMs, ...args) {
-    const name = resolveChannel(channel);
-    const invoke = getIpcBackend().invoke(name, args);
-    const timeout = new Promise((_, reject) => {
-        const id = setTimeout(() => reject(new IpcTimeoutError(name, timeoutMs)), timeoutMs);
-        // Attach a no-op catch so the invoke rejection does not surface if timeout fires first.
-        invoke.then(() => clearTimeout(id), () => clearTimeout(id));
-    });
-    return Promise.race([invoke, timeout]);
-}
-// Records the result of a host-layer IPC operation for diagnostic reporting via explainIpcBackend.
-export function observeIpcHostResult(operation, succeeded) {
-    _hostObservation = {
-        operation,
-        viability: succeeded ? 'available' : 'runtime-api-unavailable',
-    };
-}
-// Subscribes `listener` to a single message on `channel`, then auto-unsubscribes.
-// Returns an unsubscribe thunk for the not-yet-fired case.
-export function onceIpcMessage(channel, listener) {
+// Inter-process message reception, over the explicitly supplied host. Every operation takes its host and
+// reads `host.ipc.message` directly: there is no resolver, no sentinel, no installed-backend state and
+// no "no provider" runtime arm, because the `HasIpcMessage` witness is what guarantees the slot exists.
+// A caller without a provider cannot call these at all — that is a compile error, not a false answer.
+//
+// ★ THE WHOLE AMBIENT FAMILY IS GONE — getIpcBackend / setIpcBackend / installIpcHostBackend /
+// resetIpcBackendForTest / observeIpcHostResult / explainIpcBackend / explainIpcOperation /
+// hasIpcBackend / hasIpcOperation, plus the module-scoped _custom/_host/_hostConflict/_hostObservation/
+// _sentinel/_listeners registry. The sentinel in particular answered every operation, so a caller could
+// not tell an installed backend from nothing at all.
+// Subscribes to messages on `channel` for the NEXT message only, then releases the subscription.
+// Returns the unsubscribe, so a caller that never receives a message can still stop listening.
+//
+// The unsubscribe is idempotent and ORIGIN-PINNED: it releases exactly the subscription this call
+// opened, whether it runs after the first message or before any arrives.
+export function onceIpcMessage(host, channel, listener) {
     let unsubscribe = null;
-    unsubscribe = onIpcMessage(channel, (...args) => {
+    let done = false;
+    const release = () => {
+        if (done)
+            return;
+        done = true;
+        // `unsubscribe` is null only if the provider delivered synchronously during subscribe; the guard
+        // below releases in that case, so neither ordering leaks a subscription.
         unsubscribe?.();
-        listener(...args);
-    });
-    return unsubscribe;
-}
-// Registers a responder for invokeIpc calls on `channel`. The handler may return a value or a
-// Promise. Returns an unregister thunk. Requires a backend that supports `handle`; if the backend
-// does not support it, returns an inert no-op unsubscribe.
-export function onIpcInvoke(channel, handler) {
-    const backend = getIpcBackend();
-    if (typeof backend.handle !== 'function')
-        return () => { };
-    return backend.handle(resolveChannel(channel), handler);
-}
-// Subscribes `listener` to messages on `channel`; returns an unsubscribe function.
-// Incoming args are spread to the listener, mirroring sendIpcMessage's variadic shape.
-export function onIpcMessage(channel, listener) {
-    const name = resolveChannel(channel);
-    const backend = getIpcBackend();
-    const signals = _ipcSignals;
-    const unsubscribe = backend.subscribe(name, (args) => {
-        if (signals !== null)
-            emitSignal(signals.onChannelMessage, name);
-        listener(...args);
-    });
-    const tracked = () => {
-        unsubscribe();
-        _untrackListener(name, tracked);
     };
-    _trackListener(name, tracked);
-    return tracked;
-}
-// Subscribes `listener` to messages on `channel`, delivering an IpcMessageEvent with channel,
-// senderId, args, and a reply thunk. The existing args-spread onIpcMessage path stays untouched.
-export function onIpcMessageEvent(channel, listener) {
-    const name = resolveChannel(channel);
-    const backend = getIpcBackend();
-    const signals = _ipcSignals;
-    const unsubscribe = backend.subscribe(name, (args) => {
-        if (signals !== null)
-            emitSignal(signals.onChannelMessage, name);
-        const event = {
-            channel: name,
-            senderId: -1,
-            args,
-            reply(...replyArgs) {
-                if (this.senderId === -1)
-                    return;
-                backend.sendTo?.({ windowId: this.senderId }, name, replyArgs);
-            },
-        };
-        listener(event);
+    unsubscribe = host.ipc.message.subscribe(channel, (args) => {
+        if (done)
+            return;
+        release();
+        listener(...args);
     });
-    const tracked = () => {
+    if (done)
         unsubscribe();
-        _untrackListener(name, tracked);
-    };
-    _trackListener(name, tracked);
-    return tracked;
-}
-// Drops every in-package listener for `channel`, or all channels when omitted.
-export function removeAllIpcListeners(channel) {
-    if (channel !== undefined) {
-        const name = resolveChannel(channel);
-        const set = _listeners.get(name);
-        if (set !== undefined) {
-            for (const unsubscribe of [...set])
-                unsubscribe();
-        }
-    }
-    else {
-        for (const [, set] of [..._listeners]) {
-            for (const unsubscribe of [...set])
-                unsubscribe();
-        }
-    }
-}
-// Resets all backend state to initial values. Test-only — not part of the public API.
-export function resetIpcBackendForTest() {
-    _custom = null;
-    _host = null;
-    _hostConflict = false;
-    _hostObservation = null;
-}
-// Sends a fire-and-forget message on `channel`. No-ops when only the sentinel is active.
-export function sendIpcMessage(channel, ...args) {
-    getIpcBackend().send(resolveChannel(channel), args);
-}
-// Sends a fire-and-forget message to a specific target window/process. No-ops when the backend
-// does not support targeted send (i.e. `getCapabilities().canTarget` is false or `sendTo` is absent).
-export function sendIpcMessageTo(target, channel, ...args) {
-    getIpcBackend().sendTo?.(target, resolveChannel(channel), args);
+    return release;
 }
-// Installs a custom IPC backend; pass null to clear and fall back to host or sentinel.
-export function setIpcBackend(backend) {
-    _custom = backend;
-    if (_ipcSignals !== null)
-        emitSignal(_ipcSignals.onBackendChanged);
+// Subscribes to every message on `channel`. Returns the unsubscribe for THIS subscription alone —
+// releasing one listener never disturbs another on the same channel.
+export function onIpcMessage(host, channel, listener) {
+    return host.ipc.message.subscribe(channel, (args) => listener(...args));
 }
-const _sentinel = {
-    send() { },
-    invoke() {
-        return Promise.resolve(undefined);
-    },
-    subscribe() {
-        return () => { };
-    },
-    getCapabilities() {
-        return { canHandle: false, canInvoke: false, canSend: false, canTarget: false };
-    },
-};
-let _custom = null;
-let _host = null;
-let _hostConflict = false;
-let _hostObservation = null;
 //# sourceMappingURL=ipc.js.map

package/dist/ipc.js.map

@@ -1 +1 @@
-{"version":3,"file":"ipc.js","sourceRoot":"","sources":["../src/ipc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ipc.js","sourceRoot":"","sources":["../src/ipc.ts"],"names":[],"mappings":"AAEA,yGAAyG;AACzG,uGAAuG;AACvG,wGAAwG;AACxG,sGAAsG;AACtG,EAAE;AACF,+FAA+F;AAC/F,4FAA4F;AAC5F,wGAAwG;AACxG,wGAAwG;AACxG,qDAAqD;AAErD,iGAAiG;AACjG,+FAA+F;AAC/F,EAAE;AACF,kGAAkG;AAClG,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAC5B,IAAmB,EACnB,OAAe,EACf,QAA+C;IAE/C,IAAI,WAAW,GAAwB,IAAI,CAAC;IAC5C,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,IAAI,IAAI;YAAE,OAAO;QACjB,IAAI,GAAG,IAAI,CAAC;QACZ,iGAAiG;QACjG,yEAAyE;QACzE,WAAW,EAAE,EAAE,CAAC;IAClB,CAAC,CAAC;IACF,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;QACzD,IAAI,IAAI;YAAE,OAAO;QACjB,OAAO,EAAE,CAAC;QACV,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;IACH,IAAI,IAAI;QAAE,WAAW,EAAE,CAAC;IACxB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,kGAAkG;AAClG,qEAAqE;AACrE,MAAM,UAAU,YAAY,CAC1B,IAAmB,EACnB,OAAe,EACf,QAA+C;IAE/C,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAC1E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/ipc",
-  "version": "0.5.0-next.1944.cd6b6e7",
+  "version": "0.5.1-edge.638.d4dbd4e",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,12 +38,13 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/signals": "0.5.0-next.1944.cd6b6e7",
-    "@flighthq/types": "0.5.0-next.1944.cd6b6e7"
+    "@flighthq/signals": "0.5.1-edge.638.d4dbd4e",
+    "@flighthq/types": "0.5.1-edge.638.d4dbd4e"
   },
   "devDependencies": {
+    "@flighthq/entity": "*",
     "typescript": "^5.3.0"
   },
-  "description": "Inter-process messaging (send, invoke, per-channel subscribe) over a swappable web/native backend",
+  "description": "Inter-process message reception over an explicit host capability",
   "sideEffects": false
 }

package/src/ipc.test.ts

@@ -1,575 +1,136 @@
-import type { IpcBackend, IpcBackendCapabilities, IpcChannel, IpcSignals } from '@flighthq/types/contract';
-import { IpcTimeoutError } from '@flighthq/types/contract';
-
-import {
-  createIpcChannel,
-  enableIpcSignals,
-  getIpcBackend,
-  getIpcListenerCount,
-  getIpcSignals,
-  hasIpcBackend,
-  invokeIpc,
-  invokeIpcWithTimeout,
-  onceIpcMessage,
-  onIpcInvoke,
-  onIpcMessage,
-  onIpcMessageEvent,
-  removeAllIpcListeners,
-  sendIpcMessage,
-  sendIpcMessageTo,
-  setIpcBackend,
-  explainIpcBackend,
-  installIpcHostBackend,
-  observeIpcHostResult,
-  resetIpcBackendForTest,
-} from './ipc';
-
-interface FakeIpcBackend extends IpcBackend {
-  sent: { channel: string; args: readonly unknown[] }[];
-  sentTo: { target: { windowId: number }; channel: string; args: readonly unknown[] }[];
-  result: unknown;
-  handlers: Map<string, (...args: readonly unknown[]) => unknown | Promise<unknown>>;
-  fire: (channel: string, args: readonly unknown[]) => void;
-}
-
-function fakeBackend(
-  opts: { canSend?: boolean; canInvoke?: boolean; canHandle?: boolean; canTarget?: boolean } = {},
-): FakeIpcBackend {
-  const { canSend = true, canInvoke = true, canHandle = true, canTarget = true } = opts;
-
-  const listeners = new Map<string, (args: readonly unknown[]) => void>();
-  const backend: FakeIpcBackend = {
-    sent: [],
-    sentTo: [],
-    result: undefined,
-    handlers: new Map(),
-    send(channel, args) {
-      this.sent.push({ channel, args });
-    },
-    invoke(channel, _args) {
-      return Promise.resolve(this.result);
-    },
-    subscribe(channel, listener) {
-      listeners.set(channel, listener);
-      return () => {
-        listeners.delete(channel);
-      };
-    },
-    handle(channel, handler) {
-      this.handlers.set(channel, handler);
-      return () => {
-        this.handlers.delete(channel);
-      };
-    },
-    sendTo(target, channel, args) {
-      this.sentTo.push({ target, channel, args });
+import { createEntity } from '@flighthq/entity/contract';
+import type { EntityWithoutRuntime, HasIpcMessage, IpcMessageBackend } from '@flighthq/types/contract';
+
+import { onIpcMessage, onceIpcMessage } from './ipc';
+
+// A host carrying a recording message provider. Nothing installs anywhere, so two hosts can be live at
+// once — the property the ambient seam could not express.
+function messageHost(): HasIpcMessage & {
+  deliver(channel: string, ...args: readonly unknown[]): void;
+  subscriberCount(channel: string): number;
+} {
+  const channels = new Map<string, Set<(args: readonly unknown[]) => void>>();
+  return {
+    deliver(channel: string, ...args: readonly unknown[]): void {
+      for (const listener of [...(channels.get(channel) ?? [])]) listener(args);
     },
-    getCapabilities(): Readonly<IpcBackendCapabilities> {
-      return { canHandle, canInvoke, canSend, canTarget };
+    ipc: {
+      message: createEntity<EntityWithoutRuntime<IpcMessageBackend>>({
+        subscribe(channel: string, listener: (args: readonly unknown[]) => void): () => void {
+          const set = channels.get(channel) ?? new Set();
+          channels.set(channel, set);
+          set.add(listener);
+          return () => set.delete(listener);
+        },
+      }),
     },
-    fire(channel, args) {
-      listeners.get(channel)?.(args);
+    subscriberCount(channel: string): number {
+      return channels.get(channel)?.size ?? 0;
     },
   };
-  return backend;
 }
 
-afterEach(() => {
-  setIpcBackend(null);
-  removeAllIpcListeners();
-});
-
-describe('createIpcChannel', () => {
-  it('returns a descriptor with the given name', () => {
-    const ch: IpcChannel = createIpcChannel('events.ready');
-    expect(ch.name).toBe('events.ready');
-  });
-
-  it('accepts IpcChannel descriptors in sendIpcMessage', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const ch = createIpcChannel('log');
-    sendIpcMessage(ch, 'hello');
-    expect(backend.sent).toEqual([{ channel: 'log', args: ['hello'] }]);
-  });
-
-  it('accepts IpcChannel descriptors in onIpcMessage', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const ch = createIpcChannel('event');
-    const received: unknown[] = [];
-    onIpcMessage(ch, (...args) => received.push(...args));
-    backend.fire('event', ['x']);
-    expect(received).toEqual(['x']);
-  });
-});
-
-describe('enableIpcSignals', () => {
-  it('returns an IpcSignals group', () => {
-    const signals: IpcSignals = enableIpcSignals();
-    expect(signals.onBackendChanged).toBeDefined();
-    expect(signals.onChannelMessage).toBeDefined();
-  });
-
-  it('returns the same instance on repeated calls', () => {
-    const a = enableIpcSignals();
-    const b = enableIpcSignals();
-    expect(a).toBe(b);
-  });
-
-  it('fires onBackendChanged when setIpcBackend is called', () => {
-    const signals = enableIpcSignals();
-    let fired = 0;
-    signals.onBackendChanged.emit = () => {
-      fired++;
+describe('onceIpcMessage', () => {
+  it('delivers the first message and then releases the subscription', () => {
+    const host = messageHost();
+    const seen: (readonly unknown[])[] = [];
+    onceIpcMessage(host, 'ping', (...args) => seen.push(args));
+    host.deliver('ping', 1);
+    host.deliver('ping', 2);
+    expect(seen).toEqual([[1]]);
+    expect(host.subscriberCount('ping')).toBe(0);
+  });
+
+  // A caller that never receives a message must still be able to stop listening.
+  it('returns an unsubscribe that works before any message arrives', () => {
+    const host = messageHost();
+    let count = 0;
+    const stop = onceIpcMessage(host, 'ping', () => count++);
+    stop();
+    expect(host.subscriberCount('ping')).toBe(0);
+    host.deliver('ping');
+    expect(count).toBe(0);
+  });
+
+  it('releases exactly once across repeated stop calls', () => {
+    let releases = 0;
+    const host: HasIpcMessage = {
+      ipc: {
+        message: createEntity<EntityWithoutRuntime<IpcMessageBackend>>({
+          subscribe(): () => void {
+            return () => releases++;
+          },
+        }),
+      },
     };
-    setIpcBackend(fakeBackend());
-    expect(fired).toBe(1);
-    setIpcBackend(null);
-    expect(fired).toBe(2);
-  });
-
-  it('fires onChannelMessage when a message is received', () => {
-    const signals = enableIpcSignals();
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const channels: string[] = [];
-    signals.onChannelMessage.emit = (ch) => {
-      channels.push(ch);
+    const stop = onceIpcMessage(host, 'ping', () => {});
+    stop();
+    stop();
+    expect(releases).toBe(1);
+  });
+
+  // ★ ACQUISITION RACE: a provider that delivers synchronously DURING subscribe returns its unsubscribe
+  // only afterwards. Without the guard the subscription would leak, because release ran before there was
+  // anything to release.
+  it('releases even when the provider delivers during subscribe', () => {
+    let released = false;
+    const host: HasIpcMessage = {
+      ipc: {
+        message: createEntity<EntityWithoutRuntime<IpcMessageBackend>>({
+          subscribe(_channel, listener): () => void {
+            listener([42]);
+            return () => (released = true);
+          },
+        }),
+      },
     };
-    onIpcMessage('events', () => {});
-    backend.fire('events', []);
-    expect(channels).toEqual(['events']);
-  });
-
-  it('does not emit onChannelMessage at subscribe time, only on delivery', () => {
-    const signals = enableIpcSignals();
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const channels: string[] = [];
-    signals.onChannelMessage.emit = (ch) => {
-      channels.push(ch);
-    };
-    onIpcMessage('events', () => {});
-    onIpcMessageEvent('events2', () => {});
-    // Registering listeners must not emit; the signal is a per-delivery notification.
-    expect(channels).toEqual([]);
-    backend.fire('events', []);
-    backend.fire('events2', []);
-    expect(channels).toEqual(['events', 'events2']);
-  });
-});
-
-describe('explainIpcBackend', () => {
-  afterEach(() => resetIpcBackendForTest());
-
-  it('reports host-not-enabled when no backend is installed', () => {
-    resetIpcBackendForTest();
-    const explanation = explainIpcBackend();
-    expect(explanation.layer).toBe('host-not-enabled');
-    expect(explanation.conflict).toBe(false);
-    expect(explanation.viability).toBe('unobserved');
-  });
-
-  it('reports custom layer when a custom backend is set', () => {
-    setIpcBackend(fakeBackend());
-    expect(explainIpcBackend().layer).toBe('custom');
-  });
-
-  it('reports host layer when a host backend is installed', () => {
-    installIpcHostBackend(fakeBackend());
-    expect(explainIpcBackend().layer).toBe('host');
-  });
-
-  it('reports conflict when two different host backends are installed', () => {
-    installIpcHostBackend(fakeBackend());
-    installIpcHostBackend(fakeBackend());
-    expect(explainIpcBackend().conflict).toBe(true);
-  });
-});
-
-describe('getIpcBackend', () => {
-  it('falls back to a web backend', () => {
-    expect(getIpcBackend()).not.toBeNull();
-  });
-
-  it('returns the registered backend', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    expect(getIpcBackend()).toBe(backend);
-  });
-});
-
-describe('getIpcBackend (sentinel)', () => {
-  it('no-ops send, resolves invoke to undefined, returns an inert unsubscribe', async () => {
-    const backend = getIpcBackend();
-    expect(() => backend.send('channel', [1])).not.toThrow();
-    expect(await backend.invoke('channel', [])).toBeUndefined();
-    expect(typeof backend.subscribe('channel', () => {})).toBe('function');
-  });
-
-  it('reports canSend/canInvoke/canHandle/canTarget as false', () => {
-    const backend = getIpcBackend();
-    const caps = backend.getCapabilities!();
-    expect(caps.canSend).toBe(false);
-    expect(caps.canInvoke).toBe(false);
-    expect(caps.canHandle).toBe(false);
-    expect(caps.canTarget).toBe(false);
-  });
-});
-
-describe('getIpcListenerCount', () => {
-  it('returns 0 for an unknown channel', () => {
-    expect(getIpcListenerCount('never')).toBe(0);
-  });
-
-  it('increments when listeners are added', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    onIpcMessage('ch', () => {});
-    onIpcMessage('ch', () => {});
-    expect(getIpcListenerCount('ch')).toBe(2);
-  });
-
-  it('decrements when a listener unsubscribes', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const off = onIpcMessage('ch', () => {});
-    expect(getIpcListenerCount('ch')).toBe(1);
-    off();
-    expect(getIpcListenerCount('ch')).toBe(0);
-  });
-
-  it('accepts an IpcChannel descriptor', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const ch = createIpcChannel('typed');
-    onIpcMessage(ch, () => {});
-    expect(getIpcListenerCount(ch)).toBe(1);
-  });
-});
-
-describe('getIpcSignals', () => {
-  it('returns null before enableIpcSignals is called', async () => {
-    // The IpcSignals group is a module-level singleton, so once any test in this suite calls
-    // enableIpcSignals the value persists. Re-import the module in isolation to assert the
-    // lazy-null contract deterministically: a fresh module has no group until enable is called.
-    vi.resetModules();
-    const fresh = await import('./ipc');
-    expect(fresh.getIpcSignals()).toBeNull();
-    // Delivery still works with the group disabled — the emit is guarded, never required.
-    const backend = fakeBackend();
-    fresh.setIpcBackend(backend);
-    const received: unknown[] = [];
-    fresh.onIpcMessage('disabled', (...args) => received.push(...args));
-    backend.fire('disabled', ['x']);
-    expect(received).toEqual(['x']);
-    expect(fresh.getIpcSignals()).toBeNull();
-    fresh.setIpcBackend(null);
-  });
-
-  it('returns the signals object after enableIpcSignals', () => {
-    const signals = enableIpcSignals();
-    expect(getIpcSignals()).toBe(signals);
-  });
-});
-
-describe('hasIpcBackend', () => {
-  it('returns false before any backend is set', () => {
-    expect(hasIpcBackend()).toBe(false);
-  });
-
-  it('returns true after setting a native backend', () => {
-    setIpcBackend(fakeBackend());
-    expect(hasIpcBackend()).toBe(true);
-  });
-
-  it('returns false after resetting to null', () => {
-    setIpcBackend(fakeBackend());
-    setIpcBackend(null);
-    expect(hasIpcBackend()).toBe(false);
-  });
-});
-
-describe('installIpcHostBackend', () => {
-  afterEach(() => resetIpcBackendForTest());
-
-  it('installs a host backend that getIpcBackend returns', () => {
-    const backend = fakeBackend();
-    installIpcHostBackend(backend);
-    expect(getIpcBackend()).toBe(backend);
-  });
-
-  it('is first-host-wins: a second different backend sets conflict', () => {
-    const first = fakeBackend();
-    const second = fakeBackend();
-    installIpcHostBackend(first);
-    installIpcHostBackend(second);
-    expect(getIpcBackend()).toBe(first);
-    expect(explainIpcBackend().conflict).toBe(true);
-  });
-});
-
-describe('invokeIpc', () => {
-  it('passes variadic args as an array and resolves the backend result', async () => {
-    const backend = fakeBackend();
-    backend.result = 42;
-    setIpcBackend(backend);
-    expect(await invokeIpc('compute', 1, 2)).toBe(42);
-  });
-
-  it('accepts an IpcChannel descriptor', async () => {
-    const backend = fakeBackend();
-    backend.result = 'ok';
-    setIpcBackend(backend);
-    expect(await invokeIpc(createIpcChannel('compute'), 1)).toBe('ok');
-  });
-});
-
-describe('invokeIpcWithTimeout', () => {
-  it('resolves when the backend responds before timeout', async () => {
-    const backend = fakeBackend();
-    backend.result = 99;
-    setIpcBackend(backend);
-    expect(await invokeIpcWithTimeout('cmd', 1000)).toBe(99);
-  });
-
-  it('rejects with IpcTimeoutError when the backend does not respond in time', async () => {
-    // Replace invoke with one that never resolves.
-    const backend = fakeBackend();
-    backend.invoke = (_channel, _args) => new Promise(() => {});
-    setIpcBackend(backend);
-    await expect(invokeIpcWithTimeout('cmd', 10)).rejects.toBeInstanceOf(IpcTimeoutError);
-  });
-
-  it('IpcTimeoutError carries channel and timeoutMs', async () => {
-    const backend = fakeBackend();
-    backend.invoke = () => new Promise(() => {});
-    setIpcBackend(backend);
-    let err: IpcTimeoutError | undefined;
-    try {
-      await invokeIpcWithTimeout('slow-channel', 5);
-    } catch (e) {
-      err = e as IpcTimeoutError;
-    }
-    expect(err?.channel).toBe('slow-channel');
-    expect(err?.timeoutMs).toBe(5);
-  });
-});
-
-describe('observeIpcHostResult', () => {
-  afterEach(() => resetIpcBackendForTest());
-
-  it('records a successful observation', () => {
-    installIpcHostBackend(fakeBackend());
-    observeIpcHostResult('send', true);
-    const explanation = explainIpcBackend();
-    expect(explanation.operation).toBe('send');
-    expect(explanation.viability).toBe('available');
-  });
-
-  it('records a failed observation', () => {
-    installIpcHostBackend(fakeBackend());
-    observeIpcHostResult('send', false);
-    expect(explainIpcBackend().viability).toBe('runtime-api-unavailable');
-  });
-});
-
-describe('onceIpcMessage', () => {
-  it('auto-unsubscribes after the first message', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const received: unknown[] = [];
-    onceIpcMessage('ping', (...args) => received.push(...args));
-    backend.fire('ping', ['first']);
-    backend.fire('ping', ['second']);
-    expect(received).toEqual(['first']);
-  });
-
-  it('can be manually unsubscribed before the message fires', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const received: unknown[] = [];
-    const off = onceIpcMessage('ping', () => received.push('fired'));
-    off();
-    backend.fire('ping', []);
-    expect(received).toHaveLength(0);
-  });
-});
-
-describe('onIpcInvoke', () => {
-  it('registers a handler via backend.handle', async () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    onIpcInvoke('compute', (...args) => (args[0] as number) * 2);
-    expect(backend.handlers.has('compute')).toBe(true);
-  });
-
-  it('returns an inert unsubscribe when backend has no handle method', () => {
-    const backend = fakeBackend();
-    // Remove optional handle method.
-    delete (backend as Partial<FakeIpcBackend>).handle;
-    setIpcBackend(backend);
-    const off = onIpcInvoke('compute', () => {});
-    expect(typeof off).toBe('function');
-    expect(() => off()).not.toThrow();
-  });
-
-  it('unregisters the handler when unsubscribe is called', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const off = onIpcInvoke('compute', () => {});
-    off();
-    expect(backend.handlers.has('compute')).toBe(false);
+    const seen: (readonly unknown[])[] = [];
+    onceIpcMessage(host, 'ping', (...args) => seen.push(args));
+    expect(seen).toEqual([[42]]);
+    expect(released).toBe(true);
   });
 });
 
 describe('onIpcMessage', () => {
-  it('spreads incoming args to the listener and unsubscribes', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const received: unknown[] = [];
-    const unsubscribe = onIpcMessage('event', (...args) => received.push(args));
-    backend.fire('event', ['a', 'b']);
-    expect(received).toEqual([['a', 'b']]);
-    unsubscribe();
-    backend.fire('event', ['c']);
-    expect(received).toEqual([['a', 'b']]);
-  });
-
-  it('tracks listener count correctly', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    expect(getIpcListenerCount('evt')).toBe(0);
-    const off = onIpcMessage('evt', () => {});
-    expect(getIpcListenerCount('evt')).toBe(1);
-    off();
-    expect(getIpcListenerCount('evt')).toBe(0);
-  });
-});
-
-describe('onIpcMessageEvent', () => {
-  it('delivers an IpcMessageEvent with channel, senderId -1, and args', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const events: Array<{ channel: string; senderId: number; args: readonly unknown[] }> = [];
-    const off = onIpcMessageEvent('ch', (ev) =>
-      events.push({ channel: ev.channel, senderId: ev.senderId, args: ev.args }),
-    );
-    backend.fire('ch', ['hello', 42]);
-    expect(events).toEqual([{ channel: 'ch', senderId: -1, args: ['hello', 42] }]);
-    off();
-  });
-
-  it('reply is a no-op when senderId is -1, even with a sendTo-capable backend', () => {
-    // No backend surfaces sender identity yet, so senderId is permanently -1 and reply must
-    // early-return before touching backend.sendTo. Use a sendTo-capable fake to prove the gate
-    // is on senderId, not method presence: a reply still produces zero outbound sends. This pins
-    // the forward-compatible contract until a backend supplies a real senderId.
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    let observedSenderId: number | undefined;
-    const off = onIpcMessageEvent('ch', (ev) => {
-      observedSenderId = ev.senderId;
-      ev.reply('pong');
-    });
-    backend.fire('ch', []);
-    expect(observedSenderId).toBe(-1);
-    expect(typeof backend.sendTo).toBe('function');
-    expect(backend.sentTo).toHaveLength(0);
-    off();
-  });
-
-  it('tracks listener count and unsubscribes correctly', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const off = onIpcMessageEvent('ch2', () => {});
-    expect(getIpcListenerCount('ch2')).toBe(1);
-    off();
-    expect(getIpcListenerCount('ch2')).toBe(0);
-  });
-});
-
-describe('removeAllIpcListeners', () => {
-  it('removes all listeners for a specific channel', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const received: string[] = [];
-    onIpcMessage('a', () => received.push('a1'));
-    onIpcMessage('a', () => received.push('a2'));
-    onIpcMessage('b', () => received.push('b1'));
-    removeAllIpcListeners('a');
-    backend.fire('a', []);
-    backend.fire('b', []);
-    // 'a' listeners removed, 'b' still active.
-    expect(received).toEqual(['b1']);
-  });
-
-  it('removes all listeners for all channels when omitted', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const received: string[] = [];
-    onIpcMessage('a', () => received.push('a'));
-    onIpcMessage('b', () => received.push('b'));
-    removeAllIpcListeners();
-    backend.fire('a', []);
-    backend.fire('b', []);
-    expect(received).toHaveLength(0);
-  });
-
-  it('accepts an IpcChannel descriptor', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    const ch = createIpcChannel('typed');
-    const received: number[] = [];
-    onIpcMessage(ch, () => received.push(1));
-    removeAllIpcListeners(ch);
-    backend.fire('typed', []);
-    expect(received).toHaveLength(0);
-  });
-});
-
-describe('resetIpcBackendForTest', () => {
-  it('clears all backend slots', () => {
-    setIpcBackend(fakeBackend());
-    installIpcHostBackend(fakeBackend());
-    observeIpcHostResult('send', true);
-    resetIpcBackendForTest();
-    expect(explainIpcBackend().layer).toBe('host-not-enabled');
-    expect(explainIpcBackend().conflict).toBe(false);
-    expect(explainIpcBackend().viability).toBe('unobserved');
-  });
-});
-
-describe('sendIpcMessage', () => {
-  it('forwards channel and args array to the backend', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    sendIpcMessage('log', 'hi', 7);
-    expect(backend.sent).toEqual([{ channel: 'log', args: ['hi', 7] }]);
-  });
-});
-
-describe('sendIpcMessageTo', () => {
-  it('forwards target, channel, and args to backend.sendTo', () => {
-    const backend = fakeBackend();
-    setIpcBackend(backend);
-    sendIpcMessageTo({ windowId: 3 }, 'log', 'hello');
-    expect(backend.sentTo).toEqual([{ target: { windowId: 3 }, channel: 'log', args: ['hello'] }]);
-  });
-
-  it('no-ops when backend has no sendTo method', () => {
-    const backend = fakeBackend();
-    delete (backend as Partial<FakeIpcBackend>).sendTo;
-    setIpcBackend(backend);
-    expect(() => sendIpcMessageTo({ windowId: 1 }, 'log', 'hi')).not.toThrow();
-  });
-});
-
-describe('setIpcBackend', () => {
-  it('clears back to the web fallback when passed null', () => {
-    setIpcBackend(fakeBackend());
-    setIpcBackend(null);
-    expect(getIpcBackend()).not.toBeNull();
+  it('delivers every message on its channel with the sent arguments', () => {
+    const host = messageHost();
+    const seen: (readonly unknown[])[] = [];
+    onIpcMessage(host, 'ping', (...args) => seen.push(args));
+    host.deliver('ping', 1, 'two');
+    host.deliver('ping', 3);
+    expect(seen).toEqual([[1, 'two'], [3]]);
+  });
+
+  it('delivers only its own channel', () => {
+    const host = messageHost();
+    let count = 0;
+    onIpcMessage(host, 'wanted', () => count++);
+    host.deliver('other', 1);
+    expect(count).toBe(0);
+  });
+
+  // ★ ORIGIN-PINNED: releasing one listener must not disturb another on the SAME channel.
+  it('unsubscribes exactly its own subscription', () => {
+    const host = messageHost();
+    const kept: unknown[] = [];
+    const stopDropped = onIpcMessage(host, 'shared', () => kept.push('dropped'));
+    onIpcMessage(host, 'shared', () => kept.push('kept'));
+    stopDropped();
+    host.deliver('shared');
+    expect(kept).toEqual(['kept']);
+    expect(host.subscriberCount('shared')).toBe(1);
+  });
+
+  // ★ Two hosts live at once, each serving its own subscription. Unwritable under the ambient seam,
+  // which had exactly one answer per process.
+  it('routes each subscription to the host it was given', () => {
+    const first = messageHost();
+    const second = messageHost();
+    const seen: string[] = [];
+    onIpcMessage(first, 'c', () => seen.push('first'));
+    onIpcMessage(second, 'c', () => seen.push('second'));
+    second.deliver('c');
+    first.deliver('c');
+    expect(seen).toEqual(['second', 'first']);
   });
 });