@mt-tl/server 0.1.0

package/src/update-publisher.ts

@@ -0,0 +1,47 @@
+import { createRedisUpdateBus } from './lib.js'
+import type { JsonValue } from '@mt-tl/tl'
+
+/** A standalone publisher returned by {@link createUpdatePublisher}. */
+export interface UpdatePublisher {
+    /** Push a TL update (`{ _: name, ... }`) to a `subject` (internal user id) —
+     * delivered to whatever node holds them. */
+    push(subject: string, update: unknown): Promise<void>
+    /** Push to a specific auth key — including an anonymous connection (no pts). */
+    pushToAuthKey(authKeyId: string, update: unknown): Promise<void>
+    /** Disconnect from the shared bus. */
+    close(): Promise<void>
+}
+
+/** Options for {@link createUpdatePublisher}. */
+export interface UpdatePublisherConfig {
+    /** Redis URL of the shared pub/sub update bus (the same `REDIS_URL` your servers use). */
+    redisUrl: string
+}
+
+/**
+ * Creates a server-push publisher for code running **outside** the server — a
+ * webhook receiver, a cron worker, another microservice. It drops the update on
+ * the shared Redis bus; the server fleet's router looks up presence and delivers
+ * it to whichever node holds the user (rendered for that client's layer). No
+ * client connection and no running server are needed — only the shared bus.
+ *
+ * Inside a handler, push with `ctx.push(subject, update)` instead — this is for
+ * cross-process pushes, which is why it needs the shared `redisUrl`.
+ *
+ * @example
+ * ```ts
+ * const updates = await createUpdatePublisher({ redisUrl: process.env.REDIS_URL! })
+ * await updates.push(subject, { _: 'updateNewMessage', message })
+ * await updates.close()
+ * ```
+ */
+export async function createUpdatePublisher(config: UpdatePublisherConfig): Promise<UpdatePublisher> {
+    if (!config.redisUrl) throw new Error('createUpdatePublisher requires redisUrl')
+    const handle = await createRedisUpdateBus(config.redisUrl)
+    return {
+        push: (subject, update) => handle.bus.publishUpdate({ subject, update: update as JsonValue }),
+        pushToAuthKey: (authKeyId, update) =>
+            handle.bus.publishUpdate({ authKeyId, update: update as JsonValue }),
+        close: () => handle.close(),
+    }
+}

package/src/updates/mongo-update-log.ts

@@ -0,0 +1,49 @@
+import type { JsonValue } from '@mt-tl/tl'
+import type { UpdateLog } from '../core/updates.js'
+
+/**
+ * Durable {@link UpdateLog} on MongoDB, for protocol-managed updates
+ * (`config.updates.managed`). `pts` is assigned atomically per subject via a
+ * counters document (`$inc`), so concurrent replicas never collide; each update
+ * is stored with its pts for `updates.getDifference`. Opens its own connection
+ * (the updates box is logically separate from auth/salt/session storage).
+ */
+export async function createMongoUpdateLog(
+    mongoUrl: string,
+    dbName: string,
+): Promise<{ log: UpdateLog; close: () => Promise<void> }> {
+    const { MongoClient } = await import('mongodb')
+    const client = new MongoClient(mongoUrl)
+    await client.connect()
+    const db = client.db(dbName)
+    const counters = db.collection<{ _id: string; pts: number }>('update_counters')
+    const log = db.collection<{ subject: string; pts: number; update: JsonValue }>('updates')
+    await log.createIndex({ subject: 1, pts: 1 })
+
+    return {
+        log: {
+            async append(subject, update) {
+                const doc = await counters.findOneAndUpdate(
+                    { _id: subject },
+                    { $inc: { pts: 1 } },
+                    { upsert: true, returnDocument: 'after' },
+                )
+                const pts = doc?.pts ?? 1
+                await log.insertOne({ subject, pts, update })
+                return { pts }
+            },
+            async since(subject, sincePts) {
+                const docs = await log
+                    .find({ subject, pts: { $gt: sincePts } })
+                    .sort({ pts: 1 })
+                    .toArray()
+                return docs.map(d => ({ pts: d.pts, update: d.update }))
+            },
+            async currentPts(subject) {
+                const doc = await counters.findOne({ _id: subject })
+                return doc?.pts ?? 0
+            },
+        },
+        close: () => client.close(),
+    }
+}

package/src/updates/presence-binder.ts

@@ -0,0 +1,51 @@
+import type { Connection } from '../transport/connection.js'
+import type { ConnectionRegistry } from '../transport/connection-registry.js'
+import type { Presence } from './presence.js'
+
+/**
+ * Couples a connection's authorized subject to the local registry and the global
+ * presence map. The pipeline binds on authenticated messages; the dispatcher
+ * binds/unbinds on bindUser/unbindUser effects; the carriers unbind on close.
+ */
+export interface PresenceBinder {
+    bind(conn: Connection, subject: string): void
+    /** Register a connection by its auth key (enables push to anonymous connections). */
+    bindAuthKey(conn: Connection, authKeyId: string): void
+    unbind(conn: Connection): void
+}
+
+export class NoopPresenceBinder implements PresenceBinder {
+    bind(): void {}
+    bindAuthKey(): void {}
+    unbind(): void {}
+}
+
+export class NodePresenceBinder implements PresenceBinder {
+    constructor(
+        private readonly nodeId: string,
+        private readonly registry: ConnectionRegistry,
+        private readonly presence: Presence,
+    ) {}
+
+    bind(conn: Connection, subject: string): void {
+        if (this.registry.subjectOf(conn) === subject) return // already bound — cheap no-op
+        this.registry.register(subject, conn)
+        void this.presence.add(subject, this.nodeId).catch(() => {})
+    }
+
+    bindAuthKey(conn: Connection, authKeyId: string): void {
+        this.registry.registerAuthKey(authKeyId, conn) // no-op if already registered
+        void this.presence.addAuthKey(authKeyId, this.nodeId).catch(() => {})
+    }
+
+    unbind(conn: Connection): void {
+        const { subject, authKeyId } = this.registry.unregister(conn)
+        // Only drop this node's presence once no local connection remains for the key.
+        if (subject !== undefined && !this.registry.hasSubject(subject)) {
+            void this.presence.remove(subject, this.nodeId).catch(() => {})
+        }
+        if (authKeyId !== undefined && !this.registry.hasAuthKey(authKeyId)) {
+            void this.presence.removeAuthKey(authKeyId, this.nodeId).catch(() => {})
+        }
+    }
+}

package/src/updates/presence.ts

@@ -0,0 +1,61 @@
+/**
+ * Global online-presence: which gateway node(s) currently hold a connection for
+ * a subject. Written by gateways, read by the Update Router to route updates only
+ * to nodes that actually hold the subject (no broadcast fan-out).
+ *
+ * Eventually-consistent is fine — a stale entry just routes to a node that drops
+ * the update, and the client recovers via pts/getDifference.
+ */
+export interface Presence {
+    add(subject: string, nodeId: string): Promise<void>
+    remove(subject: string, nodeId: string): Promise<void>
+    lookup(subject: string): Promise<string[]>
+    /** Presence for a specific auth key (anonymous-capable delivery target). */
+    addAuthKey(authKeyId: string, nodeId: string): Promise<void>
+    removeAuthKey(authKeyId: string, nodeId: string): Promise<void>
+    lookupAuthKey(authKeyId: string): Promise<string[]>
+}
+
+/** In-memory presence (single-process / tests). Use a Redis impl across nodes. */
+export class InMemoryPresence implements Presence {
+    // Keyed by a prefixed target string: `u:<subject>` or `a:<authKeyId>`.
+    private map = new Map<string, Set<string>>()
+
+    private addKey(key: string, nodeId: string): void {
+        let set = this.map.get(key)
+        if (!set) {
+            set = new Set()
+            this.map.set(key, set)
+        }
+        set.add(nodeId)
+    }
+    private removeKey(key: string, nodeId: string): void {
+        const set = this.map.get(key)
+        if (!set) return
+        set.delete(nodeId)
+        if (set.size === 0) this.map.delete(key)
+    }
+    private lookupKey(key: string): string[] {
+        const set = this.map.get(key)
+        return set ? [...set] : []
+    }
+
+    async add(subject: string, nodeId: string): Promise<void> {
+        this.addKey(`u:${subject}`, nodeId)
+    }
+    async remove(subject: string, nodeId: string): Promise<void> {
+        this.removeKey(`u:${subject}`, nodeId)
+    }
+    async lookup(subject: string): Promise<string[]> {
+        return this.lookupKey(`u:${subject}`)
+    }
+    async addAuthKey(authKeyId: string, nodeId: string): Promise<void> {
+        this.addKey(`a:${authKeyId}`, nodeId)
+    }
+    async removeAuthKey(authKeyId: string, nodeId: string): Promise<void> {
+        this.removeKey(`a:${authKeyId}`, nodeId)
+    }
+    async lookupAuthKey(authKeyId: string): Promise<string[]> {
+        return this.lookupKey(`a:${authKeyId}`)
+    }
+}

package/src/updates/push.ts

@@ -0,0 +1,90 @@
+import {
+    fromJson,
+    MigrationRegistry,
+    noopLogger,
+    type JsonValue,
+    type Logger,
+    type TlObject,
+} from '@mt-tl/tl'
+import type { Connection } from '../transport/connection.js'
+import type { ConnectionRegistry } from '../transport/connection-registry.js'
+import type { Responder } from '../dispatch/types.js'
+import type { LayeredRegistry } from '../tl/layered-registry.js'
+import { renderUpdateForLayer } from './render.js'
+
+/**
+ * Node-side delivery of a routed update to the user's local connections, as an
+ * encrypted server notification (msg_id % 4 == 3). Best-effort: if the user has
+ * no local connection, the update is dropped (the client recovers via pts).
+ *
+ * Each connection is rendered for its own negotiated layer: types not
+ * representable there become `updateUnsupported` (pts-bearing) or are dropped.
+ */
+export class PushService {
+    private readonly migrations: MigrationRegistry
+    private readonly log: Logger
+
+    constructor(
+        private readonly registry: ConnectionRegistry,
+        private readonly responder: Responder,
+        private readonly layered?: LayeredRegistry,
+        migrations?: MigrationRegistry,
+        logger?: Logger,
+    ) {
+        this.migrations = migrations ?? new MigrationRegistry()
+        this.log = logger ?? noopLogger
+    }
+
+    deliver(subject: string, update: JsonValue): void {
+        this.deliverTo(this.registry.getBySubject(subject), update, { subject })
+    }
+
+    /** Deliver to the connections of a specific auth key (anonymous-capable target). */
+    deliverToAuthKey(authKeyId: string, update: JsonValue): void {
+        this.deliverTo(this.registry.getByAuthKey(authKeyId), update, { authKeyId })
+    }
+
+    private deliverTo(
+        conns: Connection[],
+        update: JsonValue,
+        target: { subject?: string; authKeyId?: string },
+    ): void {
+        const tl = fromJson(update)
+        if (!tl || typeof tl !== 'object' || Array.isArray(tl) || !('_' in tl)) return
+        const base = tl as TlObject
+        const type = base._
+
+        // Full update payload at debug — "what we're pushing out" (the canonical
+        // form, before per-connection layer rendering).
+        this.log.debug('update.data', { ...target, type, update })
+
+        // No local connection for the target — best-effort drop (the client recovers
+        // via pts on its next getDifference). Expected, so debug not error.
+        if (conns.length === 0) {
+            this.log.debug('update.nodest', { ...target, type })
+            return
+        }
+
+        let delivered = 0
+        for (const conn of conns) {
+            // The client opted out of updates on this connection (invokeWithoutUpdates).
+            if (conn.ctx.noUpdates) continue
+            // Render canonical → client layer (non-additive), then per-layer representability.
+            let body: TlObject | null = this.migrations.down(base, conn.ctx.apiLayer) as TlObject
+            if (this.layered?.hasLayers()) {
+                body = renderUpdateForLayer(body, conn.ctx.apiLayer, this.layered)
+            }
+            if (!body) {
+                this.log.debug('update.skip', { ...target, type, conn: conn.id, layer: conn.ctx.apiLayer })
+                continue
+            }
+            try {
+                this.responder.sendEncrypted(conn, body, { isNotification: true, contentRelated: false })
+                delivered++
+            } catch (err) {
+                this.log.error('update.fail', { ...target, type, conn: conn.id, err })
+            }
+        }
+        if (delivered) this.log.info('update.push', { ...target, type, conns: delivered })
+    }
+}

package/src/updates/redis-bus.ts

@@ -0,0 +1,86 @@
+import type { NodeDelivery, UpdateMessage } from './types.js'
+import type { UpdateBus } from './update-bus.js'
+
+/**
+ * Minimal Redis surfaces (for testability). Pub/sub needs TWO connections: a
+ * connection in subscriber mode cannot issue regular commands, so publishing and
+ * subscribing use separate clients.
+ */
+export interface RedisPubLike {
+    publish(channel: string, message: string): Promise<unknown> | unknown
+    quit(): Promise<unknown>
+}
+export interface RedisSubLike {
+    subscribe(channel: string): Promise<unknown> | unknown
+    on(event: 'message', listener: (channel: string, message: string) => void): unknown
+    quit(): Promise<unknown>
+}
+
+const CH_IN = 'updates.in'
+const nodeChannel = (nodeId: string) => `updates.node.${nodeId}`
+
+/**
+ * Redis pub/sub {@link UpdateBus} for multi-instance server-push (infra stays
+ * Mongo + Redis). `updates.in` carries emitted updates to the router;
+ * `updates.node.{id}` carries routed deliveries to a node.
+ *
+ * Caveat: Redis pub/sub is **fan-out**, not a work queue. Per-node channels are
+ * fine (one subscriber per nodeId). But `updates.in` is delivered to *every*
+ * subscriber — run a SINGLE router with this bus (enough for the in-process-first
+ * model), or shard `updates.in` by subject across routers. For competing-consumer
+ * semantics at very large scale, switch the bus to Redis Streams.
+ */
+export class RedisUpdateBus implements UpdateBus {
+    private readonly handlers = new Map<string, (msg: unknown) => void>()
+
+    constructor(
+        private readonly pub: RedisPubLike,
+        private readonly sub: RedisSubLike,
+    ) {
+        this.sub.on('message', (channel, message) => {
+            const handler = this.handlers.get(channel)
+            if (!handler) return
+            try {
+                handler(JSON.parse(message))
+            } catch {
+                /* drop malformed */
+            }
+        })
+    }
+
+    async publishUpdate(msg: UpdateMessage): Promise<void> {
+        await this.pub.publish(CH_IN, JSON.stringify(msg))
+    }
+
+    subscribeUpdates(handler: (msg: UpdateMessage) => void): void {
+        this.handlers.set(CH_IN, handler as (msg: unknown) => void)
+        void this.sub.subscribe(CH_IN)
+    }
+
+    async publishToNode(nodeId: string, msg: NodeDelivery): Promise<void> {
+        await this.pub.publish(nodeChannel(nodeId), JSON.stringify(msg))
+    }
+
+    subscribeNode(nodeId: string, handler: (msg: NodeDelivery) => void): void {
+        this.handlers.set(nodeChannel(nodeId), handler as (msg: unknown) => void)
+        void this.sub.subscribe(nodeChannel(nodeId))
+    }
+
+    async close(): Promise<void> {
+        await Promise.all([this.pub.quit().catch(() => {}), this.sub.quit().catch(() => {})])
+    }
+}
+
+export interface RedisBusHandle {
+    bus: RedisUpdateBus
+    close: () => Promise<void>
+}
+
+/** Connects two Redis clients (publish + subscribe) and builds a {@link RedisUpdateBus}. */
+export async function createRedisUpdateBus(url: string): Promise<RedisBusHandle> {
+    const IoRedis = (await import('ioredis')).default
+    const pub = new IoRedis(url, { lazyConnect: false })
+    const sub = new IoRedis(url, { lazyConnect: false })
+    const bus = new RedisUpdateBus(pub, sub)
+    return { bus, close: () => bus.close() }
+}

package/src/updates/redis-presence.ts

@@ -0,0 +1,87 @@
+import Redis from 'ioredis'
+import type { Presence } from './presence.js'
+
+/** Minimal subset of ioredis used by {@link RedisPresence} (for testability). */
+export interface RedisLike {
+    zadd(key: string, score: number, member: string): Promise<unknown>
+    zrem(key: string, member: string): Promise<unknown>
+    zrangebyscore(key: string, min: number | string, max: number | string): Promise<string[]>
+    zremrangebyscore(key: string, min: number | string, max: number | string): Promise<unknown>
+    pexpire(key: string, ms: number): Promise<unknown>
+}
+
+export interface RedisPresenceOptions {
+    ttlMs?: number
+    now?: () => number
+}
+
+/**
+ * Redis-backed presence using a per-subject sorted set `presence:{subject}` with
+ * member = nodeId and score = expiry epoch (now + ttl). This gives per-member
+ * TTL: a node's entry is considered live while its score is in the future and
+ * is refreshed by a heartbeat; stale entries are pruned on lookup. Eventually
+ * consistent by design (a crashed node's entry just expires).
+ */
+export class RedisPresence implements Presence {
+    constructor(
+        private readonly redis: RedisLike,
+        private readonly opts: RedisPresenceOptions = {},
+    ) {}
+
+    private ttl(): number {
+        return this.opts.ttlMs ?? 60_000
+    }
+    private now(): number {
+        return (this.opts.now ?? Date.now)()
+    }
+    private key(subject: string): string {
+        return `presence:${subject}`
+    }
+    private authKey(authKeyId: string): string {
+        return `presence:a:${authKeyId}`
+    }
+
+    private async addKey(key: string, nodeId: string): Promise<void> {
+        await this.redis.zadd(key, this.now() + this.ttl(), nodeId)
+        await this.redis.pexpire(key, this.ttl() * 2)
+    }
+    private async lookupKey(key: string): Promise<string[]> {
+        const now = this.now()
+        await this.redis.zremrangebyscore(key, 0, now) // drop expired members
+        return this.redis.zrangebyscore(key, now, '+inf') // live members
+    }
+
+    async add(subject: string, nodeId: string): Promise<void> {
+        await this.addKey(this.key(subject), nodeId)
+    }
+    async remove(subject: string, nodeId: string): Promise<void> {
+        await this.redis.zrem(this.key(subject), nodeId)
+    }
+    async lookup(subject: string): Promise<string[]> {
+        return this.lookupKey(this.key(subject))
+    }
+    async addAuthKey(authKeyId: string, nodeId: string): Promise<void> {
+        await this.addKey(this.authKey(authKeyId), nodeId)
+    }
+    async removeAuthKey(authKeyId: string, nodeId: string): Promise<void> {
+        await this.redis.zrem(this.authKey(authKeyId), nodeId)
+    }
+    async lookupAuthKey(authKeyId: string): Promise<string[]> {
+        return this.lookupKey(this.authKey(authKeyId))
+    }
+}
+
+export interface RedisPresenceHandle {
+    presence: RedisPresence
+    close: () => Promise<void>
+}
+
+export function createRedisPresence(url: string, ttlMs: number): RedisPresenceHandle {
+    const client = new Redis(url, { lazyConnect: false })
+    return {
+        presence: new RedisPresence(client, { ttlMs }),
+        close: async () => {
+            await client.quit()
+        },
+    }
+}

package/src/updates/render.ts

@@ -0,0 +1,53 @@
+import type { LayeredRegistry } from '../tl/layered-registry.js'
+import type { TlObject } from '@mt-tl/tl'
+
+/**
+ * Renders a server update for a specific client layer.
+ *
+ * - Representable at the layer → unchanged.
+ * - Not representable but pts-bearing → `updateUnsupported{pts, pts_count}`
+ *   (preserves the pts accounting so the client resyncs via getDifference).
+ * - Not representable and ephemeral (no pts) → dropped (returns null).
+ *
+ * Recurses into the common containers (`updateShort`, `updates`,
+ * `updatesCombined`) so a single unrepresentable inner update doesn't sink the
+ * whole batch.
+ */
+export function renderUpdateForLayer(
+    update: TlObject,
+    layer: number,
+    layered: LayeredRegistry,
+): TlObject | null {
+    if (layered.representable(update, layer)) return update
+
+    switch (update._) {
+        case 'updateShort': {
+            const inner = renderLeaf(update.update as TlObject, layer, layered)
+            return inner ? { ...update, update: inner } : null
+        }
+        case 'updates':
+        case 'updatesCombined': {
+            const list = Array.isArray(update.updates) ? (update.updates as TlObject[]) : []
+            const rendered = list
+                .map(u => renderLeaf(u, layer, layered))
+                .filter((u): u is TlObject => u !== null)
+            return { ...update, updates: rendered }
+        }
+        default:
+            return renderLeaf(update, layer, layered)
+    }
+}
+
+function renderLeaf(update: TlObject, layer: number, layered: LayeredRegistry): TlObject | null {
+    if (layered.representable(update, layer)) return update
+    const pts = numberField(update, 'pts')
+    if (pts !== undefined) {
+        return { _: 'updateUnsupported', pts, pts_count: numberField(update, 'pts_count') ?? 0 }
+    }
+    return null // ephemeral, no pts — safe to drop
+}
+
+function numberField(obj: TlObject, key: string): number | undefined {
+    const v = obj[key]
+    return typeof v === 'number' ? v : undefined
+}

package/src/updates/router.ts

@@ -0,0 +1,52 @@
+import type { JsonValue } from '@mt-tl/tl'
+import type { Presence } from './presence.js'
+import type { UpdateBus } from './update-bus.js'
+import type { UpdateMessage } from './types.js'
+
+export interface RouterOptions {
+    /**
+     * Anti-DDoS valve: return false to drop/coalesce an update under load.
+     * Safe to drop — clients recover via pts/getDifference. Default: deliver all.
+     */
+    shouldDeliver?: (subject: string, update: JsonValue) => boolean
+    onError?: (err: unknown, msg: UpdateMessage) => void
+}
+
+/**
+ * Presence-aware Update Router (standalone service, shard by subject in prod).
+ * Consumes worker updates, looks up which nodes hold the subject, and delivers
+ * only to those nodes — so 8 idle nodes never receive an update for a subject on
+ * node 1. This is the single place to throttle/coalesce per subject.
+ */
+export class UpdateRouter {
+    constructor(
+        private readonly bus: UpdateBus,
+        private readonly presence: Presence,
+        private readonly opts: RouterOptions = {},
+    ) {}
+
+    start(): void {
+        this.bus.subscribeUpdates(msg => {
+            void this.route(msg).catch(err => this.opts.onError?.(err, msg))
+        })
+    }
+
+    private async route(msg: UpdateMessage): Promise<void> {
+        // Auth-key-addressed delivery (anonymous connection); skips the per-user valve.
+        if (msg.authKeyId !== undefined) {
+            const nodes = await this.presence.lookupAuthKey(msg.authKeyId)
+            await Promise.all(
+                nodes.map(nodeId =>
+                    this.bus.publishToNode(nodeId, { authKeyId: msg.authKeyId, update: msg.update }),
+                ),
+            )
+            return
+        }
+        if (msg.subject === undefined) return
+        if (this.opts.shouldDeliver && !this.opts.shouldDeliver(msg.subject, msg.update)) return
+        const nodes = await this.presence.lookup(msg.subject)
+        await Promise.all(
+            nodes.map(nodeId => this.bus.publishToNode(nodeId, { subject: msg.subject, update: msg.update })),
+        )
+    }
+}

package/src/updates/types.ts

@@ -0,0 +1,24 @@
+import type { JsonValue } from '@mt-tl/tl'
+
+/**
+ * An update to deliver, addressed to exactly one target: a bound `subject` (the
+ * common case, pts-logged) OR an `authKeyId` (a specific, possibly anonymous,
+ * connection — e.g. pushing API to a not-yet-registered client; no pts). Set one.
+ */
+export interface UpdateMessage {
+    /** The subject (internal user id) to deliver to. */
+    subject?: string
+    /** Decimal auth-key id, to address a specific (possibly anonymous) connection. */
+    authKeyId?: string
+    /** A TL update object as tagged JSON ({ _: name, ... }). */
+    update: JsonValue
+    /** Permanent-update sequence number (for getDifference recovery); opaque here. */
+    pts?: number
+}
+
+/** A routed delivery from the Update Router to a specific gateway node. */
+export interface NodeDelivery {
+    subject?: string
+    authKeyId?: string
+    update: JsonValue
+}

package/src/updates/update-bus.ts

@@ -0,0 +1,49 @@
+import { EventEmitter } from 'node:events'
+import type { NodeDelivery, UpdateMessage } from './types.js'
+
+/**
+ * Message bus connecting publishers -> Update Router -> server nodes. Two impls:
+ * an in-memory one (single process) and a Redis pub/sub one (multi-instance:
+ * an `updates.in` channel for emissions and per-node `updates.node.{id}` channels
+ * for routed deliveries).
+ */
+export interface UpdateBus {
+    /** Publisher side: emit an update for a user. Fire-and-forget. */
+    publishUpdate(msg: UpdateMessage): Promise<void>
+    /** Router side: receive all emitted updates. */
+    subscribeUpdates(handler: (msg: UpdateMessage) => void): void
+    /** Router side: deliver a routed update to a specific node. */
+    publishToNode(nodeId: string, msg: NodeDelivery): Promise<void>
+    /** Node side: receive deliveries addressed to this node. */
+    subscribeNode(nodeId: string, handler: (msg: NodeDelivery) => void): void
+    close(): Promise<void>
+}
+
+/** In-memory bus (single process / tests). */
+export class InMemoryUpdateBus implements UpdateBus {
+    private emitter = new EventEmitter()
+
+    constructor() {
+        this.emitter.setMaxListeners(0)
+    }
+
+    async publishUpdate(msg: UpdateMessage): Promise<void> {
+        this.emitter.emit('update', msg)
+    }
+
+    subscribeUpdates(handler: (msg: UpdateMessage) => void): void {
+        this.emitter.on('update', handler)
+    }
+
+    async publishToNode(nodeId: string, msg: NodeDelivery): Promise<void> {
+        this.emitter.emit(`node:${nodeId}`, msg)
+    }
+
+    subscribeNode(nodeId: string, handler: (msg: NodeDelivery) => void): void {
+        this.emitter.on(`node:${nodeId}`, handler)
+    }
+
+    async close(): Promise<void> {
+        this.emitter.removeAllListeners()
+    }
+}