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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.10",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT",
   "author": {
@@ -28,51 +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/bus-receiver.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/npm-proxy.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/pubsub.ts",
-    "server/sign.ts",
-    "server/sse-server.ts",
-    "server/sse-session.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",
@@ -83,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
 }
@@ -106,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 → server-e2e}/bus-receiver.ts

@@ -1,6 +1,6 @@
 // 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 /
+// 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.
@@ -69,13 +69,13 @@ export function createBusReceiver(deps: BusReceiverDeps): (msg: BusMessage) => P
         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.
+      // `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,

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
@@ -71,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[][]>
 }
 
@@ -104,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(
@@ -157,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
@@ -166,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
@@ -185,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)
@@ -195,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
   } }
@@ -203,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)
   } }
 }
@@ -221,7 +227,7 @@ function buildRevisionExists(sql: NeonSql): GetStmt<[string, string], unknown> {
 
 function buildRevisionById(sql: NeonSql): GetStmt<[string, string], RevisionRow> {
   return { get: async (tag, id) => {
-    const rows = await sql(REVISION_BY_ID_SQL, [tag, id]) as Array<Record<string, unknown>>
+    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
   } }
@@ -283,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],
         ),
@@ -297,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
@@ -312,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>
@@ -334,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 }
@@ -352,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 = {

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

@@ -1,9 +1,7 @@
 // Shared SQL + row-mapping for the `workspace_revision` chain, used by
 // BOTH backends — `./db.ts` (SQLite) and `./db-neon.ts` (Neon/Postgres).
-// The two backends previously carried byte-for-byte-equal query strings
-// (modulo `?`↔`$N` placeholders) and a copy of the same row mapper; that
-// duplication is collapsed here so a query edit can't silently drift
-// between backends.
+// Single source of truth (modulo `?`↔`$N` placeholders) so a query edit
+// can't silently drift between backends.
 //
 // Single source of truth, in `$N` (Postgres) form:
 //   • the read queries (`headFor`, `seqOfId`, `lastKeyframeSeq`, the
@@ -60,11 +58,10 @@ export function numOrNull(v: unknown): number | null {
 // `Record<string, unknown>` rows whose `keyframe` may be a number OR (on
 // a future driver change) a string; `node:sqlite` hands back native
 // numbers. The `num`/`numOrNull` coercion is safe over both — a native
-// `0`/`1` integer passes through unchanged, so SQLite rows round-trip
-// identically to the bespoke pass-through they had before, while Neon
-// rows keep their defensive string→number coercion. `base` is the only
-// nullable column (first revision); `keyframe` collapses to a strict
-// 0 / 1 via the `=== 1` check the chain-broadcast contract relies on.
+// `0`/`1` integer passes through unchanged, while Neon rows keep their
+// defensive string→number coercion. `base` is the only nullable column
+// (first revision); `keyframe` collapses to a strict 0 / 1 via the
+// `=== 1` check the chain-broadcast contract relies on.
 export function mapRevisionRow(r: Record<string, unknown>): RevisionRow {
   return {
     base: (r['base'] as string | null) ?? null,
@@ -109,7 +106,7 @@ export const CHAIN_FROM_SQL =
 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)`
+// pubsub (server-e2e/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

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

@@ -1,5 +1,5 @@
-// Shared async-statement primitives. Both `server/db.ts` (workspace_revision
-// chain) and `server/objstore/store.ts` (objstore tables) expose Handles
+// Shared async-statement primitives. Both `server-e2e/db.ts` (workspace_revision
+// chain) and `server-e2e/objstore/store.ts` (objstore tables) expose Handles
 // whose statements look like `{ get(...) → Promise<…>, all(...) → Promise<[…]>,
 // run(...) → Promise<void> }`. The underlying `node:sqlite` driver is
 // synchronous; the wrappers below catch sync errors and route them through