@preventive/triage 1.0.0-alpha.1 → 1.0.0-alpha.11

package/{server → server-e2e}/sync-handlers.ts

@@ -5,6 +5,8 @@
 // entrypoint so the protocol logic (the save pipeline, the
 // subscribe/catch-up path) is one cohesive, testable unit.
 
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { Buffer } from 'node:buffer'
 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'
@@ -13,9 +15,8 @@ import { MAX_CIPHERTEXT_LEN, MAX_FIELD_LEN, validCiphertextShape, validNonce, va
 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.
+// 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
@@ -25,6 +26,47 @@ type WireRevision = {
   signature: string
 }
 
+// Structured result of the shared save pipeline (`commitSave`), rendered
+// per transport: WS → protocol frames; REST → JSON + HTTP status.
+type SaveOutcome =
+  | { kind: 'rejected' }                                   // malformed / bad sig → WS drop / REST 400
+  | { kind: 'ack'; id: string; base: string | null }       // committed → save-ack / 200
+  | { kind: 'duplicate'; id: string; base: string | null } // replay → ack-only / 200
+  | { kind: 'too-large'; base: string | null }             // ciphertext over cap → save-error / 413
+  | { kind: 'unauthorized'; base: string | null }          // new-workspace gate → unauthorized / 401
+  | { kind: 'stale-base'; base: string | null; revisions: WireRevision[] } // conflict → state+error / 409
+
+// Hard cap on a `POST /api/sync/save` JSON body. The save frame is the small
+// fields + a base64 ciphertext capped at MAX_CIPHERTEXT_LEN (2 MiB); 4 MiB
+// (the WS plane's maxPayload / the SSE plane's maxBodyBytes) leaves headroom
+// for the envelope so the in-pipeline size policy — not the reader — decides
+// `too-large`. Bounds the read so a hostile client can't stream an unbounded
+// body into memory before the parse.
+const SAVE_BODY_MAX = 4 * 1024 * 1024
+
+// Read a JSON request body up to `SAVE_BODY_MAX`, returning the parsed value
+// or null on overflow / parse failure / read error (mirrors the objstore
+// mint reader). The REST save body is the only body this module reads.
+async function readSaveBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let total = 0
+  try {
+    for await (const chunk of req) {
+      const buf = chunk as Buffer
+      total += buf.length
+      if (total > SAVE_BODY_MAX) return null
+      chunks.push(buf)
+    }
+  } catch { return null }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) }
+  catch { return null }
+}
+
+function respondJson(res: ServerResponse, status: number, obj: object): void {
+  res.writeHead(status, { 'content-type': 'application/json' })
+  res.end(JSON.stringify(obj))
+}
+
 export type SyncHandlersDeps = {
   handle: Handle
   send: (socket: WebSocket, msg: object) => void
@@ -39,6 +81,11 @@ export type SyncHandlersDeps = {
   subscribe: (socket: WebSocket, tag: string) => void
   getNonce: (socket: WebSocket) => string | undefined
   requiresAuth: (socket: WebSocket) => boolean
+  // Whether an operator password is configured. The REST save plane's
+  // new-workspace gate (it has no socket to read operator-auth state from)
+  // collapses to `passwordConfigured && workspace-new` — the socket-less
+  // analog of `requiresAuth`, matching the objstore `restPutGate`.
+  passwordConfigured: boolean
   sendUnauthorized: (socket: WebSocket, ctx: UnauthorizedContext) => void
   workspaceExists: (tag: string) => Promise<boolean>
   // Objstore inventory snapshot for a workspace tag, as wire rows. The
@@ -53,6 +100,10 @@ export type SyncHandlersDeps = {
 
 export type SyncHandlers = {
   handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
+  // Session-independent REST save plane (`POST /api/sync/save`), wired into
+  // the HTTP dispatcher in server-e2e/http.ts. Runs the same pipeline as
+  // `handleSave` and renders the outcome as a JSON response.
+  handleSaveRest: (req: IncomingMessage, res: ServerResponse) => 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).
@@ -60,7 +111,7 @@ export type SyncHandlers = {
 }
 
 export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
-  const { handle, send, broadcast, publishRevision, subscribe, getNonce, requiresAuth, sendUnauthorized, workspaceExists, objstoreResources, debug } = deps
+  const { handle, send, broadcast, publishRevision, subscribe, getNonce, requiresAuth, passwordConfigured, 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
@@ -88,21 +139,34 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     send(socket, { type: 'workspace-save-error', workspaceTag, base, reason })
   }
 
-  // Normalise `keyframe` on outbound chain entries to a strict boolean.
+  // 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 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.
+  // 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> {
+  // Transport-agnostic save pipeline, shared by the WS `handleSave` renderer
+  // and the REST `handleSaveRest` renderer. Runs the full validate → precheck
+  // → sig-verify → size/auth gates → commit → broadcast pipeline and returns a
+  // structured `SaveOutcome` the caller renders for its transport. Two params
+  // abstract the transport:
+  //   - `authRequired`: the new-workspace gate decision (WS: requiresAuth(
+  //     socket); REST: passwordConfigured — a REST request can't be operator-
+  //     authorised, so the gate collapses to "password set AND workspace new").
+  //   - `except`: the broadcast exclusion — the originating socket on the WS
+  //     path (so it isn't echoed its own save), or null on the REST path (the
+  //     request isn't a subscriber socket; the originator's own echo lands on
+  //     its subscription stream and is an idempotent no-op — applyChainToBase
+  //     skips a revision whose id already equals the client's baseRevision,
+  //     and a same-content re-apply converges. Matches objstore-deleted's
+  //     `except: null`).
+  async function commitSave(msg: SaveMsg, authRequired: boolean, except: WebSocket | null): Promise<SaveOutcome> {
     // `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
+    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 { kind: 'rejected' }
     // 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)
@@ -117,77 +181,43 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     //   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.
+    //      lock. See `commitRevisionSqlite` / `tryCommitNeon` in db*.ts.
     let canonical: Uint8Array<ArrayBuffer>
-    try { canonical = canonicalSave(msg) } catch { return }
+    try { canonical = canonicalSave(msg) } catch { return { kind: 'rejected' } }
     const id = await computeRevisionIdFromCanonical(canonical)
     const tag = msg.workspaceTag
+    const baseNorm = msg.base ?? null
     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
+      return { kind: 'duplicate', id, base: baseNorm }
     }
     if (!await verifyEd25519(tag, canonical, msg.signature)) {
       if (debug) console.warn('reject save: bad signature', debugTag(tag))
-      return
+      return { kind: 'rejected' }
     }
     // 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
+      return { kind: 'too-large', base: baseNorm }
     }
     // 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)) {
+    // doesn't yet exist on the server. Checked AFTER sig verify so the
+    // `unauthorized` outcome only reaches a legitimate signer; shape /
+    // sig attacks still drop silently. The TOCTOU between `workspaceExists`
+    // and the commit's gated INSERT is an accepted soft-policy race — a
+    // racer still had to produce a valid Ed25519 signature (= holds the
+    // seed). Same gate the objstore put-begin applies.
+    if (authRequired && !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
+      return { kind: 'unauthorized', base: baseNorm }
     }
-    // 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.
+    // Save does NOT subscribe the sender — that would be a replay vector
+    // (a captured frame replayed from any connection would attach as a
+    // subscriber without holding the seed). Explicit `workspace-subscribe`
+    // (signs the per-connection nonce) is the ONLY attach path. 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
@@ -197,46 +227,32 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     })
     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
+      return { kind: 'duplicate', id, base: baseNorm }
     }
     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).
+      // Client claimed a base that's no longer head. The catch-up chain is
+      // computed OUTSIDE any lock — a concurrent commit landing here only
+      // means the catch-up is fresher (benign; clients tolerate extra
+      // revisions). The WS renderer sends `workspace-state` (catch-up) FIRST
+      // then the typed `stale-base` error; the REST renderer returns the
+      // chain in the 409 body. Either way the catch-up clears the client's
+      // pending and the error is a no-op on the now-missing pending (a
+      // recoverable race — client rebases + re-saves).
       //
-      // 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`.
+      // The catch-up CAN be empty: a client holding a base from a chain
+      // this deployment no longer has (wiped / moved DB, SQLite→Neon
+      // migration — head=null, no keyframe, no rows) gets `revisions: []`.
+      // The client detects that shape (pending survives the catch-up) and
+      // answers with a full-state push re-anchored at base=null, which
+      // commits as the new chain root — see the client's
+      // `handleSaveError` stale-base branch.
       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
+      return { kind: 'stale-base', base: baseNorm, revisions }
     }
     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.
+    // Carry `keyframe` as a strict boolean on the broadcast wire — peers
+    // strict-compare `=== true` (matching the canonical-payload contract).
     broadcast(tag, {
       type: 'workspace-state',
       workspaceTag: tag,
@@ -248,28 +264,67 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
         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.
+    }, except)
+    // Cross-instance fan-out. The bus payload carries only the revision id —
+    // peers on OTHER instances re-fetch the row. SQLite mode passes a no-op;
+    // Neon mode publishes via pg_notify. Best-effort.
     publishRevision(tag, id)
+    return { kind: 'ack', id, base: baseNorm }
+  }
+
+  // WS renderer: run the shared pipeline against this socket and render the
+  // outcome as the protocol frames the client expects on its stream. A
+  // `rejected` outcome drops silently (matches the prior malformed/bad-sig
+  // behaviour). For every non-rejected outcome the tag was validated inside
+  // `commitSave`, so the cast to string is sound.
+  async function handleSave(socket: WebSocket, msg: SaveMsg): Promise<void> {
+    const outcome = await commitSave(msg, requiresAuth(socket), socket)
+    if (outcome.kind === 'rejected') return
+    const tag = msg.workspaceTag as string
+    if (outcome.kind === 'unauthorized') { sendUnauthorized(socket, { kind: 'gated', workspaceTag: tag, base: outcome.base }); return }
+    if (outcome.kind === 'too-large') { sendSaveError(socket, tag, outcome.base, 'too-large'); return }
+    if (outcome.kind === 'stale-base') {
+      // State FIRST (its handler clears pending), then the typed error.
+      send(socket, { type: 'workspace-state', workspaceTag: tag, revisions: outcome.revisions })
+      sendSaveError(socket, tag, outcome.base, 'stale-base')
+      return
+    }
+    // ack | duplicate
+    send(socket, { type: 'workspace-save-ack', workspaceTag: tag, base: outcome.base, id: outcome.id })
+  }
+
+  // REST renderer: the session-independent `POST /api/sync/save` plane. Reads
+  // the save frame from the JSON body, runs the SAME pipeline (no socket;
+  // new-workspace gate = passwordConfigured; broadcast except = null), and
+  // maps the outcome to a JSON + HTTP status the client switches on. SSE-mode
+  // clients POST here so a save doesn't take over their event-stream; a 401
+  // routes them to the in-band frame (which runs the operator auth flow).
+  // Mounted + gated (same-origin, shutdown, idle-timeout) in server-e2e/http.ts.
+  async function handleSaveRest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const body = await readSaveBody(req)
+    if (!body || typeof body !== 'object') { respondJson(res, 400, { reason: 'bad-request' }); return }
+    const outcome = await commitSave(body as SaveMsg, passwordConfigured, null)
+    if (outcome.kind === 'ack' || outcome.kind === 'duplicate') { respondJson(res, 200, { ok: true, id: outcome.id }); return }
+    if (outcome.kind === 'stale-base') { respondJson(res, 409, { reason: 'stale-base', revisions: outcome.revisions }); return }
+    if (outcome.kind === 'too-large') { respondJson(res, 413, { reason: 'too-large' }); return }
+    if (outcome.kind === 'unauthorized') { respondJson(res, 401, { reason: 'unauthorized' }); return }
+    respondJson(res, 400, { reason: 'bad-request' })
   }
 
   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
+    // 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
@@ -323,5 +378,5 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     send(socket, { type: 'workspace-state', workspaceTag: tag, revisions })
   }
 
-  return { handleSave, handleSubscribe, sendSaveError }
+  return { handleSave, handleSaveRest, handleSubscribe, sendSaveError }
 }

package/{server → server-e2e}/util.ts

@@ -8,6 +8,15 @@ import { randomBytes } from 'node:crypto'
 // is an Ed25519 public key; operator logs shouldn't carry it verbatim.
 export function debugTag(s: string): string { return `${s.slice(0, 12)}…` }
 
+// Truncated view of a content hash / staging id for logs (objstore GC +
+// 503 diagnostics). Same 12-char prefix convention as `debugTag`; named
+// separately so call sites read as "this is a blob id, not a workspace
+// tag". Tolerates a non-string (logs a placeholder) so a diagnostic
+// path can't itself throw on bad input.
+export function debugId(s: unknown): string {
+  return typeof s === 'string' ? `${s.slice(0, 12)}…` : '<no-id>'
+}
+
 // 16 random bytes → 22 base64url chars (no padding). The shared shape
 // for per-socket challenge nonces and staging ids — collision is
 // 1/2^128. `isValidStagingId` in objstore/store.ts validates exactly

package/{server → server-e2e}/ws-server.ts

@@ -16,6 +16,7 @@ import { Buffer } from 'node:buffer'
 import type { IncomingMessage as HttpRequest } from 'node:http'
 import { decodeUtf8 } from '../common/utf8.js'
 import type { SaveErrorReason } from '../common/save-error-reason.ts'
+import type { ServerInfo } from '../common/server-info.ts'
 import { Peer, type PeerRegistry } from './peer.ts'
 import { errMsg, errStack, randomId } from './util.ts'
 import type { SaveMsg, SubscribeMsg } from './sign.ts'
@@ -36,6 +37,9 @@ type IncomingMessage = {
 // SSE path doesn't need them.
 export type PeerConnectionDeps = {
   peers: PeerRegistry
+  // The mode this server advertises, emitted as the first `server-info`
+  // frame on every connection (see setupPeerConnection).
+  serverInfo: ServerInfo
   send: (socket: WebSocket, msg: object) => void
   unsubscribeAll: (socket: WebSocket) => void
   handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
@@ -55,33 +59,36 @@ export type WsServerDeps = PeerConnectionDeps & {
 }
 
 // Per-connection setup: create Peer, send challenge, wire message /
-// close / error / pong listeners. Shared between the WS connection
-// handler below and the SSE+POST adapter in ./sse-server.ts. The
-// `socket` parameter is the WebSocket-shaped surface (a real `ws`
-// `WebSocket`, or an `SseSession` cast through `as unknown as
-// WebSocket`); the function only uses the subset both expose.
+// close / error / pong listeners. `socket` is the WebSocket-shaped
+// surface — a real `ws` `WebSocket`, or an `SseSession` cast through
+// `as unknown as WebSocket`; only the subset both expose is used.
 export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: PeerConnectionDeps): void {
   const {
-    peers, send, unsubscribeAll, handleSave, handleSubscribe, handleAuthenticate,
+    peers, serverInfo, send, unsubscribeAll, handleSave, handleSubscribe, handleAuthenticate,
     sendSaveError, objstore, track, isShuttingDown, maxInflightPerSocket, debug,
   } = deps
   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.
+  // One Peer holds this connection's state, created before any client
+  // frame can arrive (`socket.on('message')` is wired below). The
+  // heartbeat sweep's two-tick liveness check (see below) is the only
+  // thing closing FDs for an otherwise-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
+  // Issue the per-connection challenge nonce FIRST — before the client can
+  // send anything that needs it, AND as frame #0 so clients/tests that
+  // positionally read the first frame as the challenge keep working. The
+  // client signs it into every `workspace-subscribe` (see canonicalSubscribe
+  // in server-e2e/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 })
+  // Then advertise the sync protocol (the mode probe), right after the
+  // challenge — the WS plane and the SSE fallback share this path. A client
+  // uses it to detect the mode, cache it, and refuse a cross-mode switch.
+  // Unauthenticated + mode-agnostic; an older client ignores it (predicate
+  // readers skip it; the workspaceTag demux drops it).
+  send(socket, { type: 'server-info', ...serverInfo })
   // Per-socket handlers are DELIBERATELY NOT serialized (vs the
   // client-side `messageQueue = messageQueue.then(...)` Promise
   // chain inside `client/triage-sync.ts:onTransportMessage`).
@@ -90,10 +97,10 @@ export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: P
   // 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
+  // `UNIQUE(workspace_tag, seq)` PK — see `server-e2e/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
+  // `server-e2e/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
@@ -133,7 +140,7 @@ export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: P
     // 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.
+    // audit `server-e2e/index.ts:590` + post-#58 audit follow-up.
     if (parsed.type === 'ping') {
       send(socket, { type: 'pong' })
       return
@@ -228,9 +235,8 @@ export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: P
   // 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.
+  // violations). `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)) })
 }
 

package/strip-types-loader.js

@@ -0,0 +1,94 @@
+// Module customization hook that erases TypeScript types using Node's
+// built-in `module.stripTypeScriptTypes()` — the same eraser that powers
+// Node's unflagged `.ts` execution, exposed here as an explicit loader so
+// this package can run its own `.ts` source after it's installed as a
+// dependency. Built on Node's bundled eraser, it needs no third-party dep
+// (cf. `amaro`, which is just the library Node already bundles for this).
+//
+// Why this is needed at all — Node DISABLES built-in `.ts` stripping for
+// any file under `node_modules` (it throws ERR_UNSUPPORTED_NODE_MODULES_
+// TYPE_STRIPPING), which is exactly where this package's `.ts` files live
+// once it's a dependency. A registered `load` hook is not bound by that
+// rule, so it restores `.ts` execution from inside `node_modules`.
+//
+// Registered as an entry point — `@preventive/triage/strip-types-loader` —
+// so consumers can run the server (or import `@preventive/triage/server`)
+// with the hook active:
+//   node --import @preventive/triage/strip-types-loader <entry>
+//
+// `registerHooks` (synchronous, in-thread) is used over the async,
+// worker-thread `module.register`: stripping is a pure synchronous string
+// transform, so there's no reason to round-trip every load through a
+// worker — and the read below is synchronous too.
+//
+// We must read + strip the source OURSELVES rather than delegate to
+// `nextLoad`: under `node_modules`, `nextLoad`'s default format detection
+// is what throws ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING, before our
+// hook ever sees the source. Reading the bytes and short-circuiting with
+// an explicit format sidesteps that gate.
+//
+// `mode: 'strip'` (types elided, no enum/namespace transform) suffices —
+// the repo is `erasableSyntaxOnly` (tsconfig.json). Strip mode replaces
+// each elided type with equal-width whitespace, so line AND column
+// positions survive 1:1 and stack traces stay exact without a source map.
+
+import { isUtf8 } from 'node:buffer'
+import { readFileSync } from 'node:fs'
+import { registerHooks, stripTypeScriptTypes } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+// `.ts` / `.mts` -> ESM, `.cts` -> CommonJS. The `kind` group is the
+// optional `m`/`c` infix; absent (plain `.ts`) defaults to ESM, which is
+// correct for this `"type": "module"` package.
+const TS_RE = /\.(?<kind>[cm])?ts$/u
+
+// Defence-in-depth: assert strip mode only ERASED — every output character
+// is either unchanged, replaced by whitespace, or replaced by a semicolon
+// (swc's ASI guard — swc-project/swc#9331). This enforces at runtime what
+// tsconfig's `erasableSyntaxOnly` asserts at type-check time: nothing but
+// type syntax was removed, so the bytes Node runs can't silently diverge
+// from the bytes we wrote.
+//
+// The comparison is per-CODE-POINT, not per-byte. swc preserves byte
+// offsets by swapping each elided multi-byte character for a *same-width*
+// Unicode whitespace char — e.g. an em-dash (U+2014) in a type-level
+// comment becomes U+2002 EN SPACE, not ASCII 0x20 — so a raw-byte check
+// would false-positive on the many such comments in this codebase. `\s`
+// matches those Unicode spaces, and strip preserves code-unit length too,
+// so string indices stay aligned.
+const WHITESPACE = /\s/u
+
+function assertOnlyErased(url, source, stripped) {
+  if (source.length !== stripped.length) {
+    throw new Error(`strip-types-loader: ${url} changed length ${source.length} -> ${stripped.length}; not a pure type erasure`)
+  }
+  for (let i = 0; i < stripped.length; i++) {
+    const ch = stripped[i]
+    if (ch === source[i] || ch === ';' || WHITESPACE.test(ch)) continue
+    throw new Error(`strip-types-loader: ${url} char ${i} changed ${JSON.stringify(source[i])} -> ${JSON.stringify(ch)}; not a pure type erasure`)
+  }
+}
+
+registerHooks({
+  load(url, context, nextLoad) {
+    const match = TS_RE.exec(new URL(url).pathname)
+    if (match) {
+      const bytes = readFileSync(fileURLToPath(url))
+      // Assert the source is valid UTF-8 before decoding: a mis-encoded
+      // file (latin-1, UTF-16, a stray binary) would otherwise decode with
+      // U+FFFD replacement chars and we'd strip / execute silent garbage.
+      if (!isUtf8(bytes)) {
+        throw new Error(`strip-types-loader: ${url} is not valid UTF-8`)
+      }
+      const raw = bytes.toString('utf8')
+      const stripped = stripTypeScriptTypes(raw, { mode: 'strip' })
+      assertOnlyErased(url, raw, stripped)
+      return {
+        format: match.groups.kind === 'c' ? 'commonjs' : 'module',
+        source: stripped,
+        shortCircuit: true,
+      }
+    }
+    return nextLoad(url, context)
+  },
+})