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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.10",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT",
   "author": {
@@ -28,46 +28,65 @@
     "#client/sync.js": "./client/sync.js",
     "#client/sync-host.js": "./client/sync-host.js"
   },
+  "exports": {
+    "./reap": "./api/reap.ts",
+    "./server": "./server-e2e/index.ts",
+    "./strip-types-loader": "./strip-types-loader.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
-    "triage-server": "server/index.ts"
+    "triage-server": "server-e2e/cli.js"
   },
   "files": [
-    "server/auth.ts",
-    "server/config.ts",
-    "server/db-neon.ts",
-    "server/db-revision-sql.ts",
-    "server/db-stmt.ts",
-    "server/db.ts",
-    "server/http.ts",
-    "server/hub.ts",
-    "server/index.ts",
-    "server/lifecycle.ts",
-    "server/neon-driver.ts",
-    "server/objstore/blob-fs.ts",
-    "server/objstore/blob-vercel.ts",
-    "server/objstore/blob.ts",
-    "server/objstore/fs.ts",
-    "server/objstore/handlers.ts",
-    "server/objstore/init.ts",
-    "server/objstore/reaper.ts",
-    "server/objstore/rest.ts",
-    "server/objstore/sign.ts",
-    "server/objstore/store-neon.ts",
-    "server/objstore/store.ts",
-    "server/objstore/tokens.ts",
-    "server/origin.ts",
-    "server/peer.ts",
-    "server/sign.ts",
-    "server/static.ts",
-    "server/sync-handlers.ts",
-    "server/util.ts",
-    "server/validation.ts",
-    "server/ws-server.ts",
-    "server/config.example.json",
+    "api/reap.ts",
+    "server-e2e/auth.ts",
+    "server-e2e/bus-receiver.ts",
+    "server-e2e/cli.js",
+    "server-e2e/config.ts",
+    "server-e2e/db-neon.ts",
+    "server-e2e/db-revision-sql.ts",
+    "server-e2e/db-stmt.ts",
+    "server-e2e/db.ts",
+    "server-e2e/http.ts",
+    "server-e2e/hub.ts",
+    "server-e2e/index.ts",
+    "server-e2e/lifecycle.ts",
+    "server-e2e/neon-driver.ts",
+    "server-e2e/npm-proxy.ts",
+    "server-e2e/objstore/blob-fs.ts",
+    "server-e2e/objstore/blob-vercel.ts",
+    "server-e2e/objstore/blob.ts",
+    "server-e2e/objstore/fetch-mint-guard.ts",
+    "server-e2e/objstore/fs.ts",
+    "server-e2e/objstore/handlers.ts",
+    "server-e2e/objstore/init.ts",
+    "server-e2e/objstore/reaper.ts",
+    "server-e2e/objstore/rest-deny.ts",
+    "server-e2e/objstore/rest-mint.ts",
+    "server-e2e/objstore/rest.ts",
+    "server-e2e/objstore/sign.ts",
+    "server-e2e/objstore/store-neon.ts",
+    "server-e2e/objstore/store.ts",
+    "server-e2e/objstore/tokens.ts",
+    "server-e2e/peer.ts",
+    "server-e2e/pubsub.ts",
+    "server-e2e/sign.ts",
+    "server-e2e/sse-server.ts",
+    "server-e2e/sse-session.ts",
+    "server-e2e/static.ts",
+    "server-e2e/sync-handlers.ts",
+    "server-e2e/util.ts",
+    "server-e2e/validation.ts",
+    "server-e2e/ws-server.ts",
+    "server-e2e/config.example.json",
+    "server-common/origin.ts",
     "common/save-error-reason.ts",
+    "common/server-info.ts",
     "common/utf8.d.ts",
     "common/utf8.js",
     "out/brotli-fallback.js",
+    "out/client-admin.js",
+    "out/client-managed.js",
     "out/client-sync.js",
     "out/graph.js",
     "out/icon-maskable.svg",
@@ -78,37 +97,39 @@
     "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",
-    "lint:js": "oxlint -c .oxlintrc.json --ignore-pattern=ui/logs.js ./tests/ ./common/ ./server/ ./client/ ./ui/",
+    "lint:js": "oxlint -c .oxlintrc.json --ignore-pattern=ui/logs.js ./tests/ ./common/ ./server-common/ ./server-e2e/ ./server-managed/ ./client/ ./ui/ ./api/",
     "lint:css": "stylelint 'ui/**/*.css'",
     "lint:ts": "tsc --noEmit",
     "prepack": "node --run build",
     "build": "node build.js build",
     "serve": "node build.js serve",
-    "server": "node server/index.ts",
-    "test": "node --js-base-64 --experimental-test-module-mocks --test ./tests/*.test.js"
+    "server": "node server-e2e/index.ts",
+    "server-managed": "node server-managed/index.ts",
+    "test": "node --js-base-64 --experimental-test-module-mocks --test-timeout=120000 --test ./tests/*.test.js"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "^0.4.5",
-    "@exodus/stasis": "^1.0.0-alpha.1",
-    "@noble/ciphers": "^2.2.0",
-    "@preventive/terminal": "^1.2.2",
+    "@electric-sql/pglite": "^0.5.5",
+    "@exodus/stasis-core": "^1.0.0-beta.4",
+    "@noble/ciphers": "^2.3.0",
+    "@preventive/terminal": "^1.3.0",
     "@rray/frontend": "^1.0.0",
-    "@stylistic/stylelint-plugin": "^5.1.0",
-    "@types/node": "^25.6.2",
+    "@stylistic/stylelint-plugin": "^5.3.0",
+    "@types/node": "^26.2.0",
     "@types/ws": "^8.18.1",
     "brotli": "^1.3.3",
-    "esbuild": "^0.27.4",
-    "lit": "^3.3.2",
+    "esbuild": "^0.28.2",
+    "lit": "^3.3.3",
     "minify-html-literals": "^1.3.5",
-    "oxlint": "^1.63.0",
+    "oxlint": "^1.79.0",
     "prismjs": "^1.30.0",
-    "stylelint": "^17.11.0",
+    "stylelint": "^17.14.1",
     "stylelint-config-recommended": "^18.0.0",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "dependencies": {
     "ws": "^8.20.1"

package/{server → server-common}/origin.ts

@@ -1,8 +1,8 @@
-// Same-origin gate for the WS upgrade and REST data plane. We don't
-// support cross-origin browser clients, so any Origin header present
-// on an incoming request MUST match the server's own host (derived
-// from `req.headers.host`, or from `X-Forwarded-Host` /
-// `X-Forwarded-Proto` when a trusted reverse proxy is in front).
+// Same-origin gate, shared by the e2e and managed servers (server-common).
+// We don't support cross-origin browser clients, so any Origin header present
+// on an incoming request MUST match the server's own host (derived from
+// `req.headers.host`, or from `X-Forwarded-Host` / `X-Forwarded-Proto` when a
+// trusted reverse proxy is in front).
 //
 // Why "present-must-match" rather than "always required":
 // - Browser WebSocket handshakes always carry Origin (RFC 6455), so a

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

@@ -31,6 +31,10 @@ export type AuthenticateMsg = { password?: unknown }
 export type Auth = {
   // True iff the gate is configured AND this socket hasn't authenticated.
   requiresAuth(socket: WebSocket): boolean
+  // Static "is a server password configured" flag — the socket-less
+  // predicate the REST put-begin gate needs (a REST request can never be
+  // operator-authorized, so `requiresAuth` collapses to this there).
+  passwordConfigured: boolean
   handleAuthenticate(socket: WebSocket, msg: AuthenticateMsg): void
   sendUnauthorized(socket: WebSocket, ctx: UnauthorizedContext): void
 }
@@ -76,6 +80,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
@@ -95,5 +110,5 @@ export function createAuth(deps: {
     send(socket, { type: 'authenticated' })
   }
 
-  return { requiresAuth, handleAuthenticate, sendUnauthorized }
+  return { requiresAuth, passwordConfigured: CONFIGURED_PASSWORD_HMAC != null, handleAuthenticate, sendUnauthorized }
 }

package/server-e2e/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-e2e/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
+      }
+      // `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 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-e2e/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-e2e/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 → server-e2e}/config.ts

@@ -18,6 +18,7 @@ export type Config = {
   dbPath: string
   objstoreDir: string
   reapIntervalMs: number
+  reapDisabled: boolean
   maxInflightPerSocket: number
   debug: boolean
   neonUrl: string | null
@@ -44,11 +45,11 @@ function intEnv(name: string, def: number, min: number, max: number, hint = ''):
   return n
 }
 
-const HELP = `Usage: node server/index.ts
+const HELP = `Usage: node server-e2e/index.ts
 Environment:
   PORT                       listen port (default 8765)
   HOST                       bind host (default 127.0.0.1)
-  DB_PATH                    sqlite file (default: server/data/data.db);
+  DB_PATH                    sqlite file (default: server-e2e/data/data.db);
                              ignored when DATABASE_URL is set
   DATABASE_URL               Neon Postgres connection string; if set,
                              selects the Neon backend instead of
@@ -78,6 +79,13 @@ Environment:
                              DATABASE_URL + BLOB_READ_WRITE_TOKEN
                              are set (bytes live in Vercel Blob).
   OBJSTORE_REAP_INTERVAL_MS  orphan reaper period (default 600000)
+  OBJSTORE_REAP_DISABLED     set '1' / 'true' to disable the orphan
+                             reaper ENTIRELY — no boot sweep, no
+                             periodic GC. Orphaned/superseded blobs and
+                             stale staging rows then accumulate
+                             unbounded; only set this if an external job
+                             handles GC (e.g. a cron calling reapOrphans).
+                             Default OFF (reaper runs).
   TRUST_PROXY                set '1' / 'true' to honour X-Forwarded-
                              Host / X-Forwarded-Proto when computing
                              the same-origin gate's expected origin.
@@ -95,7 +103,7 @@ Environment:
                              that need to deterministically
                              exercise the cap.
   CONFIG_PATH                operator config JSON path (default:
-                             server/config.json). Currently the
+                             server-e2e/config.json). Currently the
                              only field is { "password": "..." }
                              which gates first-action creation of
                              a new workspace on the
@@ -156,13 +164,18 @@ export function loadConfig(): Config {
   // 0 = OS-assigned ephemeral port (the test harness boots with PORT=0).
   const port = intEnv('PORT', 8765, 0, 65535)
   const host = env['HOST'] ?? '127.0.0.1'
-  // `fileURLToPath` decodes percent-escapes / non-ASCII path segments
-  // correctly (the older `new URL(...).pathname` left `%20` raw).
+  // `fileURLToPath` decodes percent-escapes / non-ASCII path segments;
+  // `new URL(...).pathname` would leave `%20` raw.
   const dbPath = env['DB_PATH'] ?? fileURLToPath(new URL('./data/data.db', import.meta.url))
   // `path.join` so a Windows DB_PATH doesn't get a mixed-separator child.
   const objstoreDir = env['OBJSTORE_DIR'] ?? join(dirname(dbPath), 'objstore')
   // No practical upper bound beyond the safe-integer range.
   const reapIntervalMs = intEnv('OBJSTORE_REAP_INTERVAL_MS', 10 * 60 * 1000, 1, Number.MAX_SAFE_INTEGER)
+  // Hard off-switch for the orphan reaper (both the boot sweep AND the
+  // periodic timer). '1' / 'true' (case-insensitive) → disabled; anything
+  // else, including unset, leaves it ON. Same boolean shape as TRUST_PROXY.
+  const reapDisabledEnv = env['OBJSTORE_REAP_DISABLED']
+  const reapDisabled = reapDisabledEnv === '1' || reapDisabledEnv?.toLowerCase() === 'true'
   const debug = env['DEBUG'] === '1'
 
   const configPath = env['CONFIG_PATH'] ?? fileURLToPath(new URL('./config.json', import.meta.url))
@@ -174,8 +187,8 @@ export function loadConfig(): Config {
   const password = rawPassword ?? null
   // Upper bound 65_536 — bounds memory under hostile load; a deployer
   // passing MAX_SAFE_INTEGER would silently defeat the cap. Validated
-  // here (after the config.json / password parse) to preserve the
-  // pre-split error-precedence order.
+  // here, after the config.json / password parse, to keep the
+  // error-precedence order.
   const maxInflightPerSocket = intEnv('MAX_INFLIGHT_PER_SOCKET', 64, 1, 65_536)
 
   if (argv.includes('--help') || argv.includes('-h')) {
@@ -189,7 +202,7 @@ export function loadConfig(): Config {
   const tokenSecret = tokenSecretB64 ? decodeTokenSecret(tokenSecretB64) : null
 
   return {
-    port, host, dbPath, objstoreDir, reapIntervalMs, maxInflightPerSocket,
+    port, host, dbPath, objstoreDir, reapIntervalMs, reapDisabled, maxInflightPerSocket,
     debug, neonUrl, blobToken, tokenSecret, password,
     trustProxyEnv: env['TRUST_PROXY'],
   }

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

@@ -4,15 +4,20 @@
 // dialect on the wire.
 //
 // `@neondatabase/serverless` is an OPTIONAL peer dep — selected by
-// the `DATABASE_URL` branch in `server/index.ts`. The peer dep
+// the `DATABASE_URL` branch in `server-e2e/index.ts`. The peer dep
 // itself is loaded lazily via the dynamic `import()` inside
 // `openNeonDb` below, so a SQLite-only deployment never installs it
 // (`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>
@@ -325,7 +340,7 @@ export async function openNeonDb(connectionString: string): Promise<Handle> {
   // in-process Postgres (PGlite) via `mock.module`: that hook can only
   // intercept a specifier it can RESOLVE, and the optional peer dep
   // isn't installed in a SQLite-only checkout. The wrapper path always
-  // resolves — see `server/neon-driver.ts`. Cast through `unknown`
+  // resolves — see `server-e2e/neon-driver.ts`. Cast through `unknown`
   // because the wrapper's `export *` re-exports a `@ts-ignore`'d
   // (possibly-absent) module, so tsc can't see `neon`'s type here.
   const mod = (await import('./neon-driver.ts')) as unknown as { neon: (url: string) => NeonSql }
@@ -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