@furystack/cross-node-bus 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+## [1.0.0] - 2026-05-21
+
+### 💥 Breaking Changes
+
+### Initial 1.0.0 release
+
+First public release of `@furystack/cross-node-bus` — a transport-agnostic publish/subscribe primitive for FuryStack apps that scale beyond a single process. There is no migration path from a previous version because none exists; this section is required by the major-release contract.
+
+### ✨ Features
+
+### `CrossNodeBus` — shared, typed, multi-node event bus
+
+A pluggable pub/sub primitive that lets every subsystem coordinate across nodes via the same shared facade. Subsystems and apps build typed wrappers (e.g. `IdentityEventBus`, `EntityChangeBus`) on top of one bus instance per injector tree.
+
+```typescript
+import { CrossNodeBus } from '@furystack/cross-node-bus'
+
+const bus = injector.get(CrossNodeBus)
+using sub = bus.subscribe('my-topic', ({ payload, originId }) => {
+  console.log('received', payload, 'from', originId)
+})
+await bus.publish('my-topic', { hello: 'world' })
+```
+
+Self-delivery is on by default: a publisher receives its own messages. Subscribers that only care about sibling traffic use `subscribeRemoteOnly(topic, handler)`.
+
+### In-process default adapter
+
+`CrossNodeBus` resolves to an in-process implementation by default — single-node deployments work without any configuration. The default adapter:
+
+- Assigns numeric monotonic seq tokens per topic.
+- Retains the last 1 000 messages per topic for replay.
+- Implements `replay`, `oldestSeq`, and `compareSeq` so facades can do delta sync against the in-process bus the same way they would against Redis.
+
+Multi-node deployments override the binding with a transport adapter (see `@furystack/redis-cross-node-bus`).
+
+### Capability flags + fail-loud registration
+
+Every adapter exposes a `capabilities` descriptor (`persistent`, `replay`, `assignsSequence`). Facades assert the flags they need at registration time so misconfigured deployments fail loudly rather than serving stale data.
+
+```typescript
+const bus = injector.get(CrossNodeBus)
+if (!bus.capabilities.replay) {
+  throw new Error('This facade requires replay-capable transport')
+}
+```
+
+### `replay()` + `compareSeq()` + `oldestSeq()` for delta sync
+
+Adapters that retain a window of past messages let consumers reconnect with a `lastSeq` and replay just the gap. `compareSeq` lets facades order seq tokens without leaking the adapter-specific encoding (in-process: integer counters; Redis Streams: `<ms>-<n>`). When the requested seq predates the retained window, `replay()` throws `ReplayWindowExceededError` so facades fall back to a snapshot.
+
+### `subscribeForeign()` for explicit cross-service eavesdrop
+
+Cross-service traffic is opt-in and greppable: a service that wants to observe another service's topic prefix calls `subscribeForeign(prefix, topic, handler)`. Adapters that lack the underlying capability throw at registration time. There is no implicit cross-service fan-out.
+
+### Test helper: `createInProcessBusNetwork`
+
+Exposed under `@furystack/cross-node-bus/testing`. Mints N in-process `CrossNodeBus` instances backed by a single shared `MemoryBroker`, so multi-node behaviour can be unit-tested without spinning up a real broker:
+
+```typescript
+import { createInProcessBusNetwork } from '@furystack/cross-node-bus/testing'
+
+using network = createInProcessBusNetwork({ count: 3 })
+const [a, b, c] = network.buses
+// a.publish(...) is observed by b and c
+```
+
+### Telemetry hooks
+
+`CrossNodeBusTelemetry` emits `onCrossNodePublished`, `onCrossNodeReceived`, `onCrossNodeError`, and `onCrossNodeWindowEvicted` events with `topic`, `originId`, `byteLength` / `lagMs` / error-and-phase / eviction context — wire it into existing logging without touching adapter code. The shared sink is exposed via `CrossNodeBusTelemetryToken` so adapter factories (in-process or transport-specific) inject the same hub.
+
+`onCrossNodeWindowEvicted` only fires for adapters that own their replay buffer (the in-process default today). Network-broker adapters that delegate trimming to the broker — Redis Streams' `MAXLEN`, NATS JetStream's max-bytes — cannot observe individual evictions on the client side; consumers needing that signal should read it from the broker's native metrics.
+
+### ⬆️ Dependencies
+
+- Bumped `@types/node` to `^25.9.1` and `vitest` to `^4.1.7`. No source changes — dev-tooling bump only.

package/README.md

@@ -0,0 +1,49 @@
+# @furystack/cross-node-bus
+
+Transport-agnostic publish/subscribe primitive for FuryStack. Provides the
+`CrossNodeBus` interface, a default in-process adapter, and a testing
+harness for multi-instance scenarios. Concrete cross-process adapters
+(Redis Streams, NATS, …) ship in their own packages.
+
+See `docs/internal/cross-node-bus-spike.md` for the full design.
+
+## Installation
+
+```bash
+npm install @furystack/cross-node-bus
+# or
+yarn add @furystack/cross-node-bus
+```
+
+## Usage
+
+The default factory resolves an `InProcessCrossNodeBus`. Single-node
+deployments work without further configuration. Multi-node deployments
+bind a transport adapter such as `@furystack/redis-cross-node-bus`.
+
+```ts
+import { createInjector } from '@furystack/inject'
+import { CrossNodeBus } from '@furystack/cross-node-bus'
+
+await using injector = createInjector()
+const bus = injector.get(CrossNodeBus)
+
+using sub = bus.subscribe('my-topic', (message) => {
+  console.log(message.originId, message.payload)
+})
+
+await bus.publish('my-topic', { hello: 'world' })
+```
+
+### Testing harness
+
+The `@furystack/cross-node-bus/testing` subpath ships a multi-instance
+in-process harness so facade authors can write multi-node integration
+tests without spinning up a broker.
+
+```ts
+import { createInProcessBusNetwork } from '@furystack/cross-node-bus/testing'
+
+using network = createInProcessBusNetwork({ count: 2 })
+const [a, b] = network.buses
+```

package/esm/cross-node-bus-telemetry.d.ts

@@ -0,0 +1,74 @@
+import { type Token } from '@furystack/inject';
+import { EventHub, type ListenerErrorPayload } from '@furystack/utils';
+/**
+ * Phase of the bus pipeline an `onCrossNodeError` event refers to. `serialize`
+ * is reserved for future adapters that fail when JSON-encoding payloads;
+ * the in-process default never produces it.
+ */
+export type CrossNodeBusErrorPhase = 'publish' | 'subscribe' | 'subscribeForeign' | 'replay' | 'serialize';
+/**
+ * Union of telemetry signals emitted by every {@link CrossNodeBus} adapter.
+ * Each adapter forwards into the same hub so subscribers can observe the
+ * whole bus surface from one place — independent of which transport is
+ * bound.
+ */
+export type CrossNodeBusTelemetryEvents = {
+    /** Fired after a message has been accepted by the transport. */
+    onCrossNodePublished: {
+        topic: string;
+        originId: string;
+        byteLength: number;
+    };
+    /**
+     * Fired once per message arriving at the bus, before local fan-out.
+     * `lagMs = Date.now() - Date.parse(message.emittedAt)`; clock skew can
+     * produce negative values, which adapters report verbatim.
+     */
+    onCrossNodeReceived: {
+        topic: string;
+        originId: string;
+        lagMs: number;
+    };
+    onCrossNodeError: {
+        topic: string;
+        error: unknown;
+        phase: CrossNodeBusErrorPhase;
+    };
+    /**
+     * Fired when an adapter that owns its replay buffer drops a retained
+     * message to honor the configured replay window. Operators alert on the
+     * trend so the window can be tuned before reconnecting clients start
+     * hitting `ReplayWindowExceededError`.
+     *
+     * Only adapters that own the buffer emit this signal — today that is
+     * {@link InProcessCrossNodeBus} via {@link MemoryBroker}. Network-broker
+     * adapters that delegate trimming to the broker (Redis Streams' `MAXLEN`,
+     * NATS JetStream's max-bytes) cannot observe individual evictions on the
+     * client side; consumers needing that signal should read it from the
+     * broker's native metrics (e.g. `redis_streams_length` from the Prom
+     * exporter).
+     */
+    onCrossNodeWindowEvicted: {
+        topic: string;
+        evictedSeq: string;
+        retainedCount: number;
+    };
+    onListenerError: ListenerErrorPayload;
+};
+/**
+ * Application-facing telemetry surface for the cross-node bus. Subscribers
+ * use the standard {@link EventHub} `addListener` / `subscribe` API.
+ */
+export declare class CrossNodeBusTelemetry extends EventHub<CrossNodeBusTelemetryEvents> {
+}
+/**
+ * DI token for the shared {@link CrossNodeBusTelemetry} instance.
+ *
+ * Singleton because the bus token itself is singleton — co-locating both at
+ * the root injector keeps every override factory (including transport
+ * adapters) free to inject telemetry without lifetime-compatibility
+ * gymnastics. Each test still gets isolation by minting its own root
+ * injector with `createInjector()`.
+ */
+export declare const CrossNodeBusTelemetryToken: Token<CrossNodeBusTelemetry, 'singleton'>;
+//# sourceMappingURL=cross-node-bus-telemetry.d.ts.map

package/esm/cross-node-bus-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-bus-telemetry.d.ts","sourceRoot":"","sources":["../src/cross-node-bus-telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,QAAQ,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAEtE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,WAAW,GAAG,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE1G;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,gEAAgE;IAChE,oBAAoB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7E;;;;OAIG;IACH,mBAAmB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACvE,gBAAgB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,sBAAsB,CAAA;KAAE,CAAA;IAClF;;;;;;;;;;;;;OAaG;IACH,wBAAwB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;IACtF,eAAe,EAAE,oBAAoB,CAAA;CACtC,CAAA;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ,CAAC,2BAA2B,CAAC;CAAG;AAEnF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAE,KAAK,CAAC,qBAAqB,EAAE,WAAW,CAS/E,CAAA"}

package/esm/cross-node-bus-telemetry.js

@@ -0,0 +1,28 @@
+import { defineService } from '@furystack/inject';
+import { EventHub } from '@furystack/utils';
+/**
+ * Application-facing telemetry surface for the cross-node bus. Subscribers
+ * use the standard {@link EventHub} `addListener` / `subscribe` API.
+ */
+export class CrossNodeBusTelemetry extends EventHub {
+}
+/**
+ * DI token for the shared {@link CrossNodeBusTelemetry} instance.
+ *
+ * Singleton because the bus token itself is singleton — co-locating both at
+ * the root injector keeps every override factory (including transport
+ * adapters) free to inject telemetry without lifetime-compatibility
+ * gymnastics. Each test still gets isolation by minting its own root
+ * injector with `createInjector()`.
+ */
+export const CrossNodeBusTelemetryToken = defineService({
+    name: 'furystack/cross-node-bus/CrossNodeBusTelemetry',
+    lifetime: 'singleton',
+    factory: ({ onDispose }) => {
+        const telemetry = new CrossNodeBusTelemetry();
+        // eslint-disable-next-line furystack/prefer-using-wrapper -- delegated to onDispose
+        onDispose(() => telemetry[Symbol.dispose]());
+        return telemetry;
+    },
+});
+//# sourceMappingURL=cross-node-bus-telemetry.js.map

package/esm/cross-node-bus-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-bus-telemetry.js","sourceRoot":"","sources":["../src/cross-node-bus-telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAc,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,QAAQ,EAA6B,MAAM,kBAAkB,CAAA;AA2CtE;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,QAAqC;CAAG;AAEnF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAA8C,aAAa,CAAC;IACjG,IAAI,EAAE,gDAAgD;IACtD,QAAQ,EAAE,WAAW;IACrB,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE;QACzB,MAAM,SAAS,GAAG,IAAI,qBAAqB,EAAE,CAAA;QAC7C,oFAAoF;QACpF,SAAS,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QAC5C,OAAO,SAAS,CAAA;IAClB,CAAC;CACF,CAAC,CAAA"}

package/esm/cross-node-bus-telemetry.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cross-node-bus-telemetry.spec.d.ts.map

package/esm/cross-node-bus-telemetry.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-bus-telemetry.spec.d.ts","sourceRoot":"","sources":["../src/cross-node-bus-telemetry.spec.ts"],"names":[],"mappings":""}

package/esm/cross-node-bus-telemetry.spec.js

@@ -0,0 +1,115 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { createInjector } from '@furystack/inject';
+import { describe, expect, it, vi } from 'vitest';
+import { CrossNodeBusTelemetry, CrossNodeBusTelemetryToken } from './cross-node-bus-telemetry.js';
+describe('CrossNodeBusTelemetryToken', () => {
+    it('resolves a CrossNodeBusTelemetry instance', async () => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const injector = __addDisposableResource(env_1, createInjector(), true);
+            const telemetry = injector.get(CrossNodeBusTelemetryToken);
+            expect(telemetry).toBeInstanceOf(CrossNodeBusTelemetry);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    });
+    it('disposes the telemetry instance with the injector scope', async () => {
+        const injector = createInjector();
+        const telemetry = injector.get(CrossNodeBusTelemetryToken);
+        const handler = vi.fn();
+        telemetry.addListener('onCrossNodePublished', handler);
+        await injector[Symbol.asyncDispose]();
+        telemetry.emit('onCrossNodePublished', { topic: 'x', originId: 'y', byteLength: 0 });
+        expect(handler).not.toHaveBeenCalled();
+    });
+    it('shares the singleton instance across child scopes', async () => {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const injector = __addDisposableResource(env_2, createInjector(), true);
+            const scopeA = __addDisposableResource(env_2, injector.createScope({ owner: 'a' }), true);
+            const scopeB = __addDisposableResource(env_2, injector.createScope({ owner: 'b' }), true);
+            const telA = scopeA.get(CrossNodeBusTelemetryToken);
+            const telB = scopeB.get(CrossNodeBusTelemetryToken);
+            expect(telA).toBe(telB);
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            const result_2 = __disposeResources(env_2);
+            if (result_2)
+                await result_2;
+        }
+    });
+    it('issues independent instances per root injector', () => {
+        const a = createInjector();
+        const b = createInjector();
+        try {
+            expect(a.get(CrossNodeBusTelemetryToken)).not.toBe(b.get(CrossNodeBusTelemetryToken));
+        }
+        finally {
+            void a[Symbol.asyncDispose]();
+            void b[Symbol.asyncDispose]();
+        }
+    });
+});
+//# sourceMappingURL=cross-node-bus-telemetry.spec.js.map

package/esm/cross-node-bus-telemetry.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-bus-telemetry.spec.js","sourceRoot":"","sources":["../src/cross-node-bus-telemetry.spec.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAA;AAEjG,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC1C,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;;;YACzD,MAAY,QAAQ,kCAAG,cAAc,EAAE,OAAA,CAAA;YACvC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;YAC1D,MAAM,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,qBAAqB,CAAC,CAAA;;;;;;;;;;;KACxD,CAAC,CAAA;IAEF,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAA;QACjC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;QAC1D,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;QACvB,SAAS,CAAC,WAAW,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAA;QACtD,MAAM,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAA;QAErC,SAAS,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAA;QACpF,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAA;IACxC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;;;YACjE,MAAY,QAAQ,kCAAG,cAAc,EAAE,OAAA,CAAA;YACvC,MAAY,MAAM,kCAAG,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,OAAA,CAAA;YACzD,MAAY,MAAM,kCAAG,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,OAAA,CAAA;YAEzD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;YACnD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;YAEnD,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;;;;;;;;;;;KACxB,CAAC,CAAA;IAEF,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,GAAG,cAAc,EAAE,CAAA;QAC1B,MAAM,CAAC,GAAG,cAAc,EAAE,CAAA;QAC1B,IAAI,CAAC;YACH,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAA;QACvF,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAA;YAC7B,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAA;QAC/B,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/esm/cross-node-bus.d.ts

@@ -0,0 +1,78 @@
+import { type Token } from '@furystack/inject';
+import type { BusMessage, CrossNodeBusCapabilities } from './types.js';
+/**
+ * Transport-agnostic publish/subscribe primitive. Implementations talk to a
+ * concrete broker (in-process map, Redis Streams, …); facades layer typed
+ * event contracts on top.
+ *
+ * Self-delivery is on by default — a publisher receives its own messages.
+ * Subscribers that need a local-vs-remote distinction either filter on
+ * `message.originId === bus.nodeId` or use
+ * {@link CrossNodeBus.subscribeRemoteOnly}.
+ */
+export interface CrossNodeBus extends Disposable {
+    /** Stable, unique id of this node. Included in every published message. */
+    readonly nodeId: string;
+    /** Static description of what this adapter can do. */
+    readonly capabilities: CrossNodeBusCapabilities;
+    /**
+     * Publishes `payload` on `topic`. Resolves once the message has been
+     * accepted by the underlying transport (not when it has been delivered to
+     * all subscribers).
+     */
+    publish(topic: string, payload: unknown): Promise<void>;
+    /**
+     * Subscribes to every message published on `topic`, including ones
+     * originating from this node.
+     */
+    subscribe(topic: string, handler: (message: BusMessage) => void): Disposable;
+    /**
+     * Convenience for the common "I only care about messages from other nodes"
+     * pattern. Equivalent to {@link CrossNodeBus.subscribe} + filter on
+     * `message.originId !== bus.nodeId`.
+     */
+    subscribeRemoteOnly(topic: string, handler: (message: BusMessage) => void): Disposable;
+    /**
+     * Subscribe to a topic owned by another `topicPrefix`. Explicit, greppable
+     * cross-service eavesdrop. Adapters that lack the underlying capability
+     * throw at registration time.
+     */
+    subscribeForeign(prefix: string, topic: string, handler: (message: BusMessage) => void): Disposable;
+    /**
+     * Replay messages on `topic` whose `seq` is greater than `fromSeq`. Throws
+     * synchronously when {@link CrossNodeBusCapabilities.replay} is `false` or
+     * when `fromSeq` is older than the adapter's retained window — facades
+     * fall back to a full snapshot in the latter case.
+     */
+    replay(topic: string, fromSeq: string): AsyncIterable<BusMessage>;
+    /**
+     * Compares two adapter-issued seq tokens from the **same topic**. Returns a
+     * negative number when `a` precedes `b`, zero when equal, a positive number
+     * when `a` follows `b`. Facades use this for dedup and "have we seen newer?"
+     * checks without leaking the adapter-specific seq encoding.
+     *
+     * Behavior across topics, adapters, or for tokens this adapter never issued
+     * is undefined.
+     */
+    compareSeq(a: string, b: string): number;
+    /**
+     * Returns the oldest retained seq for `topic`, or `undefined` when nothing
+     * is currently retained. Throws synchronously when
+     * {@link CrossNodeBusCapabilities.replay} is `false`. Facades use this to
+     * decide whether a delta replay is feasible before calling
+     * {@link CrossNodeBus.replay}.
+     */
+    oldestSeq(topic: string): string | undefined;
+}
+/**
+ * Shared {@link CrossNodeBus} token. Resolves an `InProcessCrossNodeBus` by
+ * default — single-node deployments work without configuration. Multi-node
+ * deployments override the binding with a transport adapter, e.g.
+ * `defineRedisCrossNodeBusAdapter({ … })`.
+ *
+ * Singleton: a single bus per injector tree is the right semantic for
+ * cross-process publish/subscribe. Tests get isolation by minting their own
+ * root injector with `createInjector()`.
+ */
+export declare const CrossNodeBus: Token<CrossNodeBus, 'singleton'>;
+//# sourceMappingURL=cross-node-bus.d.ts.map

package/esm/cross-node-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-bus.d.ts","sourceRoot":"","sources":["../src/cross-node-bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAEtE;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB,sDAAsD;IACtD,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAA;IAE/C;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,UAAU,CAAA;IAE5E;;;;OAIG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,UAAU,CAAA;IAEtF;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,UAAU,CAAA;IAEnG;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,CAAA;IAEjE;;;;;;;;OAQG;IACH,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAExC;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAC7C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,WAAW,CAIxD,CAAA"}

package/esm/cross-node-bus.js

@@ -0,0 +1,18 @@
+import { defineService } from '@furystack/inject';
+import { defineInProcessCrossNodeBus } from './define-in-process-cross-node-bus.js';
+/**
+ * Shared {@link CrossNodeBus} token. Resolves an `InProcessCrossNodeBus` by
+ * default — single-node deployments work without configuration. Multi-node
+ * deployments override the binding with a transport adapter, e.g.
+ * `defineRedisCrossNodeBusAdapter({ … })`.
+ *
+ * Singleton: a single bus per injector tree is the right semantic for
+ * cross-process publish/subscribe. Tests get isolation by minting their own
+ * root injector with `createInjector()`.
+ */
+export const CrossNodeBus = defineService({
+    name: 'furystack/cross-node-bus/CrossNodeBus',
+    lifetime: 'singleton',
+    factory: defineInProcessCrossNodeBus(),
+});
+//# sourceMappingURL=cross-node-bus.js.map

package/esm/cross-node-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-bus.js","sourceRoot":"","sources":["../src/cross-node-bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAc,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,uCAAuC,CAAA;AA4EnF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAqC,aAAa,CAAC;IAC1E,IAAI,EAAE,uCAAuC;IAC7C,QAAQ,EAAE,WAAW;IACrB,OAAO,EAAE,2BAA2B,EAAE;CACvC,CAAC,CAAA"}

package/esm/cross-node-bus.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cross-node-bus.spec.d.ts.map

package/esm/cross-node-bus.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-bus.spec.d.ts","sourceRoot":"","sources":["../src/cross-node-bus.spec.ts"],"names":[],"mappings":""}

package/esm/cross-node-bus.spec.js

@@ -0,0 +1,123 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { createInjector } from '@furystack/inject';
+import { describe, expect, it, vi } from 'vitest';
+import { CrossNodeBus } from './cross-node-bus.js';
+import { CrossNodeBusTelemetryToken } from './cross-node-bus-telemetry.js';
+import { defineInProcessCrossNodeBus } from './define-in-process-cross-node-bus.js';
+import { InProcessCrossNodeBus } from './in-process-cross-node-bus.js';
+describe('CrossNodeBus token', () => {
+    it('resolves an InProcessCrossNodeBus by default', async () => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const injector = __addDisposableResource(env_1, createInjector(), true);
+            const bus = injector.get(CrossNodeBus);
+            expect(bus).toBeInstanceOf(InProcessCrossNodeBus);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    });
+    it('disposes the bus when the injector scope tears down', async () => {
+        const injector = createInjector();
+        const bus = injector.get(CrossNodeBus);
+        await injector[Symbol.asyncDispose]();
+        expect(() => bus.subscribe('topic', () => undefined)).toThrow(/disposed/);
+    });
+    it('honors override bindings via defineInProcessCrossNodeBus', async () => {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const injector = __addDisposableResource(env_2, createInjector(), true);
+            injector.bind(CrossNodeBus, defineInProcessCrossNodeBus({ nodeId: 'svc-a-1', topicPrefix: 'svc-a/' }));
+            const bus = injector.get(CrossNodeBus);
+            expect(bus.nodeId).toBe('svc-a-1');
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            const result_2 = __disposeResources(env_2);
+            if (result_2)
+                await result_2;
+        }
+    });
+    it('publishes drive the scoped CrossNodeBusTelemetryToken', async () => {
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            const injector = __addDisposableResource(env_3, createInjector(), true);
+            const telemetry = injector.get(CrossNodeBusTelemetryToken);
+            const handler = vi.fn();
+            const _sub = __addDisposableResource(env_3, telemetry.subscribe('onCrossNodePublished', handler), false);
+            const bus = injector.get(CrossNodeBus);
+            await bus.publish('topic', { hi: 'there' });
+            expect(handler).toHaveBeenCalledTimes(1);
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            const result_3 = __disposeResources(env_3);
+            if (result_3)
+                await result_3;
+        }
+    });
+});
+//# sourceMappingURL=cross-node-bus.spec.js.map

package/esm/cross-node-bus.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-bus.spec.js","sourceRoot":"","sources":["../src/cross-node-bus.spec.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAA;AAC1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,uCAAuC,CAAA;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;;;YAC5D,MAAY,QAAQ,kCAAG,cAAc,EAAE,OAAA,CAAA;YACvC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;YACtC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,qBAAqB,CAAC,CAAA;;;;;;;;;;;KAClD,CAAC,CAAA;IAEF,EAAE,CAAC,qDAAqD,EAAE,KAAK,IAAI,EAAE;QACnE,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAA;QACjC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACtC,MAAM,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAA;QACrC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;IAC3E,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0DAA0D,EAAE,KAAK,IAAI,EAAE;;;YACxE,MAAY,QAAQ,kCAAG,cAAc,EAAE,OAAA,CAAA;YACvC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,2BAA2B,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAA;YAEtG,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;YACtC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;;;;;;;;;;;KACnC,CAAC,CAAA;IAEF,EAAE,CAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;;;YACrE,MAAY,QAAQ,kCAAG,cAAc,EAAE,OAAA,CAAA;YACvC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;YAC1D,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;YACvB,MAAM,IAAI,kCAAG,SAAS,CAAC,SAAS,CAAC,sBAAsB,EAAE,OAAO,CAAC,QAAA,CAAA;YAEjE,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;YACtC,MAAM,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;YAE3C,MAAM,CAAC,OAAO,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;;;;;;;;;;;KACzC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/esm/define-in-process-cross-node-bus.d.ts

@@ -0,0 +1,26 @@
+import type { ServiceFactory } from '@furystack/inject';
+import { type InProcessCrossNodeBusOptions } from './in-process-cross-node-bus.js';
+import type { CrossNodeBus } from './cross-node-bus.js';
+/**
+ * Options accepted by {@link defineInProcessCrossNodeBus}. `telemetry` is
+ * intentionally absent — the factory always injects
+ * {@link CrossNodeBusTelemetryToken} from the surrounding scope.
+ */
+export type DefineInProcessCrossNodeBusOptions = Omit<InProcessCrossNodeBusOptions, 'telemetry'>;
+/**
+ * Returns a {@link ServiceFactory} bound to {@link CrossNodeBus}. Use it to
+ * override the default factory at boot:
+ *
+ * ```ts
+ * injector.bind(
+ *   CrossNodeBus,
+ *   defineInProcessCrossNodeBus({ topicPrefix: 'svc-a/' }),
+ * )
+ * ```
+ *
+ * Mirrors the `defineXxxCrossNodeBusAdapter` shape future transport
+ * adapters expose. Wires telemetry and disposal into the surrounding
+ * injector scope.
+ */
+export declare const defineInProcessCrossNodeBus: (options?: DefineInProcessCrossNodeBusOptions) => ServiceFactory<CrossNodeBus>;
+//# sourceMappingURL=define-in-process-cross-node-bus.d.ts.map

package/esm/define-in-process-cross-node-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-in-process-cross-node-bus.d.ts","sourceRoot":"","sources":["../src/define-in-process-cross-node-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD,OAAO,EAAyB,KAAK,4BAA4B,EAAE,MAAM,gCAAgC,CAAA;AACzG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD;;;;GAIG;AACH,MAAM,MAAM,kCAAkC,GAAG,IAAI,CAAC,4BAA4B,EAAE,WAAW,CAAC,CAAA;AAEhG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,GACtC,UAAS,kCAAuC,KAC/C,cAAc,CAAC,YAAY,CAQ7B,CAAA"}