@furystack/cross-node-bus 1.0.0

package/esm/testing/create-in-process-bus-network.spec.js

@@ -0,0 +1,142 @@
+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 { describe, expect, it, vi } from 'vitest';
+import { createInProcessBusNetwork } from './create-in-process-bus-network.js';
+describe('createInProcessBusNetwork', () => {
+    it('mints `count` buses sharing one broker', async () => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const network = __addDisposableResource(env_1, createInProcessBusNetwork({ count: 3 }), false);
+            expect(network.buses).toHaveLength(3);
+            expect(network.broker).toBeDefined();
+            const handlerB = vi.fn();
+            const handlerC = vi.fn();
+            const _subB = __addDisposableResource(env_1, network.buses[1].subscribe('topic', handlerB), false);
+            const _subC = __addDisposableResource(env_1, network.buses[2].subscribe('topic', handlerC), false);
+            await network.buses[0].publish('topic', { from: 0 });
+            expect(handlerB).toHaveBeenCalledTimes(1);
+            expect(handlerC).toHaveBeenCalledTimes(1);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    });
+    it('honors per-bus topicPrefixes for multi-service simulation', async () => {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const network = __addDisposableResource(env_2, createInProcessBusNetwork({
+                count: 2,
+                topicPrefixes: ['svc-a/', 'svc-b/'],
+            }), false);
+            const [busA, busB] = network.buses;
+            const onB = vi.fn();
+            const eavesdrop = vi.fn();
+            const _subB = __addDisposableResource(env_2, busB.subscribe('events', onB), false);
+            const _foreign = __addDisposableResource(env_2, busB.subscribeForeign('svc-a/', 'events', eavesdrop), false);
+            await busA.publish('events', { from: 'a' });
+            expect(onB).not.toHaveBeenCalled();
+            expect(eavesdrop).toHaveBeenCalledTimes(1);
+            expect((eavesdrop.mock.calls[0]?.[0]).originId).toBe(busA.nodeId);
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            __disposeResources(env_2);
+        }
+    });
+    it('honors per-bus nodeIds', () => {
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            const network = __addDisposableResource(env_3, createInProcessBusNetwork({
+                count: 2,
+                nodeIds: ['alice', 'bob'],
+            }), false);
+            expect(network.buses[0].nodeId).toBe('alice');
+            expect(network.buses[1].nodeId).toBe('bob');
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            __disposeResources(env_3);
+        }
+    });
+    it('disposes every bus and the broker on teardown', () => {
+        const network = createInProcessBusNetwork({ count: 2 });
+        network[Symbol.dispose]();
+        for (const bus of network.buses) {
+            expect(() => bus.subscribe('topic', () => undefined)).toThrow(/disposed/);
+        }
+        expect(() => network.broker.publish('topic', 'a', null)).toThrow(/disposed/);
+    });
+    describe('input validation', () => {
+        it('rejects non-positive count', () => {
+            expect(() => createInProcessBusNetwork({ count: 0 })).toThrow(RangeError);
+            expect(() => createInProcessBusNetwork({ count: 1.5 })).toThrow(RangeError);
+        });
+        it('rejects mismatched topicPrefixes length', () => {
+            expect(() => createInProcessBusNetwork({ count: 2, topicPrefixes: ['only-one/'] })).toThrow(RangeError);
+        });
+        it('rejects mismatched nodeIds length', () => {
+            expect(() => createInProcessBusNetwork({ count: 2, nodeIds: ['only-one'] })).toThrow(RangeError);
+        });
+    });
+});
+//# sourceMappingURL=create-in-process-bus-network.spec.js.map

package/esm/testing/create-in-process-bus-network.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-in-process-bus-network.spec.js","sourceRoot":"","sources":["../../src/testing/create-in-process-bus-network.spec.ts"],"names":[],"mappings":"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"}

package/esm/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './create-in-process-bus-network.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAA"}

package/esm/testing/index.js

@@ -0,0 +1,2 @@
+export * from './create-in-process-bus-network.js';
+//# sourceMappingURL=index.js.map

package/esm/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAA"}

package/esm/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Message envelope delivered to subscribers and emitted on the wire by every
+ * adapter. Adapters refuse messages whose {@link BusMessage.v} they do not
+ * recognise — see the rolling-deploy strategy in
+ * `docs/internal/cross-node-bus-spike.md` §12.
+ */
+export type BusMessage = {
+    /** Wire-format version. Adapters refuse incompatible versions. */
+    readonly v: 1;
+    /** `nodeId` of the publisher. */
+    readonly originId: string;
+    /** ISO-8601 publish timestamp from the publisher's clock (diagnostic only). */
+    readonly emittedAt: string;
+    /**
+     * Adapter-assigned per-topic monotonic id. Optional because non-sequencing
+     * adapters do not provide one.
+     */
+    readonly seq?: string;
+    /** Caller-supplied payload. Must be JSON-serializable. */
+    readonly payload: unknown;
+};
+/**
+ * Static description of a transport's behavior. Declared by every adapter
+ * and asserted by facades at registration time so misconfigured deployments
+ * fail loudly rather than serving stale data.
+ */
+export type CrossNodeBusCapabilities = {
+    /** Messages survive process restarts. */
+    readonly persistent: boolean;
+    /** Replay returns retained messages on demand. */
+    readonly replay: boolean;
+    /** Adapter assigns a server-monotonic {@link BusMessage.seq}. */
+    readonly assignsSequence: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kEAAkE;IAClE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAA;IACb,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,iEAAiE;IACjE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAClC,CAAA"}

package/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@furystack/cross-node-bus",
+  "version": "1.0.0",
+  "description": "Transport-agnostic cross-process publish/subscribe primitive for FuryStack",
+  "type": "module",
+  "scripts": {
+    "build": "tsc --outDir ./esm"
+  },
+  "exports": {
+    ".": {
+      "types": "./esm/index.d.ts",
+      "import": "./esm/index.js"
+    },
+    "./testing": {
+      "types": "./esm/testing/index.d.ts",
+      "import": "./esm/testing/index.js"
+    }
+  },
+  "files": [
+    "esm",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/furystack/furystack.git"
+  },
+  "keywords": [
+    "FuryStack",
+    "pubsub",
+    "event-bus",
+    "cross-node",
+    "in-process"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Gallay Lajos <gallay.lajos@gmail.com>",
+  "license": "GPL-2.0",
+  "bugs": {
+    "url": "https://github.com/furystack/furystack/issues"
+  },
+  "homepage": "https://github.com/furystack/furystack",
+  "dependencies": {
+    "@furystack/inject": "^13.0.1",
+    "@furystack/utils": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "sideEffects": false
+}

package/src/cross-node-bus-telemetry.spec.ts

@@ -0,0 +1,44 @@
+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 () => {
+    await using injector = createInjector()
+    const telemetry = injector.get(CrossNodeBusTelemetryToken)
+    expect(telemetry).toBeInstanceOf(CrossNodeBusTelemetry)
+  })
+
+  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 () => {
+    await using injector = createInjector()
+    await using scopeA = injector.createScope({ owner: 'a' })
+    await using scopeB = injector.createScope({ owner: 'b' })
+
+    const telA = scopeA.get(CrossNodeBusTelemetryToken)
+    const telB = scopeB.get(CrossNodeBusTelemetryToken)
+
+    expect(telA).toBe(telB)
+  })
+
+  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]()
+    }
+  })
+})

package/src/cross-node-bus-telemetry.ts

@@ -0,0 +1,69 @@
+import { defineService, 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 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 const CrossNodeBusTelemetryToken: Token<CrossNodeBusTelemetry, 'singleton'> = 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
+  },
+})

package/src/cross-node-bus.spec.ts

@@ -0,0 +1,41 @@
+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 () => {
+    await using injector = createInjector()
+    const bus = injector.get(CrossNodeBus)
+    expect(bus).toBeInstanceOf(InProcessCrossNodeBus)
+  })
+
+  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 () => {
+    await using injector = createInjector()
+    injector.bind(CrossNodeBus, defineInProcessCrossNodeBus({ nodeId: 'svc-a-1', topicPrefix: 'svc-a/' }))
+
+    const bus = injector.get(CrossNodeBus)
+    expect(bus.nodeId).toBe('svc-a-1')
+  })
+
+  it('publishes drive the scoped CrossNodeBusTelemetryToken', async () => {
+    await using injector = createInjector()
+    const telemetry = injector.get(CrossNodeBusTelemetryToken)
+    const handler = vi.fn()
+    using _sub = telemetry.subscribe('onCrossNodePublished', handler)
+
+    const bus = injector.get(CrossNodeBus)
+    await bus.publish('topic', { hi: 'there' })
+
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+})

package/src/cross-node-bus.ts

@@ -0,0 +1,92 @@
+import { defineService, type Token } from '@furystack/inject'
+import { defineInProcessCrossNodeBus } from './define-in-process-cross-node-bus.js'
+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 const CrossNodeBus: Token<CrossNodeBus, 'singleton'> = defineService({
+  name: 'furystack/cross-node-bus/CrossNodeBus',
+  lifetime: 'singleton',
+  factory: defineInProcessCrossNodeBus(),
+})

package/src/define-in-process-cross-node-bus.ts

@@ -0,0 +1,38 @@
+import type { ServiceFactory } from '@furystack/inject'
+import { CrossNodeBusTelemetryToken } from './cross-node-bus-telemetry.js'
+import { InProcessCrossNodeBus, 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 const defineInProcessCrossNodeBus = (
+  options: DefineInProcessCrossNodeBusOptions = {},
+): ServiceFactory<CrossNodeBus> => {
+  return ({ inject, onDispose }) => {
+    const telemetry = inject(CrossNodeBusTelemetryToken)
+    const bus = new InProcessCrossNodeBus({ ...options, telemetry })
+    // eslint-disable-next-line furystack/prefer-using-wrapper -- delegated to onDispose
+    onDispose(() => bus[Symbol.dispose]())
+    return bus
+  }
+}

package/src/errors.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import { ReplayWindowExceededError, UnsupportedCapabilityError } from './errors.js'
+
+describe('errors', () => {
+  describe('ReplayWindowExceededError', () => {
+    it('captures the topic, fromSeq and oldestRetainedSeq', () => {
+      const error = new ReplayWindowExceededError('topic', '5', '7')
+      expect(error.name).toBe('ReplayWindowExceededError')
+      expect(error.topic).toBe('topic')
+      expect(error.fromSeq).toBe('5')
+      expect(error.oldestRetainedSeq).toBe('7')
+      expect(error.message).toContain('topic')
+      expect(error.message).toContain('5')
+      expect(error.message).toContain('7')
+    })
+
+    it('reports "none" when no messages are retained', () => {
+      const error = new ReplayWindowExceededError('topic', '5', undefined)
+      expect(error.oldestRetainedSeq).toBeUndefined()
+      expect(error.message).toContain('none')
+    })
+  })
+
+  describe('UnsupportedCapabilityError', () => {
+    it('captures the missing capability name', () => {
+      const error = new UnsupportedCapabilityError('replay')
+      expect(error.name).toBe('UnsupportedCapabilityError')
+      expect(error.capability).toBe('replay')
+      expect(error.message).toContain('replay')
+    })
+  })
+})

package/src/errors.ts

@@ -0,0 +1,38 @@
+import type { CrossNodeBusCapabilities } from './types.js'
+
+/**
+ * Thrown synchronously by {@link CrossNodeBus.replay} when `fromSeq` falls
+ * outside the adapter's retained window. Facades catch this and fall back
+ * to a full-snapshot path.
+ */
+export class ReplayWindowExceededError extends Error {
+  public readonly topic: string
+  public readonly fromSeq: string
+  public readonly oldestRetainedSeq: string | undefined
+
+  constructor(topic: string, fromSeq: string, oldestRetainedSeq: string | undefined) {
+    super(
+      `Replay window exceeded for topic "${topic}": requested fromSeq=${fromSeq}, oldest retained=${
+        oldestRetainedSeq ?? 'none'
+      }`,
+    )
+    this.name = 'ReplayWindowExceededError'
+    this.topic = topic
+    this.fromSeq = fromSeq
+    this.oldestRetainedSeq = oldestRetainedSeq
+  }
+}
+
+/**
+ * Thrown synchronously by an adapter when a caller invokes a method that
+ * requires a capability the adapter does not advertise.
+ */
+export class UnsupportedCapabilityError extends Error {
+  public readonly capability: keyof CrossNodeBusCapabilities
+
+  constructor(capability: keyof CrossNodeBusCapabilities) {
+    super(`Adapter does not support capability: ${capability}`)
+    this.name = 'UnsupportedCapabilityError'
+    this.capability = capability
+  }
+}