@furystack/cross-node-bus 1.0.0

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

@@ -0,0 +1,428 @@
+import { describe, expect, it, vi } from 'vitest'
+import { CrossNodeBusTelemetry } from './cross-node-bus-telemetry.js'
+import { ReplayWindowExceededError } from './errors.js'
+import { InProcessCrossNodeBus } from './in-process-cross-node-bus.js'
+import { MemoryBroker } from './memory-broker.js'
+import type { BusMessage } from './types.js'
+
+const collect = async (iterable: AsyncIterable<BusMessage>): Promise<BusMessage[]> => {
+  const out: BusMessage[] = []
+  for await (const message of iterable) out.push(message)
+  return out
+}
+
+describe('InProcessCrossNodeBus', () => {
+  describe('basics', () => {
+    it('exposes a non-empty nodeId by default', () => {
+      using bus = new InProcessCrossNodeBus()
+      expect(typeof bus.nodeId).toBe('string')
+      expect(bus.nodeId.length).toBeGreaterThan(0)
+      expect(bus.nodeId.startsWith('local-')).toBe(true)
+    })
+
+    it('honors a caller-supplied nodeId', () => {
+      using bus = new InProcessCrossNodeBus({ nodeId: 'fixed' })
+      expect(bus.nodeId).toBe('fixed')
+    })
+
+    it('declares replay + assignsSequence capabilities and non-persistent', () => {
+      using bus = new InProcessCrossNodeBus()
+      expect(bus.capabilities).toEqual({ persistent: false, replay: true, assignsSequence: true })
+    })
+  })
+
+  describe('publish + subscribe', () => {
+    it('delivers self-published messages by default', async () => {
+      using bus = new InProcessCrossNodeBus({ nodeId: 'self' })
+      const handler = vi.fn()
+      using _sub = bus.subscribe('topic', handler)
+
+      await bus.publish('topic', { n: 1 })
+
+      expect(handler).toHaveBeenCalledTimes(1)
+      const message = handler.mock.calls[0]?.[0] as BusMessage
+      expect(message.originId).toBe('self')
+      expect(message.payload).toEqual({ n: 1 })
+      expect(message.seq).toBe('1')
+    })
+
+    it('multiplexes a single broker subscription across local handlers', async () => {
+      const broker = new MemoryBroker()
+      const brokerSubscribe = vi.spyOn(broker, 'subscribe')
+      try {
+        using bus = new InProcessCrossNodeBus({ broker, nodeId: 'self' })
+        using _a = bus.subscribe('topic', () => undefined)
+        using _b = bus.subscribe('topic', () => undefined)
+        using _c = bus.subscribe('topic', () => undefined)
+
+        expect(brokerSubscribe).toHaveBeenCalledTimes(1)
+      } finally {
+        broker[Symbol.dispose]()
+      }
+    })
+
+    it('releases the broker subscription when the last local handler disposes', async () => {
+      using broker = new MemoryBroker()
+      using bus = new InProcessCrossNodeBus({ broker, nodeId: 'self' })
+      const handler = vi.fn()
+
+      const sub = bus.subscribe('topic', handler)
+      sub[Symbol.dispose]()
+      await bus.publish('topic', null)
+      expect(handler).not.toHaveBeenCalled()
+
+      const handler2 = vi.fn()
+      using _sub2 = bus.subscribe('topic', handler2)
+      await bus.publish('topic', null)
+      expect(handler2).toHaveBeenCalledTimes(1)
+    })
+
+    it('isolates one local handler error from another and from the bus', async () => {
+      using bus = new InProcessCrossNodeBus({ nodeId: 'self' })
+      const ok = vi.fn()
+      using _failing = bus.subscribe('topic', () => {
+        throw new Error('boom')
+      })
+      using _ok = bus.subscribe('topic', ok)
+
+      await expect(bus.publish('topic', null)).resolves.toBeUndefined()
+      expect(ok).toHaveBeenCalledTimes(1)
+    })
+
+    it('subscribeRemoteOnly skips messages originating on this node', async () => {
+      using broker = new MemoryBroker()
+      using busA = new InProcessCrossNodeBus({ broker, nodeId: 'a' })
+      using busB = new InProcessCrossNodeBus({ broker, nodeId: 'b' })
+      const handler = vi.fn()
+      using _sub = busA.subscribeRemoteOnly('topic', handler)
+
+      await busA.publish('topic', { from: 'a' })
+      await busB.publish('topic', { from: 'b' })
+
+      expect(handler).toHaveBeenCalledTimes(1)
+      expect((handler.mock.calls[0]?.[0] as BusMessage).originId).toBe('b')
+    })
+  })
+
+  describe('topicPrefix + subscribeForeign', () => {
+    it('prefixes topics on the wire and isolates buses with different prefixes', async () => {
+      using broker = new MemoryBroker()
+      using svcA = new InProcessCrossNodeBus({ broker, nodeId: 'a', topicPrefix: 'svc-a/' })
+      using svcB = new InProcessCrossNodeBus({ broker, nodeId: 'b', topicPrefix: 'svc-b/' })
+      const onA = vi.fn()
+      const onB = vi.fn()
+      using _subA = svcA.subscribe('events', onA)
+      using _subB = svcB.subscribe('events', onB)
+
+      await svcA.publish('events', { from: 'a' })
+
+      expect(onA).toHaveBeenCalledTimes(1)
+      expect(onB).not.toHaveBeenCalled()
+    })
+
+    it('subscribeForeign delivers messages from a foreign prefix on demand', async () => {
+      using broker = new MemoryBroker()
+      using svcA = new InProcessCrossNodeBus({ broker, nodeId: 'a', topicPrefix: 'svc-a/' })
+      using svcB = new InProcessCrossNodeBus({ broker, nodeId: 'b', topicPrefix: 'svc-b/' })
+      const eavesdrop = vi.fn()
+      using _foreign = svcB.subscribeForeign('svc-a/', 'events', eavesdrop)
+
+      await svcA.publish('events', { from: 'a' })
+
+      expect(eavesdrop).toHaveBeenCalledTimes(1)
+      expect((eavesdrop.mock.calls[0]?.[0] as BusMessage).originId).toBe('a')
+    })
+  })
+
+  describe('replay', () => {
+    it('yields messages newer than fromSeq', async () => {
+      using bus = new InProcessCrossNodeBus({ nodeId: 'a' })
+      await bus.publish('topic', { n: 1 })
+      await bus.publish('topic', { n: 2 })
+      await bus.publish('topic', { n: 3 })
+
+      const yielded = await collect(bus.replay('topic', '1'))
+      expect(yielded.map((m) => (m.payload as { n: number }).n)).toEqual([2, 3])
+    })
+
+    it('throws ReplayWindowExceededError when fromSeq is too old', () => {
+      const bus = new InProcessCrossNodeBus({ replayWindow: 2 })
+      try {
+        void bus.publish('topic', null)
+        void bus.publish('topic', null)
+        void bus.publish('topic', null)
+        expect(() => bus.replay('topic', '0')).toThrow(ReplayWindowExceededError)
+      } finally {
+        bus[Symbol.dispose]()
+      }
+    })
+  })
+
+  describe('telemetry', () => {
+    it('emits onCrossNodePublished with byteLength after a successful publish', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      try {
+        using bus = new InProcessCrossNodeBus({ nodeId: 'a', telemetry })
+        const events: Array<{ topic: string; originId: string; byteLength: number }> = []
+        using _sub = telemetry.subscribe('onCrossNodePublished', (event) => {
+          events.push(event)
+        })
+
+        await bus.publish('topic', { hi: 'there' })
+
+        expect(events).toEqual([
+          { topic: 'topic', originId: 'a', byteLength: Buffer.byteLength(JSON.stringify({ hi: 'there' })) },
+        ])
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('emits onCrossNodeReceived once per arrival regardless of handler count', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      try {
+        using bus = new InProcessCrossNodeBus({ nodeId: 'a', telemetry })
+        const arrivals = vi.fn()
+        using _sub = telemetry.subscribe('onCrossNodeReceived', arrivals)
+        using _h1 = bus.subscribe('topic', () => undefined)
+        using _h2 = bus.subscribe('topic', () => undefined)
+        using _h3 = bus.subscribe('topic', () => undefined)
+
+        await bus.publish('topic', null)
+        expect(arrivals).toHaveBeenCalledTimes(1)
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('emits onCrossNodeError with phase=subscribe when a local handler throws', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      try {
+        using bus = new InProcessCrossNodeBus({ nodeId: 'a', telemetry })
+        const errors: Array<{ phase: string; topic: string; error: unknown }> = []
+        using _sub = telemetry.subscribe('onCrossNodeError', (event) => {
+          errors.push(event)
+        })
+        using _failing = bus.subscribe('topic', () => {
+          throw new Error('boom')
+        })
+
+        await bus.publish('topic', null)
+        expect(errors).toHaveLength(1)
+        expect(errors[0]?.phase).toBe('subscribe')
+        expect(errors[0]?.topic).toBe('topic')
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('emits onCrossNodeError with phase=subscribe when a direct broker subscriber throws during fan-out', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      using broker = new MemoryBroker()
+      try {
+        using bus = new InProcessCrossNodeBus({ broker, nodeId: 'a', telemetry })
+        const errors: Array<{ phase: string; topic: string }> = []
+        using _sub = telemetry.subscribe('onCrossNodeError', (event) => {
+          errors.push(event)
+        })
+        // A direct broker subscriber bypasses the bus's `#deliver` try/catch;
+        // its throw routes through the broker's `onSubscriberError` sink.
+        using _failing = broker.subscribe('topic', () => {
+          throw new Error('boom')
+        })
+
+        await bus.publish('topic', null)
+        expect(errors.some((event) => event.phase === 'subscribe' && event.topic === 'topic')).toBe(true)
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('emits onCrossNodeError with phase=subscribe when broker.subscribe throws on first hookup', () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      const broker = new MemoryBroker()
+      try {
+        using bus = new InProcessCrossNodeBus({ broker, nodeId: 'a', telemetry })
+        const errors: Array<{ phase: string }> = []
+        using _sub = telemetry.subscribe('onCrossNodeError', (event) => {
+          errors.push(event)
+        })
+        broker[Symbol.dispose]()
+        expect(() => bus.subscribe('topic', () => undefined)).toThrow(/disposed/)
+        expect(errors.some((event) => event.phase === 'subscribe')).toBe(true)
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('emits onCrossNodeError with phase=publish when the broker rejects publish', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      const broker = new MemoryBroker()
+      try {
+        using bus = new InProcessCrossNodeBus({ broker, nodeId: 'a', telemetry })
+        const errors: Array<{ phase: string }> = []
+        using _sub = telemetry.subscribe('onCrossNodeError', (event) => {
+          errors.push(event)
+        })
+        broker[Symbol.dispose]()
+        await expect(bus.publish('topic', null)).rejects.toThrow(/disposed/)
+        expect(errors.some((event) => event.phase === 'publish')).toBe(true)
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('emits onCrossNodeError with phase=replay when the underlying broker rejects', () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      using broker = new MemoryBroker({ replayWindow: 1 })
+      try {
+        using bus = new InProcessCrossNodeBus({ broker, nodeId: 'a', telemetry })
+        const errors: Array<{ phase: string }> = []
+        using _sub = telemetry.subscribe('onCrossNodeError', (event) => {
+          errors.push(event)
+        })
+        void bus.publish('topic', null)
+        void bus.publish('topic', null)
+        expect(() => bus.replay('topic', '0')).toThrow()
+        expect(errors.some((event) => event.phase === 'replay')).toBe(true)
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('emits onCrossNodeWindowEvicted with displayTopic when a private broker rolls', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      try {
+        using bus = new InProcessCrossNodeBus({ nodeId: 'a', telemetry, replayWindow: 2 })
+        const evictions: Array<{ topic: string; evictedSeq: string; retainedCount: number }> = []
+        using _sub = telemetry.subscribe('onCrossNodeWindowEvicted', (event) => {
+          evictions.push(event)
+        })
+        // No subscriber → displayTopic falls back to wire (= 'topic' here, no prefix)
+        await bus.publish('topic', null) // seq 1
+        await bus.publish('topic', null) // seq 2
+        await bus.publish('topic', null) // seq 3 → evicts seq 1
+        expect(evictions).toEqual([{ topic: 'topic', evictedSeq: '1', retainedCount: 2 }])
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('attributes window-evicted topic to the original subscribe call when topicPrefix is set', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      try {
+        using bus = new InProcessCrossNodeBus({ nodeId: 'a', telemetry, replayWindow: 2, topicPrefix: 'svc-a/' })
+        using _h = bus.subscribe('events', () => undefined)
+        const evictions: Array<{ topic: string }> = []
+        using _sub = telemetry.subscribe('onCrossNodeWindowEvicted', (event) => {
+          evictions.push({ topic: event.topic })
+        })
+        await bus.publish('events', null)
+        await bus.publish('events', null)
+        await bus.publish('events', null) // first eviction
+        expect(evictions).toEqual([{ topic: 'events' }])
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('does not emit onCrossNodeWindowEvicted when the broker is supplied externally', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      using broker = new MemoryBroker({ replayWindow: 2 })
+      try {
+        using bus = new InProcessCrossNodeBus({ broker, nodeId: 'a', telemetry })
+        const onEvicted = vi.fn()
+        using _sub = telemetry.subscribe('onCrossNodeWindowEvicted', onEvicted)
+        await bus.publish('topic', null)
+        await bus.publish('topic', null)
+        await bus.publish('topic', null)
+        expect(onEvicted).not.toHaveBeenCalled()
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+
+    it('emits onCrossNodeError with phase=serialize when JSON.stringify throws', async () => {
+      const telemetry = new CrossNodeBusTelemetry()
+      try {
+        using bus = new InProcessCrossNodeBus({ nodeId: 'a', telemetry })
+        const errors: Array<{ phase: string }> = []
+        using _sub = telemetry.subscribe('onCrossNodeError', (event) => {
+          errors.push(event)
+        })
+
+        const cycle: Record<string, unknown> = {}
+        cycle.self = cycle
+
+        await bus.publish('topic', cycle)
+        expect(errors.some((event) => event.phase === 'serialize')).toBe(true)
+      } finally {
+        telemetry[Symbol.dispose]()
+      }
+    })
+  })
+
+  describe('compareSeq', () => {
+    it('returns negative, zero, positive for a<b, a==b, a>b', () => {
+      using bus = new InProcessCrossNodeBus()
+      expect(bus.compareSeq('1', '2')).toBeLessThan(0)
+      expect(bus.compareSeq('5', '5')).toBe(0)
+      expect(bus.compareSeq('10', '2')).toBeGreaterThan(0)
+    })
+  })
+
+  describe('oldestSeq', () => {
+    it('returns undefined before any publish', () => {
+      using bus = new InProcessCrossNodeBus()
+      expect(bus.oldestSeq('topic')).toBeUndefined()
+    })
+
+    it('returns the oldest retained seq honoring topicPrefix', async () => {
+      using broker = new MemoryBroker()
+      using bus = new InProcessCrossNodeBus({ broker, topicPrefix: 'svc/' })
+      await bus.publish('topic', null)
+      await bus.publish('topic', null)
+      expect(bus.oldestSeq('topic')).toBe('1')
+      // direct broker access proves the prefix was applied on the wire.
+      expect(broker.oldestSeq('svc/topic')).toBe('1')
+    })
+
+    it('throws after dispose', () => {
+      const bus = new InProcessCrossNodeBus()
+      bus[Symbol.dispose]()
+      expect(() => bus.oldestSeq('topic')).toThrow(/disposed/)
+    })
+  })
+
+  describe('disposal', () => {
+    it('rejects publish/subscribe/replay after dispose', async () => {
+      const bus = new InProcessCrossNodeBus()
+      bus[Symbol.dispose]()
+      expect(() => bus.subscribe('topic', () => undefined)).toThrow(/disposed/)
+      expect(() => bus.subscribeForeign('p/', 'topic', () => undefined)).toThrow(/disposed/)
+      expect(() => bus.replay('topic', '0')).toThrow(/disposed/)
+      await expect(bus.publish('topic', null)).rejects.toThrow(/disposed/)
+    })
+
+    it('is idempotent', () => {
+      const bus = new InProcessCrossNodeBus()
+      bus[Symbol.dispose]()
+      expect(() => bus[Symbol.dispose]()).not.toThrow()
+    })
+
+    it('disposes its private broker when it owns one', () => {
+      const bus = new InProcessCrossNodeBus()
+      const handler = vi.fn()
+      const sub = bus.subscribe('topic', handler)
+      bus[Symbol.dispose]()
+      expect(() => sub[Symbol.dispose]()).not.toThrow()
+    })
+
+    it('does not dispose a shared broker', () => {
+      using broker = new MemoryBroker()
+      const bus = new InProcessCrossNodeBus({ broker })
+      bus[Symbol.dispose]()
+      expect(() => broker.publish('topic', 'a', null)).not.toThrow()
+    })
+  })
+})

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

@@ -0,0 +1,248 @@
+import { randomUUID } from 'node:crypto'
+import type { CrossNodeBusTelemetry } from './cross-node-bus-telemetry.js'
+import { MemoryBroker } from './memory-broker.js'
+import type { CrossNodeBus } from './cross-node-bus.js'
+import type { BusMessage, CrossNodeBusCapabilities } from './types.js'
+
+/**
+ * Options accepted by {@link InProcessCrossNodeBus}.
+ */
+export type InProcessCrossNodeBusOptions = {
+  /**
+   * Shared {@link MemoryBroker}. When omitted a private broker is minted —
+   * single-instance behavior matches an isolated EventHub. The testing
+   * harness passes the same broker to N buses so they can observe each
+   * other's publishes without an external transport.
+   */
+  broker?: MemoryBroker
+  /** Stable, per-process identifier. Defaults to `local-${crypto.randomUUID()}`. */
+  nodeId?: string
+  /**
+   * Wire-level prefix applied to every topic on `publish` / `subscribe`.
+   * Defaults to `''` (no prefix). Multi-service simulations pick distinct
+   * prefixes per bus so cross-service eavesdrop can be exercised against a
+   * single shared broker.
+   */
+  topicPrefix?: string
+  /**
+   * Convenience for the common case of "one bus, fresh private broker, this
+   * many retained messages per topic". Ignored when `broker` is provided.
+   */
+  replayWindow?: number
+  /** Sink for `onCrossNodePublished` / `onCrossNodeReceived` / `onCrossNodeError`. */
+  telemetry?: CrossNodeBusTelemetry
+}
+
+const CAPABILITIES: CrossNodeBusCapabilities = Object.freeze({
+  persistent: false,
+  replay: true,
+  assignsSequence: true,
+})
+
+type LocalEntry = {
+  handler: (message: BusMessage) => void
+  /** Original topic the caller subscribed with — used for telemetry attribution. */
+  displayTopic: string
+}
+
+/**
+ * In-process default {@link CrossNodeBus} adapter. Backs single-node
+ * deployments out of the box and powers the multi-instance testing harness
+ * exposed at `@furystack/cross-node-bus/testing`.
+ *
+ * Local fan-out is multiplexed: regardless of how many handlers subscribe
+ * to a single wire topic, the bus opens exactly one broker subscription and
+ * dispatches arrivals to its own handler set. This keeps `onCrossNodeReceived`
+ * counting one event per arrival rather than per handler invocation, and
+ * mirrors the consumer-group shape future network adapters will use.
+ */
+export class InProcessCrossNodeBus implements CrossNodeBus {
+  public readonly nodeId: string
+  public readonly capabilities: CrossNodeBusCapabilities = CAPABILITIES
+
+  readonly #broker: MemoryBroker
+  readonly #ownsBroker: boolean
+  readonly #topicPrefix: string
+  readonly #telemetry: CrossNodeBusTelemetry | undefined
+
+  /** displayTopic per wire topic — keyed by wire string for O(1) routing. */
+  readonly #localHandlers: Map<string, Set<LocalEntry>> = new Map()
+  /** Live broker subscription per wire topic, opened on first local handler. */
+  readonly #brokerHandles: Map<string, Disposable> = new Map()
+
+  #disposed = false
+
+  constructor(options: InProcessCrossNodeBusOptions = {}) {
+    this.#ownsBroker = options.broker === undefined
+    this.nodeId = options.nodeId ?? `local-${randomUUID()}`
+    this.#topicPrefix = options.topicPrefix ?? ''
+    this.#telemetry = options.telemetry
+    this.#broker =
+      options.broker ??
+      new MemoryBroker({
+        replayWindow: options.replayWindow,
+        onEviction: (wire, evictedSeq, retainedCount) =>
+          this.#telemetry?.emit('onCrossNodeWindowEvicted', {
+            topic: this.#displayTopicFor(wire),
+            evictedSeq,
+            retainedCount,
+          }),
+      })
+  }
+
+  public async publish(topic: string, payload: unknown): Promise<void> {
+    this.#ensureLive()
+    const wire = this.#wireTopic(topic)
+    let byteLength = 0
+    if (this.#telemetry) {
+      try {
+        byteLength = Buffer.byteLength(JSON.stringify(payload) ?? '')
+      } catch (error) {
+        this.#telemetry.emit('onCrossNodeError', { topic, error, phase: 'serialize' })
+      }
+    }
+    try {
+      this.#broker.publish(wire, this.nodeId, payload, (error) => {
+        this.#telemetry?.emit('onCrossNodeError', { topic, error, phase: 'subscribe' })
+      })
+    } catch (error) {
+      this.#telemetry?.emit('onCrossNodeError', { topic, error, phase: 'publish' })
+      throw error
+    }
+    this.#telemetry?.emit('onCrossNodePublished', { topic, originId: this.nodeId, byteLength })
+  }
+
+  public subscribe(topic: string, handler: (message: BusMessage) => void): Disposable {
+    this.#ensureLive()
+    return this.#subscribeWire(this.#wireTopic(topic), topic, handler, 'subscribe')
+  }
+
+  public subscribeRemoteOnly(topic: string, handler: (message: BusMessage) => void): Disposable {
+    return this.subscribe(topic, (message) => {
+      if (message.originId !== this.nodeId) handler(message)
+    })
+  }
+
+  public subscribeForeign(prefix: string, topic: string, handler: (message: BusMessage) => void): Disposable {
+    this.#ensureLive()
+    return this.#subscribeWire(`${prefix}${topic}`, topic, handler, 'subscribeForeign')
+  }
+
+  public replay(topic: string, fromSeq: string): AsyncIterable<BusMessage> {
+    this.#ensureLive()
+    try {
+      return this.#broker.replay(this.#wireTopic(topic), fromSeq)
+    } catch (error) {
+      this.#telemetry?.emit('onCrossNodeError', { topic, error, phase: 'replay' })
+      throw error
+    }
+  }
+
+  public compareSeq(a: string, b: string): number {
+    return Number(a) - Number(b)
+  }
+
+  public oldestSeq(topic: string): string | undefined {
+    this.#ensureLive()
+    return this.#broker.oldestSeq(this.#wireTopic(topic))
+  }
+
+  public [Symbol.dispose](): void {
+    if (this.#disposed) return
+    this.#disposed = true
+    for (const handle of this.#brokerHandles.values()) {
+      handle[Symbol.dispose]()
+    }
+    this.#brokerHandles.clear()
+    this.#localHandlers.clear()
+    if (this.#ownsBroker) {
+      this.#broker[Symbol.dispose]()
+    }
+  }
+
+  #wireTopic(topic: string): string {
+    return `${this.#topicPrefix}${topic}`
+  }
+
+  /**
+   * Reverse-resolve the caller-facing display topic for a wire topic. When
+   * local handlers exist their displayTopic is authoritative — `subscribe`
+   * always yields `prefix+t` and `subscribeForeign` always yields `p+t`, so
+   * the first entry is representative. Falls back to the wire string when no
+   * subscriber on this bus has registered (publish-only buses never need to
+   * round-trip a display name; the wire is the most accurate label).
+   */
+  #displayTopicFor(wire: string): string {
+    const handlers = this.#localHandlers.get(wire)
+    if (!handlers) return wire
+    const first = handlers.values().next().value
+    return first ? first.displayTopic : wire
+  }
+
+  #subscribeWire(
+    wire: string,
+    displayTopic: string,
+    handler: (message: BusMessage) => void,
+    phase: 'subscribe' | 'subscribeForeign',
+  ): Disposable {
+    const entry: LocalEntry = { handler, displayTopic }
+    let handlers = this.#localHandlers.get(wire)
+    if (!handlers) {
+      handlers = new Set()
+      this.#localHandlers.set(wire, handlers)
+      try {
+        const brokerHandle = this.#broker.subscribe(wire, (message) => this.#deliver(wire, message))
+        this.#brokerHandles.set(wire, brokerHandle)
+      } catch (error) {
+        this.#localHandlers.delete(wire)
+        this.#telemetry?.emit('onCrossNodeError', { topic: displayTopic, error, phase })
+        throw error
+      }
+    }
+    handlers.add(entry)
+    return {
+      [Symbol.dispose]: () => {
+        const current = this.#localHandlers.get(wire)
+        if (!current) return
+        current.delete(entry)
+        if (current.size === 0) {
+          this.#localHandlers.delete(wire)
+          this.#brokerHandles.get(wire)?.[Symbol.dispose]()
+          this.#brokerHandles.delete(wire)
+        }
+      },
+    }
+  }
+
+  #deliver(wire: string, message: BusMessage): void {
+    const handlers = this.#localHandlers.get(wire)
+    if (!handlers || handlers.size === 0) return
+    if (this.#telemetry) {
+      // Multiple subscribers on the same wire share a displayTopic that maps
+      // 1:1 to the wire string: `subscribe(t)` always yields prefix+t and
+      // `subscribeForeign(p, t)` always yields p+t. The first entry's
+      // displayTopic is therefore representative.
+      const first = handlers.values().next().value
+      if (first) {
+        this.#telemetry.emit('onCrossNodeReceived', {
+          topic: first.displayTopic,
+          originId: message.originId,
+          lagMs: Date.now() - Date.parse(message.emittedAt),
+        })
+      }
+    }
+    for (const entry of handlers) {
+      try {
+        entry.handler(message)
+      } catch (error) {
+        this.#telemetry?.emit('onCrossNodeError', { topic: entry.displayTopic, error, phase: 'subscribe' })
+      }
+    }
+  }
+
+  #ensureLive(): void {
+    if (this.#disposed) {
+      throw new Error('InProcessCrossNodeBus has been disposed')
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './cross-node-bus-telemetry.js'
+export * from './cross-node-bus.js'
+export * from './define-in-process-cross-node-bus.js'
+export * from './errors.js'
+export * from './in-process-cross-node-bus.js'
+export * from './memory-broker.js'
+export type { BusMessage, CrossNodeBusCapabilities } from './types.js'