cursedbelt 2.7.0 → 3.0.0

package/src/server/sync/types.ts

@@ -1,108 +0,0 @@
-/**
- * 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/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/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

@@ -1,67 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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

@@ -1,93 +0,0 @@
-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

@@ -1,282 +0,0 @@
-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']);
-  });
-});