cursedbelt-server 1.0.0

package/src/server/sync/types.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 class StopBatch extends Error {
+	constructor(reason: string) {
+		super(reason);
+		this.name = "StopBatch";
+	}
+}
+
+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/src/server/ws/eventBus.spec.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from 'bun:test';
+import type { ServerWebSocket } from 'bun';
+import { Hono } from 'hono';
+import { createEventBus } from './eventBus';
+import type { EventBusData } from './types';
+
+function mockWs() {
+  return {
+    sent: [] as string[],
+    send(p: string) {
+      this.sent.push(p);
+      return p.length;
+    },
+  };
+}
+const asWs = (m: ReturnType<typeof mockWs>) => m as unknown as ServerWebSocket<EventBusData>;
+
+describe('createEventBus', () => {
+  test('broadcasts the { event, data } envelope to every open socket', () => {
+    const bus = createEventBus();
+    const a = mockWs();
+    const b = mockWs();
+    bus.handlers.open?.(asWs(a));
+    bus.handlers.open?.(asWs(b));
+
+    bus.broadcast('update', { n: 1 });
+    expect(a.sent).toEqual(['{"event":"update","data":{"n":1}}']);
+    expect(b.sent).toEqual(['{"event":"update","data":{"n":1}}']);
+  });
+
+  test('clientCount tracks open/close', () => {
+    const bus = createEventBus();
+    const a = mockWs();
+    expect(bus.clientCount()).toBe(0);
+    bus.handlers.open?.(asWs(a));
+    expect(bus.clientCount()).toBe(1);
+    bus.handlers.close?.(asWs(a), 1000, '');
+    expect(bus.clientCount()).toBe(0);
+  });
+
+  test('a closed socket no longer receives broadcasts', () => {
+    const bus = createEventBus();
+    const a = mockWs();
+    bus.handlers.open?.(asWs(a));
+    bus.handlers.close?.(asWs(a), 1000, '');
+    bus.broadcast('x', {});
+    expect(a.sent).toEqual([]);
+  });
+
+  test('inbound frames are ignored (push-only no-op message handler)', () => {
+    const bus = createEventBus();
+    const a = mockWs();
+    bus.handlers.open?.(asWs(a));
+    expect(() => bus.handlers.message(asWs(a), 'whatever')).not.toThrow();
+    expect(a.sent).toEqual([]);
+  });
+
+  test('upgradeHandler returns 426 when the server cannot upgrade', async () => {
+    const bus = createEventBus();
+    const app = new Hono();
+    app.get('/events', bus.upgradeHandler);
+    const res = await app.fetch(new Request('http://localhost/events'), {
+      upgrade: () => false,
+    });
+    expect(res.status).toBe(426);
+  });
+});

package/src/server/ws/eventBus.ts

@@ -0,0 +1,46 @@
+import type { Server, ServerWebSocket } from 'bun';
+import type { MiddlewareHandler } from 'hono';
+import type { EventBus, EventBusData } 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 function createEventBus(): EventBus {
+  const sockets = new Set<ServerWebSocket<EventBusData>>();
+
+  const upgradeHandler: MiddlewareHandler = async (c) => {
+    const server = c.env as unknown as Server<EventBusData>;
+    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/src/server/ws/hub.integration.spec.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { serveBun } from '../app';
+import type { AuthUser } from '../auth/types';
+import { createWsHub } from './hub';
+import type { WsChannel, WsMessage } from './types';
+import type { CursedbeltEnv } from '../context';
+
+const testUser: AuthUser = { id: 'u1', roles: [], getOnly: false, sessionId: 's1' };
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) throw new Error('waitFor timed out');
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+function nextMessage(ws: WebSocket): Promise<WsMessage> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('no message within 2s')), 2000);
+    ws.addEventListener(
+      'message',
+      (e) => {
+        clearTimeout(timer);
+        resolve(JSON.parse(String((e as MessageEvent).data)));
+      },
+      { once: true },
+    );
+  });
+}
+
+describe('createWsHub — integration (real Bun.serve)', () => {
+  test('upgrade → message round-trip → disconnect, with getClients reflecting state', async () => {
+    let connectedId: string | undefined;
+    let disconnected = false;
+    const channel: WsChannel = {
+      name: 'test',
+      presence: true,
+      onConnect(client) {
+        connectedId = client.id;
+      },
+      onMessage(client, msg, hub) {
+        if (msg.event === 'echo') hub.send(client.id, 'echoed', msg.data);
+      },
+      onDisconnect() {
+        disconnected = true;
+      },
+    };
+    const hub = createWsHub({ channels: { test: channel }, authenticate: async () => testUser });
+    const app = new Hono<CursedbeltEnv>();
+    app.get('/ws/:channel', hub.upgradeHandler);
+    const server = serveBun(app, { port: 0, websocket: hub.handlers });
+
+    const ws = new WebSocket(`ws://localhost:${server.port}/ws/test`);
+    try {
+      await new Promise<void>((resolve, reject) => {
+        ws.addEventListener('open', () => resolve(), { once: true });
+        ws.addEventListener('error', () => reject(new Error('ws failed to open')), { once: true });
+      });
+
+      await waitFor(() => hub.getClients('test').length === 1);
+      expect(connectedId).toBeDefined();
+      expect(hub.getPresence('test')).toEqual([expect.objectContaining({ userId: 'u1' })]);
+
+      const reply = nextMessage(ws);
+      ws.send(JSON.stringify({ event: 'echo', data: { msg: 'hi' } }));
+      expect(await reply).toEqual({ event: 'echoed', data: { msg: 'hi' } });
+
+      ws.close();
+      await waitFor(() => disconnected && hub.getClients('test').length === 0);
+    } finally {
+      ws.close();
+      hub.close();
+      server.stop(true);
+    }
+  });
+
+  test('unauthenticated upgrade → HTTP 401 (not a WS close)', async () => {
+    const hub = createWsHub({ channels: {}, authenticate: async () => null });
+    const app = new Hono<CursedbeltEnv>();
+    app.get('/ws/:channel', hub.upgradeHandler);
+    const server = serveBun(app, { port: 0, websocket: hub.handlers });
+    try {
+      const res = await fetch(`http://localhost:${server.port}/ws/test`);
+      expect(res.status).toBe(401);
+      expect((await res.json()).error.message).toBe('Unauthorized');
+    } finally {
+      hub.close();
+      server.stop(true);
+    }
+  });
+});

package/src/server/ws/hub.spec.ts

@@ -0,0 +1,282 @@
+import { describe, expect, mock, test } from 'bun:test';
+import type { ServerWebSocket } from 'bun';
+import { Hono } from 'hono';
+import type { AuthUser } from '../auth/types';
+import { createWsHub, sweepStaleClients } from './hub';
+import type { WsChannel, WsClient, WsData, WsHub } from './types';
+
+const testUser: AuthUser = { id: 'u1', roles: [], getOnly: false, sessionId: 's1' };
+
+interface MockWs extends ServerWebSocket<WsData> {
+  sent: string[];
+  closedWith?: [number, string];
+  pings: number;
+}
+
+function mockWs(data: WsData): MockWs {
+  const ws = {
+    data,
+    sent: [] as string[],
+    pings: 0,
+    closedWith: undefined as [number, string] | undefined,
+    send(payload: string) {
+      this.sent.push(payload);
+      return payload.length;
+    },
+    close(code?: number, reason?: string) {
+      this.closedWith = [code ?? 1000, reason ?? ''];
+    },
+    ping() {
+      this.pings += 1;
+      return 0;
+    },
+  };
+  return ws as unknown as MockWs;
+}
+
+/** Register a connected mock client through the hub's real `open` handler. */
+function connect(hub: WsHub, data: WsData): MockWs {
+  const ws = mockWs(data);
+  hub.handlers.open?.(ws);
+  return ws;
+}
+
+const data = (over: Partial<WsData> = {}): WsData => ({
+  clientId: crypto.randomUUID(),
+  user: testUser,
+  channel: 'test',
+  ...over,
+});
+
+describe('createWsHub — message routing & lifecycle', () => {
+  test('routes an inbound frame to the channel.onMessage of its channel', () => {
+    const onMessage = mock(() => {});
+    const channel: WsChannel = { name: 'test', onMessage };
+    const hub = createWsHub({ channels: { test: channel }, authenticate: async () => testUser });
+
+    const ws = connect(hub, data({ clientId: 'c1' }));
+    hub.handlers.message(ws, JSON.stringify({ event: 'hello', data: { a: 1 } }));
+
+    expect(onMessage).toHaveBeenCalledTimes(1);
+    expect(onMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'c1', channel: 'test' }),
+      { event: 'hello', data: { a: 1 } },
+      hub,
+    );
+    hub.close();
+  });
+
+  test('fires onConnect on open and onDisconnect on close, removing the client', () => {
+    const onConnect = mock(() => {});
+    const onDisconnect = mock(() => {});
+    const hub = createWsHub({
+      channels: { test: { name: 'test', onMessage: () => {}, onConnect, onDisconnect } },
+      authenticate: async () => testUser,
+    });
+
+    const ws = connect(hub, data({ clientId: 'c1' }));
+    expect(onConnect).toHaveBeenCalledTimes(1);
+    expect(hub.getClient('c1')).toBeDefined();
+
+    hub.handlers.close?.(ws, 1000, 'bye');
+    expect(onDisconnect).toHaveBeenCalledTimes(1);
+    expect(hub.getClient('c1')).toBeUndefined();
+    hub.close();
+  });
+
+  test('ignores a malformed (non-JSON) frame without throwing', () => {
+    const onMessage = mock(() => {});
+    const hub = createWsHub({
+      channels: { test: { name: 'test', onMessage } },
+      authenticate: async () => testUser,
+    });
+    const ws = connect(hub, data());
+    expect(() => hub.handlers.message(ws, 'not json {')).not.toThrow();
+    expect(onMessage).not.toHaveBeenCalled();
+    hub.close();
+  });
+
+  test('a message bumps lastPingAt; a pong does too', () => {
+    const hub = createWsHub({
+      channels: { test: { name: 'test', onMessage: () => {} } },
+      authenticate: async () => testUser,
+    });
+    const ws = connect(hub, data({ clientId: 'c1' }));
+    const before = hub.getClient('c1')?.lastPingAt ?? 0;
+    hub.handlers.pong?.(ws, Buffer.from(''));
+    expect(hub.getClient('c1')?.lastPingAt).toBeGreaterThanOrEqual(before);
+    hub.close();
+  });
+});
+
+describe('createWsHub — broadcast / send / room', () => {
+  const hubWith = () =>
+    createWsHub({
+      channels: {
+        test: { name: 'test', onMessage: () => {} },
+        other: { name: 'other', onMessage: () => {} },
+      },
+      authenticate: async () => testUser,
+    });
+
+  test('broadcast reaches only clients on the channel', () => {
+    const hub = hubWith();
+    const a = connect(hub, data({ clientId: 'a', channel: 'test' }));
+    const b = connect(hub, data({ clientId: 'b', channel: 'test' }));
+    const c = connect(hub, data({ clientId: 'c', channel: 'other' }));
+
+    hub.broadcast('test', 'ping', {});
+    expect(a.sent).toEqual(['{"event":"ping","data":{}}']);
+    expect(b.sent).toEqual(['{"event":"ping","data":{}}']);
+    expect(c.sent).toEqual([]);
+    hub.close();
+  });
+
+  test('broadcastToRoom matches the room applied from the upgrade ?room= data', () => {
+    const hub = hubWith();
+    const a = connect(hub, data({ clientId: 'a', channel: 'test', room: 'r1' }));
+    const b = connect(hub, data({ clientId: 'b', channel: 'test', room: 'r2' }));
+    expect(hub.getClient('a')?.meta.roomId).toBe('r1');
+
+    hub.broadcastToRoom('test', 'r1', 'm', { x: 1 });
+    expect(a.sent).toEqual(['{"event":"m","data":{"x":1}}']);
+    expect(b.sent).toEqual([]);
+    hub.close();
+  });
+
+  test('send targets a single client by id', () => {
+    const hub = hubWith();
+    const a = connect(hub, data({ clientId: 'a' }));
+    const b = connect(hub, data({ clientId: 'b' }));
+    hub.send('a', 'hi', { n: 2 });
+    expect(a.sent).toEqual(['{"event":"hi","data":{"n":2}}']);
+    expect(b.sent).toEqual([]);
+    hub.send('missing', 'x', {}); // no-op, no throw
+    hub.close();
+  });
+
+  test('getClients filters by channel; getPresence honors the presence flag', () => {
+    const hub = createWsHub({
+      channels: {
+        test: { name: 'test', onMessage: () => {}, presence: true },
+        other: { name: 'other', onMessage: () => {} },
+      },
+      authenticate: async () => testUser,
+    });
+    connect(hub, data({ clientId: 'a', channel: 'test', user: { ...testUser, id: 'ua' } }));
+    connect(hub, data({ clientId: 'b', channel: 'other', user: { ...testUser, id: 'ub' } }));
+
+    expect(hub.getClients().length).toBe(2);
+    expect(hub.getClients('test').map((c) => c.id)).toEqual(['a']);
+    expect(hub.getPresence('test')).toEqual([expect.objectContaining({ userId: 'ua' })]);
+    expect(hub.getPresence('other')).toEqual([]); // presence not enabled
+    hub.close();
+  });
+});
+
+describe('createWsHub — upgradeHandler', () => {
+  const fakeServer = (upgradeResult: boolean) => {
+    let captured: { data?: WsData } | undefined;
+    const server = {
+      upgrade(_req: Request, opts: { data?: WsData }) {
+        captured = opts;
+        return upgradeResult;
+      },
+    };
+    return { server, getData: () => captured?.data };
+  };
+
+  test('authenticate → null yields an HTTP 401 envelope (not a WS close), never upgrading', () => {
+    const hub = createWsHub({ channels: {}, authenticate: async () => null });
+    const app = new Hono();
+    app.get('/ws/:channel', hub.upgradeHandler);
+    const { server, getData } = fakeServer(true);
+
+    return Promise.resolve(app.fetch(new Request('http://localhost/ws/test'), server)).then(async (res) => {
+      expect(res.status).toBe(401);
+      expect((await res.json()).error.message).toBe('Unauthorized');
+      expect(getData()).toBeUndefined();
+      hub.close();
+    });
+  });
+
+  test('authenticate throwing is treated as unauthorized (401), not a 500', async () => {
+    const hub = createWsHub({
+      channels: {},
+      authenticate: async () => {
+        throw new Error('boom');
+      },
+    });
+    const app = new Hono();
+    app.get('/ws/:channel', hub.upgradeHandler);
+    const res = await app.fetch(new Request('http://localhost/ws/test'), fakeServer(true).server);
+    expect(res.status).toBe(401);
+    hub.close();
+  });
+
+  test('success: upgrades with { clientId, user, channel, room } and returns a handled response', async () => {
+    const hub = createWsHub({ channels: {}, authenticate: async () => testUser });
+    const app = new Hono();
+    app.get('/ws/:channel', hub.upgradeHandler);
+    const { server, getData } = fakeServer(true);
+
+    const res = await app.fetch(new Request('http://localhost/ws/chat?room=lobby'), server);
+    expect(res.status).toBe(204);
+    const d = getData();
+    expect(d?.channel).toBe('chat');
+    expect(d?.room).toBe('lobby');
+    expect(d?.user).toEqual(testUser);
+    expect(typeof d?.clientId).toBe('string');
+    hub.close();
+  });
+
+  test('channel falls back to ?channel= then "default"', async () => {
+    const hub = createWsHub({ channels: {}, authenticate: async () => testUser });
+    const app = new Hono();
+    app.get('/ws', hub.upgradeHandler);
+    const f1 = fakeServer(true);
+    await app.fetch(new Request('http://localhost/ws?channel=foo'), f1.server);
+    expect(f1.getData()?.channel).toBe('foo');
+
+    const f2 = fakeServer(true);
+    await app.fetch(new Request('http://localhost/ws'), f2.server);
+    expect(f2.getData()?.channel).toBe('default');
+    hub.close();
+  });
+
+  test('a failed upgrade returns 426', async () => {
+    const hub = createWsHub({ channels: {}, authenticate: async () => testUser });
+    const app = new Hono();
+    app.get('/ws/:channel', hub.upgradeHandler);
+    const res = await app.fetch(new Request('http://localhost/ws/test'), fakeServer(false).server);
+    expect(res.status).toBe(426);
+    hub.close();
+  });
+});
+
+describe('sweepStaleClients (heartbeat)', () => {
+  const client = (lastPingAt: number): WsClient & { ws: MockWs } => {
+    const ws = mockWs(data());
+    return {
+      id: 'x',
+      user: testUser,
+      ws,
+      channel: 'test',
+      connectedAt: 0,
+      lastPingAt,
+      meta: {},
+    };
+  };
+
+  test('pings fresh clients and closes stale ones with 1001', () => {
+    const now = 1_000_000;
+    const fresh = client(now - 1_000);
+    const stale = client(now - 200_000);
+    sweepStaleClients([fresh, stale], now, 120_000);
+
+    expect(fresh.ws.pings).toBe(1);
+    expect(fresh.ws.closedWith).toBeUndefined();
+    expect(stale.ws.pings).toBe(0);
+    expect(stale.ws.closedWith).toEqual([1001, 'stale']);
+  });
+});