@preventive/triage 1.0.0-alpha.4 → 1.0.0-alpha.41

package/server/lifecycle.ts

@@ -1,204 +0,0 @@
-// Process lifecycle: the in-flight request tracker, the `shuttingDown`
-// gate, the graceful-shutdown choreography, and the signal / error /
-// uncaught-exception handlers that drive it. Two-phase so the bits the
-// HTTP + WS planes need (`track`, `isShuttingDown`) exist BEFORE those
-// servers are built, while the teardown is `install()`ed afterward —
-// once the server objects, heartbeat timer, and reaper exist.
-
-import type { Server } from 'node:http'
-import type { WebSocketServer } from 'ws'
-import type { SseSession } from './sse-session.ts'
-import { errStack } from './util.ts'
-
-export type ShutdownDeps = {
-  httpServer: Server
-  wss: WebSocketServer
-  heartbeatTimer: ReturnType<typeof setInterval>
-  // Stops the periodic reaper AND awaits any in-flight sweep.
-  stopReaper: () => Promise<void>
-  // Live SSE+POST session iterator (mirrors `wss.clients` for the SSE
-  // fallback transport). Walked alongside `wss.clients` to send the
-  // 1001 close frame and apply the terminate-grace timer to both
-  // transports uniformly.
-  sseSessions: () => Iterable<SseSession>
-  // App-specific teardown, run AFTER the in-flight drain: close the DB.
-  // Swallows its own errors (a failed close shouldn't abort the exit).
-  closeDb: () => Promise<void>
-}
-
-export type Lifecycle = {
-  // Collects in-flight async handlers so `shutdown` can drain them
-  // before closing the DB. Passed to the HTTP + WS planes.
-  track: (promise: Promise<unknown>) => void
-  // Read by the REST shutdown gate + the WS message loop to drop new
-  // work once teardown began.
-  isShuttingDown: () => boolean
-  // Wire the graceful shutdown + the error / signal / process-catchall
-  // handlers. Call once, after the server objects exist.
-  install: (deps: ShutdownDeps) => void
-}
-
-export function createLifecycle(): Lifecycle {
-  // In-flight async message handlers. `shutdown` awaits this set before
-  // closing the DB so a SIGINT mid-save can't resume against a closed
-  // handle (which would throw inside the commit's gated INSERT after
-  // the client believed its save was committed).
-  const inFlight = new Set<Promise<unknown>>()
-  function track(promise: Promise<unknown>): void {
-    inFlight.add(promise)
-    // Trailing `.catch(() => {})` swallows the rejection that `.finally`
-    // propagates through its returned promise — without it, a tracked
-    // handler that rejects (or whose caller's catch handler itself
-    // throws) trips the `unhandledRejection` catchall below and crashes
-    // the process via `fireShutdown(1)`.
-    promise.finally(() => inFlight.delete(promise)).catch(() => {})
-  }
-  let shuttingDown = false
-  // Live exit code the in-progress shutdown will pass to `process.exit`.
-  // Re-entry can ESCALATE it from 0 → 1 (e.g. a `wss.error` firing
-  // during a SIGTERM-driven graceful shutdown shouldn't leave the
-  // launcher seeing a clean exit code) but can never DE-escalate.
-  // Audit round-13.
-  let pendingExitCode = 0
-
-  function install(deps: ShutdownDeps): void {
-    const { httpServer, wss, heartbeatTimer, stopReaper, sseSessions, closeDb } = deps
-
-    async function shutdown(exitCode: number = 0): Promise<void> {
-      // Re-entry: don't restart the teardown, but escalate the pending
-      // exit code if the new caller is non-zero (e.g. a wss.error during
-      // a SIGTERM-driven graceful shutdown). Without this, an error
-      // arriving mid-shutdown would silently exit 0 and the launcher
-      // would record a clean stop.
-      if (shuttingDown) {
-        if (exitCode !== 0 && pendingExitCode === 0) pendingExitCode = exitCode
-        return
-      }
-      shuttingDown = true
-      pendingExitCode = exitCode
-      console.log('Shutting down…')
-      // Stop the heartbeat so a tick can't fire mid-shutdown and ping a
-      // socket the close-loop below already started tearing down.
-      clearInterval(heartbeatTimer)
-      // Send a 1001 (going away) close frame to every open socket BEFORE
-      // shutting the listener. Lets clients distinguish a server-initiated
-      // graceful shutdown from a network drop, so they can skip their
-      // reconnect backoff. Fire-and-forget — `process.exit` below would
-      // force-kill any in-progress flush anyway. `try/catch` shrugs at
-      // sockets already in CLOSING / CLOSED.
-      for (const socket of wss.clients) {
-        try { socket.close(1001, 'Server shutting down') } catch {}
-      }
-      // Same close frame on every SSE+POST session — the adapter
-      // translates `close(1001, …)` into a structured `event: close`
-      // record on the SSE stream so the client transport can read the
-      // code and skip its reconnect backoff (parity with the WS path).
-      for (const session of sseSessions()) {
-        try { session.close(1001, 'Server shutting down') } catch {}
-      }
-      // Force-terminate any client that doesn't ack the close frame
-      // within a short grace window. `wss.close()` waits for every client
-      // to emit `'close'`, and `ws` only TCP-RSTs unresponsive peers
-      // after its own ~30 s `closeTimeout`. A single dead/blackholed peer
-      // would otherwise stretch SIGTERM/SIGINT response by that full
-      // timeout. Audit round-11.
-      const TERMINATE_GRACE_MS = 1_000
-      const terminateTimer = setTimeout(() => {
-        for (const socket of wss.clients) {
-          const rs = socket.readyState
-          if (rs === socket.OPEN || rs === socket.CLOSING) {
-            try { socket.terminate() } catch {}
-          }
-        }
-        // SSE sessions are tracked separately from `wss.clients`; apply
-        // the same terminate-grace policy so a stranded SSE response
-        // can't pin the HTTP keep-alive shutdown branch below.
-        for (const session of sseSessions()) {
-          const rs = session.readyState
-          if (rs === session.OPEN || rs === session.CLOSING) {
-            try { session.terminate() } catch {}
-          }
-        }
-        // Same grace for HTTP keep-alive sockets that didn't respect the
-        // `Connection: close` hint, which would otherwise hold
-        // `httpServer.close()` until their TCP timeout.
-        try { httpServer.closeAllConnections() } catch {}
-      }, TERMINATE_GRACE_MS)
-      // Don't keep the event loop alive solely for the grace timer.
-      terminateTimer.unref?.()
-      // Stop the periodic reaper AND wait for any in-flight sweep (incl.
-      // the startup sweep) before the DB close — otherwise a
-      // readdir / unlink would race a closed DB.
-      await stopReaper()
-      // Free idle HTTP keep-alive sockets up front so close() below
-      // doesn't wait on them. Active in-flight requests still finish.
-      try { httpServer.closeIdleConnections() } catch {}
-      // Close http.Server first to stop accepting new upgrades + HTTP
-      // requests. Guard with `.listening` because `close()` throws
-      // ERR_SERVER_NOT_RUNNING when bind never succeeded (the http error
-      // handler is the path that invoked shutdown in that case).
-      if (httpServer.listening) {
-        await new Promise<void>((resolve) => { httpServer.close(() => resolve()) })
-      }
-      await new Promise<void>((resolve) => { wss.close(() => resolve()) })
-      clearTimeout(terminateTimer)
-      // Drain in-flight handlers so a save that's mid-pipeline finishes
-      // its commit before the DB closes. `handleSave` splits its
-      // canonical/id/dup-precheck/verify/commit work across awaits, so
-      // the window spans several yield points. `Promise.allSettled` so a
-      // single handler rejection doesn't abort the drain.
-      if (inFlight.size > 0) await Promise.allSettled([...inFlight])
-      // App teardown AFTER the drain: close the DB.
-      await closeDb()
-      // Read `pendingExitCode` (not the parameter) so a re-entrant
-      // `shutdown(1)` that landed during the drain wins over the original
-      // `shutdown(0)`. See round-13 escalation note.
-      process.exit(pendingExitCode)
-    }
-
-    // `.catch` defends against an unguarded `await` slipping into
-    // `shutdown`: an unhandled rejection there would skip the non-zero
-    // exit the launcher relies on.
-    function fireShutdown(code: number): void {
-      shutdown(code).catch((err) => {
-        console.warn('shutdown error:', errStack(err))
-        process.exit(code === 0 ? 1 : code)
-      })
-    }
-
-    // Route bind / post-listen failures through `shutdown` so the
-    // in-flight drain + DB close still run before exit. Without this,
-    // `ws` re-emits the error as uncaughtException and the launcher sees
-    // a confusing crash rather than the bind failure. Audit round-9 M2.
-    httpServer.on('error', (err: Error) => {
-      console.error('Server error:', errStack(err))
-      fireShutdown(1)
-    })
-    // Symmetric with the http.Server error handler — route through
-    // `fireShutdown(1)` so the launcher sees a non-zero exit, and the
-    // re-entry escalation bumps `pendingExitCode` 0 → 1 for a `wss.error`
-    // arriving mid-graceful-SIGTERM.
-    wss.on('error', (err: Error) => {
-      console.error('WS server error:', errStack(err))
-      fireShutdown(1)
-    })
-    // Wrap signal handlers so the signal name (the listener's first arg)
-    // doesn't bleed into shutdown's `exitCode`.
-    process.on('SIGINT', () => fireShutdown(0))
-    process.on('SIGTERM', () => fireShutdown(0))
-    // Process-level catchalls so a stray rejection / uncaught exception
-    // doesn't bypass `shutdown()` — Node 20+ exits on unhandled
-    // rejection, which would skip the drain + DB close. Log forensically
-    // and route through `fireShutdown(1)`. Audit round-11 observability.
-    process.on('unhandledRejection', (reason) => {
-      console.error('Unhandled rejection:', errStack(reason))
-      fireShutdown(1)
-    })
-    process.on('uncaughtException', (err) => {
-      console.error('Uncaught exception:', errStack(err))
-      fireShutdown(1)
-    })
-  }
-
-  return { track, isShuttingDown: () => shuttingDown, install }
-}

package/server/sync-handlers.ts

@@ -1,320 +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'
-
-// Wire shape `chainForWire` produces from a `chainFrom` row, with
-// `keyframe` normalised from the SQLite INTEGER 0/1 to a strict boolean.
-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
-  // Cross-instance pub/sub for live broadcasts. Fired alongside the
-  // local `broadcast` after a successful commit so peers on OTHER
-  // server instances see the new revision in real time. Carries only
-  // `(tag, revisionId)` — the receiver re-fetches the row from
-  // workspace_revision because the ciphertext can exceed the bus's
-  // payload budget. Optional: a SQLite deployment passes a no-op.
-  publishRevision: (tag: string, revisionId: string) => 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, publishRevision, 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` to a strict boolean on outbound chain entries.
-  // SQLite stores the column as INTEGER (0/1) and `chainFrom` returns
-  // raw rows; the wire contract (and canonical signing payload) uses
-  // strict `=== true`. Convert once on the send side — forwarding the
-  // integer relies on clients coercing via `Boolean()` before rebuilding
-  // canonical bytes, fragile against any client that strict-compares.
-  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
-    }
-    // Save does NOT subscribe the sending socket — that would be a
-    // replay vector: a passive observer who captured one valid
-    // `workspace-save` frame could replay it from any TCP connection to
-    // attach as a subscriber and mirror every future encrypted
-    // broadcast, without holding the seed (the duplicate-id path returns
-    // ack-only, doesn't reject the socket). Explicit `workspace-subscribe`
-    // (signs the per-connection challenge nonce) is the ONLY attach path.
-    // Audit round-9 H1.
-    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). An integer 0/1 here would make a keyframe look like a
-    // regular delta on broadcast paths.
-    broadcast(tag, {
-      type: 'workspace-state',
-      workspaceTag: tag,
-      revisions: [{
-        base: baseNorm,
-        id,
-        keyframe,
-        nonce: msg.nonce,
-        ciphertext: msg.ciphertext,
-        signature: msg.signature,
-      }],
-    }, socket)
-    // Cross-instance fan-out. The bus payload carries only the revision
-    // id — peers on OTHER instances re-fetch the row from
-    // workspace_revision to compose their local `workspace-state`. Sized
-    // for the bus's 8 KB payload budget, which can't carry a 2 MiB
-    // ciphertext. SQLite mode passes a no-op; Neon mode publishes via
-    // pg_notify. Best-effort: a dropped publish only means peers on
-    // other instances miss the live push, but they still catch up via
-    // the shared DB on their next subscribe / reconnect.
-    publishRevision(tag, id)
-  }
-
-  async function handleSubscribe(socket: WebSocket, msg: SubscribeMsg): Promise<void> {
-    // Mirror handleSave's wire gate: length-cap + base64url-alphabet on
-    // workspaceTag / signature / from BEFORE canonicalSubscribe UTF-8-
-    // encodes them and verifyEd25519 base64-decodes the signature.
-    // Without it a peer can submit up-to-maxPayload strings and force
-    // O(n) encode + decode per subscribe before the 32/64-byte length
-    // gates reject — a CPU-DoS surface handleSave is already hardened
-    // against. `from` keeps the `string | null` contract (null = full-
-    // chain catch-up); a legit signer's `from` is a base64url revision
-    // id, so any non-string / over-long / wrong-alphabet value can't be
-    // one the signature was computed over, and the chain-lookup path
-    // (`typeof msg.from === 'string' ? msg.from : null`) still treats a
-    // null / absent `from` as the keyframe-fallback.
-    if (!validTagSigBase(msg.workspaceTag, MAX_FIELD_LEN) || !validTagSigBase(msg.signature, MAX_FIELD_LEN) || (msg.from != null && !validTagSigBase(msg.from, MAX_FIELD_LEN))) 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 }
-}