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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT",
   "author": {
@@ -28,11 +28,18 @@
     "#client/sync.js": "./client/sync.js",
     "#client/sync-host.js": "./client/sync-host.js"
   },
+  "exports": {
+    "./server": "./server/index.ts",
+    "./strip-types-loader": "./strip-types-loader.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
-    "triage-server": "server/index.ts"
+    "triage-server": "server/cli.js"
   },
   "files": [
     "server/auth.ts",
+    "server/bus-receiver.ts",
+    "server/cli.js",
     "server/config.ts",
     "server/db-neon.ts",
     "server/db-revision-sql.ts",
@@ -43,6 +50,7 @@
     "server/index.ts",
     "server/lifecycle.ts",
     "server/neon-driver.ts",
+    "server/npm-proxy.ts",
     "server/objstore/blob-fs.ts",
     "server/objstore/blob-vercel.ts",
     "server/objstore/blob.ts",
@@ -57,7 +65,10 @@
     "server/objstore/tokens.ts",
     "server/origin.ts",
     "server/peer.ts",
+    "server/pubsub.ts",
     "server/sign.ts",
+    "server/sse-server.ts",
+    "server/sse-session.ts",
     "server/static.ts",
     "server/sync-handlers.ts",
     "server/util.ts",
@@ -78,7 +89,8 @@
     "out/terminal.js",
     "out/view.css",
     "out/view.html",
-    "out/view.js"
+    "out/view.js",
+    "strip-types-loader.js"
   ],
   "scripts": {
     "lint": "node --run lint:js && node --run lint:css && node --run lint:ts",

package/server/auth.ts

@@ -76,6 +76,17 @@ export function createAuth(deps: {
   }
   function handleAuthenticate(socket: WebSocket, msg: AuthenticateMsg): void {
     if (typeof msg.password !== 'string' || msg.password.length === 0 || msg.password.length > MAX_AUTH_PASSWORD_LEN) return
+    // Already-authorized short-circuit. The SSE plane carries
+    // `body.password` on every POST (sse-server.ts:dispatchBody
+    // synthesises a fresh `authenticate` frame each time), so re-
+    // emitting `authenticated` per POST would chatter the wire AND
+    // re-fire triage-sync's `authenticated` consumer hook (its "kick
+    // deferred sends" path) on every flush. The wire signal is needed
+    // exactly once per `unauthorized → authorized` transition; after
+    // that, the client already knows. WS plane unaffected (sends
+    // authenticate at most once per socket per the runAuthFlow guard
+    // in client/sync/socket-transport.ts).
+    if (isAuthorized(socket)) return
     // No-config short-circuit: when not gating, treat any authenticate
     // as success so a client can cache + replay its password on
     // reconnect even against an un-gated server (wire shape stays

package/server/bus-receiver.ts

@@ -0,0 +1,95 @@
+// Cross-instance bus receiver: maps a `BusMessage` envelope (lookup
+// hint + sender from the Postgres LISTEN/NOTIFY channel) into a local
+// wire broadcast. Pulled out of `server/index.ts` so the rev / objput /
+// objdel branches — including the keyframe boolean coercion and the
+// `objectMetaWire` shape — are testable without bringing up the whole
+// server.
+//
+// The receiver mirrors the publisher's commit→broadcast→publish
+// ordering, just shifted by the bus round-trip:
+//   1. NOTIFY lands → bus envelope arrives here.
+//   2. For hint-only kinds (rev, objput) re-fetch the row from the
+//      shared DB; for self-contained kinds (objdel) skip the fetch.
+//   3. Broadcast to LOCAL subscribers via `broadcastLocalRaw` with no
+//      `except` — the originator is on a DIFFERENT instance by
+//      construction, so it must NOT be filtered out (the symmetric
+//      same-instance broadcast already happened on the publisher).
+
+import type { Handle as DbHandle } from './db.ts'
+import { type Handle as ObjstoreHandle, getLive, objectMetaWire } from './objstore/store.ts'
+import type { BusMessage } from './pubsub.ts'
+
+export type BusReceiverDeps = {
+  // Read-side of the workspace_revision Handle (the bus uses only
+  // `revisionById`; the publisher path uses the full Handle). Typed
+  // as the broader Handle for ease of wiring at the call site.
+  handle: DbHandle
+  // Read-side of the objstore Handle (used for `getLive` on objput).
+  objstoreHandle: ObjstoreHandle
+  // Local-only fan-out into this instance's subscriber map. The
+  // payload is pre-serialised so the hub can stringify once for N
+  // subscribers (mirrors the existing `broadcast` fast path).
+  broadcastLocalRaw: (tag: string, payload: string) => void
+  debug: boolean
+}
+
+export function createBusReceiver(deps: BusReceiverDeps): (msg: BusMessage) => Promise<void> {
+  const { handle, objstoreHandle, broadcastLocalRaw, debug } = deps
+  return async (msg) => {
+    if (msg.kind === 'rev') {
+      const row = await handle.revisionById.get(msg.tag, msg.id)
+      if (!row) {
+        // Not found is expected when a peer instance published a
+        // revision id that hasn't replicated to this instance yet —
+        // shouldn't happen on a single-primary Neon endpoint, but a
+        // future read-replica deployment could see it transiently.
+        // Drop the broadcast; the client will reconcile via chain
+        // re-pull on its next subscribe.
+        if (debug) console.warn(`pubsub: revision ${msg.id.slice(0, 8)}… not found for ${msg.tag.slice(0, 12)}…`)
+        return
+      }
+      broadcastLocalRaw(msg.tag, JSON.stringify({
+        type: 'workspace-state',
+        workspaceTag: msg.tag,
+        // Mirror `chainForWire`'s strict-boolean coercion in
+        // ./sync-handlers.ts — the DB stores `keyframe` as an integer
+        // (0/1) but the wire contract uses strict `=== true`.
+        revisions: [{ ...row, keyframe: row.keyframe === 1 }],
+      }))
+      return
+    }
+    if (msg.kind === 'objput') {
+      const row = await getLive(objstoreHandle, msg.tag, msg.res)
+      if (!row) {
+        // Possible after a remote put → remote delete sequence where
+        // both NOTIFYs landed by the time we processed the put. The
+        // subsequent objdel NOTIFY will (or has) drive the right
+        // broadcast — skip silently. Also possible under a future
+        // read-replica deployment with replication lag.
+        if (debug) console.warn(`pubsub: objput ${msg.res.slice(0, 8)}… missing for ${msg.tag.slice(0, 12)}…`)
+        return
+      }
+      // Note: `getLive` returns the CURRENT live row, which may be a
+      // strictly NEWER version than the NOTIFY referred to (two
+      // closely-spaced puts on one resourceTag arrive at the receiver
+      // with the DB already showing v2 for both). Broadcasting v2 twice
+      // is sound — client `putHandlers` already absorb same-instance
+      // PUT echoes (rest.ts uses `except: null`), so handlers must be
+      // idempotent on (resourceTag, version) anyway.
+      broadcastLocalRaw(msg.tag, JSON.stringify({
+        type: 'objstore-put',
+        workspaceTag: msg.tag,
+        ...objectMetaWire(row),
+      }))
+      return
+    }
+    // 'objdel' — the row is gone from workspace_object post-commit, so
+    // the bus payload itself IS the wire data; no DB lookup.
+    broadcastLocalRaw(msg.tag, JSON.stringify({
+      type: 'objstore-deleted',
+      workspaceTag: msg.tag,
+      resourceTag: msg.res,
+      version: msg.ver,
+    }))
+  }
+}

package/server/cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Executable entry for the `triage-server` bin.
+//
+// Node refuses to strip TypeScript types from files under node_modules
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so once this package is
+// installed as a dependency, server/index.ts can't be executed directly.
+// This launcher registers the built-in-type-stripping hook FIRST
+// (synchronous, in-thread — see ../strip-types-loader.js), then loads the
+// server with the hook active and starts it.
+//
+// The `await import()` is load-bearing: a static `import './index.ts'`
+// would be fetched during this module's instantiation — before the body
+// runs and before the hook is registered — and would hit the node_modules
+// strip error. Deferring to a dynamic import runs it only after the static
+// `../strip-types-loader.js` import has evaluated and registered the hook.
+//
+// Because the server is imported here (not the process entry), its
+// `import.meta.main` auto-start gate stays off, so we call the exported
+// `start()` ourselves.
+import '../strip-types-loader.js'
+const { start } = await import('./index.ts')
+start()

package/server/db-neon.ts

@@ -10,9 +10,14 @@
 // (`autoInstallPeers: false` in `pnpm-workspace.yaml`) and never
 // reaches the import.
 //
-// API shape: `neon(connectionString)` returns a tagged-template +
-// callable function. We use the function-call form
-// `sql(text, params)`. `tryCommitNeon` (below) folds the dup-check
+// API shape: `neon(connectionString)` returns a tagged-template
+// callable with a `.query(text, params)` value-placeholder method.
+// We use the `sql.query(text, params)` form everywhere — our queries
+// are dynamically composed strings + parameter arrays from
+// `./db-revision-sql.ts`, so the tagged-template form doesn't fit.
+// The function-call form (`sql(text, params)`) that the 0.x driver
+// accepted was removed in `@neondatabase/serverless@1.0.0`; the peer
+// dep declares `^1.0.2`. `tryCommitNeon` (below) folds the dup-check
 // + head-check + gated INSERT into a single pipelined
 // `sql.transaction([...])` — NO commit-time advisory lock. The gated
 // INSERT's head-check and `MAX(seq)` run inside one Postgres
@@ -46,7 +51,8 @@ import type { AllStmt, GetStmt, RunStmt } from './db-stmt.ts'
 import { type CommitResult, type Handle, type RevisionInsert, type RevisionRow, isUniqueViolation } from './db.ts'
 import {
   CHAIN_AFTER_SQL, CHAIN_ALL_SQL, CHAIN_FROM_SQL, GATED_INSERT_SQL_PG, HEAD_FOR_SQL,
-  LAST_KEYFRAME_SEQ_SQL, REVISION_EXISTS_SQL, SEQ_OF_ID_SQL, mapRevisionRow, num, numOrNull,
+  LAST_KEYFRAME_SEQ_SQL, REVISION_BY_ID_SQL, REVISION_EXISTS_SQL, SEQ_OF_ID_SQL,
+  mapRevisionRow, num, numOrNull,
 } from './db-revision-sql.ts'
 
 // `num` / `numOrNull` (safe-integer BIGINT coercion) live in the shared
@@ -70,15 +76,16 @@ export { num, numOrNull }
 // side. Used by the DDL bootstrap below to prevent partial schema
 // creation on a transient mid-batch network failure.
 //
-// `transaction` is typed against the query promise the call form
+// `transaction` is typed against the query promise `sql.query`
 // returns (NOT plain `Promise<unknown>`) so a misuse like
 // `sql.transaction([Promise.resolve(123)])` fails at compile time
 // rather than failing opaquely inside the driver. The driver itself
 // inspects each promise's internal shape and rejects non-query
 // promises at runtime; the type narrows that to a static error.
-type NeonQueryPromise = ReturnType<NeonSqlCall>
-type NeonSqlCall = (queryText: string, params?: readonly unknown[]) => Promise<unknown[]>
-export type NeonSql = NeonSqlCall & {
+type NeonQueryPromise = ReturnType<NeonQueryCall>
+type NeonQueryCall = (queryText: string, params?: readonly unknown[]) => Promise<unknown[]>
+export type NeonSql = {
+  query: NeonQueryCall
   transaction: (queries: NeonQueryPromise[]) => Promise<unknown[][]>
 }
 
@@ -103,7 +110,7 @@ const DDL_LOCK_KEY_REVISION_SUB = 0x7273_6e72 // 'rsnr'
 const DURABLE_SYNC_COMMIT_LEVELS = new Set(['local', 'on', 'remote_write', 'remote_apply'])
 
 export async function assertDurableSyncCommit(sql: NeonSql): Promise<void> {
-  const rows = await sql(`SHOW synchronous_commit`, []) as Array<{ synchronous_commit?: unknown }>
+  const rows = await sql.query(`SHOW synchronous_commit`, []) as Array<{ synchronous_commit?: unknown }>
   const level = String(rows[0]?.synchronous_commit ?? '').trim().toLowerCase()
   if (!DURABLE_SYNC_COMMIT_LEVELS.has(level)) {
     throw new Error(
@@ -156,7 +163,7 @@ const SCHEMA_PG = [
 
 // Generic statement-builder helpers shared by both Neon planes
 // (workspace_revision here + the objstore tables in store-neon.ts).
-// They remove the repeated `{ run/get: async (...args) => sql(...) }`
+// They remove the repeated `{ run/get: async (...args) => sql.query(...) }`
 // wrapper for the statements whose positional args map straight to
 // the query's `$1..$N` placeholders and whose rows need no coercion.
 // Statements that coerce BIGINT (via `num`) or map snake_case rows
@@ -165,14 +172,14 @@ const SCHEMA_PG = [
 
 // Trivial passthrough write: args → $1..$N in order, no result shape.
 export function runStmt<P extends unknown[]>(sql: NeonSql, query: string): RunStmt<P> {
-  return { run: async (...args: P) => { await sql(query, args as readonly unknown[]) } }
+  return { run: async (...args: P) => { await sql.query(query, args as readonly unknown[]) } }
 }
 
 // First-row read with no coercion (callers needing BIGINT→number or
 // snake_case mapping build their own). Returns `undefined` on the
 // empty result set, matching the SQLite `wrapGet` contract.
 export function getRowStmt<P extends unknown[], T>(sql: NeonSql, query: string): GetStmt<P, T> {
-  return { get: async (...args: P) => (await sql(query, args as readonly unknown[]) as T[])[0] }
+  return { get: async (...args: P) => (await sql.query(query, args as readonly unknown[]) as T[])[0] }
 }
 
 // Per-statement builders — extracted so `openNeonDb` stays small
@@ -184,7 +191,7 @@ function buildHeadFor(sql: NeonSql): GetStmt<[string], { id: string }> {
 
 function buildSeqOfId(sql: NeonSql): GetStmt<[string, string], { seq: number }> {
   return { get: async (tag, id) => {
-    const rows = await sql(SEQ_OF_ID_SQL, [tag, id]) as Array<{ seq: number | string }>
+    const rows = await sql.query(SEQ_OF_ID_SQL, [tag, id]) as Array<{ seq: number | string }>
     const r = rows[0]
     if (!r) return undefined
     const n = numOrNull(r.seq)
@@ -194,7 +201,7 @@ function buildSeqOfId(sql: NeonSql): GetStmt<[string, string], { seq: number }>
 
 function buildLastKeyframeSeq(sql: NeonSql): GetStmt<[string], { s: number | null }> {
   return { get: async (tag) => {
-    const rows = await sql(LAST_KEYFRAME_SEQ_SQL, [tag]) as Array<{ s: number | string | null }>
+    const rows = await sql.query(LAST_KEYFRAME_SEQ_SQL, [tag]) as Array<{ s: number | string | null }>
     const r = rows[0]
     return r ? { s: numOrNull(r.s) } : undefined
   } }
@@ -202,14 +209,14 @@ function buildLastKeyframeSeq(sql: NeonSql): GetStmt<[string], { s: number | nul
 
 function buildChain(sql: NeonSql, query: string): AllStmt<[string], RevisionRow> {
   return { all: async (tag) => {
-    const rows = await sql(query, [tag]) as Array<Record<string, unknown>>
+    const rows = await sql.query(query, [tag]) as Array<Record<string, unknown>>
     return rows.map(mapRevisionRow)
   } }
 }
 
 function buildChainSeq(sql: NeonSql, query: string): AllStmt<[string, number], RevisionRow> {
   return { all: async (tag, seq) => {
-    const rows = await sql(query, [tag, seq]) as Array<Record<string, unknown>>
+    const rows = await sql.query(query, [tag, seq]) as Array<Record<string, unknown>>
     return rows.map(mapRevisionRow)
   } }
 }
@@ -218,6 +225,14 @@ function buildRevisionExists(sql: NeonSql): GetStmt<[string, string], unknown> {
   return getRowStmt(sql, REVISION_EXISTS_SQL)
 }
 
+function buildRevisionById(sql: NeonSql): GetStmt<[string, string], RevisionRow> {
+  return { get: async (tag, id) => {
+    const rows = await sql.query(REVISION_BY_ID_SQL, [tag, id]) as Array<Record<string, unknown>>
+    const r = rows[0]
+    return r ? mapRevisionRow(r) : undefined
+  } }
+}
+
 // Atomic commit of a single revision (Neon backend). Wraps the
 // dup-check, head-check and gated INSERT in one pipelined
 // transaction — NO commit-time advisory lock. Cross-replica
@@ -274,7 +289,7 @@ function tryCommitNeon(sql: NeonSql): (input: RevisionInsert) => Promise<CommitR
         // matches `base = NULL` on the first revision against the
         // empty-chain head (also NULL); plain `=` would be NULL → false
         // and the first revision would never insert.
-        sql(
+        sql.query(
           GATED_INSERT_SQL_PG,
           [tag, id, baseNorm, keyframeCol, nonce, ciphertext, signature, createdAt],
         ),
@@ -288,8 +303,8 @@ function tryCommitNeon(sql: NeonSql): (input: RevisionInsert) => Promise<CommitR
         // stable: our id present ⇒ duplicate, else the head moved ⇒
         // stale-base. (The INSERT itself is still authoritative — its own
         // single-statement snapshot is what prevents a chain fork.)
-        sql(REVISION_EXISTS_SQL, [tag, id]),
-        sql(HEAD_FOR_SQL, [tag]),
+        sql.query(REVISION_EXISTS_SQL, [tag, id]),
+        sql.query(HEAD_FOR_SQL, [tag]),
       ])
     } catch (err) {
       // A unique-violation reaches here when a cross-replica racer (or
@@ -303,9 +318,9 @@ function tryCommitNeon(sql: NeonSql): (input: RevisionInsert) => Promise<CommitR
       // escaping to `handleSave`'s IIFE. Other errors (network, syntax,
       // type mismatch) rethrow.
       if (!isUniqueViolation(err)) throw err
-      const dupRows = await sql(REVISION_EXISTS_SQL, [tag, id]) as Array<unknown>
+      const dupRows = await sql.query(REVISION_EXISTS_SQL, [tag, id]) as Array<unknown>
       if (dupRows.length > 0) return { kind: 'inserted' }
-      const headRows = await sql(HEAD_FOR_SQL, [tag]) as Array<{ id: string }>
+      const headRows = await sql.query(HEAD_FOR_SQL, [tag]) as Array<{ id: string }>
       return { kind: 'stale-base', head: headRows[0]?.id ?? null }
     }
     const insertRows = results[0] as Array<unknown>
@@ -343,8 +358,8 @@ export async function openNeonDb(connectionString: string): Promise<Handle> {
   // their DDL (the advisory lock releases at COMMIT; the
   // `IF NOT EXISTS` clauses then make the second runner a no-op).
   await sql.transaction([
-    sql(`SELECT pg_advisory_xact_lock($1, $2)`, [DDL_LOCK_KEY_REVISION, DDL_LOCK_KEY_REVISION_SUB]),
-    ...SCHEMA_PG.map((stmt) => sql(stmt, [])),
+    sql.query(`SELECT pg_advisory_xact_lock($1, $2)`, [DDL_LOCK_KEY_REVISION, DDL_LOCK_KEY_REVISION_SUB]),
+    ...SCHEMA_PG.map((stmt) => sql.query(stmt, [])),
   ])
 
   const handle: Handle = {
@@ -359,6 +374,7 @@ export async function openNeonDb(connectionString: string): Promise<Handle> {
     chainAfterSeq: buildChainSeq(sql, CHAIN_AFTER_SQL),
     chainFromSeq: buildChainSeq(sql, CHAIN_FROM_SQL),
     revisionExists: buildRevisionExists(sql),
+    revisionById: buildRevisionById(sql),
     tryCommit: tryCommitNeon(sql),
     // The serverless HTTP client is stateless — no socket to close.
     // Async no-op so shutdown's `handle.close()` works uniformly

package/server/db-revision-sql.ts

@@ -108,6 +108,15 @@ export const CHAIN_FROM_SQL =
   FROM workspace_revision WHERE workspace_tag = $1 AND seq >= $2 ORDER BY seq ASC`
 export const REVISION_EXISTS_SQL =
   `SELECT 1 AS one FROM workspace_revision WHERE workspace_tag = $1 AND id = $2`
+// Fetch a single revision row by content-addressed id. The cross-instance
+// pubsub (server/pubsub.ts) NOTIFY payload carries only `(tag, revisionId)`
+// because the full `workspace-state` broadcast envelope is bounded by
+// `MAX_CIPHERTEXT_LEN` (2 MiB) and Postgres NOTIFY caps payloads at ~8 KB.
+// The receiver re-fetches the row from this shared table to construct the
+// wire broadcast for its local peers.
+export const REVISION_BY_ID_SQL =
+  `SELECT base, id, keyframe, nonce, ciphertext, signature
+  FROM workspace_revision WHERE workspace_tag = $1 AND id = $2`
 
 // The gated commit INSERT, in `$N` form. One statement folds the
 // dup-check, the head-equals-base check, the server-assigned seq

package/server/db.ts

@@ -60,7 +60,8 @@ import { dirname } from 'node:path'
 import { type AllStmt, type GetStmt, wrapAll, wrapGet } from './db-stmt.ts'
 import {
   CHAIN_AFTER_SQL, CHAIN_ALL_SQL, CHAIN_FROM_SQL, GATED_INSERT_SQL_SQLITE, HEAD_FOR_SQL,
-  LAST_KEYFRAME_SEQ_SQL, REVISION_EXISTS_SQL, SEQ_OF_ID_SQL, mapRevisionRow, toSqlitePlaceholders,
+  LAST_KEYFRAME_SEQ_SQL, REVISION_BY_ID_SQL, REVISION_EXISTS_SQL, SEQ_OF_ID_SQL,
+  mapRevisionRow, toSqlitePlaceholders,
 } from './db-revision-sql.ts'
 
 // `CHECK (keyframe IN (0, 1))` is the value-domain guard on the
@@ -181,6 +182,10 @@ export type Handle = {
   chainAfterSeq: AllStmt<[string, number], RevisionRow>
   chainFromSeq: AllStmt<[string, number], RevisionRow>
   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`).
+  revisionById: GetStmt<[string, string], RevisionRow>
   gatedInsert?: GetStmt<[string, string, string | null, number, string, string, string, number], { seq: number }>
   tryCommit: (input: RevisionInsert) => Promise<CommitResult>
   close: () => Promise<void>
@@ -288,6 +293,17 @@ function openDbInner(db: DatabaseSync): SqliteHandle {
     const raw = wrapAll<P, Record<string, unknown>>(db.prepare(toSqlitePlaceholders(query)))
     return { all: async (...args: P) => (await raw.all(...args)).map(mapRevisionRow) }
   }
+  // Reuses `wrapGet` for the prepared statement, then maps the row
+  // through the shared coercion so the returned shape matches `chainFrom`.
+  const revisionByIdStmt: GetStmt<[string, string], RevisionRow> = (() => {
+    const raw = wrapGet<[string, string], Record<string, unknown>>(
+      db.prepare(toSqlitePlaceholders(REVISION_BY_ID_SQL)),
+    )
+    return { get: async (tag, id) => {
+      const row = await raw.get(tag, id)
+      return row ? mapRevisionRow(row) : undefined
+    } }
+  })()
   const handle: SqliteHandle = {
     db,
     headFor: wrapGet<[string], { id: string }>(db.prepare(toSqlitePlaceholders(HEAD_FOR_SQL))),
@@ -297,6 +313,7 @@ function openDbInner(db: DatabaseSync): SqliteHandle {
     chainAfterSeq: chainStmt<[string, number]>(CHAIN_AFTER_SQL),
     chainFromSeq: chainStmt<[string, number]>(CHAIN_FROM_SQL),
     revisionExists: wrapGet<[string, string], unknown>(db.prepare(toSqlitePlaceholders(REVISION_EXISTS_SQL))),
+    revisionById: revisionByIdStmt,
     // SQLite null-safe equality is `IS`; the numbered `?N` form (with
     // reuse) maps `$1`/`$2`/`$3` to repeated positional binds. `RETURNING
     // seq` works in node:sqlite (see objstore's `insertLiveIfAbsent`).

package/server/http.ts

@@ -1,8 +1,9 @@
 // HTTP plane: the REST byte-transfer routing (`/api/objstore/...`), the
-// static UI bundle, and the WebSocket upgrade gate. Built once at boot
-// with the WS server plus the lifecycle hooks it needs (`track` to
-// drain in-flight requests on shutdown, `isShuttingDown` to gate new
-// ones). The WS *connection* handler is wired on `wss` separately in
+// static UI bundle, the SSE+POST fallback transport for the sync
+// protocol, and the WebSocket upgrade gate. Built once at boot with
+// the WS server plus the lifecycle hooks it needs (`track` to drain
+// in-flight requests on shutdown, `isShuttingDown` to gate new ones).
+// The WS *connection* handler is wired on `wss` separately in
 // index.ts; this module only owns the upgrade handshake.
 
 import { type IncomingMessage as HttpRequest, type Server, type ServerResponse, createServer } from 'node:http'
@@ -10,6 +11,8 @@ import { Buffer } from 'node:buffer'
 import { fileURLToPath } from 'node:url'
 import type { WebSocketServer } from 'ws'
 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'
 import { loadStatic } from './static.ts'
 import { errStack } from './util.ts'
 
@@ -31,6 +34,11 @@ type HasHeaders = { headers: HttpRequest['headers'] }
 export type HttpServerDeps = {
   wss: WebSocketServer
   restDeps: ObjstoreRestDeps
+  // 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
+  // plane inherits them.
+  sseServer: SseServer
   isOriginAllowed: (req: HasHeaders) => boolean
   isShuttingDown: () => boolean
   track: (promise: Promise<unknown>) => void
@@ -39,7 +47,7 @@ export type HttpServerDeps = {
 }
 
 export function createHttpServer(deps: HttpServerDeps): Server {
-  const { wss, restDeps, isOriginAllowed, isShuttingDown, track, restPutIdleTimeoutMs, debug } = deps
+  const { wss, restDeps, sseServer, isOriginAllowed, isShuttingDown, track, 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
@@ -47,6 +55,34 @@ export function createHttpServer(deps: HttpServerDeps): Server {
   const handleStatic = loadStatic(fileURLToPath(new URL('../out', import.meta.url)))
 
   const httpServer = createServer((req: HttpRequest, res: ServerResponse) => {
+    // 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
+    // WS upgrade and REST plane). The sseServer.handle() function
+    // returns true iff it matched and consumed the request; on false
+    // we fall through to the REST / static / 404 ladder below.
+    if (typeof req.url === 'string' && req.url.split('?', 1)[0] === SSE_OPEN_PATH) {
+      if (!isOriginAllowed(req)) {
+        res.writeHead(403, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ error: 'origin-denied' }))
+        return
+      }
+      // sseServer.handle owns its own shutdown / cap / 503 ladder.
+      // Each POST's response stays open as the session's downstream
+      // channel until the next POST takes over — the response is
+      // long-lived even though the request is one-shot — and the
+      // shutdown gate inside sseServer prevents accepting new POSTs
+      // once shuttingDown latches, so outstanding sessions drain via
+      // the lifecycle's sseSessions() close loop.
+      if (sseServer.handle(req, res)) 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
+    // match); the lifecycle's `track` awaits it so SIGTERM drains
+    // outstanding upstream fetches.
+    const npmP = dispatchNpmAdvisories(req, res, { isOriginAllowed, isShuttingDown, debug })
+    if (npmP) { track(npmP); return }
     if (matchRoute(req.url) != null) {
       // Shutdown gate. The WS plane gates new messages on `shuttingDown`;
       // REST handlers go through a separate path and must mirror it.

package/server/hub.ts

@@ -19,8 +19,18 @@ export type Hub = {
   // `except: null` is the REST-originated path — byte transfer landed
   // via HTTP, not a particular WS socket, so it hits every subscriber.
   // WS-originated broadcasts pass the originator so it doesn't see its
-  // own message echoed back.
+  // 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
+  // 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
+  // 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
 }
 
 export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number; debug: boolean }): Hub {
@@ -82,6 +92,16 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     // catch-up with a multi-MB ciphertext × N subscribers, per-recipient
     // JSON.stringify would dominate CPU; this is the cheap win.
     const payload = JSON.stringify(msg)
+    fanOut(set, payload, except)
+  }
+
+  function broadcastLocalRaw(tag: string, payload: string): void {
+    const set = subscribers.get(tag)
+    if (!set) return
+    fanOut(set, payload, null)
+  }
+
+  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
     // mid-broadcast triggers `unsubscribeAll` from the 'close' handler,
@@ -94,5 +114,5 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     }
   }
 
-  return { subscribe, unsubscribeAll, send, sendRaw, broadcast }
+  return { subscribe, unsubscribeAll, send, sendRaw, broadcast, broadcastLocalRaw }
 }