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

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

@@ -10,49 +10,30 @@
 // `base` points at the previous revision's `id` (or null for the
 // first revision in a workspace).
 //
-// `keyframe` is `1` for a revision the client emits with the full
-// state baked in (rather than just a delta). The wire-level flag
-// is also covered by the signature, so the column value MUST match
-// what the signed canonical bytes claim — `canonicalSave` in
-// `server/sign.ts` (called from `handleSave` in `server/index.ts`)
-// encodes `keyframe ? '1' : ''` into the bytes that `verifyEd25519`
-// then checks against the wire-supplied signature, so a wire flag
-// that doesn't match what the signer hashed fails verify and never
-// reaches this column. Client-driven: the server only stores what
-// the client sent and treats keyframes as catch-up roots when a
-// from=null subscriber arrives.
+// `keyframe` is `1` for a revision the client emits with full state
+// baked in (rather than a delta). The wire flag is covered by the
+// signature, so the column value MUST match the signed canonical
+// bytes: `canonicalSave` (server-e2e/sign.ts, via `handleSave`) encodes
+// `keyframe ? '1' : ''` into the bytes `verifyEd25519` checks, so a
+// mismatched wire flag fails verify and never reaches this column.
+// Client-driven: the server stores what the client sent and treats
+// keyframes as catch-up roots when a from=null subscriber arrives.
 //
 // `node:sqlite` is the built-in driver (Node ≥ 22 experimental,
-// stable in 24+). The driver is synchronous under the hood; the
-// Handle wraps each prepared statement so call sites `await`
-// uniformly. This is async-ready surface for a future async DB
-// backend — every operation today resolves in the current microtask
-// off a sync `node:sqlite` call.
+// stable in 24+), synchronous under the hood; the Handle wraps each
+// prepared statement so call sites `await` uniformly — async-ready
+// surface for a future async DB backend (every op resolves in the
+// current microtask off a sync call).
 //
-// Because operations are now async, two handlers can interleave
-// across an `await`. `commitRevision` (below) does NOT take an
-// in-process lock — it folds the dup recheck, base-equality check,
-// MAX(seq) and INSERT into ONE gated INSERT statement
-// (`commitRevisionSqlite` below):
-//   INSERT … SELECT COALESCE(MAX(seq),0)+1 … WHERE NOT EXISTS(dup)
-//     AND head IS base RETURNING seq
-// `node:sqlite` is synchronous, so that single statement runs to
-// completion without yielding the event loop — no concurrent commit
-// can interleave mid-statement, and the head-check + MAX(seq) read
-// from ONE consistent snapshot. That single-snapshot property is
-// what makes a per-tag lock redundant: the lock formerly existed
-// only to stop a chain fork where a racer read `head` from one
-// snapshot but `MAX(seq)` from a LATER one (after a sibling
-// committed) and inserted (seq=N+2, base=X) alongside the winner's
-// (seq=N+1, base=X) — same base, different seq, no PK conflict. With
-// both reads inside one statement that interleaving is impossible:
-// a racer's snapshot is either before the winner's commit (→ same
-// seq=N+1 → the UNIQUE(workspace_tag, seq) PK rejects the second →
-// recovery → stale-base) or after it (→ head ≠ base → no insert →
-// stale-base). Exactly one commits; the loser gets stale-base.
-// SQLite also serialises writers internally, and the PK backstops
-// the unsupported multi-connection case. See `commitRevisionSqlite`
-// for the full fork-safety argument.
+// Operations being async, two handlers can interleave across an
+// `await`. `commitRevision` (below) takes NO in-process lock — it
+// folds the dup recheck, base-equality check, MAX(seq) and INSERT
+// into ONE gated INSERT (`commitRevisionSqlite`). `node:sqlite` runs
+// that statement to completion without yielding, so its head-check +
+// MAX(seq) read ONE snapshot, which is what makes a per-tag lock
+// redundant. SQLite also serialises writers internally, and the PK
+// backstops the unsupported multi-connection case. See
+// `commitRevisionSqlite` for the full fork-safety argument.
 
 import { DatabaseSync } from 'node:sqlite'
 import { mkdirSync } from 'node:fs'
@@ -64,24 +45,20 @@ import {
   mapRevisionRow, toSqlitePlaceholders,
 } from './db-revision-sql.ts'
 
-// `CHECK (keyframe IN (0, 1))` is the value-domain guard on the
-// keyframe column. STRICT (the table marker) enforces the column's
-// TYPE — an INTEGER stays an INTEGER — but NOT its value range:
-// `keyframe = 2` is a perfectly valid integer that STRICT accepts,
-// which `mapRevisionRow`'s `=== 1` check then silently coerces back to
-// 0. That divergence between the stored row and the signed canonical
-// (which only ever encodes 0 / 1) poisons chain-replay verifies for
-// any peer who recomputes — the same operator-with-direct-DB-write
-// attack vector the STRICT guard in `openDbInner` catches for the
-// column TYPE. The CHECK closes the value-domain half, giving SQLite
-// the protection the Neon schema's identical `CHECK (keyframe IN
-// (0, 1))` carries (see `db-neon.ts`).
+// `CHECK (keyframe IN (0, 1))` is the value-domain guard. STRICT
+// (the table marker) enforces the column TYPE (an INTEGER stays an
+// INTEGER) but NOT its value range: `keyframe = 2` is a valid integer
+// STRICT accepts, which `mapRevisionRow`'s `=== 1` check then coerces
+// back to 0. That divergence from the signed canonical (only ever
+// 0 / 1) poisons chain-replay verifies for any recomputing peer — the
+// same operator-with-direct-DB-write vector the STRICT guard in
+// `openDbInner` catches for TYPE. The CHECK closes the value-domain
+// half, matching the Neon schema's identical CHECK (see `db-neon.ts`).
 //
-// `WORKSPACE_REVISION_DEF` is the parenthesised column + constraint
-// body (plus the STRICT marker), shared by the initial `CREATE TABLE`
-// and the `migrateAddKeyframeCheck` rebuild below — so a table the
-// rebuild produces is byte-identical in shape to a freshly-created
-// one, and a future column edit can't drift the two apart.
+// Parenthesised column + constraint body (plus STRICT marker), shared
+// by the initial `CREATE TABLE` and the `migrateAddKeyframeCheck`
+// rebuild below — so a rebuilt table is byte-identical in shape to a
+// fresh one and a future column edit can't drift the two apart.
 const WORKSPACE_REVISION_DEF = `(
     workspace_tag TEXT NOT NULL,
     seq INTEGER NOT NULL,
@@ -105,10 +82,10 @@ const SCHEMA = `
   ${WORKSPACE_REVISION_TAG_ID_INDEX};
 `
 
-// Row shape returned by the chain queries. SQLite stores `keyframe`
-// as INTEGER (0 / 1); `chainForWire` in server/index.ts normalises
-// to a strict boolean before broadcasting, but the raw row carries
-// the integer. `base` is nullable on the very first revision.
+// Row shape from the chain queries. `keyframe` is stored as INTEGER
+// (0 / 1); the raw row carries the integer — `chainForWire` in
+// server-e2e/index.ts normalises to a strict boolean before broadcasting.
+// `base` is nullable on the very first revision.
 export type RevisionRow = {
   base: string | null
   id: string
@@ -119,9 +96,8 @@ export type RevisionRow = {
 }
 
 // Input to `commitRevision`. `keyframe` is a strict boolean here —
-// the canonical-payload contract uses `=== true`, and the storage
-// path coerces to 0 / 1 via `keyframe ? 1 : 0` before hitting the
-// STRICT INTEGER column.
+// the canonical-payload contract uses `=== true`; the storage path
+// coerces to 0 / 1 before hitting the STRICT INTEGER column.
 export type RevisionInsert = {
   tag: string
   id: string
@@ -142,37 +118,31 @@ export type CommitResult =
   | { kind: 'duplicate' }
   | { kind: 'stale-base'; head: string | null }
 
-// Bag of pre-prepared statements + the underlying connection.
-// Held for the process lifetime; `close()` runs from `shutdown()`.
+// Pre-prepared statements + the underlying connection, held for the
+// process lifetime; `close()` runs from `shutdown()`.
 //
-// `db` is the raw `DatabaseSync` and is SQLite-only. The Neon
-// backend (`./db-neon.ts`) constructs a Handle with `db` unset.
-// Callers that reach into `db` directly (e.g. `openObjstore`,
-// test-only fixture SQL) are SQLite-coupled by construction —
-// passing them a Neon-backed Handle is the operator's mistake to
-// catch at the `if (DATABASE_URL)` switch in `server/index.ts`.
+// `db` is the raw `DatabaseSync`, SQLite-only — the Neon backend
+// (`./db-neon.ts`) constructs a Handle with `db` unset. Callers that
+// reach into `db` directly (e.g. `openObjstore`, test-only fixture
+// SQL) are SQLite-coupled by construction; passing them a Neon-backed
+// Handle is the operator's mistake to catch at the `if (DATABASE_URL)`
+// switch in `server-e2e/index.ts`.
 //
-// `tryCommit` is the backend-specific atomic-commit primitive that
+// `tryCommit` is the backend-specific atomic-commit primitive
 // `commitRevision` dispatches through. SQLite runs one synchronous
-// gated INSERT (no in-process lock — `node:sqlite` doesn't yield
-// mid-statement, so the head-check + MAX(seq) read one snapshot;
-// see `commitRevisionSqlite`). Neon wraps the dup-check + head-check
-// + gated INSERT in a pipelined transaction; it relies on Postgres'
-// READ-COMMITTED single-statement snapshot (the gated INSERT's
-// head-check and MAX(seq) read one snapshot) plus the
-// `UNIQUE(workspace_tag, seq)` PK to keep cross-replica racers from
-// forking the chain — see `db-neon.ts`'s `tryCommitNeon`.
+// gated INSERT (see `commitRevisionSqlite`); Neon wraps it in a
+// pipelined transaction (see `db-neon.ts`'s `tryCommitNeon`). Both
+// rely on a single-statement snapshot + the `UNIQUE(workspace_tag,
+// seq)` PK for fork-safety; see those functions for the argument.
 //
 // `gatedInsert` is SQLite-only (like `db`): it backs
-// `commitRevisionSqlite`'s single gated INSERT (the dup-gate +
-// head-equals-base-gate + server-assigned seq folded into one
-// statement, mirroring the Neon path's gated INSERT). The Neon
-// backend leaves it unset — its gated INSERT lives inside the
-// pipelined `sql.transaction([...])`, not a standalone statement
-// object. Kept on the Handle (rather than a module-private closure)
-// so the SQLite white-box tests can wrap `.get` to inject a
-// unique-violation / non-unique failure into the commit, the same
-// recovery paths the Neon suite stages via `failNextCommit`.
+// `commitRevisionSqlite`'s single gated INSERT. The Neon backend
+// leaves it unset — its gated INSERT lives inside the pipelined
+// `sql.transaction([...])`, not a standalone statement object. Kept
+// on the Handle (not a module-private closure) so SQLite white-box
+// tests can wrap `.get` to inject a unique-violation / non-unique
+// failure into the commit, exercising the same recovery paths the
+// Neon suite stages via `failNextCommit`.
 export type Handle = {
   db?: DatabaseSync
   headFor: GetStmt<[string], { id: string }>
@@ -184,7 +154,7 @@ export type Handle = {
   revisionExists: GetStmt<[string, string], unknown>
   // Single-revision fetch by content-addressed id. The cross-instance
   // pubsub receiver uses this to assemble a `workspace-state` from a
-  // NOTIFY hint (see `server/pubsub.ts`).
+  // NOTIFY hint (see `server-e2e/pubsub.ts`).
   revisionById: GetStmt<[string, string], RevisionRow>
   gatedInsert?: GetStmt<[string, string, string | null, number, string, string, string, number], { seq: number }>
   tryCommit: (input: RevisionInsert) => Promise<CommitResult>
@@ -192,23 +162,22 @@ export type Handle = {
 }
 
 // Narrowing alias for the SQLite-backed Handle: `db` is guaranteed
-// to be set. `openDb` returns this so call sites that need direct
+// set. `openDb` returns this so call sites needing direct
 // `DatabaseSync` access (e.g. `openObjstore(handle.db, …)` in
-// `server/index.ts`'s SQLite branch) can reach `handle.db` without
-// an optional-chain or non-null assertion. A Neon-backed Handle
-// (`openNeonDb`) keeps the wider `db?: DatabaseSync` shape; routing
-// a Neon Handle into a SQLite-coupled call site is a compile-time
-// error. Mirrors the same pattern in `server/objstore/store.ts`.
+// `server-e2e/index.ts`'s SQLite branch) reach `handle.db` without an
+// optional-chain or non-null assertion. A Neon-backed Handle
+// (`openNeonDb`) keeps the wider `db?: DatabaseSync` shape, so routing
+// one into a SQLite-coupled call site is a compile-time error. Mirrors
+// `server-e2e/objstore/store.ts`.
 export type SqliteHandle = Handle & { db: DatabaseSync }
 
 export function openDb(path: string): SqliteHandle {
   mkdirSync(dirname(path), { recursive: true })
   const db = new DatabaseSync(path)
-  // Any throw between the DatabaseSync constructor and the return
-  // would otherwise leak the underlying file / WAL / shm locks until
-  // process exit — close before re-raising so the operator can fix
-  // the underlying issue (failed STRICT check, ALTER TABLE error,
-  // …) and re-run without a stale lock pinning the file.
+  // A throw between the DatabaseSync constructor and the return would
+  // leak the file / WAL / shm locks until process exit — close before
+  // re-raising so the operator can fix the cause (failed STRICT check,
+  // ALTER TABLE error, …) and re-run without a stale lock on the file.
   try {
     return openDbInner(db)
   } catch (err) {
@@ -218,35 +187,30 @@ export function openDb(path: string): SqliteHandle {
 }
 
 function openDbInner(db: DatabaseSync): SqliteHandle {
-  // WAL gives concurrent readers + faster writes and survives
-  // crashes between commits without corrupting the file. Foreign
-  // keys aren't strictly needed here (single-table schema) but
-  // turning them on preserves the option to add referential
-  // tables later without revisiting init.
+  // WAL gives concurrent readers + faster writes and survives crashes
+  // between commits without corrupting the file. Foreign keys aren't
+  // needed here (single-table schema) but turning them on keeps the
+  // option to add referential tables later without revisiting init.
   db.exec('PRAGMA journal_mode = WAL;')
   // FULL (not NORMAL): the server emits `workspace-save-ack` BEFORE
-  // returning to the event loop after `commitRevision`. With NORMAL,
-  // SQLite only fsyncs at WAL checkpoint, so a power loss between
-  // ack and the next checkpoint loses the row even though the
-  // originator and broadcast peers were told the revision committed.
-  // FULL fsyncs per commit; durability matches the contract the
-  // ack implies. Trade-off is per-commit fsync latency, acceptable
-  // for the protocol's edit-driven write pattern (triage edits, not
-  // streaming throughput). Audit round-9 M1.
+  // returning to the event loop after `commitRevision`. NORMAL only
+  // fsyncs at WAL checkpoint, so a power loss between ack and the next
+  // checkpoint loses a row the originator + peers were told committed.
+  // FULL fsyncs per commit, matching the durability the ack implies.
+  // Trade-off is per-commit fsync latency, acceptable for the edit-
+  // driven write pattern (triage edits, not streaming). Audit round-9 M1.
   db.exec('PRAGMA synchronous = FULL;')
   db.exec('PRAGMA foreign_keys = ON;')
   db.exec(SCHEMA)
   // Fail-loud on a pre-existing non-STRICT table — `CREATE TABLE IF
-  // NOT EXISTS … STRICT` is a no-op when the table already exists,
-  // so a deployment that predates the STRICT marker would silently
-  // keep its non-STRICT shape. Without STRICT, an operator with
-  // direct DB write access could insert mis-typed rows (e.g. a
-  // `keyframe = "1\nfoo"` text value in the INTEGER column) and
-  // poison the chain — the signed canonical the client originally
-  // hashed says `keyframe = 1`, but the stored `keyframe = "1\nfoo"`
-  // round-trips back into the canonical as a different string,
-  // making every subsequent verify fail. Operator must migrate
-  // before this server boots.
+  // NOT EXISTS … STRICT` is a no-op when the table exists, so a
+  // deployment predating the STRICT marker keeps its non-STRICT shape.
+  // Without STRICT, an operator with direct DB write access could
+  // insert mis-typed rows (e.g. `keyframe = "1\nfoo"` text in the
+  // INTEGER column) and poison the chain: the signed canonical says
+  // `keyframe = 1`, but the stored text round-trips into the canonical
+  // as a different string, failing every subsequent verify. Operator
+  // must migrate before this server boots.
   const meta = db.prepare(
     `SELECT strict FROM pragma_table_list WHERE schema = 'main' AND name = 'workspace_revision'`,
   ).get() as { strict: number } | undefined
@@ -254,13 +218,11 @@ function openDbInner(db: DatabaseSync): SqliteHandle {
     throw new Error('workspace_revision is non-STRICT — migrate via rename+create+copy before booting')
   }
   // Idempotent migration for DBs created before the keyframe column
-  // existed. Inspect the column list rather than catching every
-  // ALTER error — the previous shape swallowed `try { ALTER } catch
-  // {}` for ANY failure (lock contention, disk full, corrupt page),
-  // masking real problems as "column already exists". Now we only
-  // ALTER when the column is genuinely missing, and any failure of
-  // the ALTER itself bubbles up as an open-time crash where the
-  // operator can act on it.
+  // existed. Inspect the column list rather than `try { ALTER } catch
+  // {}`: a blanket catch swallows ANY failure (lock contention, disk
+  // full, corrupt page) as "column already exists". ALTER only when
+  // the column is genuinely missing, so an ALTER failure bubbles up as
+  // an open-time crash the operator can act on.
   const columns = db.prepare(`PRAGMA table_info(workspace_revision)`).all() as Array<{ name: string }>
   if (!columns.some((c) => c.name === 'keyframe')) {
     // ADD COLUMN carries the CHECK so a legacy DB migrating up lands
@@ -507,9 +469,8 @@ export function commitRevision(handle: Handle, input: RevisionInsert): Promise<C
 //     base gate fails → `stale-base`.
 //   • Two retransmits with the same id: the second's dup gate fails →
 //     `duplicate`.
-// These are PROVEN green, unchanged, by the no-fork concurrency tests
-// in `tests/server-db.test.js` (two/N concurrent same-base, mixed,
-// chainFrom-during-commits) which now pass with no lock present.
+// Covered by the no-fork concurrency tests in `tests/server-db.test.js`
+// (two/N concurrent same-base, mixed, chainFrom-during-commits).
 //
 // SQLite serialises writers internally even ACROSS connections, but a
 // multi-connection deployment is unsupported regardless. The

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

@@ -10,6 +10,7 @@ import { type IncomingMessage as HttpRequest, type Server, type ServerResponse,
 import { Buffer } from 'node:buffer'
 import { fileURLToPath } from 'node:url'
 import type { WebSocketServer } from 'ws'
+import { CONFIG_PATH, type ServerInfo } from '../common/server-info.ts'
 import { type ObjstoreRestDeps, handleRest, matchRoute } from './objstore/rest.ts'
 import { SSE_OPEN_PATH, type SseServer } from './sse-server.ts'
 import { dispatchNpmAdvisories } from './npm-proxy.ts'
@@ -20,6 +21,12 @@ import { errStack } from './util.ts'
 // similar) can route `/api/*` → this process and `/*` → the static UI
 // bundle with a single location block.
 export const WS_UPGRADE_PATH = '/api/sync'
+// Session-independent triage-sync save plane: `POST /api/sync/save`. The
+// SSE-mode alternative to the in-band `workspace-save` frame — a save POSTed
+// here commits + broadcasts WITHOUT taking over the client's SSE event-stream
+// (each in-band POST forces a stream takeover; see sse-server.ts). Sibling of
+// the WS upgrade path so one nginx `/api/*` block routes both.
+export const SAVE_REST_PATH = '/api/sync/save'
 function isUpgradePath(url: string | undefined): boolean {
   if (typeof url !== 'string') return false
   // Strip `?…` so clients can carry build / debug tags. Exact match
@@ -34,6 +41,10 @@ type HasHeaders = { headers: HttpRequest['headers'] }
 export type HttpServerDeps = {
   wss: WebSocketServer
   restDeps: ObjstoreRestDeps
+  // This server's `server-info` (mode advertisement), served as JSON at
+  // GET /api/config so a client can detect the protocol without a sync
+  // connection (the WS connect frame stays the source of truth).
+  serverInfo: ServerInfo
   // SSE+POST fallback. Owns its own session map + lifecycle; we just
   // give it first crack at requests that match `SSE_OPEN_PATH`. Same
   // same-origin / shutdown gates run BEFORE the dispatch so the SSE
@@ -42,12 +53,68 @@ export type HttpServerDeps = {
   isOriginAllowed: (req: HasHeaders) => boolean
   isShuttingDown: () => boolean
   track: (promise: Promise<unknown>) => void
+  // Handler for `POST /api/sync/save` (see SAVE_REST_PATH). Owns body parse +
+  // the save pipeline + JSON response; this module owns the gates (method,
+  // same-origin, shutdown, idle-timeout) and the graceful-drain tracking.
+  handleSaveRest: (req: HttpRequest, res: ServerResponse) => Promise<void>
   restPutIdleTimeoutMs: number
   debug: boolean
 }
 
+// `POST /api/sync/save` dispatch. Returns the in-flight handler promise when
+// the request matched the route (the caller `track`s it for graceful drain),
+// or null when it's for a different route. The gate ladder — method →
+// shutdown → same-origin → idle-timeout — mirrors the objstore REST branch; a
+// gate rejection writes its own response and returns an already-settled
+// promise. Kept out of `createHttpServer` so that dispatcher stays compact.
+function dispatchSaveRest(
+  req: HttpRequest, res: ServerResponse,
+  deps: {
+    handleSaveRest: (req: HttpRequest, res: ServerResponse) => Promise<void>
+    isOriginAllowed: (req: HasHeaders) => boolean
+    isShuttingDown: () => boolean
+    restPutIdleTimeoutMs: number
+    debug: boolean
+  },
+): Promise<void> | null {
+  if (typeof req.url !== 'string' || req.url.split('?', 1)[0] !== SAVE_REST_PATH) return null
+  if (req.method !== 'POST') {
+    res.writeHead(405, { 'content-type': 'application/json', 'allow': 'POST', 'connection': 'close' })
+    res.end(JSON.stringify({ error: 'method-not-allowed' }))
+    return Promise.resolve()
+  }
+  // Shutdown gate — parity with the objstore REST branch (a POST on an
+  // existing keep-alive socket after SIGTERM but before close() drains).
+  if (deps.isShuttingDown()) {
+    res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+    res.end(JSON.stringify({ error: 'shutting-down' }))
+    return Promise.resolve()
+  }
+  // Same-origin gate — a hostile cross-origin page would carry an Origin
+  // header (browser-set on fetch); same-origin XHR may omit it (allowed).
+  if (!deps.isOriginAllowed(req)) {
+    res.writeHead(403, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({ error: 'origin-denied' }))
+    return Promise.resolve()
+  }
+  // Idle-body timeout — a slow-loris trickling the JSON body would otherwise
+  // hold the connection indefinitely.
+  req.setTimeout(deps.restPutIdleTimeoutMs, () => {
+    if (deps.debug) console.warn(`sync-save REST idle ${deps.restPutIdleTimeoutMs}ms → abort`)
+    try { req.destroy(new Error('idle-timeout')) } catch {}
+  })
+  // Outer catch is the unhandled-rejection guard for a throw OUTSIDE the
+  // handler's own try/catch — logs and terminates the response so the TCP
+  // socket doesn't dangle (same policy as the objstore handleRest wrapper).
+  return deps.handleSaveRest(req, res).catch((err) => {
+    console.warn('sync-save REST handler error:', errStack(err))
+    if (res.headersSent) { try { res.destroy() } catch {} }
+    else { try { res.writeHead(500, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: 'internal' })) } catch {} }
+  })
+}
+
 export function createHttpServer(deps: HttpServerDeps): Server {
-  const { wss, restDeps, sseServer, isOriginAllowed, isShuttingDown, track, restPutIdleTimeoutMs, debug } = deps
+  const { wss, restDeps, sseServer, serverInfo, isOriginAllowed, isShuttingDown, track, handleSaveRest, restPutIdleTimeoutMs, debug } = deps
   // Static-file plane (see ./static.ts). The directory is the
   // `build.js build` output sibling to this file; the loader handles
   // enumeration, pre-compression, and ETag derivation. Plugged in after
@@ -55,6 +122,19 @@ export function createHttpServer(deps: HttpServerDeps): Server {
   const handleStatic = loadStatic(fileURLToPath(new URL('../out', import.meta.url)))
 
   const httpServer = createServer((req: HttpRequest, res: ServerResponse) => {
+    // Static mode probe: GET /api/config → this server's `server-info` as JSON.
+    // A client uses it to detect the protocol up front; the WS connect frame
+    // stays the source of truth and catches a later mode change. Public, no body.
+    if (typeof req.url === 'string' && req.url.split('?', 1)[0] === CONFIG_PATH) {
+      if (req.method !== 'GET') {
+        res.writeHead(405, { 'content-type': 'application/json', allow: 'GET' })
+        res.end(JSON.stringify({ error: 'method-not-allowed' }))
+        return
+      }
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' })
+      res.end(JSON.stringify(serverInfo))
+      return
+    }
     // SSE+POST fallback plane. Same-origin gate first (Origin header
     // is set by the browser on cross-origin EventSource + fetch, so
     // a hostile origin would surface here just like it does on the
@@ -76,6 +156,12 @@ export function createHttpServer(deps: HttpServerDeps): Server {
       // the lifecycle's sseSessions() close loop.
       if (sseServer.handle(req, res)) return
     }
+    // Triage-sync save REST plane (see SAVE_REST_PATH) — session-independent
+    // `POST /api/sync/save` so an SSE-mode save doesn't take over the
+    // event-stream. The dispatch helper owns the gate ladder; we `track` the
+    // returned in-flight promise so SIGTERM drains it (mirrors npm-advisories).
+    const saveP = dispatchSaveRest(req, res, { handleSaveRest, isOriginAllowed, isShuttingDown, restPutIdleTimeoutMs, debug })
+    if (saveP) { track(saveP); return }
     // npm advisories proxy — same-origin + shutdown gates live in the
     // helper so this dispatcher stays compact. `dispatchNpmAdvisories`
     // returns the in-flight promise (or null when the route didn't
@@ -103,20 +189,22 @@ export function createHttpServer(deps: HttpServerDeps): Server {
       // that holds a valid token (e.g. via XSS that read a freshly-minted
       // one) would PUT with its own Origin header — caught here.
       // Same-origin XHR/fetch may omit Origin; that path is allowed (see
-      // `isOriginAllowed`). Transport audit `server/objstore/rest.ts:103`.
+      // `isOriginAllowed`). Transport audit `server-e2e/objstore/rest.ts:103`.
       if (!isOriginAllowed(req)) {
         res.writeHead(403, { 'content-type': 'application/json' })
         res.end(JSON.stringify({ error: 'origin-denied' }))
         return
       }
-      // PUT idle-body timeout — a slow-loris client trickling bytes
-      // within the declared Content-Length holds the staging fd + an
-      // inFlightSids slot indefinitely. `req.setTimeout` fires on
-      // inactivity; we destroy the request, aborting the body pipeline.
-      // Transport audit `server/objstore/rest.ts:218`.
-      if (req.method === 'PUT') {
+      // Idle-body timeout for the body-bearing REST methods — a slow-loris
+      // client trickling bytes holds the connection (and, for PUT, the
+      // staging fd + inFlightSids slot) indefinitely. PUT carries the raw
+      // blob within its declared Content-Length; POST carries the small
+      // fetch-mint JSON body. `req.setTimeout` fires on inactivity; we
+      // destroy the request, aborting the body pipeline.
+      // Transport audit `server-e2e/objstore/rest.ts:218`.
+      if (req.method === 'PUT' || req.method === 'POST') {
         req.setTimeout(restPutIdleTimeoutMs, () => {
-          if (debug) console.warn(`REST PUT idle ${restPutIdleTimeoutMs}ms → abort`)
+          if (debug) console.warn(`REST ${req.method} idle ${restPutIdleTimeoutMs}ms → abort`)
           try { req.destroy(new Error('idle-timeout')) } catch {}
         })
       }

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

@@ -21,13 +21,13 @@ export type Hub = {
   // WS-originated broadcasts pass the originator so it doesn't see its
   // own message echoed back. Local-only: callers that ALSO want a
   // cross-instance fan-out are expected to publish to the pubsub bus
-  // alongside this call (server/pubsub.ts). The hub deliberately stays
+  // alongside this call (server-e2e/pubsub.ts). The hub deliberately stays
   // ignorant of the bus so its transport invariants (backpressure cap,
   // stringify-once, terminate-on-overflow) are unchanged.
   broadcast(tag: string, msg: object, except: WebSocket | null): void
   // Broadcasts an ALREADY-SERIALISED payload to every local subscriber
   // for `tag`. Used by the pubsub bus receiver
-  // (server/bus-receiver.ts, wired up from server/index.ts) to relay
+  // (server-e2e/bus-receiver.ts, wired up from server-e2e/index.ts) to relay
   // a remote-instance event into this instance's fan-out. No `except`:
   // the originator is on a different instance by construction.
   broadcastLocalRaw(tag: string, payload: string): void
@@ -71,7 +71,7 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     // kernel yet — a slow / blackholed peer accumulates them unboundedly
     // during fan-out broadcasts. Drop above the cap and terminate the
     // socket so the heartbeat doesn't keep it alive on ping/pong while
-    // every broadcast piles up. Transport audit `server/index.ts:225`.
+    // every broadcast piles up. Transport audit `server-e2e/index.ts:225`.
     if (socket.bufferedAmount > maxBufferedBytes) {
       if (debug) console.warn(`drop broadcast: socket buffered ${socket.bufferedAmount}B > cap`)
       try { socket.terminate() } catch {}
@@ -102,12 +102,11 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
   }
 
   function fanOut(set: Set<WebSocket>, payload: string, except: WebSocket | null): void {
-    // Snapshot before iterating — `send`'s try/catch swallows
-    // socket.send errors, but a socket transitioning to CLOSED
+    // Snapshot before iterating — a socket transitioning to CLOSED
     // mid-broadcast triggers `unsubscribeAll` from the 'close' handler,
-    // which mutates `set` while we're walking it. The snapshot keeps a
-    // future refactor (different collection, async send) from silently
-    // skipping subscribers. Audit M4 round-3.
+    // mutating `set` while we walk it. The snapshot also keeps a future
+    // refactor (different collection, async send) from silently skipping
+    // subscribers. Audit M4 round-3.
     for (const s of [...set]) {
       if (s === except) continue
       sendRaw(s, payload)