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

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // DeepView triage-sync relay server. WebSocket front-end, SQLite
 // backing store. Implements the protocol described in
-// `client/triage-sync.js` (and `server/sign.ts` for the canonical
+// `client/triage-sync.js` (and `server-e2e/sign.ts` for the canonical
 // signature payloads):
 //
 //   server → client  challenge           { nonce } — emitted on every
@@ -75,13 +75,14 @@
 import { type WebSocket, WebSocketServer } from 'ws'
 import { errMsg, errStack } from './util.ts'
 import type { PeerRegistry } from './peer.ts'
-import { LOOPBACK_HOSTS, createOriginGate } from './origin.ts'
+import { LOOPBACK_HOSTS, createOriginGate } from '../server-common/origin.ts'
 import { createHub } from './hub.ts'
 import { createAuth } from './auth.ts'
 import { createSyncHandlers } from './sync-handlers.ts'
 import { WS_UPGRADE_PATH, createHttpServer } from './http.ts'
 import { installWsServer } from './ws-server.ts'
 import { SSE_OPEN_PATH, installSseServer } from './sse-server.ts'
+import type { ServerInfo } from '../common/server-info.ts'
 import { createLifecycle } from './lifecycle.ts'
 import { loadConfig } from './config.ts'
 import { type Handle, openDb } from './db.ts'
@@ -97,20 +98,20 @@ import {
 import { createBusReceiver } from './bus-receiver.ts'
 
 // All external inputs (env vars + optional config.json) are parsed
-// and validated in ./config.ts. Destructure into the existing
-// uppercase names so the rest of this module reads unchanged.
+// and validated in ./config.ts; destructure into the uppercase names
+// the rest of this module uses.
 const config = loadConfig()
 const {
   port: PORT, host: HOST, dbPath: DB_PATH, objstoreDir: OBJSTORE_DIR,
-  reapIntervalMs: OBJSTORE_REAP_INTERVAL_MS,
+  reapIntervalMs: OBJSTORE_REAP_INTERVAL_MS, reapDisabled: OBJSTORE_REAP_DISABLED,
   maxInflightPerSocket: MAX_INFLIGHT_PER_SOCKET, debug: DEBUG,
   neonUrl: NEON_URL, blobToken: BLOB_TOKEN, tokenSecret: TOKEN_SECRET,
   password: CONFIG_PASSWORD, trustProxyEnv: TRUST_PROXY_ENV,
 } = config
 
 // Same-origin gate for the WS upgrade and REST data plane (see
-// ./origin.ts). `TRUST_PROXY_ENV` (from config) also feeds the
-// boot-time misconfiguration fail-fast below.
+// ./origin.ts). `TRUST_PROXY_ENV` also feeds the boot-time
+// misconfiguration fail-fast below.
 const { trustProxy: TRUST_PROXY, isOriginAllowed } = createOriginGate(HOST, TRUST_PROXY_ENV)
 
 // Per-socket buffered-bytes cap. `socket.send` returns synchronously
@@ -120,28 +121,27 @@ const { trustProxy: TRUST_PROXY, isOriginAllowed } = createOriginGate(HOST, TRUS
 // MB of fan-out broadcasts in this buffer with no backpressure on
 // the broadcast loop. Drop the message when the buffer crosses the
 // cap; the heartbeat will eventually close a peer that never
-// drains. Transport audit `server/index.ts:225`.
+// drains. Transport audit `server-e2e/index.ts:225`.
 const MAX_BUFFERED_BYTES = 16 * 1024 * 1024
 // Per-socket in-flight async-handler cap (MAX_INFLIGHT_PER_SOCKET,
 // env-validated in config). Each inbound text frame spawns a
 // `track(handler)` IIFE; an authorised peer firing valid frames could
 // otherwise grow the set without bound, stretching SIGTERM drain time.
 // Saves dropped at the cap surface as a typed `busy` NACK. Transport
-// audit `server/index.ts:590`.
+// audit `server-e2e/index.ts:590`.
 
 // Per-connection state registry. One `Peer` per accepted socket holds
 // the challenge nonce, auth flag, heartbeat liveness, in-flight count,
-// and subscribed tags (see ./peer.ts) — replacing what were five
-// parallel per-socket WeakMaps. The connection handler holds the Peer
-// in a closure for the hot paths; cross-function call sites resolve it
-// via `peers.get(socket)`.
+// and subscribed tags (see ./peer.ts). The connection handler holds
+// the Peer in a closure for the hot paths; cross-function call sites
+// resolve it via `peers.get(socket)`.
 const peers: PeerRegistry = new WeakMap()
 
 // REST PUT idle-body timeout. A slow-loris client trickling bytes
 // within the declared Content-Length holds the staging fd and an
 // inFlightSids slot until the global staging TTL reaps it. Aborting
 // the per-chunk-idle period closes that window. Transport audit
-// `server/objstore/rest.ts:218`.
+// `server-e2e/objstore/rest.ts:218`.
 const REST_PUT_IDLE_TIMEOUT_MS = 30_000
 
 // Server-driven WS heartbeat. Every `HEARTBEAT_INTERVAL_MS` we walk
@@ -163,8 +163,8 @@ const REST_PUT_IDLE_TIMEOUT_MS = 30_000
 const HEARTBEAT_INTERVAL_MS = 30_000
 
 // Backend selection. Both planes (workspace_revision DB + the
-// v1.objstore byte store) are picked from config at boot. Two supported
-// pairings:
+// v1.objstore byte store) are picked from config at boot. Two
+// supported pairings:
 //   1. DATABASE_URL set → Neon (workspace_revision + objstore
 //      tables) + Vercel Blob Private Storage (bytes). Requires
 //      BLOB_READ_WRITE_TOKEN — fail fast at boot if missing, since
@@ -174,11 +174,10 @@ const HEARTBEAT_INTERVAL_MS = 30_000
 //      process; the only pairing the SQLite plane supports.
 // The Neon / Vercel files import their peer deps lazily inside the
 // open functions, so static imports here are safe even on a SQLite-
-// only install where the optional peer deps aren't present. Branch
-// out explicitly (rather than via a ternary) so the SQLite path
-// keeps its `SqliteHandle` narrowing — `sqliteHandle.db` is typed
-// as a non-optional `DatabaseSync` and `openObjstore` accepts it
-// without a non-null assertion.
+// only install where the optional peer deps aren't present. Explicit
+// branch (not a ternary) so the SQLite path keeps its `SqliteHandle`
+// narrowing — `sqliteHandle.db` is a non-optional `DatabaseSync` that
+// `openObjstore` accepts without a non-null assertion.
 let handle: Handle
 let objstoreHandle: ObjstoreHandle
 let objstoreBanner: string
@@ -238,8 +237,7 @@ async function workspaceExists(tag: string): Promise<boolean> {
 }
 
 // WS fan-out hub: subscriber registry + backpressure-aware send /
-// broadcast (see ./hub.ts). Destructure into the existing names so the
-// handlers / dispatcher / objstore wiring below read unchanged.
+// broadcast (see ./hub.ts).
 const hub = createHub({ peers, maxBufferedBytes: MAX_BUFFERED_BYTES, debug: DEBUG })
 const { send, broadcast, subscribe, unsubscribeAll, broadcastLocalRaw } = hub
 
@@ -276,9 +274,9 @@ if (NEON_URL) {
 }
 
 // Password gate (see ./auth.ts) — HMAC derivation + the `authenticate`
-// handshake. Destructure into the existing names for the wiring below.
+// handshake.
 const auth = createAuth({ peers, password: CONFIG_PASSWORD, send, debug: DEBUG })
-const { requiresAuth, handleAuthenticate, sendUnauthorized } = auth
+const { requiresAuth, passwordConfigured, handleAuthenticate, sendUnauthorized } = auth
 
 // Triage-sync protocol handlers (see ./sync-handlers.ts). `getNonce`
 // resolves a socket's challenge nonce and is shared with the objstore
@@ -295,9 +293,9 @@ const publishObjDeleted = (tag: string, resourceTag: string, version: number): v
   pubsub.publish({ kind: 'objdel', tag, res: resourceTag, ver: version })
 }
 
-const { handleSave, handleSubscribe, sendSaveError } = createSyncHandlers({
+const { handleSave, handleSaveRest, handleSubscribe, sendSaveError } = createSyncHandlers({
   handle, send, broadcast, publishRevision, subscribe, getNonce,
-  requiresAuth, sendUnauthorized, workspaceExists,
+  requiresAuth, passwordConfigured, sendUnauthorized, workspaceExists,
   // Folds the objstore inventory into the `workspace-subscribed` ack.
   // The objstore store keeps its own richer `Handle`, so we wire the
   // query here where both handles exist rather than coupling
@@ -308,6 +306,7 @@ const { handleSave, handleSubscribe, sendSaveError } = createSyncHandlers({
 
 const { handlers: objstore, restDeps: objstoreRestDeps, startupReap, stopReaper } = initObjstore({
   handle: objstoreHandle, reapIntervalMs: OBJSTORE_REAP_INTERVAL_MS,
+  reapDisabled: OBJSTORE_REAP_DISABLED,
   send, broadcast, publishObjPut, publishObjDeleted,
   getNonce, debug: DEBUG,
   // Auth gate for the FIRST objstore-put-begin against a workspace
@@ -318,10 +317,15 @@ const { handlers: objstore, restDeps: objstoreRestDeps, startupReap, stopReaper
   // `unauthorized` frame and bails on `true`.
   authGate: async (socket, tag) => requiresAuth(socket) && !await workspaceExists(tag),
   sendUnauthorized,
+  // Socket-less analog of `authGate` for the REST put-begin mint: a REST
+  // request can never be operator-authorized, so the gate collapses to
+  // "password configured AND workspace new". A deny routes the client to
+  // its in-band WS put-begin fallback.
+  restPutGate: async (tag) => passwordConfigured && !await workspaceExists(tag),
   // `tokenSecret` is set only when OBJSTORE_TOKEN_SECRET was
   // provided in env (see TOKEN_SECRET resolution above). Omitted
-  // → initObjstore mints a fresh per-process secret (the pre-PR
-  // behaviour, fine for single-replica).
+  // → initObjstore mints a fresh per-process secret (fine for
+  // single-replica).
   ...(TOKEN_SECRET ? { tokenSecret: TOKEN_SECRET } : {}),
 })
 
@@ -338,12 +342,17 @@ const wss = new WebSocketServer({ noServer: true, maxPayload: 4 * 1024 * 1024 })
 // every server object exists.
 const { track, isShuttingDown, install: installLifecycle } = createLifecycle()
 
+// The sync protocol this build advertises — emitted as a `server-info` frame
+// right after the challenge on every connection. This is the e2e boot, so it
+// always advertises e2e.
+const SERVER_INFO: ServerInfo = { mode: 'e2e', managed: null }
+
 // Shared per-connection dispatch surface. Both the WS plane
 // (installWsServer below) and the SSE+POST fallback (installSseServer
 // below) drive `setupPeerConnection` with this; one Peer per accepted
 // connection, one message-handler tree.
 const peerConnectionDeps = {
-  peers, send, unsubscribeAll,
+  peers, serverInfo: SERVER_INFO, send, unsubscribeAll,
   handleSave, handleSubscribe, handleAuthenticate, sendSaveError, objstore,
   track, isShuttingDown,
   maxInflightPerSocket: MAX_INFLIGHT_PER_SOCKET,
@@ -364,10 +373,6 @@ const sseServer = installSseServer({
   // Mirror the WS `maxPayload` so the SSE plane can't accept frames
   // the WS plane would reject.
   maxBodyBytes: 4 * 1024 * 1024,
-  // 90s idle ceiling. The client's JSON ping/pong is 15s; this is ~6
-  // missed pings before we close — well past any transient network
-  // hiccup, much shorter than the kernel's hours-long TCP keepalive.
-  sessionIdleMs: 90_000,
   debug: DEBUG,
 })
 
@@ -377,8 +382,8 @@ const sseServer = installSseServer({
 // drain uses `track`. The WS connection handler is wired on `wss`
 // below.
 const httpServer = createHttpServer({
-  wss, restDeps: objstoreRestDeps, sseServer, isOriginAllowed,
-  isShuttingDown, track,
+  wss, restDeps: objstoreRestDeps, sseServer, serverInfo: SERVER_INFO, isOriginAllowed,
+  isShuttingDown, track, handleSaveRest,
   restPutIdleTimeoutMs: REST_PUT_IDLE_TIMEOUT_MS, debug: DEBUG,
 })
 
@@ -447,16 +452,35 @@ const closeDb = async (): Promise<void> => {
 installLifecycle({
   httpServer, wss, heartbeatTimer, stopReaper,
   sseSessions: sseServer.sessions,
+  sseKeepaliveTimer: sseServer.keepaliveTimer,
   closeDb,
 })
 
 // Bind only after the startup orphan sweep finishes — otherwise a
 // fresh boot could serve traffic against tags whose on-disk state
-// still has residue from a prior crash. Top-level await is fine
-// for an entry-point ESM module (no other module imports this for
-// its exports — the side effect IS the program). `startupReap`
-// already resolves on any error (the reaper's own catch logs the
-// failure unconditionally and returns void), so no outer `.catch`
-// is needed here.
+// still has residue from a prior crash. `startupReap` already
+// resolves on any error (the reaper's own catch logs the failure
+// unconditionally and returns void), so no outer `.catch` is
+// needed here.
 await startupReap
-httpServer.listen(PORT, HOST)
+
+// Bind the HTTP/WS plane on the configured PORT/HOST. Exported so a
+// launcher (server-e2e/cli.js — the triage-server bin) or any `import`er can
+// start serving. The top-level `await startupReap` above means the server
+// is fully ready — DB open, DDL bootstrapped, objstore reaper swept — by
+// the time the import resolves.
+export function start(): void {
+  httpServer.listen(PORT, HOST)
+}
+
+export { httpServer, wss }
+
+// Library mode: when this module is `import`ed (rather than run as the
+// entry script) skip the auto-start so consumers can own the bind — e.g.
+// wrap CF Access / framework-preset shims around the assembled
+// `httpServer`, or just call `start()` when ready. Direct invocation via
+// `node server-e2e/index.ts` (or the `triage-server` bin) still listens.
+if (import.meta.main) {
+  start()
+}
+

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

@@ -14,6 +14,10 @@ export type ShutdownDeps = {
   httpServer: Server
   wss: WebSocketServer
   heartbeatTimer: ReturnType<typeof setInterval>
+  // The SSE keepalive-sweep timer (server-e2e/sse-server.ts). Cleared on
+  // shutdown alongside `heartbeatTimer` so a tick can't write a keepalive
+  // comment to a session the close loop below is already tearing down.
+  sseKeepaliveTimer: ReturnType<typeof setInterval>
   // Stops the periodic reaper AND awaits any in-flight sweep.
   stopReaper: () => Promise<void>
   // Live SSE+POST session iterator (mirrors `wss.clients` for the SSE
@@ -46,7 +50,12 @@ export function createLifecycle(): Lifecycle {
   const inFlight = new Set<Promise<unknown>>()
   function track(promise: Promise<unknown>): void {
     inFlight.add(promise)
-    promise.finally(() => inFlight.delete(promise))
+    // Trailing `.catch(() => {})` swallows the rejection that `.finally`
+    // propagates through its returned promise — without it, a tracked
+    // handler that rejects (or whose caller's catch handler itself
+    // throws) trips the `unhandledRejection` catchall below and crashes
+    // the process via `fireShutdown(1)`.
+    promise.finally(() => inFlight.delete(promise)).catch(() => {})
   }
   let shuttingDown = false
   // Live exit code the in-progress shutdown will pass to `process.exit`.
@@ -57,7 +66,7 @@ export function createLifecycle(): Lifecycle {
   let pendingExitCode = 0
 
   function install(deps: ShutdownDeps): void {
-    const { httpServer, wss, heartbeatTimer, stopReaper, sseSessions, closeDb } = deps
+    const { httpServer, wss, heartbeatTimer, sseKeepaliveTimer, stopReaper, sseSessions, closeDb } = deps
 
     async function shutdown(exitCode: number = 0): Promise<void> {
       // Re-entry: don't restart the teardown, but escalate the pending
@@ -72,9 +81,9 @@ export function createLifecycle(): Lifecycle {
       shuttingDown = true
       pendingExitCode = exitCode
       console.log('Shutting down…')
-      // Stop the heartbeat so a tick can't fire mid-shutdown and ping a
-      // socket the close-loop below already started tearing down.
-      clearInterval(heartbeatTimer)
+      // Stop both periodic timers (WS heartbeat + SSE keepalive) so neither
+      // fires mid-shutdown against a peer the close-loop is tearing down.
+      for (const timer of [heartbeatTimer, sseKeepaliveTimer]) clearInterval(timer)
       // Send a 1001 (going away) close frame to every open socket BEFORE
       // shutting the listener. Lets clients distinguish a server-initiated
       // graceful shutdown from a network drop, so they can skip their

package/{server → server-e2e}/npm-proxy.ts

@@ -8,7 +8,7 @@
 // the request body and answers with the upstream's JSON.
 //
 // The route is mounted at `/api/npm-advisories`. The same-origin
-// gate runs inside `dispatchNpmAdvisories` below (server/http.ts
+// gate runs inside `dispatchNpmAdvisories` below (server-e2e/http.ts
 // calls the dispatcher directly without a pre-check), so any
 // browser request from a foreign origin is rejected with 403 before
 // we ever issue a fetch — non-browser callers that omit Origin are

package/{server → server-e2e}/objstore/blob-fs.ts

@@ -48,13 +48,13 @@ async function fsOpenLiveReader(dir: string, tag: string, contentHash: string):
   const path = liveFilePath(dir, tag, contentHash)
   let fh
   try { fh = await open(path, 'r') } catch (err: unknown) {
-    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return { ok: false, reason: 'unavailable' }
+    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return { ok: false, reason: 'unavailable', detail: 'fs-enoent' }
     throw err
   }
   let size: number
   try { size = (await fh.stat()).size } catch {
     await fh.close().catch(() => {})
-    return { ok: false, reason: 'unavailable' }
+    return { ok: false, reason: 'unavailable', detail: 'fs-stat-failed' }
   }
   const stream = fh.createReadStream()
   let closed = false
@@ -90,12 +90,10 @@ export function openFsBlobBackend(dir: string): BlobBackend {
         // closed by Node's stream machinery on 'finish'.
         finalize: async () => {},
         // `destroy(err)` synchronously starts tearing the stream
-        // down; the WriteStream emits 'close' on the next tick.
-        // For the FS backend there's no remote upload to wait for,
-        // so we resolve immediately — the REST layer awaits but
-        // doesn't block on anything real here. eslint-disable for
-        // the no-await-in-async — the function signature is
-        // dictated by the BlobBackend contract.
+        // down; the WriteStream emits 'close' on the next tick. No
+        // remote upload to wait for on FS, so we resolve immediately
+        // — the REST layer awaits but doesn't block on anything real.
+        // Async signature is dictated by the BlobBackend contract.
         // eslint-disable-next-line require-await
         abort: async (err) => { writable.destroy(err as Error) },
       }

package/{server → server-e2e}/objstore/blob-vercel.ts

@@ -1,5 +1,5 @@
 // Vercel Blob Private Storage BlobBackend. Paired with the Neon DB
-// plane in `server/index.ts` when `BLOB_READ_WRITE_TOKEN` is set;
+// plane in `server-e2e/index.ts` when `BLOB_READ_WRITE_TOKEN` is set;
 // the combination is the supported multi-replica deployment shape
 // (Neon for metadata, Vercel Blob for bytes — both serverless, both
 // HTTP-backed, no shared filesystem required).
@@ -119,21 +119,19 @@ type VercelBlobSdk = {
 
 // Recognise "blob is gone" errors uniformly across read/write/delete
 // paths so callers can treat them as success (delete) or
-// not-found (read). The SDK exposes BlobNotFoundError as a class
-// with `.name === 'BlobNotFoundError'`; checking the name string
-// avoids importing the class at the top level (which would force
-// the optional peer dep to resolve).
+// not-found (read). The SDK exposes BlobNotFoundError as a class with
+// `.name === 'BlobNotFoundError'`; checking the name string avoids
+// importing the class at the top level (which would force the optional
+// peer dep to resolve).
 //
-// Class-name check ONLY. The SDK's internal mapper translates every
-// API `not_found` code into BlobNotFoundError-by-name; a bare-404
-// transport leak doesn't reach here. A prior version of this
-// function had a `/does not exist|\b404\b/` fallback that
-// DANGEROUSLY matched BlobStoreNotFoundError's message "This store
-// does not exist." — a config fault (revoked token, deleted store)
-// would silently surface as every-blob-missing across reads and
-// unlinks, masking the fatal misconfiguration. The tight name check
-// lets BlobStoreNotFoundError / other classes propagate as real
-// exceptions.
+// Class-name check ONLY — the SDK's internal mapper turns every API
+// `not_found` into BlobNotFoundError-by-name, so a bare-404 transport
+// leak doesn't reach here. A broader `/does not exist|\b404\b/` match
+// is DANGEROUS: it also matches BlobStoreNotFoundError's "This store
+// does not exist.", so a config fault (revoked token, deleted store)
+// would silently surface as every-blob-missing across reads/unlinks,
+// masking the fatal misconfiguration. The tight name check lets
+// BlobStoreNotFoundError / other classes propagate as real exceptions.
 function isNotFound(err: unknown): boolean {
   if (err == null || typeof err !== 'object') return false
   const name = (err as { name?: unknown }).name
@@ -242,20 +240,17 @@ function buildOpenStagingWriter(sdk: VercelBlobSdk, token: string): BlobBackend[
       abortSignal: ac.signal,
     })
     // Defuse a possible unhandled-rejection if abort() is called
-    // BEFORE finalize() (the REST layer's error path). Attach a
-    // detached `.catch` on the original promise so an early
-    // rejection has a handler; finalize() awaits `putPromise`
-    // directly, which still re-throws the original rejection
-    // (the .catch returns a separate chain that doesn't replace
-    // putPromise's state).
+    // BEFORE finalize() (the REST error path). The detached `.catch`
+    // gives an early rejection a handler; finalize() still awaits
+    // `putPromise` directly and re-throws the original rejection (the
+    // .catch is a separate chain, not a replacement of putPromise).
     putPromise.catch(() => {})
     return {
       writable: pt,
       // Await the upload's completion. After pipeline(req, counter,
-      // pt) resolves, pt has emitted 'end' on the read side and
-      // `put` is finalising the last multipart part. Awaiting here
-      // gives us the same "bytes durable" guarantee that
-      // pipeline-to-WriteStream gives the FS backend.
+      // pt) resolves, pt has emitted 'end' and `put` is finalising the
+      // last multipart part. Awaiting here gives the same "bytes
+      // durable" guarantee pipeline-to-WriteStream gives the FS backend.
       finalize: async () => { await putPromise },
       // Await the SDK's put-promise settlement (rejected via the
       // AbortController). Without this await, a slow upload that
@@ -315,11 +310,11 @@ function buildPromoteStagingToLive(sdk: VercelBlobSdk, token: string): BlobBacke
       //
       // `allowOverwrite: true` because the content-addressed live
       // pathname `${tag}/${contentHash}.bin` can be (re)written by a
-      // retried or racing promote of the same blob. The destination
-      // bytes are identical by construction (the path IS the hash), so
-      // the overwrite is idempotent — never a clobber of DIFFERENT
-      // bytes. Without the flag, the SDK sends `x-allow-overwrite: 0`
-      // and Vercel rejects any such re-promote with BlobAccessError.
+      // retried or racing promote of the same blob. Destination bytes
+      // are identical by construction (the path IS the hash), so the
+      // overwrite is idempotent — never a clobber of DIFFERENT bytes.
+      // Without the flag the SDK sends `x-allow-overwrite: 0` and
+      // Vercel rejects the re-promote with BlobAccessError.
       await sdk.copy(from, to, {
         access: 'private',
         allowOverwrite: true,
@@ -356,17 +351,55 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
     // origin truth. Origin fetch is the right default for a store
     // where freshness > latency.
     try { res = await sdk.get(path, { access: 'private', useCache: false, token }) } catch (err) {
-      if (isNotFound(err)) return { ok: false, reason: 'not-found' }
+      // A missing blob HERE is never "the resource doesn't exist" — the
+      // REST layer (rest.ts openLiveSnapshot) already confirmed a live row
+      // whose (version, incarnation) matches the GET token before calling
+      // us. So BlobNotFoundError means the bytes for a still-live row are
+      // momentarily gone: the reaper GC'd a hash a racing version-bump just
+      // unreferenced, or Vercel's read-after-write / edge propagation hasn't
+      // caught up to a freshly-promoted private blob. That is the documented
+      // `unavailable` (HTTP 503) transient — reconciled by reaper /
+      // propagation, retried by the client — NOT a 404. Returning
+      // `not-found` would emit a 404 the FS backend never emits for the
+      // same condition (blob-fs.ts maps ENOENT → `unavailable`), telling
+      // the client the resource is gone for good when it should refetch.
+      // See server-e2e/README.md's GET status table.
+      if (isNotFound(err)) return { ok: false, reason: 'unavailable', detail: 'vercel-get-not-found' }
       throw err
     }
-    if (res == null) return { ok: false, reason: 'not-found' }
+    // SDK returned null (no blob) — same "bytes missing for a live row"
+    // transient as the BlobNotFoundError branch above → `unavailable`, not
+    // `not-found`.
+    if (res == null) return { ok: false, reason: 'unavailable', detail: 'vercel-get-null' }
     // statusCode 304 doesn't reach here in practice — the REST
     // GET layer doesn't pass If-None-Match — but a future call
     // site could. Treat as unavailable rather than streaming a
     // null body.
-    if (res.statusCode !== 200 || res.stream == null || res.blob.size == null) {
-      return { ok: false, reason: 'unavailable' }
+    if (res.statusCode !== 200 || res.stream == null) {
+      return { ok: false, reason: 'unavailable', detail: `vercel-get-status-${res.statusCode}` }
     }
+    // `@vercel/blob@2.x`'s streaming `get()` for private blobs returns
+    // the body but does NOT populate `blob.size` nor pass a
+    // `content-length` header (verified empirically: get.size=0,
+    // content-length-hdr=null, while head.size reports the true count).
+    // The REST layer needs a size to set `content-length` and for the
+    // integrity check against the DB row, so on 0/null we fall back to
+    // head(). Two round-trips per private read until the SDK is fixed —
+    // small price vs. 503ing every read.
+    let size: number | null | undefined = res.blob?.size
+    if (size == null || size === 0) {
+      try {
+        const h = await sdk.head(path, { token })
+        size = (h as { size?: number })?.size
+      } catch (headErr) {
+        // Blob vanished between get() and the head() size fallback (a
+        // racing reaper GC) — still the "live row present, bytes gone"
+        // transient, so `unavailable` (503), matching the get() path above.
+        if (isNotFound(headErr)) return { ok: false, reason: 'unavailable', detail: 'vercel-head-not-found' }
+        throw headErr
+      }
+    }
+    if (size == null) return { ok: false, reason: 'unavailable', detail: 'vercel-no-size' }
     // SDK returns a web ReadableStream<Uint8Array>; the REST layer
     // expects a Node Readable for pipeline(). Convert via
     // Readable.fromWeb — built-in and zero-copy where possible.
@@ -376,7 +409,7 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
       ok: true,
       reader: {
         stream: nodeStream,
-        size: res.blob.size,
+        size,
         // eslint-disable-next-line require-await
         close: async () => {
           // Destroying the Node wrapper also cancels the underlying
@@ -460,7 +493,7 @@ export type VercelBlobBackendOptions = {
   // Vercel Blob R/W token, typically from BLOB_READ_WRITE_TOKEN.
   // The SDK also reads it from process.env, but passing it
   // explicitly here keeps the env-var → boot config path single-
-  // sourced through server/index.ts (matches the Neon DATABASE_URL
+  // sourced through server-e2e/index.ts (matches the Neon DATABASE_URL
   // handling — env-read at boot, threaded as a parameter).
   token: string
   // Test seam: inject a stub of the @vercel/blob module to avoid

package/{server → server-e2e}/objstore/blob.ts

@@ -11,7 +11,7 @@
 //                         the Neon DB plane for multi-replica
 //                         deployments)
 //
-// Selected at boot in `server/index.ts` and passed to `openObjstore`
+// Selected at boot in `server-e2e/index.ts` and passed to `openObjstore`
 // / `openNeonObjstore`. The DB-plane code in ./store.ts, ./rest.ts,
 // and ./reaper.ts goes through `handle.blob.*` and is backend-
 // agnostic — no `if (vercel) … else` branching in consumers.
@@ -83,13 +83,27 @@ export type LiveReader = {
   close(): Promise<void>
 }
 
-// `not-found` maps to HTTP 404 (the live blob is gone or never
-// existed); `unavailable` maps to HTTP 503 (transient backend issue
-// the reaper will eventually sort out). The REST layer uses this
-// discrimination to set the right status code.
+// A missing blob is always `unavailable` (→ HTTP 503), never a 404. The
+// byte plane has NO view of the metadata row, so it can't decide whether
+// a resource "doesn't exist" — only whether specific bytes are present
+// right now. The authoritative "this resource/version is gone" 404 is the
+// REST layer's call, made from the live row BEFORE it opens a reader
+// (rest.ts openLiveSnapshot). By the time `openLiveReader` runs the row is
+// already confirmed, so an absent blob means a transient bytes/metadata
+// desync the reaper (or store propagation) reconciles — exactly the
+// `unavailable`/503 contract, which the client retries. Both backends MUST
+// map a missing blob to `unavailable` (FS: ENOENT; Vercel: BlobNotFoundError
+// / null get()). No 404-mapping variant exists here so that bug can't recur.
+//
+// `detail` is a short, NON-SENSITIVE machine tag for the specific cause
+// (e.g. 'vercel-get-not-found', 'fs-enoent', 'vercel-no-size'). Every
+// byte-side failure collapses to the same 503 on the wire, so a permanent
+// loss (reaper GC'd the bytes) and a transient read fault are otherwise
+// indistinguishable — the REST layer logs `detail` so an operator can tell
+// them apart. Purely diagnostic; the REST status is unchanged.
 export type OpenLiveResult =
   | { ok: true; reader: LiveReader }
-  | { ok: false; reason: 'not-found' | 'unavailable' }
+  | { ok: false; reason: 'unavailable'; detail?: string }
 
 export type BlobBackend = {
   // Per-workspace setup. FS creates the on-disk staging directory;
@@ -128,9 +142,10 @@ export type BlobBackend = {
   promoteStagingToLive(tag: string, stagingId: string, contentHash: string): Promise<boolean>
 
   // Open a streaming reader for the content-addressed live blob.
-  // `not-found` lets the REST layer return 404; `unavailable` returns
-  // 503 for a transient state (file/blob missing while the row still
-  // exists — reaper will reconcile on the next sweep).
+  // Called only after the REST layer has confirmed the live row, so a
+  // missing blob is the transient "row present, bytes gone" state →
+  // `unavailable` (HTTP 503), which the reaper reconciles and the client
+  // retries. Never a 404 from here — see OpenLiveResult above.
   openLiveReader(tag: string, contentHash: string): Promise<OpenLiveResult>
 
   // Idempotent deletes. Backends MUST tolerate "already gone" as

package/server-e2e/objstore/fetch-mint-guard.ts

@@ -0,0 +1,74 @@
+// Anti-replay guard for the REST fetch-mint endpoint (POST
+// /api/objstore/{tag}/{res}, see ./rest.ts). The WS fetch handshake binds
+// the per-connection challenge nonce so a captured frame can't be
+// replayed; the REST mint has no connection, so it binds a client
+// timestamp instead and this guard supplies the matching freshness +
+// dedup the nonce gave for free:
+//
+//   - FRESHNESS: reject a request whose `ts` is outside ±`windowMs` of
+//     server time (an old captured request, or a future-dated one).
+//   - DEDUP: within the window, a signature is accepted at most once — a
+//     captured-and-replayed request (same `ts` ⇒ same signature) is
+//     rejected on the second presentation.
+//
+// Memory: each accepted signature is held for `windowMs` then pruned.
+// Entries share a uniform TTL and the Map preserves insertion order, so
+// the oldest entries expire first and a cheap front-prune (amortised
+// O(1) per entry) keeps the set bounded; a hard `maxEntries` cap drops
+// the oldest beyond it as a flood backstop.
+//
+// Scope: per-process. In a multi-replica deployment a captured request
+// could be replayed once per replica that hasn't seen its signature yet
+// (bounded by the replica count, within the window) — acceptable because
+// the mint only ever yields a short-TTL GET token over AEAD ciphertext
+// the relay can't read. A shared-store dedup (Redis/Neon) would close
+// that residual gap if ever needed.
+
+export type FetchMintVerdict = 'ok' | 'stale' | 'replay'
+
+export type FetchMintGuard = {
+  // `signature` is the request's Ed25519 signature (unique per
+  // (tag, res, ts) tuple, so it doubles as the dedup key). `ts` is the
+  // client epoch-ms timestamp the signature commits to; `now` is the
+  // server clock (injectable for tests).
+  admit: (signature: string, ts: number, now?: number) => FetchMintVerdict
+  size: () => number
+}
+
+export const DEFAULT_FETCH_MINT_WINDOW_MS = 60_000
+export const DEFAULT_FETCH_MINT_MAX_ENTRIES = 50_000
+
+export function createFetchMintGuard(
+  { windowMs = DEFAULT_FETCH_MINT_WINDOW_MS, maxEntries = DEFAULT_FETCH_MINT_MAX_ENTRIES }:
+    { windowMs?: number; maxEntries?: number } = {},
+): FetchMintGuard {
+  // signature → expiry (ms). Insertion-ordered; uniform TTL ⇒ the head is
+  // always the soonest to expire.
+  const seen = new Map<string, number>()
+
+  function admit(signature: string, ts: number, now: number = Date.now()): FetchMintVerdict {
+    // Freshness first — a stale/future request never touches the cache, so
+    // it can't be used to grow the set.
+    if (!Number.isFinite(ts) || Math.abs(now - ts) > windowMs) return 'stale'
+    // Front-prune expired entries (contiguous at the head under the
+    // uniform TTL). Breaks at the first live entry.
+    for (const [key, exp] of seen) {
+      if (exp > now) break
+      seen.delete(key)
+    }
+    // Post-prune, any remaining entry is live, so a hit is a genuine replay.
+    if (seen.has(signature)) return 'replay'
+    seen.set(signature, now + windowMs)
+    // Flood backstop: drop the oldest beyond the cap. Those are the
+    // closest to expiry anyway; dropping them only shortens their dedup
+    // window (still freshness-gated).
+    while (seen.size > maxEntries) {
+      const oldest = seen.keys().next().value
+      if (oldest === undefined) break
+      seen.delete(oldest)
+    }
+    return 'ok'
+  }
+
+  return { admit, size: () => seen.size }
+}