@furystack/cross-node-bus 1.0.0

package/src/memory-broker.spec.ts

@@ -0,0 +1,282 @@
+import { describe, expect, it, vi } from 'vitest'
+import { ReplayWindowExceededError } from './errors.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('MemoryBroker', () => {
+  describe('constructor', () => {
+    it('rejects non-positive replayWindow', () => {
+      expect(() => new MemoryBroker({ replayWindow: 0 })).toThrow(RangeError)
+      expect(() => new MemoryBroker({ replayWindow: -1 })).toThrow(RangeError)
+      expect(() => new MemoryBroker({ replayWindow: 1.5 })).toThrow(RangeError)
+    })
+
+    it('exposes the configured replayWindow', () => {
+      const broker = new MemoryBroker({ replayWindow: 42 })
+      expect(broker.replayWindow).toBe(42)
+    })
+
+    it('defaults replayWindow to 1000', () => {
+      const broker = new MemoryBroker()
+      expect(broker.replayWindow).toBe(1000)
+    })
+  })
+
+  describe('publish + subscribe', () => {
+    it('delivers messages to every subscriber on the topic', () => {
+      using broker = new MemoryBroker()
+      const a = vi.fn()
+      const b = vi.fn()
+      using _subA = broker.subscribe('topic', a)
+      using _subB = broker.subscribe('topic', b)
+
+      const message = broker.publish('topic', 'origin-1', { x: 1 })
+
+      expect(a).toHaveBeenCalledTimes(1)
+      expect(b).toHaveBeenCalledTimes(1)
+      expect(a.mock.calls[0]?.[0]).toBe(message)
+    })
+
+    it('does not deliver across topics', () => {
+      using broker = new MemoryBroker()
+      const handler = vi.fn()
+      using _sub = broker.subscribe('topic-a', handler)
+
+      broker.publish('topic-b', 'origin-1', null)
+      expect(handler).not.toHaveBeenCalled()
+    })
+
+    it('stamps version, originId, payload, ISO emittedAt and monotonic seq', () => {
+      using broker = new MemoryBroker()
+      const m1 = broker.publish('topic', 'origin-1', { n: 1 })
+      const m2 = broker.publish('topic', 'origin-2', { n: 2 })
+
+      expect(m1.v).toBe(1)
+      expect(m1.originId).toBe('origin-1')
+      expect(m1.payload).toEqual({ n: 1 })
+      expect(m1.seq).toBe('1')
+      expect(m2.seq).toBe('2')
+      expect(Number.isFinite(Date.parse(m1.emittedAt))).toBe(true)
+    })
+
+    it('keeps sequence counters per-topic', () => {
+      using broker = new MemoryBroker()
+      const a1 = broker.publish('a', 'o', null)
+      const b1 = broker.publish('b', 'o', null)
+      const a2 = broker.publish('a', 'o', null)
+
+      expect(a1.seq).toBe('1')
+      expect(b1.seq).toBe('1')
+      expect(a2.seq).toBe('2')
+    })
+
+    it('removes the subscriber on dispose', () => {
+      using broker = new MemoryBroker()
+      const handler = vi.fn()
+      const sub = broker.subscribe('topic', handler)
+      sub[Symbol.dispose]()
+
+      broker.publish('topic', 'origin-1', null)
+      expect(handler).not.toHaveBeenCalled()
+    })
+
+    it('isolates one subscriber from another that throws', () => {
+      using broker = new MemoryBroker()
+      const ok = vi.fn()
+      const onError = vi.fn()
+      const failing = vi.fn(() => {
+        throw new Error('boom')
+      })
+      using _subA = broker.subscribe('topic', failing)
+      using _subB = broker.subscribe('topic', ok)
+
+      broker.publish('topic', 'origin-1', null, onError)
+
+      expect(ok).toHaveBeenCalledTimes(1)
+      expect(onError).toHaveBeenCalledTimes(1)
+      expect(onError.mock.calls[0]?.[0]).toBeInstanceOf(Error)
+      expect(onError.mock.calls[0]?.[1]).toBe(failing)
+    })
+
+    it('falls back to console.error when no error sink is provided', () => {
+      using broker = new MemoryBroker()
+      const error = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+      try {
+        using _sub = broker.subscribe('topic', () => {
+          throw new Error('boom')
+        })
+        broker.publish('topic', 'origin-1', null)
+        expect(error).toHaveBeenCalledTimes(1)
+      } finally {
+        error.mockRestore()
+      }
+    })
+  })
+
+  describe('replay', () => {
+    it('yields messages with seq greater than fromSeq', async () => {
+      using broker = new MemoryBroker()
+      broker.publish('topic', 'origin-1', { n: 1 })
+      broker.publish('topic', 'origin-1', { n: 2 })
+      broker.publish('topic', 'origin-1', { n: 3 })
+
+      const yielded = await collect(broker.replay('topic', '1'))
+      expect(yielded.map((m) => m.seq)).toEqual(['2', '3'])
+    })
+
+    it('returns an empty stream when nothing has been published', async () => {
+      using broker = new MemoryBroker()
+      const yielded = await collect(broker.replay('topic', '0'))
+      expect(yielded).toEqual([])
+    })
+
+    it('returns an empty stream when fromSeq matches the latest seq', async () => {
+      using broker = new MemoryBroker()
+      broker.publish('topic', 'origin-1', null)
+      const yielded = await collect(broker.replay('topic', '1'))
+      expect(yielded).toEqual([])
+    })
+
+    it('throws synchronously when fromSeq falls outside the retained window', () => {
+      const broker = new MemoryBroker({ replayWindow: 2 })
+      try {
+        broker.publish('topic', 'origin-1', null) // seq 1
+        broker.publish('topic', 'origin-1', null) // seq 2
+        broker.publish('topic', 'origin-1', null) // seq 3 — drops seq 1
+
+        // window now retains seqs 2, 3. Asking from seq 0 lost seq 1.
+        expect(() => broker.replay('topic', '0')).toThrow(ReplayWindowExceededError)
+      } finally {
+        broker[Symbol.dispose]()
+      }
+    })
+
+    it('does not throw when fromSeq+1 equals the oldest retained seq', async () => {
+      using broker = new MemoryBroker({ replayWindow: 2 })
+      broker.publish('topic', 'origin-1', null) // seq 1
+      broker.publish('topic', 'origin-1', null) // seq 2
+      broker.publish('topic', 'origin-1', null) // seq 3 — retains 2, 3
+
+      const yielded = await collect(broker.replay('topic', '1'))
+      expect(yielded.map((m) => m.seq)).toEqual(['2', '3'])
+    })
+
+    it('rejects malformed fromSeq values', () => {
+      using broker = new MemoryBroker()
+      expect(() => broker.replay('topic', 'abc')).toThrow(RangeError)
+      expect(() => broker.replay('topic', '-1')).toThrow(RangeError)
+    })
+
+    it('snapshots the buffer at call time', async () => {
+      using broker = new MemoryBroker()
+      broker.publish('topic', 'origin-1', { n: 1 })
+      const iterable = broker.replay('topic', '0')
+      broker.publish('topic', 'origin-1', { n: 2 })
+
+      const yielded = await collect(iterable)
+      expect(yielded.map((m) => (m.payload as { n: number }).n)).toEqual([1])
+    })
+  })
+
+  describe('oldestSeq', () => {
+    it('returns undefined when nothing has been published', () => {
+      using broker = new MemoryBroker()
+      expect(broker.oldestSeq('topic')).toBeUndefined()
+    })
+
+    it('returns the seq of the first retained message', () => {
+      using broker = new MemoryBroker()
+      broker.publish('topic', 'origin-1', null)
+      broker.publish('topic', 'origin-1', null)
+      expect(broker.oldestSeq('topic')).toBe('1')
+    })
+
+    it('advances after the ring buffer evicts older entries', () => {
+      using broker = new MemoryBroker({ replayWindow: 2 })
+      broker.publish('topic', 'origin-1', null) // seq 1, evicted
+      broker.publish('topic', 'origin-1', null) // seq 2
+      broker.publish('topic', 'origin-1', null) // seq 3
+      expect(broker.oldestSeq('topic')).toBe('2')
+    })
+  })
+
+  describe('onEviction', () => {
+    it('fires once per shifted message with topic, evictedSeq, and retainedCount', () => {
+      const evictions: Array<{ topic: string; evictedSeq: string; retainedCount: number }> = []
+      using broker = new MemoryBroker({
+        replayWindow: 2,
+        onEviction: (topic, evictedSeq, retainedCount) => {
+          evictions.push({ topic, evictedSeq, retainedCount })
+        },
+      })
+      broker.publish('topic', 'origin-1', null) // seq 1
+      broker.publish('topic', 'origin-1', null) // seq 2
+      expect(evictions).toEqual([])
+      broker.publish('topic', 'origin-1', null) // seq 3 → evicts seq 1
+      broker.publish('topic', 'origin-1', null) // seq 4 → evicts seq 2
+      expect(evictions).toEqual([
+        { topic: 'topic', evictedSeq: '1', retainedCount: 2 },
+        { topic: 'topic', evictedSeq: '2', retainedCount: 2 },
+      ])
+    })
+
+    it('does not fire while the buffer is below replayWindow', () => {
+      const onEviction = vi.fn()
+      using broker = new MemoryBroker({ replayWindow: 5, onEviction })
+      for (let i = 0; i < 5; i += 1) broker.publish('topic', 'origin-1', null)
+      expect(onEviction).not.toHaveBeenCalled()
+    })
+
+    it('attributes evictions to the right topic when several are active', () => {
+      const evictions: Array<{ topic: string; evictedSeq: string }> = []
+      using broker = new MemoryBroker({
+        replayWindow: 1,
+        onEviction: (topic, evictedSeq) => {
+          evictions.push({ topic, evictedSeq })
+        },
+      })
+      broker.publish('a', 'origin-1', null) // seq a/1
+      broker.publish('b', 'origin-1', null) // seq b/1
+      broker.publish('a', 'origin-1', null) // evicts a/1
+      broker.publish('b', 'origin-1', null) // evicts b/1
+      expect(evictions).toEqual([
+        { topic: 'a', evictedSeq: '1' },
+        { topic: 'b', evictedSeq: '1' },
+      ])
+    })
+  })
+
+  describe('disposal', () => {
+    it('clears subscribers and rejects further calls', () => {
+      const broker = new MemoryBroker()
+      const handler = vi.fn()
+      broker.subscribe('topic', handler)
+
+      broker[Symbol.dispose]()
+
+      expect(() => broker.publish('topic', 'origin-1', null)).toThrow(/disposed/)
+      expect(() => broker.subscribe('topic', handler)).toThrow(/disposed/)
+      expect(() => broker.replay('topic', '0')).toThrow(/disposed/)
+      expect(() => broker.oldestSeq('topic')).toThrow(/disposed/)
+    })
+
+    it('is idempotent', () => {
+      const broker = new MemoryBroker()
+      broker[Symbol.dispose]()
+      expect(() => broker[Symbol.dispose]()).not.toThrow()
+    })
+
+    it('disposing a subscription after broker disposal is a no-op', () => {
+      const broker = new MemoryBroker()
+      const sub = broker.subscribe('topic', () => undefined)
+      broker[Symbol.dispose]()
+      expect(() => sub[Symbol.dispose]()).not.toThrow()
+    })
+  })
+})

package/src/memory-broker.ts

@@ -0,0 +1,199 @@
+import { ReplayWindowExceededError } from './errors.js'
+import type { BusMessage } from './types.js'
+
+/**
+ * Options accepted by {@link MemoryBroker}.
+ */
+export type MemoryBrokerOptions = {
+  /**
+   * Maximum number of messages retained per topic for {@link MemoryBroker.replay}.
+   * Defaults to `1000`. Must be a positive integer.
+   */
+  replayWindow?: number
+  /**
+   * Invoked synchronously every time the per-topic ring buffer drops a message
+   * to honor `replayWindow`. Receives the evicted message's `seq` and the new
+   * retained count after eviction. {@link InProcessCrossNodeBus} wires this to
+   * `onCrossNodeWindowEvicted` telemetry; tests and bespoke setups can supply a
+   * direct callback. Mirrors the broker-agnostic shape of `onSubscriberError`
+   * on {@link MemoryBroker.publish}.
+   */
+  onEviction?: (topic: string, evictedSeq: string, retainedCount: number) => void
+}
+
+const DEFAULT_REPLAY_WINDOW = 1000
+
+type Handler = (message: BusMessage) => void
+
+type TopicState = {
+  /** Last assigned sequence as a number. Stored as `string` on the wire. */
+  lastSeq: number
+  /** Ring buffer ordered oldest → newest. Length is bounded by `replayWindow`. */
+  buffer: BusMessage[]
+  /** Subscribers receiving every message published on this topic. */
+  handlers: Set<Handler>
+}
+
+/**
+ * In-memory broker shared by one or more {@link InProcessCrossNodeBus}
+ * instances. Owns the per-topic monotonic sequence counter, the bounded
+ * replay buffer, and the subscriber registry.
+ *
+ * The default {@link CrossNodeBus} factory mints a private broker per bus,
+ * so single-instance deployments behave like an isolated EventHub. The
+ * testing harness shares a single broker across N buses so multi-node
+ * scenarios can be exercised without spinning up an external transport.
+ */
+export class MemoryBroker implements Disposable {
+  readonly #replayWindow: number
+  readonly #onEviction: ((topic: string, evictedSeq: string, retainedCount: number) => void) | undefined
+  readonly #topics: Map<string, TopicState> = new Map()
+  #disposed = false
+
+  constructor(options: MemoryBrokerOptions = {}) {
+    const replayWindow = options.replayWindow ?? DEFAULT_REPLAY_WINDOW
+    if (!Number.isInteger(replayWindow) || replayWindow <= 0) {
+      throw new RangeError(`MemoryBroker.replayWindow must be a positive integer, got ${String(replayWindow)}`)
+    }
+    this.#replayWindow = replayWindow
+    this.#onEviction = options.onEviction
+  }
+
+  public get replayWindow(): number {
+    return this.#replayWindow
+  }
+
+  /**
+   * Stamps `payload` with a fresh per-topic sequence and a publisher-side
+   * `emittedAt`, retains the result in the ring buffer, then synchronously
+   * fans out to every subscriber on `topic`.
+   *
+   * Subscriber exceptions are caught and routed to `onSubscriberError` so a
+   * single faulty handler cannot interrupt fan-out to siblings or the bus
+   * that hosts them.
+   */
+  public publish(
+    topic: string,
+    originId: string,
+    payload: unknown,
+    onSubscriberError?: (error: unknown, handler: Handler) => void,
+  ): BusMessage {
+    this.#ensureLive()
+    const state = this.#getOrCreate(topic)
+    state.lastSeq += 1
+    const message: BusMessage = {
+      v: 1,
+      originId,
+      emittedAt: new Date().toISOString(),
+      seq: String(state.lastSeq),
+      payload,
+    }
+    state.buffer.push(message)
+    if (state.buffer.length > this.#replayWindow) {
+      const evicted = state.buffer.shift()
+      if (evicted && this.#onEviction) {
+        // `evicted.seq` is always defined for messages this broker minted —
+        // `BusMessage.seq` is optional only because non-sequencing adapters
+        // omit it. The non-null assertion is the cheapest narrowing here.
+        this.#onEviction(topic, evicted.seq as string, state.buffer.length)
+      }
+    }
+    for (const handler of state.handlers) {
+      try {
+        handler(message)
+      } catch (error) {
+        if (onSubscriberError) {
+          onSubscriberError(error, handler)
+        } else {
+          console.error('Unhandled MemoryBroker subscriber error', { topic, error })
+        }
+      }
+    }
+    return message
+  }
+
+  /**
+   * Registers `handler` for every message published on `topic`. The returned
+   * {@link Disposable} removes the handler on dispose.
+   */
+  public subscribe(topic: string, handler: Handler): Disposable {
+    this.#ensureLive()
+    const state = this.#getOrCreate(topic)
+    state.handlers.add(handler)
+    return {
+      [Symbol.dispose]: () => {
+        const current = this.#topics.get(topic)
+        if (!current) return
+        current.handlers.delete(handler)
+        if (current.handlers.size === 0 && current.buffer.length === 0 && current.lastSeq === 0) {
+          this.#topics.delete(topic)
+        }
+      },
+    }
+  }
+
+  /**
+   * Returns the oldest retained seq for `topic`, or `undefined` when no
+   * messages are currently retained. Used by {@link InProcessCrossNodeBus}
+   * to back `oldestSeq` without forcing facades into throw-and-catch.
+   */
+  public oldestSeq(topic: string): string | undefined {
+    this.#ensureLive()
+    return this.#topics.get(topic)?.buffer[0]?.seq
+  }
+
+  /**
+   * Snapshot-then-stream replay. Validates the window synchronously: callers
+   * see {@link ReplayWindowExceededError} before they iterate, which keeps
+   * the fall-back-to-snapshot decision uniform with non-iterable failure
+   * modes elsewhere in the framework.
+   *
+   * Iteration walks a frozen snapshot of the buffer captured at call time;
+   * concurrent `publish` calls do not interleave into an in-flight replay.
+   */
+  public replay(topic: string, fromSeq: string): AsyncIterable<BusMessage> {
+    this.#ensureLive()
+    const fromSeqN = Number(fromSeq)
+    if (!Number.isFinite(fromSeqN) || fromSeqN < 0) {
+      throw new RangeError(`MemoryBroker.replay fromSeq must be a non-negative integer, got "${fromSeq}"`)
+    }
+    const state = this.#topics.get(topic)
+    const buffer = state?.buffer ?? []
+    const oldestRetained = buffer.length > 0 ? buffer[0].seq : undefined
+    const oldestRetainedN = oldestRetained !== undefined ? Number(oldestRetained) : (state?.lastSeq ?? 0) + 1
+    if (fromSeqN + 1 < oldestRetainedN) {
+      throw new ReplayWindowExceededError(topic, fromSeq, oldestRetained)
+    }
+    const snapshot = buffer.filter((message) => Number(message.seq) > fromSeqN)
+    return (async function* iterate(): AsyncIterable<BusMessage> {
+      for (const message of snapshot) {
+        yield message
+      }
+    })()
+  }
+
+  /**
+   * Drops all retained messages, sequence counters, and subscribers. After
+   * disposal every method throws — re-bind a fresh broker if you need one.
+   */
+  public [Symbol.dispose](): void {
+    if (this.#disposed) return
+    this.#disposed = true
+    this.#topics.clear()
+  }
+
+  #ensureLive(): void {
+    if (this.#disposed) {
+      throw new Error('MemoryBroker has been disposed')
+    }
+  }
+
+  #getOrCreate(topic: string): TopicState {
+    let state = this.#topics.get(topic)
+    if (!state) {
+      state = { lastSeq: 0, buffer: [], handlers: new Set() }
+      this.#topics.set(topic, state)
+    }
+    return state
+  }
+}

package/src/testing/create-in-process-bus-network.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { BusMessage } from '../types.js'
+import { createInProcessBusNetwork } from './create-in-process-bus-network.js'
+
+describe('createInProcessBusNetwork', () => {
+  it('mints `count` buses sharing one broker', async () => {
+    using network = createInProcessBusNetwork({ count: 3 })
+    expect(network.buses).toHaveLength(3)
+    expect(network.broker).toBeDefined()
+
+    const handlerB = vi.fn()
+    const handlerC = vi.fn()
+    using _subB = network.buses[1].subscribe('topic', handlerB)
+    using _subC = network.buses[2].subscribe('topic', handlerC)
+
+    await network.buses[0].publish('topic', { from: 0 })
+
+    expect(handlerB).toHaveBeenCalledTimes(1)
+    expect(handlerC).toHaveBeenCalledTimes(1)
+  })
+
+  it('honors per-bus topicPrefixes for multi-service simulation', async () => {
+    using network = createInProcessBusNetwork({
+      count: 2,
+      topicPrefixes: ['svc-a/', 'svc-b/'],
+    })
+    const [busA, busB] = network.buses
+    const onB = vi.fn()
+    const eavesdrop = vi.fn()
+
+    using _subB = busB.subscribe('events', onB)
+    using _foreign = busB.subscribeForeign('svc-a/', 'events', eavesdrop)
+
+    await busA.publish('events', { from: 'a' })
+
+    expect(onB).not.toHaveBeenCalled()
+    expect(eavesdrop).toHaveBeenCalledTimes(1)
+    expect((eavesdrop.mock.calls[0]?.[0] as BusMessage).originId).toBe(busA.nodeId)
+  })
+
+  it('honors per-bus nodeIds', () => {
+    using network = createInProcessBusNetwork({
+      count: 2,
+      nodeIds: ['alice', 'bob'],
+    })
+    expect(network.buses[0].nodeId).toBe('alice')
+    expect(network.buses[1].nodeId).toBe('bob')
+  })
+
+  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)
+    })
+  })
+})

package/src/testing/create-in-process-bus-network.ts

@@ -0,0 +1,87 @@
+import { InProcessCrossNodeBus } from '../in-process-cross-node-bus.js'
+import { MemoryBroker } from '../memory-broker.js'
+import type { CrossNodeBusTelemetry } from '../cross-node-bus-telemetry.js'
+
+/**
+ * Options accepted by {@link createInProcessBusNetwork}.
+ */
+export type CreateInProcessBusNetworkOptions = {
+  /** Number of buses to mint. Must be a positive integer. */
+  count: number
+  /** Forwarded to the shared {@link MemoryBroker}. Defaults to 1000. */
+  replayWindow?: number
+  /**
+   * Per-bus topic prefixes. When provided, length must equal `count`. Useful
+   * for simulating an N-services × M-nodes deployment against a single
+   * shared broker so cross-service eavesdrop can be exercised without an
+   * external transport.
+   */
+  topicPrefixes?: readonly string[]
+  /** Per-bus stable node ids. When provided, length must equal `count`. */
+  nodeIds?: readonly string[]
+  /** Per-bus telemetry sinks. When provided, length must equal `count`. */
+  telemetries?: readonly CrossNodeBusTelemetry[]
+}
+
+/**
+ * Disposable handle returned by {@link createInProcessBusNetwork}. Disposing
+ * it tears down every bus and the shared broker in reverse order.
+ */
+export type InProcessBusNetwork = Disposable & {
+  readonly buses: readonly InProcessCrossNodeBus[]
+  readonly broker: MemoryBroker
+}
+
+/**
+ * Mints `count` {@link InProcessCrossNodeBus} instances backed by a single
+ * {@link MemoryBroker}. Publishes from any bus reach the others' subscribers
+ * exactly as they would over a real transport.
+ *
+ * @example
+ * ```ts
+ * using network = createInProcessBusNetwork({ count: 2 })
+ * const [a, b] = network.buses
+ *
+ * using sub = b.subscribe('topic', (message) => {
+ *   // …
+ * })
+ * await a.publish('topic', { hello: 'world' })
+ * ```
+ */
+export const createInProcessBusNetwork = (options: CreateInProcessBusNetworkOptions): InProcessBusNetwork => {
+  const { count, replayWindow, topicPrefixes, nodeIds, telemetries } = options
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new RangeError(`createInProcessBusNetwork.count must be a positive integer, got ${String(count)}`)
+  }
+  for (const [name, list] of [
+    ['topicPrefixes', topicPrefixes],
+    ['nodeIds', nodeIds],
+    ['telemetries', telemetries],
+  ] as const) {
+    if (list !== undefined && list.length !== count) {
+      throw new RangeError(`createInProcessBusNetwork.${name} length must equal count (${count}), got ${list.length}`)
+    }
+  }
+  const broker = new MemoryBroker({ replayWindow })
+  const buses: InProcessCrossNodeBus[] = []
+  for (let index = 0; index < count; index += 1) {
+    buses.push(
+      new InProcessCrossNodeBus({
+        broker,
+        nodeId: nodeIds?.[index],
+        topicPrefix: topicPrefixes?.[index] ?? '',
+        telemetry: telemetries?.[index],
+      }),
+    )
+  }
+  return {
+    buses,
+    broker,
+    [Symbol.dispose]: () => {
+      for (let index = buses.length - 1; index >= 0; index -= 1) {
+        buses[index][Symbol.dispose]()
+      }
+      broker[Symbol.dispose]()
+    },
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1 @@
+export * from './create-in-process-bus-network.js'

package/src/types.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
+}