@preventive/triage 1.0.0-alpha.0

package/server/objstore/fs.ts

@@ -0,0 +1,67 @@
+// Filesystem operations for the v1.objstore module — paths +
+// async durable-write primitives. Post-startup callers go through
+// `fs/promises` so a slow disk doesn't block the event loop and
+// stall unrelated requests (WS heartbeats, other workspaces).
+//
+// `liveFilePath` / `stagingFilePath` are the canonical layout —
+// the reaper derives the same shape. The live blob is CONTENT-
+// ADDRESSED: its filename is the content hash, not the resourceTag,
+// so a hash names exactly one immutable byte-string. The base64url
+// alphabet for tag / contentHash / stagingId means no `..` traversal
+// is reachable; validators in store.ts gate inputs at the wire
+// boundary.
+
+import { mkdir, open, rename, unlink } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import { errMsg } from '../util.ts'
+
+export function liveFilePath(dir: string, tag: string, contentHash: string): string {
+  return join(dir, tag, `${contentHash}.bin`)
+}
+
+export function stagingFilePath(dir: string, tag: string, stagingId: string): string {
+  return join(dir, tag, '.staging', `${stagingId}.bin`)
+}
+
+export async function ensureStagingDir(root: string, tag: string): Promise<void> {
+  await mkdir(join(root, tag, '.staging'), { recursive: true })
+}
+
+// fsync(staging) → rename(staging → live) → fsync(parent dir).
+// Order matters: a crash post-rename pre-DB-write leaves a stranded
+// committed-name file (reaper-cleaned), never the inverse. Any
+// failure along the way (ENOENT on the staging file after a racing
+// abort, EACCES, ENOSPC, EIO) → `false`, caller routes through
+// abortPut. Directory fsync isn't supported on every filesystem;
+// the inner catch silently no-ops there. PR #4 review.
+export async function durableRenameStagedToLive(stagingPath: string, livePath: string): Promise<boolean> {
+  try {
+    let fh = await open(stagingPath, 'r')
+    try { await fh.sync() } finally { await fh.close() }
+    await rename(stagingPath, livePath)
+    try {
+      fh = await open(dirname(livePath), 'r')
+      try { await fh.sync() } finally { await fh.close() }
+    } catch { /* not all FS layers support directory fsync */ }
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Tolerate ENOENT (expected race against the reaper / abort) but
+// log everything else (EACCES/EROFS/EBUSY/EIO) — silently dropping
+// those would let deletes "succeed" while files pile up on disk.
+// Don't propagate: the DB-side row drop already committed by the
+// time callers reach here, and the reaper picks up the stranded
+// file on its next sweep. PR #4 review.
+export async function unlinkIfExists(filePath: string): Promise<void> {
+  try { await unlink(filePath) } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException)?.code
+    if (code === 'ENOENT') return
+    // Log the basename only — the full path contains the workspace
+    // tag (Ed25519 public key) and shouldn't go to operator logs
+    // verbatim. PR #4 review H3.
+    console.warn(`unlink …/${basename(filePath)} failed:`, code ?? errMsg(err))
+  }
+}

package/server/objstore/handlers.ts

@@ -0,0 +1,235 @@
+// v1.objstore WS message handlers — control plane only. Byte
+// transfer lives on the REST plane (rest.ts); these handlers mint
+// the bearer tokens the REST handler validates. Each WS message
+// that authorises byte transfer requires an Ed25519 signature
+// against the workspaceTag, then a short-TTL HMAC token bound to
+// the (tag, resource, version-or-stagingId, length) tuple.
+//
+// Operations that mutate (begin / commit / delete) take NO in-process
+// lock: commit correctness is the atomic version-CAS in commitPut,
+// begin's prev_version check is advisory, and delete is a precondition-
+// checked single-row drop (see store.ts for the full lock-free
+// rationale).
+//
+// Broadcasts to peers subscribed via `workspace-subscribe` reuse
+// the existing subscriber map: `objstore-deleted` is emitted from
+// handleDelete here; `objstore-put` is emitted from the REST PUT
+// handler after commit.
+
+import type { WebSocket } from 'ws'
+import {
+  type Handle,
+  MAX_CONTENT_LENGTH,
+  type ObjectRow,
+  beginPut,
+  deleteObject,
+  getLive,
+  isValidContentHash,
+  isValidSignature,
+  isValidTag,
+  objectMetaWire,
+} from './store.ts'
+import {
+  type ObjstoreDeleteMsg,
+  type ObjstoreFetchMsg,
+  type ObjstorePutBeginMsg,
+  verifyObjstoreDeleteSig,
+  verifyObjstoreFetchSig,
+  verifyObjstorePutSig,
+} from './sign.ts'
+import { type TokenSecret, mintGetToken, mintPutToken } from './tokens.ts'
+import { debugTag } from '../util.ts'
+
+export type ObjstoreDeps = {
+  handle: Handle
+  secret: TokenSecret
+  send: (socket: WebSocket, msg: object) => void
+  broadcast: (tag: string, msg: object, except: WebSocket | null) => void
+  getNonce: (socket: WebSocket) => string | undefined
+  debug: boolean
+  // Auth gate for the FIRST put-begin against a never-before-seen
+  // workspace tag. See ObjstoreInitDeps for rationale. Run AFTER
+  // sig verify so `unauthorized` only reaches legitimate signers.
+  // Absent → no gating (no-config default).
+  authGate?: (socket: WebSocket, workspaceTag: string) => Promise<boolean>
+  sendUnauthorized?: (socket: WebSocket, ctx: { kind: 'gated'; workspaceTag: string; resourceTag: string }) => void
+}
+
+function urlPathFor(tag: string, resourceTag: string): string {
+  return `/api/objstore/${tag}/${resourceTag}`
+}
+
+// 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.
+async function verified<M extends { workspaceTag?: unknown }>(
+  deps: ObjstoreDeps, socket: WebSocket, msg: M, label: string,
+  verify: (m: M, nonce: string) => Promise<boolean>,
+): Promise<boolean> {
+  const nonce = deps.getNonce(socket)
+  if (typeof nonce !== 'string') return false
+  if (!await verify(msg, nonce)) {
+    if (deps.debug) console.warn(`reject objstore-${label}: bad sig`, debugTag(msg.workspaceTag as string))
+    return false
+  }
+  return socket.readyState === socket.OPEN
+}
+
+async function handlePutBegin(deps: ObjstoreDeps, socket: WebSocket, msg: ObjstorePutBeginMsg): Promise<void> {
+  if (!isValidTag(msg.workspaceTag) || !isValidTag(msg.resourceTag)) return
+  if (!isValidContentHash(msg.contentHash)) return
+  if (!isValidSignature(msg.signature)) return
+  // `Number.isSafeInteger` rather than `typeof === 'number'`: a NaN
+  // or non-finite value would pass typeof + comparisons (NaN <
+  // MAX_CONTENT_LENGTH is false), reaching sig verify only for the
+  // 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`.
+  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
+  const resourceTag = msg.resourceTag
+  // Auth gate for the FIRST action against a never-before-seen
+  // 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.
+  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)})`)
+    deps.sendUnauthorized(socket, { kind: 'gated', workspaceTag: tag, resourceTag })
+    return
+  }
+  const prevVersion = typeof msg.prevVersion === 'number' ? msg.prevVersion : null
+  // `verifyObjstorePutSig` already enforced the prevVersion/prevIncarnation
+  // pairing (null-iff-null + valid id shape), so this narrows safely.
+  const prevIncarnation = typeof msg.prevIncarnation === 'string' ? msg.prevIncarnation : null
+  // No lock: beginPut's prev check is advisory (a fast-fail so the
+  // client rebases before uploading). The authoritative precondition is
+  // commitPut's version+incarnation-CAS, which stays correct no matter
+  // what races between this begin and that commit.
+  const result = await beginPut(deps.handle, {
+    workspaceTag: tag, resourceTag, prevVersion, prevIncarnation,
+    expectedLength: msg.expectedLength as number,
+    contentHash: msg.contentHash as string,
+    signature: msg.signature as string,
+  })
+  if (!result.ok) {
+    // `workspace-full` is the per-workspace 100-resource cap; goes
+    // out as a typed error so the client can distinguish a quota
+    // refusal from a `conflict` (which is a version-precondition
+    // mismatch that the client can fix by re-reading + rebasing).
+    if (result.reason === 'workspace-full') {
+      deps.send(socket, { type: 'objstore-put-error', workspaceTag: tag, resourceTag, reason: 'workspace-full' })
+      return
+    }
+    deps.send(socket, conflictReply('put', tag, resourceTag, result.conflict))
+    return
+  }
+  const { token, exp } = mintPutToken(deps.secret, tag, resourceTag, result.stagingId, msg.expectedLength as number)
+  deps.send(socket, {
+    type: 'objstore-put-token',
+    workspaceTag: tag, resourceTag,
+    stagingId: result.stagingId,
+    urlPath: urlPathFor(tag, resourceTag),
+    token, expiresAt: exp,
+  })
+}
+
+// `current` is the live `ObjectRow`, which carries the server-only
+// `putAt` debug column. Project it through `objectMetaWire` before it
+// reaches the wire so the conflict frame matches the fetch/list/PUT
+// frames and never leaks `putAt`. Typed `ObjectRow | null` so the
+// projection contract is checked rather than relying on `object`.
+function conflictReply(action: 'put' | 'delete', tag: string, resourceTag: string, current: ObjectRow | null): object {
+  return current
+    ? { type: 'objstore-conflict', action, workspaceTag: tag, resourceTag, current: objectMetaWire(current) }
+    : { type: 'objstore-conflict', action, workspaceTag: tag, resourceTag }
+}
+
+async function handleDelete(deps: ObjstoreDeps, socket: WebSocket, msg: ObjstoreDeleteMsg): Promise<void> {
+  if (!isValidTag(msg.workspaceTag) || !isValidTag(msg.resourceTag) || !isValidSignature(msg.signature)) return
+  if (msg.prevVersion != null && (typeof msg.prevVersion !== 'number' || !Number.isSafeInteger(msg.prevVersion))) return
+  if (!await verified(deps, socket, msg, 'delete', verifyObjstoreDeleteSig)) return
+  const tag = msg.workspaceTag
+  const resourceTag = msg.resourceTag
+  const prev = typeof msg.prevVersion === 'number' ? msg.prevVersion : null
+  const prevIncarnation = typeof msg.prevIncarnation === 'string' ? msg.prevIncarnation : null
+  // No lock: deleteObject is a precondition-checked version-CAS drop.
+  // A concurrent commit OR delete races that CAS (not a shared blob —
+  // the live blob is content-addressed + GC'd by the reaper, never
+  // unlinked here): exactly one op wins, the loser gets conflict /
+  // not-found (and never broadcasts). See the deleteObject doc in
+  // store.ts.
+  const result = await deleteObject(deps.handle, tag, resourceTag, prev, prevIncarnation)
+  if (!result.ok) {
+    if (result.reason === 'conflict') deps.send(socket, conflictReply('delete', tag, resourceTag, result.conflict ?? null))
+    else deps.send(socket, { type: 'objstore-delete-error', workspaceTag: tag, resourceTag, reason: result.reason })
+    return
+  }
+  deps.send(socket, { type: 'objstore-deleted-ack', workspaceTag: tag, resourceTag, deletedVersion: result.deletedVersion })
+  if (result.deletedVersion === 0) return // sentinel: nothing to broadcast
+  // Broadcast to ALL subscribers (including the originator). The
+  // REST PUT path's `objstore-put` broadcast at rest.ts:308 already
+  // uses `except: null`, so a session that listens via `onPut`
+  // observes its own PUTs as echo events. The same symmetry on
+  // `onDeleted` lets `session.onDeleted` fire for the session's
+  // own deletes — pinned by `tests/objstore-client-races.test.js`.
+  deps.broadcast(tag, { type: 'objstore-deleted', workspaceTag: tag, resourceTag, version: result.deletedVersion }, null)
+  if (deps.debug) console.log(`objstore delete → ${debugTag(tag)}/${resourceTag.slice(0, 8)}…`)
+}
+
+async function handleFetch(deps: ObjstoreDeps, socket: WebSocket, msg: ObjstoreFetchMsg): Promise<void> {
+  if (!isValidTag(msg.workspaceTag) || !isValidTag(msg.resourceTag) || !isValidSignature(msg.signature)) return
+  if (!await verified(deps, socket, msg, 'fetch', verifyObjstoreFetchSig)) return
+  const tag = msg.workspaceTag
+  const resourceTag = msg.resourceTag
+  // Direct (workspace_tag, resource_tag) lookup — `listLive(...).find()`
+  // is O(n) per fetch and gets expensive for workspaces with many
+  // resources. PR #4 review.
+  const row = await getLive(deps.handle, tag, resourceTag)
+  if (!row) {
+    deps.send(socket, { type: 'objstore-fetch-not-found', workspaceTag: tag, resourceTag })
+    return
+  }
+  const { token, exp } = mintGetToken(deps.secret, tag, resourceTag, row.version, row.incarnation)
+  deps.send(socket, {
+    type: 'objstore-fetch-token',
+    workspaceTag: tag,
+    ...objectMetaWire(row),
+    urlPath: urlPathFor(tag, resourceTag),
+    token, expiresAt: exp,
+  })
+}
+
+// Staging rows abandoned by a disconnected socket are picked up by
+// the reaper's TTL pass within `STAGING_TTL_MS_DEFAULT` — no per-
+// socket bookkeeping is needed on disconnect today. If that ever
+// changes, wire a `cleanupSocket(socket)` into both this bundle and
+// server/index.ts's close handler.
+
+export type ObjstoreHandlers = {
+  handlePutBegin: (s: WebSocket, m: ObjstorePutBeginMsg) => Promise<void>
+  handleDelete: (s: WebSocket, m: ObjstoreDeleteMsg) => Promise<void>
+  handleFetch: (s: WebSocket, m: ObjstoreFetchMsg) => Promise<void>
+}
+
+export function createObjstoreHandlers(deps: ObjstoreDeps): ObjstoreHandlers {
+  return {
+    handlePutBegin: (s, m) => handlePutBegin(deps, s, m),
+    handleDelete: (s, m) => handleDelete(deps, s, m),
+    handleFetch: (s, m) => handleFetch(deps, s, m),
+  }
+}

package/server/objstore/init.ts

@@ -0,0 +1,118 @@
+// Wire-time wrapper around the v1.objstore module — takes a pre-
+// opened storage handle (SQLite or Neon, opened one level up
+// alongside the workspace_revision handle), mints a per-process
+// bearer-token secret, kicks off the orphan reaper, and returns
+// the WS handlers + REST deps + a teardown callback the index.ts
+// shutdown path calls before closing the shared DB handle.
+
+import type { WebSocket } from 'ws'
+import type { Handle } from './store.ts'
+import { reapOrphans } from './reaper.ts'
+import { type ObjstoreHandlers, createObjstoreHandlers } from './handlers.ts'
+import { type ObjstoreRestDeps } from './rest.ts'
+import { type TokenSecret, newTokenSecret } from './tokens.ts'
+import { errStack } from '../util.ts'
+
+export type ObjstoreInitDeps = {
+  // Pre-opened storage handle, sharing the SQLite connection with
+  // the workspace_revision handle in server/db.ts.
+  handle: Handle
+  reapIntervalMs: number
+  send: (socket: WebSocket, msg: object) => void
+  broadcast: (tag: string, msg: object, except: WebSocket | null) => void
+  getNonce: (socket: WebSocket) => string | undefined
+  debug: boolean
+  // Auth gate for the FIRST objstore-put-begin against a workspace
+  // tag that doesn't yet exist on the server. Returns `true` to
+  // DENY (unauthorized), `false` to allow. Called AFTER sig verify
+  // so the resulting `unauthorized` frame only reaches a legitimate
+  // signer. Falsy/missing → no gating (the no-config default).
+  authGate?: (socket: WebSocket, workspaceTag: string) => Promise<boolean>
+  sendUnauthorized?: (socket: WebSocket, ctx: { kind: 'gated'; workspaceTag: string; resourceTag: string }) => void
+  // HMAC secret for REST bearer tokens. Optional — falls back to a
+  // fresh process-local secret if omitted (the historical single-
+  // process behaviour). Multi-replica deployments MUST supply a
+  // shared secret here so a token minted on one replica's WS plane
+  // validates on another replica's REST plane (the WS-to-REST hop
+  // is not load-balancer-pinned). See server/index.ts boot logic
+  // for the env var (`OBJSTORE_TOKEN_SECRET`).
+  tokenSecret?: TokenSecret
+}
+
+export type ObjstoreInit = {
+  handlers: ObjstoreHandlers
+  restDeps: ObjstoreRestDeps
+  startupReap: Promise<void>
+  // Cancels the periodic timer AND resolves only after any
+  // currently-in-flight sweep has finished, so shutdown can safely
+  // close the DB without an outstanding readdir / unlink touching
+  // a closed handle. PR #4 review.
+  stopReaper: () => Promise<void>
+}
+
+export function initObjstore(deps: ObjstoreInitDeps): ObjstoreInit {
+  const handle = deps.handle
+  const secret = deps.tokenSecret ?? newTokenSecret()
+  const handlers = createObjstoreHandlers({
+    handle, secret,
+    send: deps.send, broadcast: deps.broadcast,
+    getNonce: deps.getNonce, debug: deps.debug,
+    ...(deps.authGate ? { authGate: deps.authGate } : {}),
+    ...(deps.sendUnauthorized ? { sendUnauthorized: deps.sendUnauthorized } : {}),
+  })
+  const restDeps: ObjstoreRestDeps = {
+    handle, secret, broadcast: deps.broadcast, debug: deps.debug,
+  }
+  // Re-entrancy guard for periodic + startup sweeps. Kicking the
+  // startup sweep through the same `enqueueSweep` path means the
+  // interval ticking before the startup pass finishes naturally
+  // short-circuits — no risk of two `reapOrphans()` racing
+  // readdir / unlink against the same dirs. PR #4 review.
+  let inFlight: Promise<void> | null = null
+  function enqueueSweep(): Promise<void> {
+    if (inFlight) return inFlight
+    // Log reaper failures unconditionally (not gated on `debug`) — a
+    // failed sweep means stranded files / staging rows that never get
+    // cleaned, and operators need to see it. Inner catch makes the
+    // promise resolve so callers (startupReap awaiter + setInterval)
+    // don't have to handle rejection.
+    const p = reapOrphans(handle).catch((err) => {
+      console.warn('objstore reaper error:', errStack(err))
+    }).finally(() => { if (inFlight === p) inFlight = null })
+    inFlight = p
+    return p
+  }
+  // Caller awaits this before accepting traffic so a fresh boot
+  // can't hand out list / fetch / put-begin against a tag whose
+  // 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.
+  let reapTimer: ReturnType<typeof setInterval> | null = null
+  const jitterMs = Math.floor(Math.random() * deps.reapIntervalMs)
+  const firstTimer = setTimeout(() => {
+    enqueueSweep()
+    reapTimer = setInterval(enqueueSweep, deps.reapIntervalMs)
+    reapTimer.unref?.()
+  }, deps.reapIntervalMs + jitterMs)
+  firstTimer.unref?.()
+  return {
+    handlers, restDeps, startupReap,
+    stopReaper: async () => {
+      clearTimeout(firstTimer)
+      if (reapTimer) clearInterval(reapTimer)
+      // Drain whichever sweep is currently running (startup or
+      // periodic) — either could be mid-readdir/unlink at SIGTERM
+      // time and would otherwise outlive `handle.close()`.
+      if (inFlight) await inFlight.catch(() => {})
+    },
+  }
+}

package/server/objstore/reaper.ts

@@ -0,0 +1,199 @@
+// Orphan reaper / GC for the v1.objstore byte plane. Two passes:
+//   1. Unreferenced live blobs. Live blobs are content-addressed
+//      (`${tag}/${contentHash}.bin`). For each workspace, build the
+//      set of content hashes the live table references, list the live
+//      blobs, and GC any blob whose hash is in NO live row AND whose
+//      age (now − last-modified) is past the grace window. The grace
+//      window (one `STAGING_TTL_MS_DEFAULT`) is what makes the
+//      reaper-vs-commit race safe without a lock: a just-promoted but
+//      not-yet-referenced blob (commit between promote and CAS) is
+//      younger than the grace, so it's never reaped out from under an
+//      in-flight commit. Covers the "DELETE dropped the row" case
+//      (the blob is now unreferenced) and the "commit crashed
+//      mid-promotion" case (a stranded, unreferenced blob).
+//   2. Stale staging. Rows in workspace_object_staging older than
+//      `stagingTtlMs` → drop row + unlink blob. Staging blobs with no
+//      row → unlink (catches a row drop that crashed before the
+//      blob delete).
+//
+// Backend-agnostic: every storage operation goes through
+// `handle.blob.*`. The FS backend (blob-fs.ts) implements list/
+// unlink against the local filesystem; the Vercel backend (blob-
+// vercel.ts) against the SDK's list / del. The reaper takes NO lock.
+// Pass 1's blob GC is made race-safe by content-addressing + the age
+// grace window + a live-reference re-read just before each unlink.
+// Pass 2's stale-staging sweep is made race-safe by an atomic
+// conditional delete (`deleteStagingIfStale`) whose `begun_at`
+// predicate can't match a row a concurrent upload just refreshed.
+
+import { type Handle, STAGING_TTL_MS_DEFAULT, isValidContentHash, isValidStagingId, isValidTag } from './store.ts'
+
+type StagingRow = {
+  workspace_tag: string
+  resource_tag: string
+  staging_id: string
+  begun_at: number
+}
+
+// GC one workspace's live blobs against the set of hashes the live
+// table references. A blob is unlinked IFF: its hash parses as a valid
+// content hash (defense against operator-seeded / foreign files), it's
+// older than the grace window (measured from the listing's
+// last-modified time), AND — re-read immediately before the unlink —
+// no live row references it. Shared by both GC passes
+// (reapUnreferencedForTag's per-tag sweep and reapOrphans'
+// whole-workspace straggler sweep).
+//
+// Two layers of race protection, neither of which is a lock:
+//   - Age grace window. A blob a freshly-promoted-but-not-yet-CAS'd
+//     commit just wrote is younger than the grace, so it survives this
+//     sweep entirely (its listing mtime is recent). This is the
+//     primary guard for the commit's promote→CAS window.
+//   - Live-set re-read just before unlink. A commit whose CAS landed
+//     after our initial per-tag snapshot but before this unlink is
+//     caught here — its row now references the hash, so we skip. The
+//     test is "no live row references this hash" (not "this resource")
+//     because the blob path carries only the hash — the reaper lists
+//     blobs by hash and can't know which resource wrote one. (Hashes
+//     are effectively unique per PUT — a random nonce per encrypt makes
+//     each ciphertext unique — so this is really "is this hash still
+//     some current version's", not a dedup/sharing check.)
+// A lock would not help here even if one existed: the commit path is
+// keyed on the resourceTag while a blob is named by its content hash,
+// so the two can't share a key. The grace window + re-read are the
+// actual safety net. init.ts runs one sweep at a time per process,
+// but a multi-replica deploy genuinely runs reapers concurrently;
+// they stay safe via idempotent unlink + the per-blob grace window +
+// live-set re-read, not via mutual exclusion.
+async function gcBlobIfUnreferenced(
+  handle: Handle, tag: string, hash: string, modifiedMs: number, now: number, grace: number,
+): Promise<void> {
+  if (!isValidContentHash(hash)) return
+  if (now - modifiedMs < grace) return
+  const refs = await liveHashSet(handle, tag)
+  if (refs.has(hash)) return
+  await handle.blob.unlinkLive(tag, hash)
+}
+
+// The set of content hashes referenced by the workspace's live rows.
+async function liveHashSet(handle: Handle, tag: string): Promise<Set<string>> {
+  const rows = await handle.selectLive.all(tag)
+  return new Set(rows.map((r) => r.content_hash))
+}
+
+// Sweep one workspace's live-blob listing against the referenced-hash
+// set. Anything unreferenced AND past the grace window → GC. The
+// snapshot we read up front can race a concurrent commit; the
+// reference re-read inside `gcBlobIfUnreferenced` (plus the grace
+// window) ensures we never unlink a blob a live row names.
+async function reapUnreferencedForTag(handle: Handle, tag: string, now: number, grace: number): Promise<void> {
+  if (!isValidTag(tag)) return
+  const blobs = await handle.blob.listLiveBlobs(tag)
+  if (blobs.length === 0) return
+  const referenced = await liveHashSet(handle, tag)
+  for (const { hash, modifiedMs } of blobs) {
+    if (!isValidContentHash(hash)) continue
+    // Referenced in our snapshot → skip the grace + re-read path
+    // entirely; only unreferenced blobs need it.
+    if (referenced.has(hash)) continue
+    await gcBlobIfUnreferenced(handle, tag, hash, modifiedMs, now, grace)
+  }
+}
+
+// Drop staging rows older than the TTL and unlink their on-storage
+// blobs. Every row field that flows into a backend call is re-
+// validated — DB tampering / a future migration that introduces an
+// unsanitised column shouldn't be able to trick the reaper into
+// touching unintended keys. PR #4 review.
+async function reapStaleStagingRows(handle: Handle, now: number, stagingTtlMs: number): Promise<void> {
+  // Push the staleness filter into SQL so the
+  // `workspace_object_staging_begun_at_idx` index handles the scan.
+  // The snapshot is O(stale-rows) cluster-wide. DB-layout audit
+  // `server/objstore/store.ts`.
+  const staleBefore = now - stagingTtlMs
+  const staging = await handle.listAllStaging.all(staleBefore) as StagingRow[]
+  for (const s of staging) {
+    if (!isValidTag(s.workspace_tag) || !isValidTag(s.resource_tag) || !isValidStagingId(s.staging_id)) {
+      // Truncate fields — the full workspace_tag is an Ed25519 public
+      // key and shouldn't land in operator logs verbatim. PR #4
+      // review H3.
+      console.warn(`reaper: skipping malformed staging row tag=${String(s.workspace_tag).slice(0, 12)}… res=${String(s.resource_tag).slice(0, 8)}… sid=${String(s.staging_id).slice(0, 8)}…`)
+      continue
+    }
+    // ATOMIC conditional delete (replaces the old in-lock begun_at
+    // re-read, PR #4 "F1"). The delete fires only if `begun_at` is
+    // STILL older than the SAME `staleBefore` we snapshotted with — so
+    // a concurrent REST PUT that finished its body and called
+    // `refreshStagingBegunAt` (bumping begun_at to ~now, well after
+    // `staleBefore`) makes the predicate fail: the row isn't deleted,
+    // `deleteStagingIfStale` returns undefined, and we skip the unlink,
+    // leaving the row for that PUT's commit. No lock, no TOCTOU window
+    // between a read and a delete — the CAS is the whole check.
+    const deleted = await handle.deleteStagingIfStale.get(s.workspace_tag, s.resource_tag, s.staging_id, staleBefore)
+    if (!deleted) continue
+    // The row was genuinely stale and we removed it; now drop its
+    // bytes. Row-first, then unlink — symmetric with deleteObject in
+    // store.ts. If a crash lands between them the bytes outlive the
+    // row, and a later sweep's orphan-staging-file pass (or this
+    // pass's idempotent unlink of an absent blob) self-heals.
+    await handle.blob.unlinkStaging(s.workspace_tag, s.staging_id)
+  }
+}
+
+// Sweep staging blobs whose row is missing — happens when a commit
+// dropped the row but crashed before the unlink (Vercel: between
+// the post-copy `del(staging)` and the DB delete; FS: not possible
+// since rename removes the staging file), or after
+// reapStaleStagingRows already nuked the row but the unlink failed.
+// Per-blob row lookup (vs a snapshot at the caller) closes the race
+// where a concurrent beginPut between snapshot-time and unlink-time
+// would have its blob unlinked while the row was already in DB. The
+// per-blob SELECT is sub-ms and sids are 16-byte random — a
+// same-sid beginPut in the microsecond between our SELECT and
+// unlink is 1/2^128. Also handles the malformed-row case: a row
+// with valid (workspace_tag, staging_id) but malformed resource_tag
+// still pins its blob. PR #4 review H1.
+async function reapOrphanedStagingFiles(handle: Handle, tag: string): Promise<void> {
+  if (!isValidTag(tag)) return
+  const entries = await handle.blob.listStagingIds(tag)
+  if (entries.length === 0) return
+  for (const stagingId of entries) {
+    // Same on-disk-foreign-file guard as reapUnreferencedForTag.
+    if (!isValidStagingId(stagingId)) continue
+    if (await handle.selectStagingByWsSid.get(tag, stagingId)) continue
+    await handle.blob.unlinkStaging(tag, stagingId)
+  }
+}
+
+export async function reapOrphans(handle: Handle, stagingTtlMs: number = STAGING_TTL_MS_DEFAULT): Promise<void> {
+  const now = Date.now()
+  // The GC grace window reuses the staging TTL: a live blob is only
+  // eligible for unlink once it's unreferenced AND older than this.
+  const grace = stagingTtlMs
+  // Pass 1: tags the live table knows about — GC unreferenced live
+  // blobs (past the grace window) against the referenced-hash set.
+  const liveTagsRows = await handle.listLiveTags.all()
+  const liveTags = liveTagsRows.map((r) => r.workspace_tag)
+  for (const tag of liveTags) await reapUnreferencedForTag(handle, tag, now, grace)
+  // Whole-workspace deletes leave residue (dirs / blob-prefixes) the
+  // live table no longer lists. Walk the backend's top-level workspace
+  // listing to find them; for each straggler tag, GC its unreferenced
+  // blobs the same way (the referenced-hash set for a fully-deleted
+  // workspace is empty, so every past-grace blob is collected, while
+  // the grace window + live-set re-read still protect a racing
+  // put-begin → commit on a tag not in our `liveTags` snapshot).
+  const topLevel = await handle.blob.listWorkspaceTags()
+  const liveSet = new Set(liveTags)
+  for (const tag of topLevel) {
+    if (liveSet.has(tag) || !isValidTag(tag)) continue
+    await reapUnreferencedForTag(handle, tag, now, grace)
+  }
+  // Pass 2: stale staging rows + orphan staging blobs. The orphan
+  // sweep does per-blob row lookups (no caller-side snapshot), so a
+  // beginPut that lands between our list and our unlink has its
+  // row found by the fresh SELECT. PR #4 review H1.
+  await reapStaleStagingRows(handle, now, stagingTtlMs)
+  for (const tag of topLevel) {
+    await reapOrphanedStagingFiles(handle, tag)
+  }
+}