trekoon 0.4.1 → 0.4.2

package/src/board/routes.ts

@@ -1,9 +1,10 @@
 import { type Database } from "bun:sqlite";
 
-import { safeErrorMessage } from "../commands/error-utils";
-import { MutationService } from "../domain/mutation-service";
+import { redactSensitive, safeErrorMessage } from "../commands/error-utils";
+import { MutationService, PreconditionFailedError } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
 import { DomainError } from "../domain/types";
+import { type BoardEventBus } from "./event-bus";
 import { buildBoardSnapshot, buildBoardSnapshotDelta } from "./snapshot";
 
 interface SnapshotDeltaSelection {
@@ -19,6 +20,7 @@ interface BoardRouteContext {
   readonly db: Database;
   readonly cwd: string;
   readonly token: string;
+  readonly eventBus?: BoardEventBus;
 }
 
 interface BoardRouteError {
@@ -106,6 +108,23 @@ function isSqliteBusyMessage(message: string): boolean {
   return normalized.includes("database is locked") || normalized.includes("database schema is locked");
 }
 
+function redactDetailLeaves(value: unknown): unknown {
+  if (typeof value === "string") {
+    return redactSensitive(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactDetailLeaves(item));
+  }
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = redactDetailLeaves(child);
+    }
+    return out;
+  }
+  return value;
+}
+
 function toBoardRouteError(error: unknown, requestLabel: string): BoardRouteError {
   if (error instanceof DomainError) {
     const status =
@@ -116,11 +135,20 @@ function toBoardRouteError(error: unknown, requestLabel: string): BoardRouteErro
           : error.code === "invalid_dependency" || error.code === "dependency_blocked"
             ? 409
           : 400;
+    // Secrets occasionally ride DomainError when an upstream layer interpolates
+    // a request body or header into the message/details (P1 finding 10).
+    // Run the canonical redactor over the message and recursively over every
+    // string-valued leaf of `details` before serialising to the wire so we
+    // never leak Bearer/Basic credentials, JWTs, or keyed `token=...` shapes.
+    const redactedMessage = redactSensitive(error.message);
+    const redactedDetails = error.details === undefined
+      ? undefined
+      : (redactDetailLeaves(error.details) as Record<string, unknown>);
     return {
       status,
       code: error.code,
-      message: error.message,
-      ...(error.details === undefined ? {} : { details: error.details }),
+      message: redactedMessage,
+      ...(redactedDetails === undefined ? {} : { details: redactedDetails }),
     };
   }
 
@@ -153,12 +181,240 @@ function describeBoardError(mutations: MutationService, error: unknown, requestL
     return routeError;
   }
 
+  // describeError can echo user-supplied values straight from a DomainError
+  // (status_transition_invalid returns error.message verbatim, dependency
+  // descriptions interpolate ids). Run the same redact pass over the
+  // friendlier message so secrets don't slip past the wire-level sanitiser.
   return {
     ...routeError,
-    message: readableMessage,
+    message: redactSensitive(readableMessage),
   };
 }
 
+function publishSnapshotDeltaIfPresent(
+  eventBus: BoardEventBus | undefined,
+  data: Record<string, unknown>,
+): void {
+  if (!eventBus) {
+    return;
+  }
+
+  const delta = readSnapshotDelta(data);
+  if (delta) {
+    eventBus.publishSnapshotDelta(delta);
+  }
+}
+
+function formatSseEvent(eventName: string, data: unknown, id?: number): string {
+  const idLine = id === undefined ? "" : `id: ${id}\n`;
+  return `${idLine}event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+// SSE backpressure thresholds (P1 finding 5).
+// A client that connects but never reads can otherwise grow the per-stream
+// queue without bound — every snapshotDelta the bus publishes is encoded
+// and pushed, retaining the bytes in `controller`'s internal queue. We
+// guard against OOM by tracking unflushed bytes and the time since the
+// consumer last pulled, and tearing the connection down once either limit
+// is exceeded.
+const SSE_MAX_QUEUED_BYTES = 1_000_000; // 1 MB hard cap → drop connection.
+const SSE_COALESCE_BYTES = 256_000;     // 256 KB soft cap → coalesce deltas.
+const SSE_STALL_MS = 30_000;            // 30 s without consumption → drop.
+const SSE_BACKPRESSURE_CHECK_MS = 1_000;
+
+function openSnapshotStream(
+  request: Request,
+  domain: TrackerDomain,
+  eventBus: BoardEventBus | undefined,
+): Response {
+  if (!eventBus) {
+    return jsonResponse(503, {
+      ok: false,
+      error: {
+        code: "stream_unavailable",
+        message: "Snapshot stream is not available on this server",
+      },
+    });
+  }
+
+  const encoder = new TextEncoder();
+  const initialSnapshot = buildBoardSnapshot(domain);
+  let unsubscribe: (() => void) | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let backpressureTimer: ReturnType<typeof setInterval> | null = null;
+
+  // Bytes enqueued but not yet consumed via `pull`. Each enqueue adds the
+  // chunk's byte length; each `pull` decrements by the next pending chunk's
+  // size (FIFO; we don't peek into the controller's internal queue).
+  let queuedBytes = 0;
+  const pendingChunkSizes: number[] = [];
+  let lastConsumeAt = Date.now();
+  let closed = false;
+  // When over the soft threshold we coalesce snapshotDeltas: only the latest
+  // is retained, dropping superseded deltas. The cached delta is flushed
+  // once the queue drains below the soft limit on the next `pull`.
+  let pendingDelta: { id: number; snapshotDelta: Record<string, unknown> } | null = null;
+
+  const cleanupTimers = (): void => {
+    if (unsubscribe) {
+      unsubscribe();
+      unsubscribe = null;
+    }
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    if (backpressureTimer) {
+      clearInterval(backpressureTimer);
+      backpressureTimer = null;
+    }
+  };
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller): void {
+      const enqueueRaw = (chunk: string): void => {
+        if (closed) {
+          return;
+        }
+        try {
+          const bytes = encoder.encode(chunk);
+          controller.enqueue(bytes);
+          queuedBytes += bytes.byteLength;
+          pendingChunkSizes.push(bytes.byteLength);
+        } catch {
+          // Controller closed; cleanup happens via cancel.
+        }
+      };
+
+      const flushPendingDelta = (): void => {
+        if (!pendingDelta || closed) {
+          return;
+        }
+        const delta = pendingDelta;
+        pendingDelta = null;
+        enqueueRaw(formatSseEvent("snapshotDelta", { snapshotDelta: delta.snapshotDelta }, delta.id));
+      };
+
+      const closeWithError = (reason: string): void => {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        try {
+          const errorFrame = formatSseEvent("stream_error", { code: "backpressure", reason });
+          controller.enqueue(encoder.encode(errorFrame));
+        } catch {
+          // Already closed.
+        }
+        cleanupTimers();
+        try {
+          controller.close();
+        } catch {
+          // Already closed.
+        }
+      };
+
+      const handleSnapshotDelta = (id: number, snapshotDelta: Record<string, unknown>): void => {
+        if (closed) {
+          return;
+        }
+        if (queuedBytes >= SSE_MAX_QUEUED_BYTES) {
+          closeWithError("queued bytes exceeded 1MB hard limit");
+          return;
+        }
+        if (queuedBytes >= SSE_COALESCE_BYTES) {
+          // Slow consumer: coalesce. The board snapshot is cumulative; the
+          // newest delta carries the freshest causally-ordered state for
+          // every entity it touches, so dropping superseded deltas is safe.
+          pendingDelta = { id, snapshotDelta };
+          return;
+        }
+        // Fast path: flush any coalesced delta first to preserve ordering,
+        // then enqueue the new one.
+        if (pendingDelta) {
+          flushPendingDelta();
+        }
+        enqueueRaw(formatSseEvent("snapshotDelta", { snapshotDelta }, id));
+      };
+
+      // Initial snapshot so late-joining tabs converge immediately.
+      enqueueRaw(formatSseEvent("snapshot", { snapshot: initialSnapshot }));
+
+      unsubscribe = eventBus.subscribe((event) => {
+        if (event.type === "snapshotDelta") {
+          handleSnapshotDelta(event.id, event.snapshotDelta);
+        }
+      });
+
+      // Heartbeats keep proxies and stale-connection detectors happy.
+      heartbeatTimer = setInterval(() => {
+        enqueueRaw(": heartbeat\n\n");
+      }, 15000);
+
+      // Backpressure watchdog: if the consumer has not pulled within
+      // SSE_STALL_MS while pending data is sitting in the queue, treat the
+      // client as dead and drop the connection so we don't pin memory.
+      backpressureTimer = setInterval(() => {
+        if (closed) {
+          return;
+        }
+        if (queuedBytes >= SSE_MAX_QUEUED_BYTES) {
+          closeWithError("queued bytes exceeded 1MB hard limit");
+          return;
+        }
+        const stalled = queuedBytes > 0 && Date.now() - lastConsumeAt > SSE_STALL_MS;
+        if (stalled) {
+          closeWithError(`no consumer pull within ${SSE_STALL_MS}ms`);
+        }
+      }, SSE_BACKPRESSURE_CHECK_MS);
+
+      const onAbort = (): void => {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        cleanupTimers();
+        try {
+          controller.close();
+        } catch {
+          // Already closed.
+        }
+      };
+
+      if (request.signal.aborted) {
+        onAbort();
+        return;
+      }
+      request.signal.addEventListener("abort", onAbort);
+    },
+    pull(): void {
+      // A pull means the consumer drained the next chunk from the queue.
+      const consumed = pendingChunkSizes.shift();
+      if (typeof consumed === "number") {
+        queuedBytes = Math.max(0, queuedBytes - consumed);
+      }
+      lastConsumeAt = Date.now();
+      // Outer-scope flush: re-walk via enqueueRaw on the active controller is
+      // unnecessary because the controller is only valid inside start();
+      // instead the next snapshotDelta arrival will see queuedBytes below the
+      // soft limit and flush pendingDelta automatically.
+    },
+    cancel(): void {
+      closed = true;
+      cleanupTimers();
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": "text/event-stream; charset=utf-8",
+      "x-accel-buffering": "no",
+    },
+  });
+}
+
 function buildMutationResponse(_domain: TrackerDomain, data: Record<string, unknown>, status = 200): Response {
   return jsonResponse(status, {
     ok: true,
@@ -301,6 +557,61 @@ function readOptionalNullableString(body: Record<string, unknown>, field: string
   return value;
 }
 
+function parseIfMatchHeader(request: Request): number | null {
+  const raw = request.headers.get("if-match");
+  if (raw === null) {
+    return null;
+  }
+
+  // RFC 7232 §3.1 allows a strong ETag (`"<value>"`) or a weak ETag
+  // (`W/"<value>"`). Trekoon does not differentiate strong from weak
+  // semantics — a millisecond updatedAt is exact either way — so we
+  // accept both shapes. The wildcard `*` is intentionally NOT supported:
+  // it would mean "any current representation matches" and would defeat
+  // the whole purpose of the optimistic-concurrency check, so we surface
+  // it as 400 invalid_input below rather than treating it as a no-op.
+  const stripped = raw.trim().replace(/^W\//iu, "");
+  const trimmed = stripped.replace(/^"+|"+$/g, "");
+  if (trimmed.length === 0) {
+    return null;
+  }
+
+  const parsed = Number(trimmed);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+    throw new DomainError({
+      code: "invalid_input",
+      message:
+        "If-Match header must be an integer updatedAt millisecond timestamp (RFC 7232 strong or W/-prefixed weak ETag); the `*` wildcard is not supported",
+      details: { header: "If-Match", value: raw },
+    });
+  }
+
+  return parsed;
+}
+
+interface PreconditionFailedDetails {
+  readonly entityKind: "epic" | "task" | "subtask";
+  readonly entityId: string;
+  readonly currentUpdatedAt: number;
+  readonly providedUpdatedAt: number;
+}
+
+function preconditionFailedResponse(details: PreconditionFailedDetails): Response {
+  return jsonResponse(409, {
+    ok: false,
+    error: {
+      code: "precondition_failed",
+      message: "If-Match version does not match current updatedAt",
+      details: {
+        entityKind: details.entityKind,
+        entityId: details.entityId,
+        currentUpdatedAt: details.currentUpdatedAt,
+        providedUpdatedAt: details.providedUpdatedAt,
+      },
+    },
+  });
+}
+
 function readIdempotencyKey(request: Request, body: Record<string, unknown>): string | null {
   const headerKey = request.headers.get("x-trekoon-idempotency-key");
   if (typeof headerKey === "string" && headerKey.trim().length > 0) {
@@ -320,6 +631,15 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
     const url = new URL(request.url);
     const requestLabel = `${request.method} ${url.pathname}`;
     const requestToken = extractToken(request, url);
+    // Plain `!==` instead of a constant-time compare is a deliberate choice
+    // (System Hardening 0.4.2, finding 32). The board server only binds to
+    // 127.0.0.1, the session token is a 256-bit cryptographically-random
+    // value rotated per board-server lifetime, and the comparison happens
+    // against an in-memory string — there is no remote-timing side-channel
+    // realistic enough to attack. Adopting `crypto.timingSafeEqual` would
+    // also require handling length-mismatch as a separate non-leaking case.
+    // Re-evaluate this decision if the board server ever listens on a
+    // non-loopback interface or uses a low-entropy / static token.
     if (requestToken !== context.token) {
       return jsonResponse(401, {
         ok: false,
@@ -332,6 +652,27 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
 
     const domain = new TrackerDomain(context.db);
     const mutations = new MutationService(context.db, context.cwd);
+    const eventBus = context.eventBus;
+
+    const respondWithMutation = (
+      domainArg: TrackerDomain,
+      data: Record<string, unknown>,
+      status = 200,
+    ): Response => {
+      publishSnapshotDeltaIfPresent(eventBus, data);
+      return buildMutationResponse(domainArg, data, status);
+    };
+
+    const respondWithMutationDelta = (
+      domainArg: TrackerDomain,
+      data: Record<string, unknown>,
+      selection: SnapshotDeltaSelection,
+      status = 200,
+    ): Response => {
+      const enrichedData = { ...data, snapshotDelta: buildSnapshotDelta(domainArg, selection) };
+      publishSnapshotDeltaIfPresent(eventBus, enrichedData);
+      return buildMutationResponse(domainArg, enrichedData, status);
+    };
 
     try {
       if (request.method === "GET" && url.pathname === "/api/snapshot") {
@@ -343,15 +684,26 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         });
       }
 
+      if (request.method === "GET" && url.pathname === "/api/snapshot/stream") {
+        return openSnapshotStream(request, domain, eventBus);
+      }
+
         const epicCascadeMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/epics\/([^/]+)\/cascade$/u) : null;
         if (epicCascadeMatch) {
+          const epicId = epicCascadeMatch[1] ?? "";
           const body = await parseJsonBody(request);
           const status = readRequiredString(body, "status");
-          const plan = mutations.updateEpicStatusCascade(epicCascadeMatch[1] ?? "", status);
-          return buildMutationDeltaResponse(domain, {
+          const ifMatch = parseIfMatchHeader(request);
+          // CAS path: precondition is enforced inside the write transaction
+          // (see PreconditionFailedError catch below). Missing-header path
+          // preserves back-compat with clients that don't send If-Match.
+          const plan = ifMatch !== null
+            ? mutations.updateEpicStatusCascadeWithIfMatch(epicId, ifMatch, status)
+            : mutations.updateEpicStatusCascade(epicId, status);
+          return respondWithMutationDelta(domain, {
             plan,
           }, {
-            epicIds: [epicCascadeMatch[1] ?? ""],
+            epicIds: [epicId],
             taskIds: plan.orderedChanges.filter((change) => change.kind === "task").map((change) => change.id),
             subtaskIds: plan.orderedChanges.filter((change) => change.kind === "subtask").map((change) => change.id),
           });
@@ -359,38 +711,53 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
 
       const epicMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/epics\/([^/]+)$/u) : null;
         if (epicMatch) {
+        const epicId = epicMatch[1] ?? "";
         const body = await parseJsonBody(request);
-        const epic = mutations.updateEpic(epicMatch[1] ?? "", {
+        const ifMatch = parseIfMatchHeader(request);
+        const epicInput = {
           title: readOptionalString(body, "title"),
           description: readOptionalString(body, "description"),
           status: readOptionalString(body, "status"),
-        });
-          return buildMutationDeltaResponse(domain, { epic }, { epicIds: [epic.id] });
+        };
+        const epic = ifMatch !== null
+          ? mutations.updateEpicWithIfMatch(epicId, ifMatch, epicInput)
+          : mutations.updateEpic(epicId, epicInput);
+          return respondWithMutationDelta(domain, { epic }, { epicIds: [epic.id] });
         }
 
       const taskMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/tasks\/([^/]+)$/u) : null;
       if (taskMatch) {
+        const taskId = taskMatch[1] ?? "";
         const body = await parseJsonBody(request);
-          const task = mutations.updateTask(taskMatch[1] ?? "", {
-            title: readOptionalString(body, "title"),
-            description: readOptionalString(body, "description"),
-            status: readOptionalString(body, "status"),
-            owner: readOptionalNullableString(body, "owner"),
-          });
-          return buildMutationDeltaResponse(domain, { task }, { epicIds: [task.epicId], taskIds: [task.id] });
+        const ifMatch = parseIfMatchHeader(request);
+        const taskInput = {
+          title: readOptionalString(body, "title"),
+          description: readOptionalString(body, "description"),
+          status: readOptionalString(body, "status"),
+          owner: readOptionalNullableString(body, "owner"),
+        };
+        const task = ifMatch !== null
+          ? mutations.updateTaskWithIfMatch(taskId, ifMatch, taskInput)
+          : mutations.updateTask(taskId, taskInput);
+          return respondWithMutationDelta(domain, { task }, { epicIds: [task.epicId], taskIds: [task.id] });
         }
 
       const subtaskMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/subtasks\/([^/]+)$/u) : null;
       if (subtaskMatch) {
+        const subtaskId = subtaskMatch[1] ?? "";
         const body = await parseJsonBody(request);
-          const subtask = mutations.updateSubtask(subtaskMatch[1] ?? "", {
-            title: readOptionalString(body, "title"),
-            description: readOptionalString(body, "description"),
-            status: readOptionalString(body, "status"),
-            owner: readOptionalNullableString(body, "owner"),
-          });
+        const ifMatch = parseIfMatchHeader(request);
+        const subtaskInput = {
+          title: readOptionalString(body, "title"),
+          description: readOptionalString(body, "description"),
+          status: readOptionalString(body, "status"),
+          owner: readOptionalNullableString(body, "owner"),
+        };
+        const subtask = ifMatch !== null
+          ? mutations.updateSubtaskWithIfMatch(subtaskId, ifMatch, subtaskInput)
+          : mutations.updateSubtask(subtaskId, subtaskInput);
           const task = domain.getTaskOrThrow(subtask.taskId);
-          return buildMutationDeltaResponse(domain, { subtask }, { epicIds: [task.epicId], taskIds: [task.id], subtaskIds: [subtask.id] });
+          return respondWithMutationDelta(domain, { subtask }, { epicIds: [task.epicId], taskIds: [task.id], subtaskIds: [subtask.id] });
         }
 
       if (request.method === "POST" && url.pathname === "/api/subtasks") {
@@ -413,7 +780,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
               subtaskIds: [subtask.id],
             }),
           };
-          return buildMutationResponse(domain, responseData, 201);
+          return respondWithMutation(domain, responseData, 201);
         }
 
         const result = mutations.createSubtaskAtomicallyWithIdempotency({
@@ -442,7 +809,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         const replaySubtaskId = readRecordId(result.responseData.subtask);
         const replayTaskId = replaySubtaskId ? domain.getSubtask(replaySubtaskId)?.taskId ?? null : null;
         const replayEpicId = replayTaskId ? domain.getTask(replayTaskId)?.epicId ?? null : null;
-        return buildMutationResponse(domain, result.state === "replay"
+        return respondWithMutation(domain, result.state === "replay"
           ? withFreshReplaySnapshotDelta(domain, result.responseData, {
             epicIds: replayEpicId ? [replayEpicId] : [],
             taskIds: replayTaskId ? [replayTaskId] : [],
@@ -470,7 +837,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
                 deletedDependencyIds,
               }),
             };
-            return buildMutationResponse(domain, responseData, 200);
+            return respondWithMutation(domain, responseData, 200);
           }
 
           const result = mutations.deleteSubtaskAtomicallyWithIdempotency({
@@ -493,7 +860,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
             }),
           });
           const replaySnapshotDelta = readSnapshotDelta(result.responseData);
-          return buildMutationResponse(domain, result.state === "replay"
+          return respondWithMutation(domain, result.state === "replay"
             ? withFreshReplaySnapshotDelta(domain, result.responseData, {
               epicIds: readRecordIds(replaySnapshotDelta?.epics),
               taskIds: readRecordIds(replaySnapshotDelta?.tasks),
@@ -519,7 +886,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
               dependencyIds: [dependency.id],
             }),
           };
-          return buildMutationResponse(domain, responseData, 201);
+          return respondWithMutation(domain, responseData, 201);
         }
 
         const result = mutations.addDependencyAtomicallyWithIdempotency({
@@ -563,7 +930,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
             dependencyIds: replayDependencyId ? [replayDependencyId] : [],
           }
           : { dependencyIds: [] };
-        return buildMutationResponse(domain, result.state === "replay"
+        return respondWithMutation(domain, result.state === "replay"
           ? withFreshReplaySnapshotDelta(domain, result.responseData, replaySelection)
           : result.responseData, result.status);
       }
@@ -598,7 +965,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
               deletedDependencyIds: existingDependencyIds,
             }),
           };
-          return buildMutationResponse(domain, responseData, 200);
+          return respondWithMutation(domain, responseData, 200);
         }
 
         const result = mutations.removeDependencyAtomicallyWithIdempotency({
@@ -622,7 +989,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
           }),
         });
         const replaySnapshotDelta = readSnapshotDelta(result.responseData);
-        return buildMutationResponse(domain, result.state === "replay"
+        return respondWithMutation(domain, result.state === "replay"
           ? withFreshReplaySnapshotDelta(domain, result.responseData, {
             taskIds: compactIds([domain.getTask(sourceId)?.id ?? "", domain.getTask(dependsOnId)?.id ?? ""]),
             subtaskIds: compactIds([domain.getSubtask(sourceId)?.id ?? "", domain.getSubtask(dependsOnId)?.id ?? ""]),
@@ -639,6 +1006,18 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         },
       });
     } catch (error: unknown) {
+      // PreconditionFailedError is a typed signal from the *WithIfMatch
+      // CAS variants. It carries the freshly-fetched currentUpdatedAt so
+      // the 409 payload is always consistent with the post-rollback state.
+      if (error instanceof PreconditionFailedError) {
+        return preconditionFailedResponse({
+          entityKind: error.entityKind,
+          entityId: error.entityId,
+          currentUpdatedAt: error.currentUpdatedAt,
+          providedUpdatedAt: error.providedUpdatedAt,
+        });
+      }
+
       const routeError = describeBoardError(mutations, error, requestLabel);
       return jsonResponse(routeError.status, {
         ok: false,