@preventive/triage 1.0.0-alpha.0 → 1.0.0-alpha.10

package/server/sync-handlers.ts

@@ -1,311 +0,0 @@
-// Triage-sync protocol handlers: `workspace-save` and
-// `workspace-subscribe`. Built once at boot with the DB handle plus
-// the transport / auth / registry primitives it needs; the WS message
-// dispatcher in index.ts calls the returned handlers. Kept out of the
-// entrypoint so the protocol logic (the save pipeline, the
-// subscribe/catch-up path) is one cohesive, testable unit.
-
-import type { WebSocket } from 'ws'
-import { SAVE_ERROR_REASONS, type SaveErrorReason } from '../common/save-error-reason.ts'
-import { type Handle, type RevisionRow, chainFrom, commitRevision, revisionExists } from './db.ts'
-import { type SaveMsg, type SubscribeMsg, canonicalSave, computeRevisionIdFromCanonical, verifyEd25519, verifySubscribeSig } from './sign.ts'
-import { MAX_CIPHERTEXT_LEN, MAX_FIELD_LEN, validCiphertextShape, validNonce, validTagSigBase } from './validation.ts'
-import { debugTag } from './util.ts'
-import type { UnauthorizedContext } from './auth.ts'
-
-// `chainForWire` accepts the row shape from `chainFrom` (where
-// `keyframe` is the SQLite INTEGER 0 / 1) and returns the same fields
-// with `keyframe` normalised to a strict boolean for the wire.
-type WireRevision = {
-  base: string | null
-  id: string
-  keyframe: boolean
-  nonce: string
-  ciphertext: string
-  signature: string
-}
-
-export type SyncHandlersDeps = {
-  handle: Handle
-  send: (socket: WebSocket, msg: object) => void
-  broadcast: (tag: string, msg: object, except: WebSocket | null) => void
-  subscribe: (socket: WebSocket, tag: string) => void
-  getNonce: (socket: WebSocket) => string | undefined
-  requiresAuth: (socket: WebSocket) => boolean
-  sendUnauthorized: (socket: WebSocket, ctx: UnauthorizedContext) => void
-  workspaceExists: (tag: string) => Promise<boolean>
-  // Objstore inventory snapshot for a workspace tag, as wire rows. The
-  // `workspace-subscribed` ack carries it. Injected — the objstore store
-  // has its own richer `Handle`, so index.ts wires `listLive(
-  // objstoreHandle, tag).then(rows => rows.map(objectMetaWire))` rather
-  // than coupling this module to that store type. Returns [] for a
-  // triage-only tag.
-  objstoreResources: (tag: string) => Promise<object[]>
-  debug: boolean
-}
-
-export type SyncHandlers = {
-  handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
-  handleSubscribe: (socket: WebSocket, msg: SubscribeMsg) => Promise<void>
-  // Exported because the dispatcher's inflight-cap `busy` NACK path
-  // emits a save-error too (the only emit site outside this module).
-  sendSaveError: (socket: WebSocket, workspaceTag: string, base: string | null, reason: SaveErrorReason) => void
-}
-
-export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
-  const { handle, send, broadcast, subscribe, getNonce, requiresAuth, sendUnauthorized, workspaceExists, objstoreResources, debug } = deps
-
-  // Typed wrapper for the three `workspace-save-error` emit sites
-  // (too-large at handleSave, stale-base after the catch-up, busy at
-  // the inflight-cap drop). Forces `reason` to be a member of
-  // `SaveErrorReason` so a typo or a server-side addition that didn't
-  // update `common/save-error-reason.ts` fails at compile time rather
-  // than turning into a wire-level surprise. The shared taxonomy is
-  // pinned by `tests/save-error-reason-taxonomy.test.js`.
-  function sendSaveError(
-    socket: WebSocket,
-    workspaceTag: string,
-    base: string | null,
-    reason: SaveErrorReason,
-  ): void {
-    // Runtime guard alongside the compile-time `SaveErrorReason` union —
-    // covers the case where the `reason` argument is a variable (not a
-    // string literal) and TS's narrowing can't enforce taxonomy
-    // membership at the call site. Throws because a server emitting a
-    // typo'd reason would be a wire-protocol break the client can't
-    // recover from; better to fail fast in the test suite than to
-    // silently land bytes the client coerces to `'rejected'`.
-    if (!SAVE_ERROR_REASONS.has(reason)) {
-      throw new Error(`sendSaveError: reason '${reason}' is not in SAVE_ERROR_REASONS — update common/save-error-reason.ts`)
-    }
-    send(socket, { type: 'workspace-save-error', workspaceTag, base, reason })
-  }
-
-  // Normalise `keyframe` on outbound chain entries to a strict boolean.
-  // SQLite stores the column as INTEGER (0/1) and `chainFrom` returns
-  // raw rows; the wire contract (and the canonical signing payload)
-  // uses strict `=== true` to mark keyframes. Forwarding the integer
-  // shape works only because every shipping client coerces via
-  // `Boolean(rev.keyframe)` before reconstructing the canonical bytes —
-  // fragile if a future client (or test harness) ever strict-compares.
-  // Convert once on the send side.
-  function chainForWire(revisions: RevisionRow[]): WireRevision[] {
-    return revisions.map((r) => ({ ...r, keyframe: r.keyframe === 1 }))
-  }
-
-  async function handleSave(socket: WebSocket, msg: SaveMsg): Promise<void> {
-    // `base` is `string | null`; null is the keyframe-root marker.
-    if (!validTagSigBase(msg.workspaceTag, MAX_FIELD_LEN) || !validNonce(msg.nonce, MAX_FIELD_LEN) || !validCiphertextShape(msg.ciphertext) || !validTagSigBase(msg.signature, MAX_FIELD_LEN) || (msg.base != null && !validTagSigBase(msg.base, MAX_FIELD_LEN))) return
-    // Compute canonical bytes + content-addressed id ONCE, then thread
-    // both through the precheck → sig verify → commit pipeline:
-    //   1. canonicalSave (sync, throws on lone-surrogate input)
-    //   2. SHA-256 → id
-    //   3. precheck: revisionExists → short-circuit ack on replay
-    //      (skips Ed25519 verify; closes the round-9 H1 CPU-DoS vector
-    //      where a passive observer floods captured saves)
-    //   4. verifyEd25519 against the SAME canonical bytes the id was
-    //      hashed from — provably tied
-    //   5. ciphertext size policy (post-sig so the explicit error only
-    //      reaches a legit signer)
-    //   6. commitRevision — re-checks dup + base + inserts via a single
-    //      gated INSERT (dup gate + head-equals-base gate + the
-    //      server-assigned seq folded into one statement) — NO write
-    //      lock. The dup recheck, headFor, base-match and insert all
-    //      collapse into that one statement, whose head-check and
-    //      MAX(seq) read one snapshot; the `UNIQUE(workspace_tag, seq)`
-    //      PK rejects any racer that computed the same seq. So two
-    //      concurrent saves with the same `base` and different ids
-    //      can't both insert (the loser's `head IS base` gate fails →
-    //      `stale-base`, no chain fork even though UNIQUE is on id, not
-    //      base), and two concurrent same-id retransmits resolve to one
-    //      `inserted` + one `duplicate` with no UNIQUE throw escaping.
-    //      See `commitRevisionSqlite` / `tryCommitNeon` in db*.ts.
-    let canonical: Uint8Array<ArrayBuffer>
-    try { canonical = canonicalSave(msg) } catch { return }
-    const id = await computeRevisionIdFromCanonical(canonical)
-    const tag = msg.workspaceTag
-    if (await revisionExists(handle, tag, id)) {
-      if (debug) console.log(`save (precheck dup ${id.slice(0, 8)}…) → ack-only`)
-      send(socket, { type: 'workspace-save-ack', workspaceTag: tag, base: msg.base ?? null, id })
-      return
-    }
-    if (!await verifyEd25519(tag, canonical, msg.signature)) {
-      if (debug) console.warn('reject save: bad signature', debugTag(tag))
-      return
-    }
-    // Size policy — emit an explicit error so the client can surface
-    // the failure to the user. Without this, an oversized save hangs
-    // forever in the client's `pending` slot (no ack, no rebase).
-    if (msg.ciphertext.length > MAX_CIPHERTEXT_LEN) {
-      if (debug) console.warn(`reject save: ciphertext too large (${msg.ciphertext.length} > ${MAX_CIPHERTEXT_LEN})`)
-      sendSaveError(socket, tag, msg.base == null || typeof msg.base !== 'string' ? null : msg.base, 'too-large')
-      return
-    }
-    // Auth gate for the FIRST action against a workspace tag that
-    // doesn't yet exist on the server (no rows in workspace_revision
-    // AND none in workspace_object). Once any row lands, the workspace
-    // is established and every signed action flows freely — access
-    // control falls back to the Ed25519 signature for the rest of the
-    // workspace's lifetime. Checked AFTER sig verify so the
-    // `unauthorized` frame only reaches a legitimate signer; shape /
-    // sig attacks still drop silently.
-    //
-    // RACE: `workspaceExists` reads at a different moment than the
-    // commit's gated INSERT (a plain TOCTOU — there is no lock spanning
-    // the two). Under concurrent saves on a fresh tag, an
-    // unauthenticated socket whose `workspaceExists` observes "true"
-    // (because an authenticated peer's commit landed between this
-    // socket's check and its commit) skips the gate and commits as the
-    // second writer. Accepted: the unauthenticated peer still had to
-    // produce a valid Ed25519 signature (= holds the workspace seed),
-    // and "two concurrent writes both authorising" is the worst case.
-    // Tightening would require folding the gate into the commit
-    // statement itself and is not worth the layer crossing for the
-    // soft-policy guarantee.
-    if (requiresAuth(socket) && !await workspaceExists(tag)) {
-      if (debug) console.warn(`reject save: unauthorized (new workspace ${debugTag(tag)})`)
-      sendUnauthorized(socket, { kind: 'gated', workspaceTag: tag, base: msg.base ?? null })
-      return
-    }
-    // NOTE: Earlier revisions auto-subscribed the sending socket here.
-    // That created a replay vector — a passive observer who captured
-    // any single valid `workspace-save` frame could replay it from any
-    // TCP connection forever to attach as a subscriber and silently
-    // mirror every future encrypted broadcast for the workspace,
-    // without ever holding the seed (the duplicate-id path returns
-    // ack-only and doesn't reject the socket). Audit round-9 H1.
-    //
-    // The legitimate client always sends an explicit
-    // `workspace-subscribe` (see `trySendSubscribe` in
-    // `client/triage-sync.js` — fires on key derivation, on socket
-    // open, on continuity-break recovery, on dismissError). The
-    // subscribe path remains the only way to attach as a subscriber.
-    const baseNorm = msg.base ?? null
-    // `keyframe === true` is what canonicalSave bound the signature to
-    // (strict equality); the signer's intent is unambiguous here.
-    const keyframe = msg.keyframe === true
-    const commit = await commitRevision(handle, {
-      tag, id, base: baseNorm, keyframe,
-      nonce: msg.nonce, ciphertext: msg.ciphertext, signature: msg.signature,
-    })
-    if (commit.kind === 'duplicate') {
-      if (debug) console.log(`save (duplicate id ${id.slice(0, 8)}…) → ack-only`)
-      send(socket, { type: 'workspace-save-ack', workspaceTag: tag, base: baseNorm, id })
-      return
-    }
-    if (commit.kind === 'stale-base') {
-      // Client claimed a base that's no longer head. Catch-up chain is
-      // computed OUTSIDE the lock — a concurrent commit landing between
-      // lock-release and `chainFrom` only means the catch-up is fresher
-      // than the recheck saw, which is benign (clients tolerate extra
-      // revisions in the chain).
-      //
-      // Wire order: send `workspace-state` (catch-up) FIRST, then the
-      // typed `workspace-save-error { reason: 'stale-base' }`. The
-      // catch-up's handler clears `session.pending`; the subsequent
-      // error frame's `handleSaveError` then early-returns on the
-      // missing pending and does NOT mark the session errored — exactly
-      // what we want, since stale-base is a recoverable race (client
-      // rebases + re-saves). The typed frame is for protocol clarity
-      // (debug surfaces / explicit rejection signal), not for triggering
-      // an error transition. Audit follow-up to round-15 —
-      // `sync-server-races.test.js:1105`.
-      const revisions = chainForWire(await chainFrom(handle, tag, baseNorm))
-      if (debug) console.log(`save (stale base ${baseNorm} vs head ${commit.head}) → chain ${revisions.length}`)
-      send(socket, { type: 'workspace-state', workspaceTag: tag, revisions })
-      sendSaveError(socket, tag, baseNorm, 'stale-base')
-      return
-    }
-    if (debug) console.log(`save${keyframe ? ' [keyframe]' : ''} → revision ${id.slice(0, 8)}… for ${debugTag(tag)}`)
-    send(socket, {
-      type: 'workspace-save-ack',
-      workspaceTag: tag,
-      base: baseNorm,
-      id,
-    })
-    // Carry `keyframe` as a strict boolean on the broadcast wire —
-    // peers strict-compare `=== true` (matching the canonical-payload
-    // contract). The previous shape emitted `keyframe ? 1 : 0` which a
-    // strict check would treat as non-keyframe, making a replayed
-    // keyframe look like a regular delta on broadcast paths even though
-    // the chain-fetch path (chainFrom → SQLite integer) DID round-trip
-    // correctly.
-    broadcast(tag, {
-      type: 'workspace-state',
-      workspaceTag: tag,
-      revisions: [{
-        base: baseNorm,
-        id,
-        keyframe,
-        nonce: msg.nonce,
-        ciphertext: msg.ciphertext,
-        signature: msg.signature,
-      }],
-    }, socket)
-  }
-
-  async function handleSubscribe(socket: WebSocket, msg: SubscribeMsg): Promise<void> {
-    if (typeof msg.workspaceTag !== 'string') return
-    // Same `string | null` contract as `base` in handleSave. The signed
-    // canonical uses `String(from)`, but the chain-lookup path
-    // (`typeof msg.from === 'string' ? msg.from : null`) treats every
-    // non-string as null — so a legit signer sending `from: { … }`
-    // would silently take the keyframe-fallback path even though the
-    // signature was over a different canonical shape. Reject at the
-    // wire gate.
-    if (msg.from != null && typeof msg.from !== 'string') return
-    // The challenge nonce we issued on this socket is bound into the
-    // signed canonical, blocking cross-connection replay of a captured
-    // subscribe frame. A subscribe arriving before we sent the
-    // challenge (impossible from the legitimate client) has no nonce to
-    // verify against — drop. Audit round-9 H2.
-    const nonce = getNonce(socket)
-    if (typeof nonce !== 'string') return
-    const ok = await verifySubscribeSig(msg, nonce)
-    if (!ok) {
-      if (debug) console.warn('reject subscribe: bad signature', debugTag(msg.workspaceTag))
-      return
-    }
-    // Bail if the socket closed during the verify await. The close
-    // handler's `unsubscribeAll(socket)` already ran (when there was
-    // nothing to remove yet), and `subscribe()` below would add the
-    // dead socket to `subscribers[tag]` — a permanent leak: broadcasts
-    // no-op via `send`'s readyState gate, but the Set entry pins the
-    // socket reference past close, blocking GC. Audit round-12.
-    if (socket.readyState !== socket.OPEN) {
-      if (debug) console.warn('reject subscribe: socket closed mid-verify', debugTag(msg.workspaceTag))
-      return
-    }
-    const tag = msg.workspaceTag
-    subscribe(socket, tag)
-    // Explicit ack — distinguishes "the server processed my subscribe
-    // and registered me as a peer" from "the WebSocket is open". A
-    // client that sent a malformed / bad-sig subscribe never gets this;
-    // a client that did gets one before the chain arrives. Lets the UI
-    // surface a `connecting → online` transition based on real handshake
-    // completion, not just socket state.
-    //
-    // The ack also carries the objstore inventory snapshot: the same
-    // subscribe that registers this socket for objstore-put / -deleted
-    // broadcasts seeds the client's initial inventory in one handshake.
-    // The client keeps it live thereafter from those broadcasts.
-    // Returns [] for a triage-only workspace. A failing inventory
-    // lookup must NOT sink the subscribe — degrade to an empty snapshot
-    // (broadcasts will fill it in) so the ack + chain still go out.
-    let resources: object[] = []
-    try { resources = await objstoreResources(tag) }
-    catch (err) { if (debug) console.warn('subscribe: objstore inventory lookup failed', debugTag(tag), err) }
-    send(socket, { type: 'workspace-subscribed', workspaceTag: tag, resources })
-    // `from` is the last revision id the client claims to have applied —
-    // now a base64url string, not an integer. We send only revisions
-    // after that. Client lying about `from` just means they get a
-    // smaller catch-up — their subsequent saves will reveal stale state
-    // on the usual base-mismatch path. Null / missing → full chain.
-    const fromId = typeof msg.from === 'string' ? msg.from : null
-    const revisions = chainForWire(await chainFrom(handle, tag, fromId))
-    if (debug) console.log(`subscribe ${debugTag(tag)} from=${fromId?.slice(0, 8) ?? 'null'} → chain ${revisions.length}`)
-    send(socket, { type: 'workspace-state', workspaceTag: tag, revisions })
-  }
-
-  return { handleSave, handleSubscribe, sendSaveError }
-}

package/server/ws-server.ts

@@ -1,245 +0,0 @@
-// WebSocket runtime: the per-connection handler (Peer setup, message
-// dispatch, close/error) and the server-driven heartbeat sweep. Wired
-// once at boot onto the shared `wss` with the protocol handlers +
-// lifecycle hooks it dispatches to. Kept out of index.ts so the WS
-// message loop — the most concurrency-sensitive surface — is one unit.
-
-import type { WebSocket, WebSocketServer } from 'ws'
-import { Buffer } from 'node:buffer'
-import { decodeUtf8 } from '../common/utf8.js'
-import type { SaveErrorReason } from '../common/save-error-reason.ts'
-import { Peer, type PeerRegistry } from './peer.ts'
-import { errMsg, errStack, randomId } from './util.ts'
-import type { SaveMsg, SubscribeMsg } from './sign.ts'
-import type { AuthenticateMsg } from './auth.ts'
-import type { ObjstoreHandlers } from './objstore/handlers.ts'
-import type { ObjstoreDeleteMsg, ObjstoreFetchMsg, ObjstorePutBeginMsg } from './objstore/sign.ts'
-
-// Wire-message envelope as it lands post-`JSON.parse`. Every field is
-// `unknown` until a handler narrows it; the type just documents the
-// dispatch surface so call sites can pattern-match on `msg.type`.
-type IncomingMessage = {
-  type?: unknown
-  [k: string]: unknown
-}
-
-export type WsServerDeps = {
-  wss: WebSocketServer
-  peers: PeerRegistry
-  send: (socket: WebSocket, msg: object) => void
-  unsubscribeAll: (socket: WebSocket) => void
-  handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
-  handleSubscribe: (socket: WebSocket, msg: SubscribeMsg) => Promise<void>
-  handleAuthenticate: (socket: WebSocket, msg: AuthenticateMsg) => void
-  sendSaveError: (socket: WebSocket, workspaceTag: string, base: string | null, reason: SaveErrorReason) => void
-  objstore: ObjstoreHandlers
-  track: (promise: Promise<unknown>) => void
-  isShuttingDown: () => boolean
-  maxInflightPerSocket: number
-  heartbeatIntervalMs: number
-  debug: boolean
-}
-
-// Wires `wss.on('connection')` + starts the heartbeat. Returns the
-// timer so shutdown can clear it.
-export function installWsServer(deps: WsServerDeps): { heartbeatTimer: ReturnType<typeof setInterval> } {
-  const {
-    wss, peers, send, unsubscribeAll, handleSave, handleSubscribe, handleAuthenticate,
-    sendSaveError, objstore, track, isShuttingDown, maxInflightPerSocket, heartbeatIntervalMs, debug,
-  } = deps
-
-  wss.on('connection', (socket: WebSocket, req) => {
-    if (debug) console.log(`connect from ${req.socket.remoteAddress}`)
-    // One Peer holds this connection's state (challenge / authorized /
-    // alive / inflight / tags). Created before any client frame can
-    // arrive (`socket.on('message')` is wired below). The heartbeat
-    // sweep flips `alive` false after each `ping()`; the `pong` listener
-    // flips it back, and a socket still false on the next sweep is
-    // terminated — the only thing closing FDs for an idle peer.
-    const peer = new Peer(randomId())
-    peers.set(socket, peer)
-    socket.on('pong', () => { peer.alive = true })
-    // Issue the per-connection challenge nonce BEFORE the client can
-    // send anything that needs it. The client signs it into every
-    // `workspace-subscribe` (see canonicalSubscribe in server/sign.ts);
-    // a captured subscribe frame can't be replayed from a different
-    // connection because that connection's nonce differs and the
-    // signature won't verify against the new canonical bytes. Round-9 H2.
-    send(socket, { type: 'challenge', nonce: peer.challenge })
-    // Per-socket handlers are DELIBERATELY NOT serialized (vs the
-    // client-side `messageQueue = messageQueue.then(...)` Promise
-    // chain inside `client/triage-sync.ts:onTransportMessage`).
-    // Each inbound frame spawns its own tracked async IIFE; two
-    // frames from the same socket can interleave across `await`
-    // boundaries inside the handlers. Per-resource correctness needs
-    // no in-process lock: `commitRevision` resolves concurrent saves
-    // via its single gated INSERT (one snapshot + the
-    // `UNIQUE(workspace_tag, seq)` PK — see `server/db.ts`), and the
-    // objstore handlers (`commitPut` / `beginPut` / `deleteObject`)
-    // via the version compare-and-set + content-addressing (see
-    // `server/objstore/store.ts`), backed by post-await
-    // `readyState === OPEN` rechecks in every objstore handler. The
-    // unbounded fan-out is capped by `maxInflightPerSocket` (see
-    // also the `'busy'` NACK at the cap below). Concurrent dispatch
-    // is intentional: it lets multi-workspace clients multiplex
-    // saves + subscribes over one socket without HOL blocking.
-    // Audit follow-up to round-15 concurrency review.
-    socket.on('message', (data: Buffer, isBinary: boolean) => {
-      // Drop new work once shutdown started — `wss.close()` stops new
-      // CONNECTIONS but already-open sockets can still send messages.
-      // Without this gate a message arriving between `wss.close()`
-      // resolving and the `inFlight` snapshot would spawn a handler
-      // that's NOT in the snapshot, then resume against the just-
-      // closed DB and throw inside the commit's gated INSERT. Audit
-      // round-9.
-      if (isShuttingDown()) return
-      // Wire protocol is JSON over text frames. A binary frame is
-      // either a buggy client or someone probing — drop without
-      // attempting to interpret it as text.
-      if (isBinary) return
-      let msg: IncomingMessage | null = null
-      try {
-        // `decodeUtf8` is fatal on invalid UTF-8 (vs `Buffer.toString`
-        // which silently substitutes U+FFFD). The substitution path
-        // would let mangled bytes pass JSON.parse only to fail
-        // signature verification deeper in the handler — wasted work
-        // and noisier logs. Fail at the gate.
-        msg = JSON.parse(decodeUtf8(data)) as IncomingMessage
-      } catch { return }
-      if (!msg || typeof msg !== 'object') return
-      const parsed: IncomingMessage = msg
-      // Per-socket inflight cap. Each tracked handler keeps the socket
-      // alive in `inFlight`, and a peer who keeps firing valid frames
-      // can spawn unbounded handlers — growing SIGTERM drain time and
-      // memory. Drop new work above the cap. Heartbeat ping is the
-      // exception: it's stateless, synchronous, and we want to KEEP
-      // responding so the peer doesn't drop the socket while we're
-      // shedding load. Pings go through a fast inline `send(pong)`
-      // path BELOW that doesn't bump the per-socket inflight counter,
-      // so a ping-spam at the cap can't outrun the gate. Transport
-      // audit `server/index.ts:590` + post-#58 audit follow-up.
-      if (parsed.type === 'ping') {
-        send(socket, { type: 'pong' })
-        return
-      }
-      // `authenticate` runs synchronously (constant-time bytes compare
-      // — no DB, no I/O), so it shares the same fast-inline path as
-      // `ping` and bypasses the per-socket inflight counter. Keeping
-      // it out of the IIFE pool means an unauthenticated client can
-      // still complete the handshake when the socket is otherwise
-      // saturated (matching the philosophy of the `busy` NACK path
-      // for `workspace-save`: don't strand a recoverable handshake
-      // behind the cap).
-      if (parsed.type === 'authenticate') {
-        handleAuthenticate(socket, parsed as AuthenticateMsg)
-        return
-      }
-      if (peer.inflight >= maxInflightPerSocket) {
-        if (debug) console.warn(`drop message: socket inflight ${peer.inflight} >= ${maxInflightPerSocket}`)
-        // For workspace-save specifically, send a typed NACK so the
-        // client's `pending` slot clears IMMEDIATELY instead of
-        // hanging until the next heartbeat (~15–30s). Reason `busy`
-        // is server-side overload; safe to retry. Same wire envelope
-        // as the existing `too-large` save-error path.
-        //
-        // Wire-order interaction with `'stale-base'`: the cap-path
-        // send is SYNCHRONOUS in this message callback and lands on
-        // the wire BEFORE any handler IIFE's `await`-completed reply.
-        // If an earlier in-flight `workspace-save` (frame F1) ends up
-        // emitting a catch-up `workspace-state` + `'stale-base'` while
-        // a later frame F2 hits the cap, the order is `'busy'`(F2) →
-        // `workspace-state`(F1) → `'stale-base'`(F1). The client's
-        // `handleSaveError` correlates on `base`, and the wire-order
-        // trick documented in `common/save-error-reason.ts` (catch-up
-        // clears `pending` before the stale-base frame's
-        // `handleSaveError` runs) still holds.
-        const rawBase = (parsed as SaveMsg).base
-        const baseField: string | null = typeof rawBase === 'string' ? rawBase : null
-        const rawTag = (parsed as SaveMsg).workspaceTag
-        const tagField = typeof rawTag === 'string' ? rawTag : null
-        if (parsed.type === 'workspace-save' && tagField != null) {
-          // `sendSaveError` runs its taxonomy-guard before the wire
-          // send and throws on an unknown reason. Every OTHER emit
-          // site lives inside the `handler` IIFE's try/catch — this
-          // cap path is the only one outside it. Mirror the same
-          // forensic envelope so a future bad reason here surfaces
-          // as `Handler error (type=workspace-save): …` rather than
-          // escaping to ws's emitter as an uncaught.
-          try {
-            sendSaveError(socket, tagField, baseField, 'busy')
-          } catch (err) {
-            console.warn('Handler error (type=workspace-save):', errStack(err))
-          }
-        }
-        return
-      }
-      peer.inflight += 1
-      const handler = (async () => {
-        try {
-          if (parsed.type === 'workspace-save') await handleSave(socket, parsed as SaveMsg)
-          else if (parsed.type === 'workspace-subscribe') await handleSubscribe(socket, parsed as SubscribeMsg)
-          // Objstore control plane — bytes ride the REST plane via
-          // tokens these handlers mint. The Objstore*Msg types are
-          // weak shapes (every field `unknown`); the handlers narrow
-          // each field through their own validators on entry.
-          else if (parsed.type === 'objstore-put-begin') await objstore.handlePutBegin(socket, parsed as ObjstorePutBeginMsg)
-          else if (parsed.type === 'objstore-delete') await objstore.handleDelete(socket, parsed as ObjstoreDeleteMsg)
-          else if (parsed.type === 'objstore-fetch') await objstore.handleFetch(socket, parsed as ObjstoreFetchMsg)
-        } catch (err) {
-          // Forensic logging for unexpected throws — the handlers all
-          // have internal narrow catches (e.g. signature reject paths);
-          // anything reaching here is unexpected. Include the wire
-          // `type` so an operator can correlate to a specific code
-          // path, and prefer `.stack` over `.message` so the post-
-          // mortem has the throw site.
-          const typeStr = typeof parsed.type === 'string' ? parsed.type : '<unknown>'
-          console.warn(`Handler error (type=${typeStr}):`, errStack(err))
-        } finally {
-          peer.inflight -= 1
-        }
-      })()
-      track(handler)
-    })
-    socket.on('close', () => {
-      // `unsubscribeAll` reads `peer.tags` (peer still registered), then
-      // we drop the Peer. The Peer's state would GC once the socket is
-      // unreachable, but `wss.clients` / `ws` internals hold the socket
-      // strongly well past `close`, so the explicit delete frees it
-      // immediately. Audit round-10 + round-13.
-      unsubscribeAll(socket)
-      peers.delete(socket)
-    })
-    // Surface socket-level errors instead of swallowing — these are
-    // the signals operators want under abuse / network flakiness
-    // (TLS handshake failures, frame-decode errors, ws-protocol
-    // violations). The previous `() => {}` left every per-connection
-    // failure invisible. `close` fires after `error` and runs the
-    // unsubscribe cleanup, so logging here doesn't risk leaking.
-    socket.on('error', (err: Error) => { console.warn('Socket error:', errMsg(err)) })
-  })
-
-  // Periodic heartbeat sweep. Two-tick liveness window: a socket that
-  // doesn't `pong` within `heartbeatIntervalMs` of our `ping` sees its
-  // tracker flip to `false`; on the NEXT tick we terminate. `try/catch`
-  // shrugs at any peer that races us into CLOSING / CLOSED (`ws.ping` /
-  // `ws.terminate` throw in that state) — the close event handles
-  // cleanup either way.
-  //
-  // `unref` so the timer alone doesn't keep the event loop alive
-  // (parity with `terminateTimer` in shutdown). Cleared in shutdown so
-  // a graceful SIGTERM doesn't fire one last ping race after wss.close.
-  const heartbeatTimer = setInterval(() => {
-    for (const ws of wss.clients) {
-      const peer = peers.get(ws)
-      if (peer?.alive === false) {
-        try { ws.terminate() } catch {}
-        continue
-      }
-      if (peer) peer.alive = false
-      try { ws.ping() } catch {}
-    }
-  }, heartbeatIntervalMs)
-  heartbeatTimer.unref?.()
-
-  return { heartbeatTimer }
-}