trekoon 0.4.2 → 0.4.4

package/src/board/assets/components/Component.js

@@ -153,8 +153,8 @@ export function preserveFormState(container, writeFn, options = {}) {
 
   // Per-form cache for getManagedControls: avoids the O(n^2) re-query that
   // occurs when many controls share the same form root.
-  const captureCache = new Map();
-  const inputs = getManagedControls(container, captureCache);
+  const controlCache = new Map();
+  const inputs = getManagedControls(container, controlCache);
 
   const activeElement = document.activeElement;
   let focusedIdentity = null;
@@ -162,7 +162,7 @@ export function preserveFormState(container, writeFn, options = {}) {
   const savedStates = inputs.map((el) => {
     const form = getFormRoot(el);
     const formId = getNamespacedFormIdentity(form);
-    const controlId = form ? getControlIdentity(el, form, captureCache) : null;
+    const controlId = form ? getControlIdentity(el, form, controlCache) : null;
     const identity = controlId ? { formId, controlId } : null;
 
     if (activeElement === el) {
@@ -180,6 +180,7 @@ export function preserveFormState(container, writeFn, options = {}) {
   }).filter(s => s.identity);
 
   writeFn();
+  controlCache.clear();
 
   const formsByIdentity = new Map(
     Array.from(container.querySelectorAll(FORM_ROOT_SELECTOR)).map((form) => [
@@ -188,16 +189,13 @@ export function preserveFormState(container, writeFn, options = {}) {
     ]),
   );
 
-  // Fresh cache for the restore pass (DOM was replaced by writeFn).
-  const restoreCache = new Map();
-
   for (const state of savedStates) {
     const { formId, controlId } = state.identity;
     if (resetFormIds.has(formId)) {
       continue;
     }
     const form = formsByIdentity.get(formId) ?? container;
-    const restored = getManagedControls(form, restoreCache).find((control) => getControlIdentity(control, form, restoreCache) === controlId);
+    const restored = getManagedControls(form, controlCache).find((control) => getControlIdentity(control, form, controlCache) === controlId);
     if (restored && restored.value !== state.value) {
       restored.value = state.value;
     }
@@ -213,7 +211,7 @@ export function preserveFormState(container, writeFn, options = {}) {
       return;
     }
     const form = formsByIdentity.get(formId) ?? container;
-    const restored = getManagedControls(form, restoreCache).find((control) => getControlIdentity(control, form, restoreCache) === controlId);
+    const restored = getManagedControls(form, controlCache).find((control) => getControlIdentity(control, form, controlCache) === controlId);
     if (restored) {
       restored.focus({ preventScroll: true });
       const focusedState = savedStates.find((state) => state.identity?.formId === formId && state.identity?.controlId === controlId);

package/src/board/assets/state/actions.js

@@ -444,6 +444,9 @@ export function createBoardActions(options) {
       const nextKey = feedback ? `${feedback.targetStatus}|${feedback.kind}` : null;
       if (prevKey === nextKey) return;
       store.dragFeedback = feedback;
+      if (typeof model.invalidateBoardStateMemo === "function") {
+        model.invalidateBoardStateMemo();
+      }
       rerender();
     },
     dropTaskStatus(taskId, nextStatus) {

package/src/board/assets/state/api.js

@@ -222,10 +222,9 @@ function createTimeoutError(method, path, timeoutMs) {
  * }}
  */
 export function createMutationQueue(model, rerender) {
-  /** @type {Array<{ optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
+  /** @type {Array<{ mutationId: string, optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
   const queue = [];
   let processing = false;
-  let nextMutationId = 1;
   /** @type {Array<() => void>} */
   let flushResolvers = [];
 
@@ -246,7 +245,7 @@ export function createMutationQueue(model, rerender) {
 
     while (queue.length > 0) {
       const mutation = queue.shift();
-      if (model.store.notice?.retryMutationId !== mutation.id) {
+      if (model.store.notice?.retryMutationId !== mutation.mutationId) {
         model.store.notice = null;
       }
 
@@ -258,8 +257,8 @@ export function createMutationQueue(model, rerender) {
 
       try {
         if (typeof mutation.optimistic === "function") {
-          const previousSnapshot = cloneSnapshot(model.store.snapshot);
-          const optimisticSnapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
+          const previousSnapshot = model.store.snapshot;
+          const optimisticSnapshot = mutation.optimistic(cloneSnapshot(previousSnapshot));
           inverseDelta = computeInverseDelta(previousSnapshot, optimisticSnapshot);
           model.store.snapshot = optimisticSnapshot;
           // Direct snapshot mutation bypasses setState/syncState; invalidate
@@ -298,7 +297,7 @@ export function createMutationQueue(model, rerender) {
           title: "Action failed",
           message,
           retryLabel: "Retry",
-          retryMutationId: mutation.id,
+          retryMutationId: mutation.mutationId,
         };
 
         if (typeof mutation.onError === "function") {
@@ -318,8 +317,10 @@ export function createMutationQueue(model, rerender) {
 
   return {
     enqueue(mutation) {
-      queue.push({ ...mutation, id: nextMutationId });
-      nextMutationId += 1;
+      queue.push({
+        ...mutation,
+        mutationId: mutation.mutationId ?? crypto.randomUUID(),
+      });
       processNext();
     },
 
@@ -569,7 +570,7 @@ export function createApi(model, options) {
  *
  * @param {object} model - Store with `applySnapshotDelta` method
  * @param {object} options
- * @param {string} options.sessionToken - Auth token (forwarded as ?token=)
+ * @param {string} options.sessionToken - Auth token for API parity; EventSource uses the same-origin HttpOnly cookie.
  * @param {function} options.rerender - Trigger UI rerender after applying deltas
  * @param {typeof EventSource} [options.EventSourceCtor] - Constructor override for tests
  * @param {string} [options.path] - Override stream path; default /api/snapshot/stream
@@ -577,7 +578,6 @@ export function createApi(model, options) {
  */
 export function subscribeSnapshotStream(model, options) {
   const {
-    sessionToken,
     rerender,
     EventSourceCtor = typeof EventSource !== "undefined" ? EventSource : null,
     path = "/api/snapshot/stream",
@@ -587,14 +587,20 @@ export function subscribeSnapshotStream(model, options) {
     return { dispose: () => {}, eventSource: null };
   }
 
-  // EventSource cannot set custom headers, so the auth token rides as a query
-  // parameter. Server `extractToken` already accepts ?token=.
-  const url = sessionToken && sessionToken.length > 0
-    ? `${path}?token=${encodeURIComponent(sessionToken)}`
-    : path;
-
   let disposed = false;
-  const eventSource = new EventSourceCtor(url);
+  let consecutiveErrors = 0;
+  const eventSource = new EventSourceCtor(path);
+
+  const clearLiveUpdateNotice = () => {
+    if (model.store?.notice?.code === "live_updates_disconnected") {
+      model.store.notice = null;
+    }
+  };
+
+  const markLiveUpdateSuccess = () => {
+    consecutiveErrors = 0;
+    clearLiveUpdateNotice();
+  };
 
   const handleSnapshotDelta = (event) => {
     if (disposed) return;
@@ -613,6 +619,7 @@ export function subscribeSnapshotStream(model, options) {
     const delta = payload?.snapshotDelta;
     if (!delta || typeof delta !== "object") return;
     model.applySnapshotDelta(delta);
+    markLiveUpdateSuccess();
     if (typeof rerender === "function") rerender();
   };
 
@@ -632,27 +639,42 @@ export function subscribeSnapshotStream(model, options) {
     if (!snapshot || typeof snapshot !== "object") return;
     if (typeof model.replaceSnapshot === "function") {
       model.replaceSnapshot(snapshot);
+      markLiveUpdateSuccess();
       if (typeof rerender === "function") rerender();
     }
   };
 
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    try {
+      eventSource.close();
+    } catch {
+      // best-effort
+    }
+  }
+
   const handleError = () => {
     if (disposed) return;
-    // Surface the disconnect to the user so they don't silently miss live
-    // updates. EventSource will keep auto-reconnecting; once a snapshot/
-    // snapshotDelta event lands again, the regular notice clearing flow
-    // (e.g. on the next mutation) replaces this notice.
+    consecutiveErrors += 1;
     if (model.store && typeof model.store === "object") {
       const existing = model.store.notice;
-      if (!existing || existing.code !== "live_updates_disconnected") {
+      const disabled = consecutiveErrors >= 5;
+      const nextCode = disabled ? "live_updates_disabled" : "live_updates_disconnected";
+      if (!existing || existing.code !== nextCode) {
         model.store.notice = {
           type: "warning",
-          code: "live_updates_disconnected",
-          title: "Live updates disconnected",
-          message: "Reconnecting to the server. Changes from other sessions may be delayed.",
+          code: nextCode,
+          title: disabled ? "Live updates disabled" : "Live updates disconnected",
+          message: disabled
+            ? "Refresh the board to resume live updates from other sessions."
+            : "Reconnecting to the server. Changes from other sessions may be delayed.",
         };
         if (typeof rerender === "function") rerender();
       }
+      if (disabled) {
+        dispose();
+      }
     }
   };
 
@@ -665,14 +687,6 @@ export function subscribeSnapshotStream(model, options) {
 
   return {
     eventSource,
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      try {
-        eventSource.close();
-      } catch {
-        // best-effort
-      }
-    },
+    dispose,
   };
 }

package/src/board/assets/state/store.js

@@ -400,6 +400,9 @@ export function createStore(initialSnapshot, options = {}) {
 
   const boardStateMemo = createBoardStateMemo(deriveBoardState);
 
+  // Direct `model.store` mutations must manually invalidate this memo before
+  // rerendering. Current direct-mutation fields: snapshot, notice, isMutating,
+  // dragFeedback.
   function notify() {
     boardStateMemo.invalidate();
     for (const listener of listeners) {

package/src/board/event-bus.ts

@@ -18,7 +18,10 @@ export type BoardEventListener = (event: BoardEvent) => void;
 
 export interface BoardEventBus {
   publishSnapshotDelta(snapshotDelta: Record<string, unknown>): BoardDeltaEvent;
+  markInProcessWrite(timestamp?: number, snapshotDelta?: Record<string, unknown>): void;
   subscribe(listener: BoardEventListener): () => void;
+  readonly lastInProcessWriteAt: number;
+  readonly lastInProcessSnapshotDelta: Record<string, unknown> | null;
   readonly subscriberCount: number;
   close(): void;
 }
@@ -27,6 +30,8 @@ export function createBoardEventBus(): BoardEventBus {
   const listeners = new Set<BoardEventListener>();
   let nextId = 1;
   let closed = false;
+  let lastInProcessWriteAt = 0;
+  let lastInProcessSnapshotDelta: Record<string, unknown> | null = null;
 
   return {
     publishSnapshotDelta(snapshotDelta: Record<string, unknown>): BoardDeltaEvent {
@@ -51,6 +56,10 @@ export function createBoardEventBus(): BoardEventBus {
 
       return event;
     },
+    markInProcessWrite(timestamp = Date.now(), snapshotDelta: Record<string, unknown> | undefined = undefined): void {
+      lastInProcessWriteAt = timestamp;
+      lastInProcessSnapshotDelta = snapshotDelta ?? null;
+    },
     subscribe(listener: BoardEventListener): () => void {
       if (closed) {
         return () => {};
@@ -64,6 +73,12 @@ export function createBoardEventBus(): BoardEventBus {
     get subscriberCount(): number {
       return listeners.size;
     },
+    get lastInProcessWriteAt(): number {
+      return lastInProcessWriteAt;
+    },
+    get lastInProcessSnapshotDelta(): Record<string, unknown> | null {
+      return lastInProcessSnapshotDelta;
+    },
     close(): void {
       closed = true;
       listeners.clear();

package/src/board/routes.ts

@@ -84,7 +84,7 @@ function readCookieToken(request: Request): string | null {
   return null;
 }
 
-function extractToken(request: Request, url: URL): string | null {
+function extractHeaderOrCookieToken(request: Request): string | null {
   const authorization: string | null = request.headers.get("authorization");
   if (authorization?.startsWith("Bearer ")) {
     return authorization.slice("Bearer ".length).trim();
@@ -95,11 +95,6 @@ function extractToken(request: Request, url: URL): string | null {
     return headerToken.trim();
   }
 
-  const queryToken: string | null = url.searchParams.get("token");
-  if (queryToken && queryToken.trim().length > 0) {
-    return queryToken.trim();
-  }
-
   return readCookieToken(request);
 }
 
@@ -108,17 +103,34 @@ function isSqliteBusyMessage(message: string): boolean {
   return normalized.includes("database is locked") || normalized.includes("database schema is locked");
 }
 
-function redactDetailLeaves(value: unknown): unknown {
+const REDACT_DETAILS_MAX_DEPTH = 16;
+
+export function redactDetailLeaves(
+  value: unknown,
+  seen: WeakSet<object> = new WeakSet<object>(),
+  depth = 0,
+): unknown {
   if (typeof value === "string") {
     return redactSensitive(value);
   }
+  if (depth >= REDACT_DETAILS_MAX_DEPTH) {
+    return "[MaxDepth]";
+  }
   if (Array.isArray(value)) {
-    return value.map((item) => redactDetailLeaves(item));
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+    return value.map((item) => redactDetailLeaves(item, seen, depth + 1));
   }
   if (value !== null && typeof value === "object") {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
     const out: Record<string, unknown> = {};
     for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
-      out[key] = redactDetailLeaves(child);
+      out[redactSensitive(key)] = redactDetailLeaves(child, seen, depth + 1);
     }
     return out;
   }
@@ -202,6 +214,7 @@ function publishSnapshotDeltaIfPresent(
   const delta = readSnapshotDelta(data);
   if (delta) {
     eventBus.publishSnapshotDelta(delta);
+    eventBus.markInProcessWrite(Date.now(), delta);
   }
 }
 
@@ -212,14 +225,10 @@ function formatSseEvent(eventName: string, data: unknown, id?: number): string {
 
 // 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.
+// queue without bound. The stream controller already exposes queue pressure
+// through `desiredSize`; once it goes negative we stop enqueueing sparse
+// deltas and retain one pending full-snapshot frame for the next drain.
+const SSE_STALL_MS = 30_000; // 30 s without consumption under pressure → drop.
 const SSE_BACKPRESSURE_CHECK_MS = 1_000;
 
 function openSnapshotStream(
@@ -243,19 +252,16 @@ function openSnapshotStream(
   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;
+  let pendingFrame: string | null = null;
+  let onAbort: (() => void) | null = null;
 
   const cleanupTimers = (): void => {
+    if (onAbort) {
+      request.signal.removeEventListener("abort", onAbort);
+      onAbort = null;
+    }
     if (unsubscribe) {
       unsubscribe();
       unsubscribe = null;
@@ -277,22 +283,29 @@ function openSnapshotStream(
           return;
         }
         try {
-          const bytes = encoder.encode(chunk);
-          controller.enqueue(bytes);
-          queuedBytes += bytes.byteLength;
-          pendingChunkSizes.push(bytes.byteLength);
+          controller.enqueue(encoder.encode(chunk));
         } catch {
           // Controller closed; cleanup happens via cancel.
         }
       };
 
-      const flushPendingDelta = (): void => {
-        if (!pendingDelta || closed) {
+      const isBackpressured = (): boolean => (controller.desiredSize ?? 1) < 0;
+
+      const queueFullSnapshot = (id: number): void => {
+        // Sparse per-mutation deltas are not cumulative, so merging them can
+        // silently drop changes. Under backpressure, retain a fresh full
+        // snapshot frame instead; EventSource clients can converge from it
+        // without relying on every skipped delta.
+        pendingFrame = formatSseEvent("snapshot", { snapshot: buildBoardSnapshot(domain) }, id);
+      };
+
+      const flushPendingFrame = (): void => {
+        if (!pendingFrame || closed || isBackpressured()) {
           return;
         }
-        const delta = pendingDelta;
-        pendingDelta = null;
-        enqueueRaw(formatSseEvent("snapshotDelta", { snapshotDelta: delta.snapshotDelta }, delta.id));
+        const frame = pendingFrame;
+        pendingFrame = null;
+        enqueueRaw(frame);
       };
 
       const closeWithError = (reason: string): void => {
@@ -318,22 +331,15 @@ function openSnapshotStream(
         if (closed) {
           return;
         }
-        if (queuedBytes >= SSE_MAX_QUEUED_BYTES) {
-          closeWithError("queued bytes exceeded 1MB hard limit");
+        if (isBackpressured()) {
+          queueFullSnapshot(id);
           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 };
+        flushPendingFrame();
+        if (isBackpressured()) {
+          queueFullSnapshot(id);
           return;
         }
-        // Fast path: flush any coalesced delta first to preserve ordering,
-        // then enqueue the new one.
-        if (pendingDelta) {
-          flushPendingDelta();
-        }
         enqueueRaw(formatSseEvent("snapshotDelta", { snapshotDelta }, id));
       };
 
@@ -348,27 +354,26 @@ function openSnapshotStream(
 
       // Heartbeats keep proxies and stale-connection detectors happy.
       heartbeatTimer = setInterval(() => {
+        if ((controller.desiredSize ?? 1) < 0) {
+          return;
+        }
         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.
+      // SSE_STALL_MS while the stream is under pressure, close with an
+      // error frame so EventSource reconnects and receives a fresh snapshot.
       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;
+        const stalled = (controller.desiredSize ?? 1) < 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 => {
+      onAbort = (): void => {
         if (closed) {
           return;
         }
@@ -387,17 +392,17 @@ function openSnapshotStream(
       }
       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);
-      }
+    pull(controller): void {
       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.
+      if (pendingFrame && !closed && (controller.desiredSize ?? 1) >= 0) {
+        const frame = pendingFrame;
+        pendingFrame = null;
+        try {
+          controller.enqueue(encoder.encode(frame));
+        } catch {
+          // Controller closed.
+        }
+      }
     },
     cancel(): void {
       closed = true;
@@ -565,35 +570,30 @@ function parseIfMatchHeader(request: Request): number | 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
+  // semantics — the entity version token 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)) {
+  if (!/^(0|[1-9]\d*)$/u.test(trimmed)) {
     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",
+        "If-Match header must be a non-negative integer version token (RFC 7232 strong or W/-prefixed weak ETag); the `*` wildcard is not supported",
       details: { header: "If-Match", value: raw },
     });
   }
 
-  return parsed;
+  return Number(trimmed);
 }
 
 interface PreconditionFailedDetails {
   readonly entityKind: "epic" | "task" | "subtask";
   readonly entityId: string;
-  readonly currentUpdatedAt: number;
-  readonly providedUpdatedAt: number;
+  readonly currentVersion: number;
+  readonly providedVersion: number;
 }
 
 function preconditionFailedResponse(details: PreconditionFailedDetails): Response {
@@ -601,12 +601,12 @@ function preconditionFailedResponse(details: PreconditionFailedDetails): Respons
     ok: false,
     error: {
       code: "precondition_failed",
-      message: "If-Match version does not match current updatedAt",
+      message: "If-Match version does not match current version",
       details: {
         entityKind: details.entityKind,
         entityId: details.entityId,
-        currentUpdatedAt: details.currentUpdatedAt,
-        providedUpdatedAt: details.providedUpdatedAt,
+        currentVersion: details.currentVersion,
+        providedVersion: details.providedVersion,
       },
     },
   });
@@ -630,7 +630,18 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
   return async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
     const requestLabel = `${request.method} ${url.pathname}`;
-    const requestToken = extractToken(request, url);
+    if (url.searchParams.has("token")) {
+      return jsonResponse(401, {
+        ok: false,
+        error: {
+          code: "unauthorized",
+          message: "Board API requests must authenticate with the session cookie or authorization header",
+        },
+      });
+    }
+    const requestToken = url.pathname === "/api/snapshot/stream"
+      ? readCookieToken(request)
+      : extractHeaderOrCookieToken(request);
     // 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
@@ -1007,14 +1018,14 @@ 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
+      // CAS variants. It carries the freshly-fetched currentVersion 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,
+          currentVersion: error.currentVersion,
+          providedVersion: error.providedVersion,
         });
       }