cursedbelt-server 1.0.0

package/dist/server/sync/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The wire and store types every consumer of this sync engine shares. The op
+ * envelope is the notes shape — `(origin, originSeq)` gives exactly-once application
+ * with no coordination — and the report is vault's cursor discipline (the reader may
+ * advance exactly to `cursor`, never further) merged with notes' `seen` (a duplicate
+ * is not an error, it is proof the dedupe ledger works).
+ *
+ * ── 🔴 "sync-kit" is a PAST NAME. The engine is `cursedbelt-server/sync` ────────────
+ * The retired generation published this as `@satellites/sync-kit`. It came across
+ * whole into `apps/vault/src/kit/sync/` when that app graduated, and came here —
+ * `cursedbelt-server/sync` — on 2026-09-15, before `apps/station` could graduate and fork
+ * it a second time. That is the move this header used to call an open question in
+ * `tasks/`; it is done, and the app-local copies are what is temporary now.
+ *
+ * `@satellites/sync-kit` is NOT installable and never was — it was never published
+ * to npm — and its design plan (`plans/01-sync-kit-adoption-design.md`) belonged to
+ * the retired monorepo and did not come across. Comments in consuming apps still say
+ * "the sync-kit adoption": that is the NAME OF AN EVENT, the 2026-08 change that
+ * moved vault from its own `oplog` table onto this engine's `sync_ops`, and it is
+ * worth keeping because the dual-compat code only makes sense in its light.
+ */
+/** One durable mutation in the shared op log. `payload` is app-defined per `kind`. */
+export interface SyncOp {
+    /** This instance's monotonic sequence for the op (assigned by the local log). */
+    seq: number;
+    /** The instance id that BORN the op (stable per instance, never per device). */
+    origin: string;
+    /** The origin's own monotonic counter — `(origin, originSeq)` is the identity. */
+    originSeq: number;
+    /** Wall-clock ms when the op was born. LWW inputs, display, nothing structural. */
+    ts: number;
+    /** App-defined kind, e.g. `doc.set`. The version-negotiation unit. */
+    kind: string;
+    payload: unknown;
+}
+/** What applying one batch did. `cursor` is the last seq FULLY applied — a stopped
+ *  batch leaves it just before the failure so the next run resumes there. */
+export interface ApplyReport {
+    /** Ops that changed local state. */
+    applied: number;
+    /** Ops already held (dedupe hit) — counted, never re-applied. */
+    seen: number;
+    /** Concurrent edits reconciled (however the app's applier chose to). */
+    conflicts: number;
+    cursor: number;
+    /** Non-null when the batch stopped early (version skew, deferred ordering…). */
+    error: string | null;
+}
+/** The peer info handshake. `opKinds` is the compatibility advertisement — a dialer
+ *  stops BEFORE the first op a peer cannot take (notes' version-skew lesson: sending
+ *  it wedges the push with an error that reads like corruption). */
+export interface PeerInfo {
+    instanceId: string;
+    head: number;
+    opKinds: string[];
+}
+/** The transport seam. Pure interface so tests drive the engine against a REAL second
+ *  store mounted in a Hono app — no HTTP mocks (the notes/vault discipline). */
+export interface RemoteApi {
+    info(): Promise<PeerInfo>;
+    pull(after: number, excludeOrigin: string): Promise<{
+        ops: SyncOp[];
+        cursor: number;
+        head: number;
+    }>;
+    push(payload: {
+        ops: SyncOp[];
+        peerHas: number;
+    }): Promise<ApplyReport>;
+    /** The receiver's "someone pressed Sync now here" stamp; null when unsupported. */
+    requestedAt?(): Promise<number | null>;
+}
+/** Context the applier gets per batch — vault's concurrency bound. */
+export interface ApplyContext {
+    /** The peer's stable instance id. */
+    peerId: string;
+    /** Max LOCAL-born seq the peer already holds of OURS — an entity whose newest
+     *  local op is beyond this AND diverges is a true concurrent edit. */
+    peerReceivedUpTo: number;
+}
+/** The app's merge logic for ONE op that passed the dedupe ledger. Return value:
+ *  - `"applied"`   — state changed
+ *  - `"ignored"`   — stale/no-op (still recorded in the ledger, cursor advances)
+ *  - `"conflict"`  — applied with a materialized conflict artifact
+ *  Throw {@link StopBatch} to stop BEFORE this op (cursor stays short of it). */
+export type ApplyOne = (op: SyncOp, ctx: ApplyContext) => "applied" | "ignored" | "conflict";
+/** Stop the current batch before the offending op — deferred ordering, a payload this
+ *  build cannot hold yet, anything where "retry after the world changes" is right. */
+export declare class StopBatch extends Error {
+    constructor(reason: string);
+}
+export interface SyncSummary {
+    remoteId: string;
+    pushed: number;
+    pulled: number;
+    conflicts: number;
+    /** Ops the export policy held back (counted, never sent). */
+    held: number;
+    /** Set when the remote runs an older schema and cannot take what comes next. */
+    blockedBy?: string;
+}

package/dist/server/sync/types.js

@@ -0,0 +1,29 @@
+/**
+ * The wire and store types every consumer of this sync engine shares. The op
+ * envelope is the notes shape — `(origin, originSeq)` gives exactly-once application
+ * with no coordination — and the report is vault's cursor discipline (the reader may
+ * advance exactly to `cursor`, never further) merged with notes' `seen` (a duplicate
+ * is not an error, it is proof the dedupe ledger works).
+ *
+ * ── 🔴 "sync-kit" is a PAST NAME. The engine is `cursedbelt-server/sync` ────────────
+ * The retired generation published this as `@satellites/sync-kit`. It came across
+ * whole into `apps/vault/src/kit/sync/` when that app graduated, and came here —
+ * `cursedbelt-server/sync` — on 2026-09-15, before `apps/station` could graduate and fork
+ * it a second time. That is the move this header used to call an open question in
+ * `tasks/`; it is done, and the app-local copies are what is temporary now.
+ *
+ * `@satellites/sync-kit` is NOT installable and never was — it was never published
+ * to npm — and its design plan (`plans/01-sync-kit-adoption-design.md`) belonged to
+ * the retired monorepo and did not come across. Comments in consuming apps still say
+ * "the sync-kit adoption": that is the NAME OF AN EVENT, the 2026-08 change that
+ * moved vault from its own `oplog` table onto this engine's `sync_ops`, and it is
+ * worth keeping because the dual-compat code only makes sense in its light.
+ */
+/** Stop the current batch before the offending op — deferred ordering, a payload this
+ *  build cannot hold yet, anything where "retry after the world changes" is right. */
+export class StopBatch extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = "StopBatch";
+    }
+}

package/dist/server/ws/eventBus.d.ts

@@ -0,0 +1,14 @@
+import type { EventBus } from './types';
+/**
+ * The push-only subset ru uses: broadcast-to-all, no auth, no inbound routing. ru
+ * mounts one bus and pushes from its task queue / caSync / Forge workers
+ * (`bus.broadcast('taskq-update', { … })`). Same Bun-native upgrade as the hub, minus
+ * the channel registry, presence, and heartbeat.
+ *
+ * @example
+ * const bus = createEventBus();
+ * app.get('/events', bus.upgradeHandler);
+ * serveBun(app, { port, websocket: bus.handlers });
+ * bus.broadcast('taskq-update', { running: 3 });
+ */
+export declare function createEventBus(): EventBus;

package/dist/server/ws/eventBus.js

@@ -0,0 +1,42 @@
+/**
+ * The push-only subset ru uses: broadcast-to-all, no auth, no inbound routing. ru
+ * mounts one bus and pushes from its task queue / caSync / Forge workers
+ * (`bus.broadcast('taskq-update', { … })`). Same Bun-native upgrade as the hub, minus
+ * the channel registry, presence, and heartbeat.
+ *
+ * @example
+ * const bus = createEventBus();
+ * app.get('/events', bus.upgradeHandler);
+ * serveBun(app, { port, websocket: bus.handlers });
+ * bus.broadcast('taskq-update', { running: 3 });
+ */
+export function createEventBus() {
+    const sockets = new Set();
+    const upgradeHandler = async (c) => {
+        const server = c.env;
+        const upgraded = server.upgrade(c.req.raw, { data: {} });
+        if (!upgraded)
+            return c.text('Upgrade required', 426);
+        return c.body(null, 204);
+    };
+    return {
+        upgradeHandler,
+        handlers: {
+            open(ws) {
+                sockets.add(ws);
+            },
+            // Push-only: inbound frames are intentionally ignored. (Bun requires a `message`
+            // handler, so this is a documented no-op rather than an omitted key.)
+            message() { },
+            close(ws) {
+                sockets.delete(ws);
+            },
+        },
+        broadcast(event, data) {
+            const payload = JSON.stringify({ event, data });
+            for (const ws of sockets)
+                ws.send(payload);
+        },
+        clientCount: () => sockets.size,
+    };
+}

package/dist/server/ws/hub.d.ts

@@ -0,0 +1,20 @@
+import type { WsChannel, WsClient, WsHub, WsHubOpts } from './types';
+/**
+ * The heartbeat sweep, factored out as a pure function so it's testable without faking
+ * timers: ping every live client, close (don't delete — let the `close` handler fire
+ * `onDisconnect` + remove) any unheard-from past `staleMs`. The hub's `setInterval`
+ * calls this with `Date.now()`.
+ */
+export declare function sweepStaleClients(clients: Iterable<WsClient>, now: number, staleMs: number): void;
+/**
+ * Build a typed WebSocket hub on Bun's native upgrade. The hub owns the transport —
+ * connection registry, channel routing, heartbeat/stale-cull, and presence-as-a-view;
+ * the registered {@link WsChannel}s own the business logic. Mount {@link WsHub.upgradeHandler}
+ * on the Hono upgrade route(s) and hand {@link WsHub.handlers} to `serveBun`'s `websocket`.
+ *
+ * @example
+ * const hub = createWsHub({ channels: wsChannels, authenticate });
+ * app.get('/ws/:channel', hub.upgradeHandler);
+ * serveBun(app, { port, websocket: hub.handlers });
+ */
+export declare function createWsHub<T extends Record<string, WsChannel<any>>>(opts: WsHubOpts<T>): WsHub;

package/dist/server/ws/hub.js

@@ -0,0 +1,154 @@
+import { ApiError, toErrorEnvelope } from '../errors';
+import { computePresence } from './presence';
+import { joinRoom, ROOM_META_KEY } from './room';
+const DEFAULT_HEARTBEAT_MS = 30_000;
+const DEFAULT_STALE_MS = 120_000;
+/** Bun's `idleTimeout` ceiling (seconds). */
+const BUN_IDLE_TIMEOUT_MAX_S = 960;
+/** Serialize the wire envelope once per fan-out. */
+const encode = (event, data) => JSON.stringify({ event, data });
+/**
+ * The heartbeat sweep, factored out as a pure function so it's testable without faking
+ * timers: ping every live client, close (don't delete — let the `close` handler fire
+ * `onDisconnect` + remove) any unheard-from past `staleMs`. The hub's `setInterval`
+ * calls this with `Date.now()`.
+ */
+export function sweepStaleClients(clients, now, staleMs) {
+    for (const client of clients) {
+        if (now - client.lastPingAt > staleMs) {
+            client.ws.close(1001, 'stale');
+        }
+        else {
+            client.ws.ping();
+        }
+    }
+}
+/**
+ * Build a typed WebSocket hub on Bun's native upgrade. The hub owns the transport —
+ * connection registry, channel routing, heartbeat/stale-cull, and presence-as-a-view;
+ * the registered {@link WsChannel}s own the business logic. Mount {@link WsHub.upgradeHandler}
+ * on the Hono upgrade route(s) and hand {@link WsHub.handlers} to `serveBun`'s `websocket`.
+ *
+ * @example
+ * const hub = createWsHub({ channels: wsChannels, authenticate });
+ * app.get('/ws/:channel', hub.upgradeHandler);
+ * serveBun(app, { port, websocket: hub.handlers });
+ */
+export function createWsHub(opts) {
+    const clients = new Map();
+    const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+    const heartbeatMs = opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+    const channelOf = (name) => opts.channels[name];
+    const clientFromWs = (ws) => clients.get(ws.data.clientId);
+    // Our heartbeat is authoritative (it also drives presence), so disable Bun's auto-ping
+    // and let its idle timeout backstop just beyond our stale window.
+    const idleTimeout = Math.min(Math.ceil(staleMs / 1000), BUN_IDLE_TIMEOUT_MAX_S);
+    const heartbeat = setInterval(() => {
+        sweepStaleClients(clients.values(), Date.now(), staleMs);
+    }, heartbeatMs);
+    // Don't keep the process alive for the heartbeat alone (server tests, graceful exit).
+    heartbeat.unref?.();
+    const upgradeHandler = async (c) => {
+        const channel = c.req.param('channel') ?? c.req.query('channel') ?? 'default';
+        const room = c.req.query('room') ?? undefined;
+        const handshake = { headers: c.req.raw.headers, url: c.req.url, channel, room };
+        let user;
+        try {
+            user = await opts.authenticate(handshake);
+        }
+        catch {
+            user = null;
+        }
+        if (!user)
+            return c.json(toErrorEnvelope(new ApiError(401, 'Unauthorized')), 401);
+        const data = { clientId: crypto.randomUUID(), user, channel, room };
+        const server = c.env;
+        const upgraded = server.upgrade(c.req.raw, { data });
+        if (!upgraded)
+            return c.text('Upgrade required', 426);
+        // Bun has taken over the socket and sent the 101; this Response is discarded by
+        // Bun.serve. (A real 101 can't be constructed — the Fetch Response ctor forbids 1xx.)
+        return c.body(null, 204);
+    };
+    const hub = {
+        upgradeHandler,
+        handlers: {
+            idleTimeout,
+            sendPings: false,
+            open(ws) {
+                const { clientId, user, channel, room } = ws.data;
+                const now = Date.now();
+                const client = {
+                    id: clientId,
+                    user,
+                    ws,
+                    channel,
+                    connectedAt: now,
+                    lastPingAt: now,
+                    meta: {},
+                };
+                if (room)
+                    joinRoom(client, room);
+                clients.set(clientId, client);
+                channelOf(channel)?.onConnect?.(client, hub);
+            },
+            message(ws, raw) {
+                const client = clientFromWs(ws);
+                if (!client)
+                    return;
+                client.lastPingAt = Date.now();
+                let msg;
+                try {
+                    msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString());
+                }
+                catch {
+                    return; // ignore malformed frames rather than crash the socket
+                }
+                channelOf(client.channel)?.onMessage(client, msg, hub);
+            },
+            // A pong (reply to our heartbeat ping) proves liveness without an app message.
+            pong(ws) {
+                const client = clientFromWs(ws);
+                if (client)
+                    client.lastPingAt = Date.now();
+            },
+            close(ws) {
+                const client = clientFromWs(ws);
+                if (!client)
+                    return;
+                channelOf(client.channel)?.onDisconnect?.(client, hub);
+                clients.delete(client.id);
+            },
+        },
+        broadcast(channel, event, data) {
+            const payload = encode(event, data);
+            for (const client of clients.values()) {
+                if (client.channel === channel)
+                    client.ws.send(payload);
+            }
+        },
+        broadcastToRoom(channel, roomId, event, data) {
+            const payload = encode(event, data);
+            for (const client of clients.values()) {
+                if (client.channel === channel && client.meta[ROOM_META_KEY] === roomId) {
+                    client.ws.send(payload);
+                }
+            }
+        },
+        send(clientId, event, data) {
+            clients.get(clientId)?.ws.send(encode(event, data));
+        },
+        getClients(channel) {
+            const all = [...clients.values()];
+            return channel ? all.filter((client) => client.channel === channel) : all;
+        },
+        getClient: (id) => clients.get(id),
+        getPresence(channel) {
+            return computePresence(clients.values(), channel, channelOf(channel)?.presence ?? false);
+        },
+        close() {
+            clearInterval(heartbeat);
+        },
+    };
+    return hub;
+}

package/dist/server/ws/index.d.ts

@@ -0,0 +1,5 @@
+export { createEventBus } from './eventBus';
+export { createWsHub } from './hub';
+export { computePresence } from './presence';
+export { joinRoom, leaveRoom, ROOM_META_KEY, roomOf } from './room';
+export type { EventBus, EventBusData, PresenceEntry, PresenceState, WsChannel, WsClient, WsData, WsHandshake, WsHub, WsHubOpts, WsMessage, } from './types';

package/dist/server/ws/index.js

@@ -0,0 +1,7 @@
+// cursedbelt-server WS hub — Bun-native upgrade, typed channel registry, heartbeat,
+// presence-as-a-view, and the push-only event-bus subset. Pairs with the partysocket
+// client in `cursedbelt/client`.
+export { createEventBus } from './eventBus';
+export { createWsHub } from './hub';
+export { computePresence } from './presence';
+export { joinRoom, leaveRoom, ROOM_META_KEY, roomOf } from './room';

package/dist/server/ws/presence.d.ts

@@ -0,0 +1,11 @@
+import type { PresenceState, WsClient } from './types';
+/**
+ * Presence is a *view* over the live client map, not a tracked structure — there is no
+ * `PresenceTracker` class to keep in sync. The hub's `getPresence(channel)` delegates
+ * here; a channel that wants to push presence does
+ * `hub.broadcast('chat', 'presence', hub.getPresence('chat'))` from its lifecycle hooks.
+ */
+/** The presence snapshot for `channel`: one `{ userId, connectedAt }` row per live
+ * client on that channel, or empty when the channel doesn't opt into presence.
+ * Pure (no timers, no state) so it's trivially testable. */
+export declare function computePresence(clients: Iterable<WsClient>, channel: string, presenceEnabled: boolean): PresenceState;

package/dist/server/ws/presence.js

@@ -0,0 +1,20 @@
+/**
+ * Presence is a *view* over the live client map, not a tracked structure — there is no
+ * `PresenceTracker` class to keep in sync. The hub's `getPresence(channel)` delegates
+ * here; a channel that wants to push presence does
+ * `hub.broadcast('chat', 'presence', hub.getPresence('chat'))` from its lifecycle hooks.
+ */
+/** The presence snapshot for `channel`: one `{ userId, connectedAt }` row per live
+ * client on that channel, or empty when the channel doesn't opt into presence.
+ * Pure (no timers, no state) so it's trivially testable. */
+export function computePresence(clients, channel, presenceEnabled) {
+    if (!presenceEnabled)
+        return [];
+    const rows = [];
+    for (const client of clients) {
+        if (client.channel === channel) {
+            rows.push({ userId: client.user.id, connectedAt: client.connectedAt });
+        }
+    }
+    return rows;
+}

package/dist/server/ws/room.d.ts

@@ -0,0 +1,17 @@
+import type { WsClient } from './types';
+/**
+ * Rooms are not a separate stateful abstraction — they are a typed convention over
+ * {@link WsClient.meta}. A channel puts a client in a room with {@link joinRoom}; the
+ * hub's `broadcastToRoom` matches on the same key. This replaces the old `wsRoom.ts` /
+ * `reconnectableRoom.ts` classes: the hub owns connections + fan-out, the channel owns
+ * membership + any history buffer.
+ */
+/** The {@link WsClient.meta} key a client's current room id lives under. The hub's
+ * `broadcastToRoom` reads the same key — keep them in lockstep. */
+export declare const ROOM_META_KEY = "roomId";
+/** Put `client` in `roomId` (replaces any current room). */
+export declare function joinRoom(client: WsClient, roomId: string): void;
+/** Remove `client` from its room (a subsequent room broadcast won't reach it). */
+export declare function leaveRoom(client: WsClient): void;
+/** The client's current room id, or undefined if it isn't in one. */
+export declare function roomOf(client: WsClient): string | undefined;

package/dist/server/ws/room.js

@@ -0,0 +1,23 @@
+/**
+ * Rooms are not a separate stateful abstraction — they are a typed convention over
+ * {@link WsClient.meta}. A channel puts a client in a room with {@link joinRoom}; the
+ * hub's `broadcastToRoom` matches on the same key. This replaces the old `wsRoom.ts` /
+ * `reconnectableRoom.ts` classes: the hub owns connections + fan-out, the channel owns
+ * membership + any history buffer.
+ */
+/** The {@link WsClient.meta} key a client's current room id lives under. The hub's
+ * `broadcastToRoom` reads the same key — keep them in lockstep. */
+export const ROOM_META_KEY = 'roomId';
+/** Put `client` in `roomId` (replaces any current room). */
+export function joinRoom(client, roomId) {
+    client.meta[ROOM_META_KEY] = roomId;
+}
+/** Remove `client` from its room (a subsequent room broadcast won't reach it). */
+export function leaveRoom(client) {
+    delete client.meta[ROOM_META_KEY];
+}
+/** The client's current room id, or undefined if it isn't in one. */
+export function roomOf(client) {
+    const room = client.meta[ROOM_META_KEY];
+    return typeof room === 'string' ? room : undefined;
+}

package/dist/server/ws/types.d.ts

@@ -0,0 +1,122 @@
+import type { ServerWebSocket, WebSocketHandler } from 'bun';
+import type { MiddlewareHandler } from 'hono';
+import type { AuthUser } from '../auth/types';
+/**
+ * Shared types for the cursedbelt WebSocket hub.
+ *
+ * cursedbelt owns the *transport* — connection lifecycle, channel routing,
+ * heartbeat/stale-cull, presence-as-a-view, and an injected `authenticate`
+ * callback. The *channels* (what each message means, the per-feature game/chat
+ * state) stay app-business; an app registers its channels into the hub and
+ * consumes the broadcast helpers. ru's push-only variant is {@link EventBus}.
+ *
+ * Built on Bun's native WS upgrade (`Server.upgrade` + `Bun.serve { websocket }`),
+ * surfaced through Hono via {@link WsHub.upgradeHandler}. No `ws`-lib, no adapter.
+ */
+/** The JSON envelope every frame uses, both directions: `{ event, data }`. The hub
+ * emits this from {@link WsHub.broadcast}/`send`; channels receive the parsed inbound
+ * envelope as their `onMessage` payload. `T` narrows `data` for a typed channel. */
+export interface WsMessage<T = unknown> {
+    event: string;
+    data: T;
+}
+/** What the hub stashes on the Bun `ServerWebSocket.data` at upgrade time so `open`
+ * can register the client without a second handshake round-trip (see the gotcha in
+ * the task spec). `room` is the optional `?room=` query param — a named room within
+ * the channel, applied to {@link WsClient.meta} on connect. */
+export interface WsData {
+    clientId: string;
+    user: AuthUser;
+    channel: string;
+    room?: string;
+}
+/** The minimal view of the WS handshake handed to {@link WsHubOpts.authenticate}. The
+ * app reads its auth cookie off `headers` and verifies it (cursedbelt never reads the
+ * cookie itself — auth *model* is app business). */
+export interface WsHandshake {
+    headers: Headers;
+    url: string;
+    channel: string;
+    room?: string;
+}
+/** A live connection. `meta` is the per-channel scratch bag (room membership via the
+ * `room.ts` helpers, game seat, typing flag, …) — the hub never interprets it beyond
+ * {@link WsHub.broadcastToRoom}'s room match. `lastPingAt` is "last time we heard from
+ * this client" (an inbound message OR a pong); the heartbeat culls on it. */
+export interface WsClient {
+    id: string;
+    user: AuthUser;
+    ws: ServerWebSocket<WsData>;
+    channel: string;
+    connectedAt: number;
+    lastPingAt: number;
+    meta: Record<string, unknown>;
+}
+/** A business channel registered into the hub. The hub routes inbound frames to
+ * `onMessage` by {@link WsClient.channel} and fires the lifecycle hooks; everything
+ * the handler *does* (broadcast shape, game state, history) is app business. */
+export interface WsChannel<TMsg = WsMessage> {
+    name: string;
+    /** Fired after the client is registered (room meta already applied). */
+    onConnect?(client: WsClient, hub: WsHub): void;
+    /** Fired once per inbound frame (the parsed `{ event, data }` envelope). */
+    onMessage(client: WsClient, msg: TMsg, hub: WsHub): void;
+    /** Fired when the socket closes (explicit, stale-culled, or peer-dropped). */
+    onDisconnect?(client: WsClient, hub: WsHub): void;
+    /** Whether this channel contributes to {@link WsHub.getPresence}. Default: false. */
+    presence?: boolean;
+}
+/** A presence row — the public, business-safe view of a connected client. */
+export interface PresenceEntry {
+    userId: string;
+    connectedAt: number;
+}
+/** The presence snapshot for a channel: one row per live, presence-enabled client. */
+export type PresenceState = PresenceEntry[];
+export interface WsHubOpts<TChannelMap extends Record<string, WsChannel<any>>> {
+    /** The business channel registry, keyed by channel name (the `?channel=`/`:channel`
+     * the client connects to). */
+    channels: TChannelMap;
+    /** Cookie→user verification for the handshake. Return `null` to reject the upgrade
+     * with a 401 (an HTTP 401, not a WS close). */
+    authenticate(handshake: WsHandshake): Promise<AuthUser | null>;
+    /** How often the heartbeat pings live clients + sweeps stale ones. Default 30_000. */
+    heartbeatIntervalMs?: number;
+    /** A client unheard-from for longer than this is culled. Default 120_000 (2 min). */
+    staleMs?: number;
+}
+export interface WsHub {
+    /** The Bun `websocket` config — pass straight to `serveBun(app, { websocket: hub.handlers })`.
+     * `message` is required by Bun; `open`/`close`/`pong` drive lifecycle + liveness. */
+    handlers: WebSocketHandler<WsData>;
+    /** Mount on the Hono upgrade route(s): `app.get('/ws/:channel', hub.upgradeHandler)`.
+     * Authenticates, then calls `Server.upgrade` (Bun-native). */
+    upgradeHandler: MiddlewareHandler;
+    /** Send `{ event, data }` to every client on `channel`. */
+    broadcast(channel: string, event: string, data: unknown): void;
+    /** Send `{ event, data }` to every client on `channel` whose room (meta) is `roomId`. */
+    broadcastToRoom(channel: string, roomId: string, event: string, data: unknown): void;
+    /** Send `{ event, data }` to one client by id (no-op if gone). */
+    send(clientId: string, event: string, data: unknown): void;
+    /** Live clients, optionally filtered to one channel. */
+    getClients(channel?: string): WsClient[];
+    /** One client by id, or undefined. */
+    getClient(clientId: string): WsClient | undefined;
+    /** The presence snapshot for a presence-enabled channel (empty otherwise). */
+    getPresence(channel: string): PresenceState;
+    /** Stop the heartbeat timer (call on shutdown / in tests to avoid a leaked interval). */
+    close(): void;
+}
+/** ru's push-only subset: broadcast-to-all, no auth, no inbound routing. One bus,
+ * mounted once; ru's task queue / caSync / Forge workers call `broadcast`. */
+export interface EventBus {
+    /** Bun `websocket` config. `message` is a documented no-op (push-only). */
+    handlers: WebSocketHandler<EventBusData>;
+    upgradeHandler: MiddlewareHandler;
+    /** Push `{ event, data }` to every connected client. */
+    broadcast(event: string, data: unknown): void;
+    /** Number of connected clients. */
+    clientCount(): number;
+}
+/** The event bus carries no per-socket data (no auth, no channel). */
+export type EventBusData = Record<never, never>;

package/dist/server/ws/types.js

@@ -0,0 +1 @@
+export {};