@preventive/triage 1.0.0-alpha.0

package/server/objstore/blob-vercel.ts

@@ -0,0 +1,508 @@
+// Vercel Blob Private Storage BlobBackend. Paired with the Neon DB
+// plane in `server/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).
+//
+// `@vercel/blob` is an OPTIONAL peer dep — loaded lazily inside
+// `openVercelBlobBackend` below so a SQLite/FS deployment never
+// reaches the import. Same dynamic-import pattern as db-neon.ts.
+//
+// Pathname layout (mirrors the FS backend's directory layout so the
+// reaper logic stays identical). Live blobs are content-addressed —
+// the pathname's filename is the content hash, not the resourceTag:
+//   ${tag}/${contentHash}.bin               — live
+//   ${tag}/.staging/${stagingId}.bin        — staging
+//
+// All blobs are created with `access: 'private'` so the URL alone
+// is not sufficient to fetch them; every read/write goes through the
+// token. The downstream REST GET layer pipes the SDK's `get()`
+// stream straight to the response without ever materialising the
+// public URL.
+//
+// Crash-safety contract (mirrors blob-fs.ts but via copy+del instead
+// of fsync+rename):
+//   PUT commit:  put(staging) → copy(staging → live) → DB version-CAS
+//                → del(staging)
+//   DELETE:      DB row drop (the reaper GCs the now-unreferenced blob)
+// A crash mid-`copy` leaves NO live blob (Vercel's copy is atomic
+// per-blob). A crash between `copy` and the CAS leaves a stranded,
+// unreferenced live blob; a crash after the CAS but before
+// `del(staging)` leaves a stranded staging blob. The reaper reconciles
+// both: `reapUnreferencedForTag` GCs a live blob that no live row
+// references (once past the grace window — content blobs are immutable
+// and may be shared, so GC is keyed on the referenced-hash set, not on
+// any single resource), and the stale-staging TTL sweep drops orphan
+// staging blobs.
+
+import { PassThrough, type Readable } from 'node:stream'
+import { Buffer } from 'node:buffer'
+import type { BlobBackend, OpenLiveResult, StagingWriter } from './blob.ts'
+import { errMsg } from '../util.ts'
+
+// Minimal structural shape of the bits of `@vercel/blob` we use.
+// Kept local so the optional peer dep doesn't have to type-resolve
+// for SQLite-only deployments. Real type details live in the
+// installed package; the fields/parameters we touch here are stable
+// per the SDK v2 public surface.
+//
+// `put` accepts the SDK's full `PutBody` union (string | Readable |
+// Buffer | Blob | ArrayBuffer | ReadableStream | File). We only ever
+// pass a Node `PassThrough` (a Readable), but the wider type lets
+// callers reuse this signature for future buffer/blob bodies without
+// type gymnastics. `copy` accepts `allowOverwrite` — REQUIRED for
+// version bumps since the live pathname is reused on re-upload.
+type VercelBlobBody = Readable | Buffer | string | Blob | ArrayBuffer | ReadableStream<Uint8Array>
+type VercelBlobSdk = {
+  put: (
+    pathname: string,
+    body: VercelBlobBody,
+    options: {
+      access: 'private' | 'public'
+      allowOverwrite?: boolean
+      contentType?: string
+      token?: string
+      multipart?: boolean
+      abortSignal?: AbortSignal
+      cacheControlMaxAge?: number
+    },
+  ) => Promise<{ url: string; pathname: string }>
+  head: (
+    pathname: string,
+    options?: { token?: string; abortSignal?: AbortSignal },
+  ) => Promise<{ size: number; pathname: string; url: string }>
+  get: (
+    pathname: string,
+    options: {
+      access: 'private' | 'public'
+      token?: string
+      useCache?: boolean
+      abortSignal?: AbortSignal
+    },
+  ) => Promise<{
+    statusCode: 200 | 304
+    stream: ReadableStream<Uint8Array> | null
+    blob: { size: number | null }
+  } | null>
+  copy: (
+    fromPathname: string,
+    toPathname: string,
+    options: {
+      access: 'private' | 'public'
+      allowOverwrite?: boolean
+      token?: string
+      contentType?: string
+      cacheControlMaxAge?: number
+    },
+  ) => Promise<{ url: string; pathname: string }>
+  del: (
+    urlOrPathname: string | string[],
+    options?: { token?: string; abortSignal?: AbortSignal },
+  ) => Promise<void>
+  list: (options: {
+    prefix?: string
+    cursor?: string
+    limit?: number
+    mode?: 'expanded' | 'folded'
+    token?: string
+  }) => Promise<{
+    // `uploadedAt` (a Date per the SDK v2 surface) is the blob's
+    // creation time — used by the reaper's GC grace window. Optional
+    // in the type because the `folded` listing path ignores it (only
+    // `listLiveBlobs` reads it, and it uses the default expanded mode).
+    blobs: Array<{ pathname: string; size: number; uploadedAt?: Date | string | number }>
+    folders?: string[]
+    cursor?: string
+    hasMore: boolean
+  }>
+}
+
+// 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).
+//
+// 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.
+function isNotFound(err: unknown): boolean {
+  if (err == null || typeof err !== 'object') return false
+  const name = (err as { name?: unknown }).name
+  return typeof name === 'string' && name === 'BlobNotFoundError'
+}
+
+function liveBlobPath(tag: string, contentHash: string): string {
+  return `${tag}/${contentHash}.bin`
+}
+function stagingBlobPath(tag: string, stagingId: string): string {
+  return `${tag}/.staging/${stagingId}.bin`
+}
+
+// Coerce the SDK's `uploadedAt` (Date | ISO string | epoch-ms number)
+// into epoch-ms for the reaper's grace-window comparison. The real SDK
+// always returns a valid `uploadedAt`; a missing / unparseable value
+// fails CLOSED to "just now" so the grace window still shields the
+// blob from GC. This matters because the grace window is the ONLY guard
+// during a commit's promote→CAS gap: no live row exists yet, so the
+// reaper's live-set re-read can't cover it. Reading an unknown
+// timestamp as "ancient" would let a sweep collect a just-promoted blob
+// out from under an in-flight commit (a metadata→bytes desync). We
+// prefer a (theoretical, real-SDK-unreachable) storage leak over that.
+function uploadedAtMs(uploadedAt: Date | string | number | undefined): number {
+  if (uploadedAt == null) return Date.now()
+  if (typeof uploadedAt === 'number') return Number.isFinite(uploadedAt) ? uploadedAt : Date.now()
+  const t = new Date(uploadedAt).getTime()
+  return Number.isFinite(t) ? t : Date.now()
+}
+
+// Strip a `.bin` suffix and reject anything else. Same defensive
+// shape the FS backend uses (the reaper refuses to touch foreign
+// files). The validator in store.ts rejects malformed tags at the
+// wire boundary; this is belt-and-braces for the listing path.
+function stripBinSuffix(pathname: string, prefix: string): string | null {
+  if (!pathname.startsWith(prefix) || !pathname.endsWith('.bin')) return null
+  return pathname.slice(prefix.length, -4)
+}
+
+// Exhaust a paginated list() call. Vercel returns a cursor when
+// hasMore is true; we walk it to completion so the reaper gets every
+// blob. The 1000-per-page default limit means a workspace with N
+// resources costs ceil(N/1000) round-trips — acceptable for the
+// periodic sweep cadence (10 minutes by default).
+async function listAll(
+  sdk: VercelBlobSdk,
+  opts: { prefix?: string; mode?: 'expanded' | 'folded'; token: string },
+): Promise<{ blobs: Array<{ pathname: string; uploadedAt?: Date | string | number | undefined }>; folders: string[] }> {
+  const blobs: Array<{ pathname: string; uploadedAt?: Date | string | number | undefined }> = []
+  const folders: string[] = []
+  let cursor: string | undefined
+  // Bounded loop to defend against a misbehaving driver that returns
+  // `hasMore: true` with no cursor (would infinite-loop otherwise).
+  // 10k pages × 1000 entries = 10M entries — far past the 100-
+  // resource per-workspace cap. Hitting this is a server-side bug;
+  // log and stop rather than spinning.
+  for (let i = 0; i < 10_000; i++) {
+    const callOpts: Parameters<VercelBlobSdk['list']>[0] = { token: opts.token }
+    if (opts.prefix !== undefined) callOpts.prefix = opts.prefix
+    if (opts.mode !== undefined) callOpts.mode = opts.mode
+    if (cursor !== undefined) callOpts.cursor = cursor
+    const page = await sdk.list(callOpts)
+    for (const b of page.blobs) blobs.push({ pathname: b.pathname, uploadedAt: b.uploadedAt })
+    if (page.folders) for (const f of page.folders) folders.push(f)
+    if (!page.hasMore) return { blobs, folders }
+    if (!page.cursor) {
+      console.warn('vercel-blob list: hasMore=true with no cursor; stopping')
+      return { blobs, folders }
+    }
+    cursor = page.cursor
+  }
+  console.warn('vercel-blob list: exceeded 10k pages; returning partial result')
+  return { blobs, folders }
+}
+
+// Per-method builders — extracted so `openVercelBlobBackend` stays
+// within the max-lines-per-function budget. Each closes over the
+// SDK instance + token. Same shape as the per-statement builders
+// in store-neon.ts.
+
+function buildOpenStagingWriter(sdk: VercelBlobSdk, token: string): BlobBackend['openStagingWriter'] {
+  // eslint-disable-next-line require-await
+  return async (tag, stagingId): Promise<StagingWriter> => {
+    // PassThrough is the bridge — the REST PUT pipeline writes
+    // into it (Node-stream side), and the SDK's `put` reads from
+    // it (web-stream-or-Node-stream, the SDK supports both). When
+    // the pipeline ends the PT, `put` sees EOF and finalises its
+    // upload.
+    const pt = new PassThrough()
+    const ac = new AbortController()
+    const putPromise = sdk.put(stagingBlobPath(tag, stagingId), pt, {
+      access: 'private',
+      // Staging keys are 16-byte random base64url; a collision is
+      // 1/2^128. `allowOverwrite: true` keeps a retry of the same
+      // stagingId from failing with the SDK's default "exists"
+      // error — the REST layer's `inFlightSids` set already
+      // prevents concurrent writes to the same sid.
+      allowOverwrite: true,
+      contentType: 'application/octet-stream',
+      token,
+      // Multipart for streaming uploads with unknown / large size.
+      // Required so the SDK doesn't try to buffer the whole body
+      // before initiating the upload — we cap at 100 MiB but the
+      // SDK shouldn't hold that in memory either.
+      multipart: true,
+      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).
+    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.
+      finalize: async () => { await putPromise },
+      // Await the SDK's put-promise settlement (rejected via the
+      // AbortController). Without this await, a slow upload that
+      // the REST layer thinks it canceled can KEEP UPLOADING in
+      // the background for several seconds, racing the post-abort
+      // staging-blob deletion and silently recreating it. The
+      // putPromise.catch() above swallows the abort rejection so
+      // awaiting the .catch chain here doesn't re-throw.
+      abort: async (err) => {
+        // Order: tear down the source FIRST so the SDK sees an
+        // immediate end of body, then signal AbortController so
+        // the SDK can cancel in-flight HTTP requests. Destroying
+        // the PassThrough alone isn't enough on every SDK version
+        // — the AbortSignal is the documented cancel surface.
+        pt.destroy(err as Error)
+        try { ac.abort(err) } catch {}
+        // Wait for the SDK to actually settle. Expected rejection
+        // is BlobRequestAbortedError from the SDK's internal abort
+        // wiring. Anything ELSE — e.g. BlobServiceNotAvailable or
+        // a multipart upload that hit a quota before abort fired —
+        // is operationally interesting and would otherwise be lost
+        // since the caller already routed to its catch block on
+        // the original pipeline error. Log it (truncated) instead
+        // of silently swallowing.
+        try { await putPromise }
+        catch (settle: unknown) {
+          const settleErr = settle as { name?: unknown; message?: unknown }
+          if (settleErr?.name !== 'BlobRequestAbortedError') {
+            console.warn(`vercel-blob put settled with non-abort error after cancel: ${String(settleErr?.name ?? '<unknown>')} ${String(settleErr?.message ?? '').slice(0, 200)}`)
+          }
+        }
+      },
+    }
+  }
+}
+
+function buildStatStaging(sdk: VercelBlobSdk, token: string): BlobBackend['statStaging'] {
+  return async (tag, stagingId): Promise<number | null> => {
+    try {
+      const h = await sdk.head(stagingBlobPath(tag, stagingId), { token })
+      return h.size
+    } catch (err) {
+      if (isNotFound(err)) return null
+      throw err
+    }
+  }
+}
+
+function buildPromoteStagingToLive(sdk: VercelBlobSdk, token: string): BlobBackend['promoteStagingToLive'] {
+  return async (tag, stagingId, contentHash): Promise<boolean> => {
+    const from = stagingBlobPath(tag, stagingId)
+    const to = liveBlobPath(tag, contentHash)
+    try {
+      // `copy` is atomic per the SDK contract — either the new
+      // pathname carries the full source bytes, or it fails. No
+      // partial state at the destination.
+      //
+      // `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.
+      await sdk.copy(from, to, {
+        access: 'private',
+        allowOverwrite: true,
+        token,
+        contentType: 'application/octet-stream',
+        // Short cache TTL so the CDN can't serve a stale version of
+        // a private blob after a re-upload. Private blobs use the
+        // CDN by default (see openLiveReader's useCache: false);
+        // belt-and-braces here for any path that pulls bypassing
+        // the get() helper.
+        cacheControlMaxAge: 60,
+      })
+    } catch (err) {
+      console.warn('vercel-blob promote: copy failed:', errMsg(err))
+      return false
+    }
+    // Staging-blob cleanup runs in the caller AFTER upsertLive so a
+    // crash between copy() and the DB write leaves the staging blob
+    // intact (commit can be retried). Same ordering principle the
+    // FS backend gets implicitly from rename's atomicity.
+    return true
+  }
+}
+
+function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['openLiveReader'] {
+  return async (tag, contentHash): Promise<OpenLiveResult> => {
+    const path = liveBlobPath(tag, contentHash)
+    let res
+    // `useCache: false` — the content-addressed pathname is immutable
+    // (the hash names exactly one byte-string), so cache staleness
+    // across versions is no longer a correctness concern; but a CDN
+    // edge could still cache a 404 from a brief window before the
+    // copy landed, so bypassing the cache keeps the read anchored to
+    // 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' }
+      throw err
+    }
+    if (res == null) return { ok: false, reason: 'not-found' }
+    // 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' }
+    }
+    // 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.
+    const { Readable: NodeReadable } = await import('node:stream')
+    const nodeStream = NodeReadable.fromWeb(res.stream as Parameters<typeof NodeReadable.fromWeb>[0])
+    return {
+      ok: true,
+      reader: {
+        stream: nodeStream,
+        size: res.blob.size,
+        // eslint-disable-next-line require-await
+        close: async () => {
+          // Destroying the Node wrapper also cancels the underlying
+          // web stream reader (Readable.fromWeb installs the
+          // cleanup). Tolerate errors — close() is idempotent and
+          // may be called after the stream already finished.
+          try { nodeStream.destroy() } catch {}
+        },
+      },
+    }
+  }
+}
+
+function buildUnlink(sdk: VercelBlobSdk, token: string, op: 'staging' | 'live', toPath: (tag: string, id: string) => string): (tag: string, id: string) => Promise<void> {
+  return async (tag, id) => {
+    try { await sdk.del(toPath(tag, id), { token }) } catch (err) {
+      if (isNotFound(err)) return
+      // Don't propagate — the DB-side row drop has already
+      // committed by the time the caller reaches here, and the
+      // reaper picks up the stranded blob on its next sweep. Same
+      // policy as FS unlinkIfExists (PR #4 review).
+      console.warn(`vercel-blob unlink ${op} failed:`, errMsg(err))
+    }
+  }
+}
+
+function buildListWorkspaceTags(sdk: VercelBlobSdk, token: string): BlobBackend['listWorkspaceTags'] {
+  return async (): Promise<string[]> => {
+    const { folders } = await listAll(sdk, { mode: 'folded', token })
+    const out: string[] = []
+    for (const f of folders) {
+      // Folder names come back with trailing slash, e.g. "ws-1/".
+      // Strip it to get the bare tag.
+      const tag = f.endsWith('/') ? f.slice(0, -1) : f
+      if (tag.length > 0) out.push(tag)
+    }
+    return out
+  }
+}
+
+// Builder for `listStagingIds`. Walks `list({ prefix })` and strips
+// the prefix + `.bin` suffix from each blob's pathname to recover the
+// bare staging id. Entries whose remainder contains a `/` are skipped
+// — they're inside a deeper sub-prefix.
+function buildListStagingIds(sdk: VercelBlobSdk, token: string, mkPrefix: (tag: string) => string): (tag: string) => Promise<string[]> {
+  return async (tag) => {
+    const prefix = mkPrefix(tag)
+    const { blobs } = await listAll(sdk, { prefix, token })
+    const out: string[] = []
+    for (const b of blobs) {
+      const id = stripBinSuffix(b.pathname, prefix)
+      if (id == null || id.includes('/')) continue
+      out.push(id)
+    }
+    return out
+  }
+}
+
+// Builder for `listLiveBlobs`. Lists the workspace prefix in `folded`
+// mode so the `.staging/` sub-prefix rolls up as a folder entry (not
+// expanded into the blobs[] array) — without it, listing `${tag}/`
+// would surface every staging blob as a live blob. Each surviving
+// entry is a top-level content-addressed live blob; we recover its
+// hash from the pathname and its `modifiedMs` from the SDK's
+// `uploadedAt` for the reaper's GC grace window.
+function buildListLiveBlobs(sdk: VercelBlobSdk, token: string): BlobBackend['listLiveBlobs'] {
+  return async (tag) => {
+    const prefix = `${tag}/`
+    const { blobs } = await listAll(sdk, { prefix, mode: 'folded', token })
+    const out: Array<{ hash: string; modifiedMs: number }> = []
+    for (const b of blobs) {
+      const hash = stripBinSuffix(b.pathname, prefix)
+      if (hash == null || hash.includes('/')) continue
+      out.push({ hash, modifiedMs: uploadedAtMs(b.uploadedAt) })
+    }
+    return out
+  }
+}
+
+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
+  // handling — env-read at boot, threaded as a parameter).
+  token: string
+  // Test seam: inject a stub of the @vercel/blob module to avoid
+  // pulling the real SDK / hitting the network in unit tests. When
+  // absent, the real package is dynamic-imported.
+  sdk?: VercelBlobSdk
+}
+
+export async function openVercelBlobBackend(opts: VercelBlobBackendOptions): Promise<BlobBackend> {
+  // Dynamic import so a SQLite/FS deployment never reaches the peer
+  // dep. `@ts-ignore` (not `@ts-expect-error`) so an operator who
+  // DOES install `@vercel/blob` doesn't trip TS2578 "unused
+  // directive" — same pattern as db-neon.ts.
+  const sdk: VercelBlobSdk = opts.sdk ?? (await loadSdk())
+  const token = opts.token
+  return {
+    // No-op: Vercel Blob has no folder concept. The pathname's
+    // slashes are presentational only — listing with mode: 'folded'
+    // synthesises the "directory" view client-side.
+    // eslint-disable-next-line require-await
+    ensureWorkspace: async () => {},
+    openStagingWriter: buildOpenStagingWriter(sdk, token),
+    statStaging: buildStatStaging(sdk, token),
+    promoteStagingToLive: buildPromoteStagingToLive(sdk, token),
+    openLiveReader: buildOpenLiveReader(sdk, token),
+    unlinkStaging: buildUnlink(sdk, token, 'staging', stagingBlobPath),
+    unlinkLive: buildUnlink(sdk, token, 'live', liveBlobPath),
+    // Workspace tags = top-level folders. `mode: 'folded'` with no
+    // prefix returns folder names at the store root; each folder is
+    // one workspace.
+    listWorkspaceTags: buildListWorkspaceTags(sdk, token),
+    // Content-addressed live blobs under `${tag}/`, with each blob's
+    // `uploadedAt` surfaced for the reaper's GC grace window. `folded`
+    // mode keeps `.staging/` rolled up as a folder entry rather than
+    // expanded into the live-blob list.
+    listLiveBlobs: buildListLiveBlobs(sdk, token),
+    listStagingIds: buildListStagingIds(sdk, token, (tag) => `${tag}/.staging/`),
+  }
+}
+
+async function loadSdk(): Promise<VercelBlobSdk> {
+  // @ts-ignore optional peer dep: '@vercel/blob'
+  const mod = (await import('@vercel/blob')) as VercelBlobSdk
+  return mod
+}

package/server/objstore/blob.ts

@@ -0,0 +1,169 @@
+// Byte-plane abstraction for the v1.objstore module. The DB plane
+// (Handle's statement set in ./store.ts) holds the metadata
+// (workspace_object + workspace_object_staging); this interface
+// holds the bytes those rows point at.
+//
+// Two implementations:
+//   - ./blob-fs.ts        local filesystem (default; the only option
+//                         for the single-process SQLite-backed DB
+//                         plane)
+//   - ./blob-vercel.ts    Vercel Blob Private Storage (paired with
+//                         the Neon DB plane for multi-replica
+//                         deployments)
+//
+// Selected at boot in `server/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.
+//
+// Live blobs are CONTENT-ADDRESSED: a live blob lives at
+// `${tag}/${contentHash}.bin`, where `contentHash` is the client-
+// supplied, signed, server-opaque hash on the staging row. Because a
+// hash names exactly one byte-string, the live blob is immutable —
+// two racing commits write to DIFFERENT addresses, neither overwrites
+// the other, and the DB row's `content_hash` literally NAMES its blob
+// file (so "row says hash B, blob holds bytes A" is impossible). The
+// hash is workspace-namespaced under `${tag}/`, so this is never a
+// global content-addressed store. `unlinkLive` is therefore only ever
+// called by the reaper's GC — commit + delete never unlink a live blob
+// inline. Reclamation is deferred (not because a blob is shared — a
+// random nonce per encrypt makes each PUT's hash unique) so it can't
+// race a concurrent commit's promote→CAS window or an in-flight GET;
+// see the grace-window rationale in reaper.ts.
+//
+// Crash-safety contract every backend MUST preserve, so the reaper's
+// "stranded file, never row-points-at-nothing" guarantee holds:
+//   PUT commit:  bytes durable in staging → promote → DB write
+//   DELETE:      DB write (the reaper GCs the now-unreferenced blob)
+// A crash at the worst moment leaves at most a stranded blob (the
+// reaper cleans these on its periodic sweep, once the blob is both
+// unreferenced and older than the GC grace window). The FS backend
+// uses fsync + rename; the Vercel backend uses copy + delete (Vercel's
+// copy is atomic per-blob, so the cross-blob staging→live transition
+// can produce a stranded staging blob if del fails, but never a
+// half-written live blob).
+
+import type { Readable, Writable } from 'node:stream'
+
+// Streaming writer for a staging slot. The REST PUT handler pipes
+// the request body through `writable`, then awaits `finalize()` to
+// confirm the upload landed. `abort(err)` is the cancel path the
+// REST layer invokes on body error / overrun / length mismatch;
+// implementations propagate the cancel to the underlying upload
+// (createWriteStream.destroy for FS, AbortController.abort for
+// fetch-based remote stores).
+//
+// `abort` returns a Promise that resolves once the underlying
+// upload has actually torn down — for the FS backend this is
+// immediate, but for fetch-based stores the SDK's in-flight HTTP
+// request may take several seconds to register the abort. The REST
+// layer MUST await `abort()` before running cleanup (e.g. blob
+// del) so a late-arriving upload chunk can't recreate the staging
+// blob after we've cleaned it up.
+//
+// The writable is NOT auto-flushed on return — the caller is
+// responsible for either ending it through pipeline() (which awaits
+// 'finish' on Writables / 'end' on Transforms) or calling
+// writable.end() manually before finalize().
+export type StagingWriter = {
+  writable: Writable
+  finalize(): Promise<void>
+  abort(err: unknown): Promise<void>
+}
+
+// Readable handle for a live blob. `size` is the byte length the
+// backend confirmed on open (used to set Content-Length on the GET
+// response and to validate against the live row's content_length
+// before piping). `close()` releases backend-side resources
+// (file descriptor for FS, fetch reader for remote stores) and is
+// called by the REST GET handler on error before pipelining.
+export type LiveReader = {
+  stream: Readable
+  size: number
+  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.
+export type OpenLiveResult =
+  | { ok: true; reader: LiveReader }
+  | { ok: false; reason: 'not-found' | 'unavailable' }
+
+export type BlobBackend = {
+  // Per-workspace setup. FS creates the on-disk staging directory;
+  // blob stores have no real folder concept (the pathname's slashes
+  // are presentational) so this is a no-op there.
+  ensureWorkspace(tag: string): Promise<void>
+
+  // Open a streaming writer to the staging slot identified by
+  // (tag, stagingId). The returned `writable` can absorb up to
+  // MAX_CONTENT_LENGTH bytes; the REST layer's counter enforces the
+  // declared length upstream.
+  openStagingWriter(tag: string, stagingId: string): Promise<StagingWriter>
+
+  // Return the storage-side byte count of the staging slot, or null
+  // if it's missing. The REST PUT layer uses this as the belt-and-
+  // braces size verification after the request body has been fully
+  // consumed; commitPut re-stats as a last line of defense against a
+  // short/truncated upload before promotion (the staging slot is
+  // single-writer — its stagingId is freshly random per begin).
+  statStaging(tag: string, stagingId: string): Promise<number | null>
+
+  // Promote staging → live at the CONTENT-ADDRESSED live path
+  // `${tag}/${contentHash}.bin`. Returns true on success, false on
+  // any I/O error. The caller (commitPut) has already validated size;
+  // this method just performs the bytes-side transition. Because the
+  // live address IS the content hash, any write to that path is
+  // byte-identical by construction, so a retried or racing promote to
+  // the same path is an idempotent rewrite, never a clobber. (Distinct
+  // PUTs get distinct hashes — a random nonce per encrypt makes each
+  // ciphertext unique — so they write distinct paths.)
+  //
+  // Crash safety: implementations MUST ensure that a crash mid-
+  // promotion leaves at most a stranded staging blob (reaper-
+  // cleanable), never a partial live blob. FS uses fsync+rename;
+  // Vercel uses atomic-copy followed by best-effort staging delete.
+  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).
+  openLiveReader(tag: string, contentHash: string): Promise<OpenLiveResult>
+
+  // Idempotent deletes. Backends MUST tolerate "already gone" as
+  // success (FS: ENOENT; Vercel: BlobNotFoundError) — abortPut relies
+  // on this for retry idempotence, and the reaper races against
+  // concurrent operations on the same key. `unlinkLive` is called
+  // ONLY by the reaper's GC (commit / delete never unlink a live blob
+  // inline — reclamation is deferred to the grace-window GC so it can't
+  // race a commit's promote→CAS window or an in-flight GET; not because
+  // the blob is shared — hashes are unique per PUT).
+  unlinkStaging(tag: string, stagingId: string): Promise<void>
+  unlinkLive(tag: string, contentHash: string): Promise<void>
+
+  // Reaper enumeration helpers. Implementations MAY paginate
+  // internally; the reaper consumes the returned full list per
+  // workspace.
+  //
+  // `listWorkspaceTags()` returns every tag with ANY trace of state
+  // (live or staging). The reaper uses it to find dirs/prefixes the
+  // live table no longer knows about (whole-workspace deletes leave
+  // residue the per-tag sweep would otherwise miss).
+  //
+  // `listLiveBlobs(tag)` returns every live blob under the tag with
+  // its `hash` (the `.bin`-stripped content hash) AND `modifiedMs`
+  // (last-modified epoch-ms: FS mtime / Vercel `uploadedAt`). The GC
+  // needs the timestamp for the age grace window — a blob is only
+  // eligible for unlink once it's BOTH unreferenced by any live row
+  // AND older than the grace, so a just-promoted but not-yet-
+  // referenced blob isn't reaped out from under an in-flight commit.
+  //
+  // `listStagingIds(tag)` returns staging ids stripped of the `.bin`
+  // suffix — the reaper compares them against the DB's `staging_id`.
+  listWorkspaceTags(): Promise<string[]>
+  listLiveBlobs(tag: string): Promise<Array<{ hash: string; modifiedMs: number }>>
+  listStagingIds(tag: string): Promise<string[]>
+}