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

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

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

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

@@ -1,5 +1,5 @@
 // Vercel Blob Private Storage BlobBackend. Paired with the Neon DB
-// plane in `server/index.ts` when `BLOB_READ_WRITE_TOKEN` is set;
+// plane in `server-e2e/index.ts` when `BLOB_READ_WRITE_TOKEN` is set;
 // the combination is the supported multi-replica deployment shape
 // (Neon for metadata, Vercel Blob for bytes — both serverless, both
 // HTTP-backed, no shared filesystem required).
@@ -35,110 +35,10 @@
 // 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 { PassThrough } from 'node:stream'
 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'
-}
+import { type VercelBlobSdk, isNotFound, loadVercelBlobSdk } from '../../server-common/vercel-blob.ts'
 
 function liveBlobPath(tag: string, contentHash: string): string {
   return `${tag}/${contentHash}.bin`
@@ -242,20 +142,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 +212,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,38 +253,55 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
     // origin truth. Origin fetch is the right default for a store
     // where freshness > latency.
     try { res = await sdk.get(path, { access: 'private', useCache: false, token }) } catch (err) {
-      if (isNotFound(err)) return { ok: false, reason: 'not-found' }
+      // A missing blob HERE is never "the resource doesn't exist" — the
+      // REST layer (rest.ts openLiveSnapshot) already confirmed a live row
+      // whose (version, incarnation) matches the GET token before calling
+      // us. So BlobNotFoundError means the bytes for a still-live row are
+      // momentarily gone: the reaper GC'd a hash a racing version-bump just
+      // unreferenced, or Vercel's read-after-write / edge propagation hasn't
+      // caught up to a freshly-promoted private blob. That is the documented
+      // `unavailable` (HTTP 503) transient — reconciled by reaper /
+      // propagation, retried by the client — NOT a 404. Returning
+      // `not-found` would emit a 404 the FS backend never emits for the
+      // same condition (blob-fs.ts maps ENOENT → `unavailable`), telling
+      // the client the resource is gone for good when it should refetch.
+      // See server-e2e/README.md's GET status table.
+      if (isNotFound(err)) return { ok: false, reason: 'unavailable', detail: 'vercel-get-not-found' }
       throw err
     }
-    if (res == null) return { ok: false, reason: 'not-found' }
+    // SDK returned null (no blob) — same "bytes missing for a live row"
+    // transient as the BlobNotFoundError branch above → `unavailable`, not
+    // `not-found`.
+    if (res == null) return { ok: false, reason: 'unavailable', detail: 'vercel-get-null' }
     // statusCode 304 doesn't reach here in practice — the REST
     // GET layer doesn't pass If-None-Match — but a future call
     // site could. Treat as unavailable rather than streaming a
     // null body.
     if (res.statusCode !== 200 || res.stream == null) {
-      return { ok: false, reason: 'unavailable' }
+      return { ok: false, reason: 'unavailable', detail: `vercel-get-status-${res.statusCode}` }
     }
-    // `@vercel/blob@2.x`'s streaming `get()` for private blobs
-    // returns the body but does NOT populate `blob.size` 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', detail: 'vercel-head-not-found' }
         throw headErr
       }
     }
-    if (size == null) return { ok: false, reason: 'unavailable' }
+    if (size == null) return { ok: false, reason: 'unavailable', detail: 'vercel-no-size' }
     // SDK returns a web ReadableStream<Uint8Array>; the REST layer
     // expects a Node Readable for pipeline(). Convert via
     // Readable.fromWeb — built-in and zero-copy where possible.
@@ -481,7 +395,7 @@ export type VercelBlobBackendOptions = {
   // Vercel Blob R/W token, typically from BLOB_READ_WRITE_TOKEN.
   // The SDK also reads it from process.env, but passing it
   // explicitly here keeps the env-var → boot config path single-
-  // sourced through server/index.ts (matches the Neon DATABASE_URL
+  // sourced through server-e2e/index.ts (matches the Neon database URL
   // handling — env-read at boot, threaded as a parameter).
   token: string
   // Test seam: inject a stub of the @vercel/blob module to avoid
@@ -495,7 +409,7 @@ export async function openVercelBlobBackend(opts: VercelBlobBackendOptions): Pro
   // 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 sdk: VercelBlobSdk = opts.sdk ?? (await loadVercelBlobSdk())
   const token = opts.token
   return {
     // No-op: Vercel Blob has no folder concept. The pathname's
@@ -521,9 +435,3 @@ export async function openVercelBlobBackend(opts: VercelBlobBackendOptions): Pro
     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 → server-e2e}/objstore/blob.ts

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

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

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

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

@@ -48,9 +48,9 @@ export type ObjstoreDeps = {
   // Cross-instance pub/sub for objstore-deleted. Fired alongside the
   // local `broadcast` after a successful delete so peers on OTHER
   // server instances see the version drop in real time. Carries the
-  // full (tag, resourceTag, version) tuple inline — the workspace_object
+  // full (tag, resourceTag, version, incarnation) tuple inline — the workspace_object
   // row is gone post-delete, so the bus payload IS the wire data.
-  publishObjDeleted: (tag: string, resourceTag: string, version: number) => void
+  publishObjDeleted: (tag: string, resourceTag: string, version: number, incarnation: string) => void
   getNonce: (socket: WebSocket) => string | undefined
   debug: boolean
   // Auth gate for the FIRST put-begin against a never-before-seen
@@ -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,22 +96,20 @@ 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
   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
+  // workspace_object). Mirrors handleSave in server-e2e/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-e2e/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)})`)
@@ -193,13 +191,14 @@ async function handleDelete(deps: ObjstoreDeps, socket: WebSocket, msg: Objstore
   // 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)
+  // A successful nonempty delete matched this authenticated incarnation.
+  deps.broadcast(tag, { type: 'objstore-deleted', workspaceTag: tag, resourceTag, version: result.deletedVersion, incarnation: prevIncarnation! }, null)
   // Cross-instance fan-out (Neon mode). The workspace_object row is
   // gone post-delete so the bus payload carries (tag, resourceTag,
-  // version) inline; the receiver builds its `objstore-deleted`
+  // version, incarnation) inline; the receiver builds its `objstore-deleted`
   // broadcast directly from the bus envelope. SQLite mode publishes
   // to a no-op.
-  deps.publishObjDeleted(tag, resourceTag, result.deletedVersion)
+  deps.publishObjDeleted(tag, resourceTag, result.deletedVersion, prevIncarnation!)
   if (deps.debug) console.log(`objstore delete → ${debugTag(tag)}/${resourceTag.slice(0, 8)}…`)
 }
 
@@ -230,7 +229,7 @@ async function handleFetch(deps: ObjstoreDeps, socket: WebSocket, msg: ObjstoreF
 // 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.
+// server-e2e/index.ts's close handler.
 
 export type ObjstoreHandlers = {
   handlePutBegin: (s: WebSocket, m: ObjstorePutBeginMsg) => Promise<void>