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

package/server/objstore/blob-vercel.ts

@@ -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,10 +351,26 @@ 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/README.md's GET status table.
+      if (isNotFound(err)) return { ok: false, reason: 'unavailable' }
       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' }
     // 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
@@ -367,23 +378,24 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
     if (res.statusCode !== 200 || res.stream == null) {
       return { ok: false, reason: 'unavailable' }
     }
-    // `@vercel/blob@2.x`'s streaming `get()` for private blobs
-    // returns the body but does NOT populate `blob.size` and does
-    // NOT pass a `content-length` header through (verified
-    // empirically: get.size=0, content-length-hdr=null while
-    // head.size reports the true byte count). The REST layer
-    // depends on a size to set `content-length` on its response
-    // and for the integrity check against the DB row, so when
-    // get() leaves it 0/null we fall back to a head() lookup.
-    // Two round-trips per private read on Vercel until the SDK is
-    // fixed — small price vs. the alternative of 503ing every read.
+    // `@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) {
-        if (isNotFound(headErr)) return { ok: false, reason: 'not-found' }
+        // 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' }
         throw headErr
       }
     }

package/server/objstore/blob.ts

@@ -83,13 +83,20 @@ 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.
 export type OpenLiveResult =
   | { ok: true; reader: LiveReader }
-  | { ok: false; reason: 'not-found' | 'unavailable' }
+  | { ok: false; reason: 'unavailable' }
 
 export type BlobBackend = {
   // Per-workspace setup. FS creates the on-disk staging directory;
@@ -128,9 +135,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/objstore/handlers.ts

@@ -68,11 +68,11 @@ function urlPathFor(tag: string, resourceTag: string): string {
 // Shared gate every objstore handler runs after its message-specific
 // field checks: fetch the socket's challenge nonce, verify the signed
 // message against it, then re-confirm the socket is still OPEN — the
-// close handler may have fired during the verify await, and attaching
-// to / replying on a closed socket is the half-handshake leak case
-// (PR #4 review F4). Returns true when the caller may proceed.
-// Centralising the post-await readyState recheck keeps that
-// easy-to-forget invariant in one auditable place.
+// close handler may have fired during the verify await, and replying
+// on a closed socket is the half-handshake leak case (PR #4 review
+// F4). Centralising the post-await readyState recheck keeps that
+// invariant in one auditable place. Returns true when the caller may
+// proceed.
 async function verified<M extends { workspaceTag?: unknown }>(
   deps: ObjstoreDeps, socket: WebSocket, msg: M, label: string,
   verify: (m: M, nonce: string) => Promise<boolean>,
@@ -96,12 +96,10 @@ async function handlePutBegin(deps: ObjstoreDeps, socket: WebSocket, msg: Objsto
   // signature to fail. Cheaper to reject up-front, and consistent
   // with `verifyObjstorePutSig`'s `isSafeNonNegativeInt` gate.
   if (!Number.isSafeInteger(msg.expectedLength) || (msg.expectedLength as number) < 0 || (msg.expectedLength as number) > MAX_CONTENT_LENGTH) return
-  // Symmetric with `handleDelete`'s prevVersion gate (line 116) and
-  // `verifyObjstorePutSig`'s `isSafeIntOrNull` (sign.ts:119). Without
-  // this, a non-safe-integer `prevVersion` (NaN, 2^53+1, ...) would
-  // pass the typeof check below and reach sig verify, burning a
-  // hash + Ed25519 round-trip on a guaranteed-fail input. Input-
-  // validation audit `server/objstore/handlers.ts:76`.
+  // Same up-front reject for `prevVersion` (symmetric with handleDelete
+  // and `verifyObjstorePutSig`'s `isSafeIntOrNull`): a non-safe-integer
+  // (NaN, 2^53+1, ...) would pass the typeof check below and reach sig
+  // verify, burning a hash + Ed25519 round-trip on a guaranteed fail.
   if (msg.prevVersion != null && (typeof msg.prevVersion !== 'number' || !Number.isSafeInteger(msg.prevVersion))) return
   if (!await verified(deps, socket, msg, 'put-begin', verifyObjstorePutSig)) return
   const tag = msg.workspaceTag
@@ -110,8 +108,8 @@ async function handlePutBegin(deps: ObjstoreDeps, socket: WebSocket, msg: Objsto
   // workspace tag (no rows in workspace_revision AND none in
   // workspace_object). Mirrors handleSave in server/index.ts; runs
   // AFTER sig verify so `unauthorized` only reaches a legitimate
-  // signer. The gate is config-driven (server/config.json
-  // `password`) and is a no-op when no password is configured.
+  // signer. Config-driven (server/config.json `password`), no-op when
+  // unconfigured.
   if (deps.authGate && deps.sendUnauthorized && await deps.authGate(socket, tag)) {
     if (socket.readyState !== socket.OPEN) return
     if (deps.debug) console.warn(`reject objstore-put-begin: unauthorized (new workspace ${debugTag(tag)})`)

package/server/objstore/init.ts

@@ -56,6 +56,16 @@ export type ObjstoreInit = {
 }
 
 export function initObjstore(deps: ObjstoreInitDeps): ObjstoreInit {
+  // Fail loud on a lopsided auth config. The put-begin gate in
+  // handlers.ts only fires when BOTH authGate and sendUnauthorized are
+  // present (it needs the reporter to emit the `unauthorized` frame),
+  // so wiring authGate WITHOUT sendUnauthorized silently fails OPEN —
+  // unauthenticated first-writes to unknown workspaces would be accepted
+  // despite the operator's intent to gate them. Reject at boot rather
+  // than regress access control silently.
+  if (deps.authGate && !deps.sendUnauthorized) {
+    throw new Error('initObjstore: authGate requires sendUnauthorized (the put-begin gate needs it to emit the unauthorized frame)')
+  }
   const handle = deps.handle
   const secret = deps.tokenSecret ?? newTokenSecret()
   const handlers = createObjstoreHandlers({
@@ -93,15 +103,14 @@ export function initObjstore(deps: ObjstoreInitDeps): ObjstoreInit {
   // on-disk state still has stranded files from a prior crash.
   const startupReap = enqueueSweep()
   // Jittered start of the periodic timer. Multi-replica deploys
-  // (Neon + Vercel Blob) commonly boot N replicas in tight lock-
-  // step (deploy rollout, cluster restart) and would otherwise
-  // sync every replica's reaper at the same wall-clock tick,
-  // hammering the DB + blob store with N×readdir+lock-acquire
-  // bursts. A random first-interval delay deconcurrencies the
-  // cluster without changing the long-term sweep cadence.
-  // Jitter range is 0…1× reapIntervalMs (i.e., the next sweep
-  // happens at [interval, 2×interval] after boot); subsequent
-  // sweeps stay at exactly `reapIntervalMs` apart.
+  // (Neon + Vercel Blob) commonly boot N replicas in tight lock-step
+  // (deploy rollout, cluster restart), which would otherwise sync every
+  // replica's reaper to the same wall-clock tick and hammer the DB +
+  // blob store with N×readdir+lock-acquire bursts. A random
+  // first-interval delay spreads the cluster out without changing the
+  // long-term cadence. Jitter is 0…1× reapIntervalMs (first sweep at
+  // [interval, 2×interval] after boot); subsequent sweeps stay exactly
+  // `reapIntervalMs` apart.
   let reapTimer: ReturnType<typeof setInterval> | null = null
   const jitterMs = Math.floor(Math.random() * deps.reapIntervalMs)
   const firstTimer = setTimeout(() => {

package/server/objstore/rest.ts

@@ -45,16 +45,14 @@ import { errStack } from '../util.ts'
 
 // Server-side fault codes that should surface as 500 `io-error`
 // rather than 400 `aborted`. `pipeline(req, ws)` rejects with the
-// first stream error; the client-side codes (socket close, the
-// manual `overrun`) are everything else. ENOENT is included because
-// `createWriteStream` will reject with it if the `${tag}/.staging`
-// dir was removed out from under us (operator action / external
-// fs activity) — that's a server-side state, not a client-fixable
-// abort. PR #4 review. The Vercel-blob backend surfaces failures
-// through other paths (rejected put promise → caught by the
-// pipeline catch as a plain Error without a `code`); those land in
-// the default `aborted` branch and the operator-facing log line
-// carries the SDK's error message.
+// first stream error; client-side codes (socket close, the manual
+// `overrun`) are everything else. ENOENT is included because
+// `createWriteStream` rejects with it if the `${tag}/.staging` dir
+// was removed out from under us (operator / external fs activity) —
+// a server-side state, not a client-fixable abort. Vercel-blob
+// failures arrive without a `code` (rejected put promise → plain
+// Error); those land in the default `aborted` branch, with the SDK
+// error in the operator log line.
 const IO_FAULT_CODES = new Set(['ENOSPC', 'EACCES', 'EROFS', 'EIO', 'EMFILE', 'ENFILE', 'EDQUOT', 'EPERM', 'ENOENT'])
 
 export type ObjstoreRestDeps = {
@@ -71,35 +69,34 @@ export type ObjstoreRestDeps = {
   debug: boolean
 }
 
-// Concurrent commits need no lock at all: the live blob is content-
-// addressed (`${tag}/${contentHash}.bin`) so two racing commits write
-// to DIFFERENT immutable addresses, and the commit itself is an atomic
-// version compare-and-set on the live row (see commitPut in store.ts).
-// Exactly one racer wins the CAS; the loser gets a 409 `conflict` and
-// rebases. This holds within a single process and across replicas —
-// there is no in-process mutex serialising commits. (The PUT *body*
-// does take a per-process single-writer reservation — `inFlightSids`
-// below — but that only rejects a duplicate upload of one staging
-// slot; it never makes distinct commits wait.)
+// Concurrent commits need no lock: the live blob is content-addressed
+// (`${tag}/${contentHash}.bin`) so two racing commits write to
+// DIFFERENT immutable addresses, and the commit is an atomic version
+// compare-and-set on the live row (see commitPut in store.ts). Exactly
+// one racer wins the CAS; the loser gets a 409 `conflict` and rebases.
+// Holds within a process and across replicas — no in-process mutex
+// serialises commits. (The PUT *body* takes a per-process single-
+// writer reservation — `inFlightSids` below — but that only rejects a
+// duplicate upload of one staging slot; distinct commits never wait.)
 
 // Per-process single-writer guard for the REST PUT body. A put-token is
 // a REUSABLE bearer capability (tokens.ts) valid for its whole TTL, so a
-// client replaying it on overlapping PUTs — a retry that doesn't cancel
-// the in-flight request, a proxy re-issuing the PUT, a double-submit —
+// client replaying it on overlapping PUTs (a retry that doesn't cancel
+// the in-flight request, a proxy re-issuing the PUT, a double-submit)
 // would otherwise have two requests stream into the SAME staging file
-// (same sid). On the FS backend `createWriteStream(…, { flags: 'w' })`
-// truncates, so the two writers clobber each other's bytes/size and BOTH
-// can fail (size-mismatch 400 + promote-race 500) with neither
-// committing. `inFlightSids` admits exactly ONE in-flight upload per
-// staging id; a concurrent same-token PUT is rejected (409) before it
-// can open a second writer. The slot is held only across the body +
-// commit and released in a `finally` (and bounded by the REST idle-body
-// timeout in server/http.ts so a slow-loris can't pin it). It is NOT a
-// commit lock — commits stay lock-free on the version-CAS above. It's
-// per-process: the Vercel multi-replica path leans on `allowOverwrite:
-// true` + the commit CAS + content-addressing for cross-replica
-// correctness (a duplicate that lands on another replica can't clobber a
-// shared local file and still loses the CAS), not on this set.
+// (same sid). On FS, `createWriteStream(…, { flags: 'w' })` truncates,
+// so the two writers clobber each other's bytes/size and BOTH can fail
+// (size-mismatch 400 + promote-race 500) with neither committing.
+// `inFlightSids` admits exactly ONE in-flight upload per staging id; a
+// concurrent same-token PUT is rejected (409) before it can open a
+// second writer. The slot is held only across body + commit, released
+// in a `finally`, and bounded by the REST idle-body timeout in
+// server/http.ts so a slow-loris can't pin it. NOT a commit lock —
+// commits stay lock-free on the version-CAS above. Per-process: the
+// Vercel multi-replica path leans on `allowOverwrite: true` + the
+// commit CAS + content-addressing for cross-replica correctness (a
+// duplicate landing on another replica can't clobber a shared local
+// file and still loses the CAS), not on this set.
 const inFlightSids = new Set<string>()
 
 // `/api/objstore/${workspaceTag}/${resourceTag}` — base64url
@@ -121,14 +118,13 @@ export function matchRoute(url: string | undefined): RouteMatch | null {
 
 function deny(res: ServerResponse, status: number, body: string): void {
   // Uniform `{ error: <reason> }` JSON envelope for every failure so
-  // clients have one shape to parse. Status + reason are NOT
-  // intentionally indistinguishable across causes — 401, 404, 405,
-  // 410, 411, 500 each map to a documented reason in server/README.md
-  // and the client decides recovery from the code. Defense against
-  // probe-driven distinguishing isn't a property the relay aims for;
-  // every error reason is reachable only after the route + bearer-
-  // token check passes (or as 401/404 from the public surface), so
-  // there's no signal here a probe couldn't otherwise enumerate.
+  // clients parse one shape. Status + reason are NOT intentionally
+  // indistinguishable across causes — 401/404/405/410/411/500 each map
+  // to a documented reason in server/README.md and the client decides
+  // recovery from the code. Probe-distinguishing defense isn't a goal:
+  // every reason is reachable only after the route + bearer-token check
+  // passes (or as 401/404 from the public surface), so a probe gains no
+  // signal it couldn't otherwise enumerate.
   res.writeHead(status, { 'content-type': 'application/json' })
   res.end(JSON.stringify({ error: body }))
 }
@@ -209,21 +205,20 @@ async function handleRestPut(
   // No lock: the commit's version-CAS arbitrates concurrent commits
   // (the live blob is content-addressed, so racers can't desync
   // metadata vs bytes — the loser surfaces a 409 `conflict`). The
-  // staging row is protected from the reaper not by a lock but by its
-  // `begun_at`: an upload under the staging TTL stays fresh through the
-  // body, and the after-body `refreshStagingBegunAt` re-extends the
-  // TTL across the commit. (An upload exceeding the TTL during the
-  // body can be reaped mid-flight → commit 410s; documented accepted
-  // tradeoff — see commitPut in store.ts.)
+  // staging row is protected from the reaper by its `begun_at`, not a
+  // lock: an upload under the staging TTL stays fresh through the body,
+  // and the after-body `refreshStagingBegunAt` re-extends the TTL across
+  // the commit. (An upload exceeding the TTL during the body can be
+  // reaped mid-flight → commit 410s; documented accepted tradeoff —
+  // see commitPut in store.ts.)
   await handleRestPutBody(deps, req, res, route, payload, declared)
 }
 
 // Map a `commitPut` failure to its wire response. Extracted from
-// `handleRestPutBody` to keep it under the per-function line cap
-// and to make the wire-mapping ladder its own audit surface — the
-// exhaustiveness `never` guard at the bottom catches a forward-
-// compat hazard where a new `CommitPutResult` reason lands without
-// updating this dispatch.
+// `handleRestPutBody` to keep it under the per-function line cap and
+// to make the wire-mapping ladder its own audit surface — the
+// exhaustiveness `never` guard at the bottom catches a new
+// `CommitPutResult` reason landing without updating this dispatch.
 function denyCommitFailure(res: ServerResponse, result: Exclude<CommitPutResult, { ok: true }>): void {
   if (result.reason === 'conflict') {
     denyConflict(res, result.conflict?.version ?? null, result.conflict?.incarnation ?? null)
@@ -273,10 +268,9 @@ async function handleRestPutBody(
   }
   inFlightSids.add(payload.sid)
   try {
-    // Stream the upload + commit, no lock. The commit's version-CAS
-    // arbitrates concurrent commits; the staging row is kept fresh for
-    // the reaper by its `begun_at` (+ the after-body refresh), not by a
-    // mutex. See the rationale in handleRestPut above.
+    // Stream the upload + commit, no lock — version-CAS arbitrates
+    // commits, the staging row stays fresh for the reaper via its
+    // `begun_at` (+ after-body refresh). See handleRestPut above.
     const result = await runUploadAndCommit(deps, route, payload, declared, req, res)
     if (result.handled) return
     if (!result.commit.ok) { denyCommitFailure(res, result.commit); return }
@@ -294,15 +288,13 @@ async function handleRestPutBody(
       ...objectMetaWire(row),
     }, null)
     // Cross-instance fan-out (Neon mode). The bus payload carries only
-    // (tag, resourceTag); peers on other instances re-fetch the live
-    // row from workspace_object to compose their local broadcast. The
-    // committed row is durable by here (commitPut's version-CAS already
-    // landed), so the receiver typically sees either THIS version or a
-    // STRICTLY newer one (also a valid broadcast — clients are
-    // idempotent on (resourceTag, version)). The receiver is allowed
-    // to find no live row at all if a subsequent delete races the
-    // notification; bus-receiver.ts drops that case silently. SQLite
-    // mode publishes to a no-op.
+    // (tag, resourceTag); peers on other instances re-fetch the live row
+    // from workspace_object to compose their broadcast. The committed
+    // row is durable by here (commitPut's version-CAS landed), so the
+    // receiver sees THIS version or a STRICTLY newer one (also valid —
+    // clients are idempotent on (resourceTag, version)), or no live row
+    // at all if a subsequent delete races the notification (bus-
+    // receiver.ts drops that silently). SQLite mode publishes to a no-op.
     deps.publishObjPut(route.tag, route.resourceTag)
     if (deps.debug) console.log(`objstore put → ${route.tag.slice(0, 12)}…/${route.resourceTag.slice(0, 8)}… v${row.version}`)
   } finally {
@@ -451,7 +443,7 @@ async function openLiveSnapshot(
   // bytes behind `live.content_hash` can never change underneath us —
   // the worst a race can do is have the reaper GC an already-superseded
   // hash just before we open it, which surfaces as openLiveReader
-  // not-found → `unavailable` → 503, and the client refetches. We can
+  // returning `unavailable` → 503, and the client refetches. We can
   // never serve torn or wrong bytes. (For the FS backend the open also
   // returns a pinned fd; for the Vercel backend a fetch-backed stream.)
   const live = await deps.handle.selectLiveOne.get(route.tag, route.resourceTag)

package/server/objstore/store-neon.ts

@@ -46,10 +46,10 @@ const DDL_LOCK_KEY_OBJSTORE_SUB = 0x6f62_6a73 // 'objs'
 // defend the commitPut conflict arithmetic — a manual `UPDATE
 // workspace_object SET version = -1` would otherwise round-trip
 // through `num()` (which only rejects non-safe-integers) and corrupt
-// the version monotonicity invariant. The SQLite schema carries the
-// identical CHECKs (see `store.ts`) — STRICT there enforces the column
-// TYPE but NOT this value domain (`version = -1` is a valid integer
-// STRICT accepts), so both backends need the explicit CHECKs.
+// version monotonicity. SQLite carries the identical CHECKs (see
+// `store.ts`): STRICT there enforces column TYPE but NOT this value
+// domain (`version = -1` is a valid integer STRICT accepts), so both
+// backends need the explicit CHECKs.
 const SCHEMA_PG = [
   `CREATE TABLE IF NOT EXISTS workspace_object (
      workspace_tag  TEXT    NOT NULL,