@erdemtuna/doc-review 0.8.1 → 0.9.0

package/src/history-coordinator.js

@@ -0,0 +1,186 @@
+import { defaultHistoryRound } from "./history-client.js";
+
+const idOf = (round) => round?.roundId || round?.id;
+const retryDelays = [1000, 2000, 4000];
+
+export function transientCaptureError(error) {
+  return ["CAPTURE_TIMEOUT", "CAPTURE_NOT_READY", "CAPTURE_UNSTABLE", "CAPTURE_BUSY", "VIEW_CHANGED"].includes(error?.code) ||
+    [408, 429, 502, 503, 504].includes(error?.status) ||
+    (error instanceof TypeError && /fetch|network|load failed/i.test(error.message));
+}
+
+export function requireCaptureSuccess(result, key) {
+  if (result?.ok === true) return result;
+  throw Object.assign(new Error(result?.round?.targets?.find((target) => target.key === key)?.capture?.error ||
+    "Content capture is unavailable"), { code: "CAPTURE_UNAVAILABLE" });
+}
+
+/** One capture at a time; delayed/finished attempts never block other rounds. */
+export function createCaptureCoordinator({ candidates, ready, capture, now = Date.now,
+  setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const attempts = new Map();
+  let timer = null;
+  let active = null;
+  let epoch = 0;
+  let stopped = false;
+  function tick() {
+    clearTimer(timer);
+    timer = null;
+    if (stopped || active || !ready()) return;
+    const jobs = candidates();
+    const job = jobs.find(({ id }) => {
+      const attempt = attempts.get(id);
+      return !attempt || (!attempt.done && attempt.due <= now());
+    });
+    if (!job) {
+      const due = jobs.map(({ id }) => attempts.get(id)).filter((entry) => entry && !entry.done)
+        .reduce((next, entry) => Math.min(next, entry.due), Infinity);
+      if (Number.isFinite(due)) timer = setTimer(tick, Math.max(0, due - now()));
+      return;
+    }
+    const attempt = attempts.get(job.id) || { count: 0, due: 0, done: false };
+    attempts.set(job.id, attempt);
+    attempt.count++;
+    const controller = new AbortController();
+    const started = epoch;
+    active = controller;
+    Promise.resolve().then(() => {
+      if (controller.signal.aborted) return;
+      return capture(job, controller.signal);
+    }).then(() => { attempt.done = true; }, (error) => {
+      if (transientCaptureError(error) && attempt.count <= retryDelays.length) {
+        attempt.due = now() + retryDelays[attempt.count - 1];
+      } else attempt.done = true;
+    }).finally(() => {
+      if (started !== epoch) return;
+      active = null;
+      tick();
+    });
+  }
+  return {
+    tick,
+    reset() {
+      epoch++;
+      active?.abort();
+      active = null;
+      clearTimer(timer);
+      timer = null;
+      attempts.clear();
+    },
+    stop() {
+      this.reset();
+      stopped = true;
+    },
+    get busy() { return !!active; },
+  };
+}
+
+export function historyPresentation({ loading, error, round, target, comparison = {}, failure }) {
+  const modes = ["content", "source"].filter((mode) => comparison[mode]?.available === true);
+  if (loading && !round) return { state: "loading", message: "Loading comparison…", modes };
+  if (error && !round) return { state: "failed", message: "History could not be loaded. Try again.", modes };
+  if (!round) return { state: "empty", message: "No review rounds yet. Send feedback to start.", modes };
+  if (modes.length) {
+    const partial = modes.length < 2 || !!target?.baselineUnavailable || !!target?.resultUnavailable;
+    return { state: partial ? "partial" : "available", modes,
+      message: modes.includes("content")
+        ? partial ? "Content available; some comparison coverage is missing." : "Comparison ready."
+        : "Source available. Content is pending or unavailable." };
+  }
+  if (failure || error || target?.capture?.status === "failed") {
+    return { state: "failed", message: "Content capture failed. Feedback is safe; retry when ready.", modes };
+  }
+  if (target?.capture?.status === "unavailable" || target?.resultRevisionId) {
+    return { state: "partial", message: "Comparison unavailable for these snapshots. Feedback is safe.", modes };
+  }
+  return { state: "waiting", message: round.feedbackStatus === "acknowledged"
+    ? "Waiting for a stable result snapshot. You can keep reviewing."
+    : "Waiting for the agent's result.", modes };
+}
+
+/** Fetch into local values, then publish atomically so selectors never relabel stale content. */
+export function createHistoryController({ request, changed = () => {}, refreshed = () => {} }) {
+  const state = {
+    rounds: [], selectedId: null, round: null, targetKey: null, mode: "content", preferredMode: null,
+    index: 0, loading: false, error: null, captureBusy: false, finalizing: false, failures: new Map(),
+  };
+  let revision = 0;
+  const targets = new Map();
+  async function refresh() {
+    const current = ++revision;
+    state.loading = true;
+    state.error = null;
+    if (state.round && (idOf(state.round) !== state.selectedId ||
+      !state.round.targets?.some((target) => target.key === state.targetKey && target.comparison))) state.round = null;
+    changed();
+    try {
+      const collection = await request("");
+      if (current !== revision) return false;
+      state.rounds = collection.rounds || [];
+      if (!state.rounds.some((round) => idOf(round) === state.selectedId)) {
+        state.selectedId = idOf(defaultHistoryRound(state.rounds)) || null;
+      }
+      const selectedId = state.selectedId;
+      let round = null;
+      let targetKey = state.targetKey || targets.get(selectedId);
+      if (selectedId) {
+        const detail = await request(`/${selectedId}`);
+        if (current !== revision) return false;
+        round = detail.round || detail;
+        const summary = state.rounds.find((item) => idOf(item) === selectedId);
+        for (const target of round.targets || []) {
+          target.filename ||= summary?.targets?.find((item) => item.key === target.key)?.filename;
+        }
+        const target = round.targets?.find((item) => item.key === targetKey) || round.targets?.[0];
+        targetKey = target?.key || null;
+        if (target) {
+          const results = await Promise.allSettled(["content", "source"].map((mode) =>
+            request(`/${selectedId}/compare?key=${encodeURIComponent(target.key)}&mode=${mode}`)));
+          if (current !== revision) return false;
+          target.comparison = Object.fromEntries(["content", "source"].map((mode, index) =>
+            [mode, results[index].status === "fulfilled" ? results[index].value
+              : { available: false, counts: null, reason: results[index].reason.message }]));
+          if (results.every((result) => result.status === "rejected")) state.error = results[0].reason;
+        }
+      }
+      state.round = round;
+      state.targetKey = targetKey;
+      if (selectedId) targets.set(selectedId, targetKey);
+      state.loading = false;
+      changed();
+      refreshed();
+      return true;
+    } catch (error) {
+      if (current !== revision) return false;
+      state.error = error;
+      state.loading = false;
+      changed();
+      return false;
+    }
+  }
+  return {
+    state, refresh,
+    selectRound(id) {
+      state.selectedId = id;
+      state.targetKey = targets.get(id) || null;
+      state.index = 0;
+      return refresh();
+    },
+    selectTarget(key) { state.targetKey = key; state.index = 0; return refresh(); },
+    cancel() { revision++; state.loading = false; },
+  };
+}
+
+/** Optional capture cannot veto delivery; a failed refresh cannot masquerade as failed Send. */
+export async function deliverFeedback({ save, capture, deliver, committed, refresh }) {
+  await save();
+  let snapshot = null;
+  let captureFailure = null;
+  try { snapshot = await capture(); } catch (error) { captureFailure = error; }
+  await deliver(snapshot);
+  committed();
+  let refreshFailure = null;
+  try { if (await refresh() === false) refreshFailure = new Error("History could not be refreshed"); }
+  catch (error) { refreshFailure = error; }
+  return { captureFailure, refreshFailure };
+}

package/src/history-policy.js

@@ -0,0 +1,43 @@
+import { COMPLETED_ROUNDS_TO_KEEP, isRevisionId } from "./revision-schema.js";
+
+function references(value, out = new Set()) {
+  if (isRevisionId(value)) out.add(value);
+  else if (Array.isArray(value)) for (const item of value) references(item, out);
+  else if (value && typeof value === "object") for (const item of Object.values(value)) references(item, out);
+  return out;
+}
+
+export function unsentRevisionReferences(data) {
+  const out = new Set();
+  for (const page of Object.values(data.pages || {})) {
+    references(page.comments, out);
+    references(page.edits, out);
+    references(page.revisionRefs, out);
+  }
+  return out;
+}
+
+export function historyRevisionReferences(data) {
+  const out = unsentRevisionReferences(data);
+  references(data.histories, out);
+  references(data.batches, out);
+  return out;
+}
+
+export function retainHistory(data) {
+  const pinned = unsentRevisionReferences(data);
+  let changed = false;
+  for (const history of Object.values(data.histories || {})) {
+    const completed = history.rounds
+      .filter((round) => round.completedAt)
+      .sort((a, b) => b.completedAt - a.completedAt || b.ordinal - a.ordinal);
+    const keep = new Set(completed.slice(0, COMPLETED_ROUNDS_TO_KEEP).map((round) => round.roundId));
+    const rounds = history.rounds.filter((round) =>
+      !round.completedAt || keep.has(round.roundId) || [...references(round.targets)].some((id) => pinned.has(id)));
+    if (rounds.length !== history.rounds.length) {
+      history.rounds = rounds;
+      changed = true;
+    }
+  }
+  return changed;
+}

package/src/history-server.js

@@ -0,0 +1,463 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { stripSdk } from "./html-transform.js";
+import { isMarkdown } from "./markdown.js";
+import { compareSemanticSnapshots, compareSources, DIFF_VERSION } from "./revision-diff.js";
+import { REVISION_LIMITS } from "./revision-schema.js";
+import { normalizeView, compareCapturedViews } from "./view-identity.js";
+
+const SOURCE_LIMIT = REVISION_LIMITS.sourceBytes;
+const hash = (value) => crypto.createHash("sha1").update(value).digest("hex");
+
+export class HistoryRequestError extends Error {
+  constructor(message, { status = 400, code = "history_invalid_request", targets = [] } = {}) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.targets = targets;
+  }
+}
+
+export function historyErrorStatus(error) {
+  if (Number.isInteger(error.status) && error.status >= 400 && error.status < 600) return error.status;
+  return {
+    INVALID_REVISION: 400, SNAPSHOT_TOO_LARGE: 413, CAPTURE_CONFLICT: 409, CAPTURE_FINALIZED: 409,
+  }[error.code] ?? 500;
+}
+
+function sourceFor(page) {
+  if (!page) {
+    throw new HistoryRequestError("The reviewed target is no longer available.", {
+      status: 409, code: "history_target_unavailable",
+    });
+  }
+  if (page.kind === "url") return null;
+  let stat;
+  let content;
+  try {
+    stat = fs.statSync(page.file);
+    if (stat.size <= SOURCE_LIMIT) content = stripSdk(fs.readFileSync(page.file, "utf8"));
+  } catch (error) {
+    if (!["ENOENT", "EACCES", "EPERM"].includes(error.code)) throw error;
+    throw new HistoryRequestError("The reviewed source is missing or cannot be read.", {
+      status: 409, code: "history_source_unavailable",
+    });
+  }
+  if (stat.size > SOURCE_LIMIT) {
+    throw new HistoryRequestError(`The source exceeds the ${SOURCE_LIMIT / (1024 * 1024)} MiB history capture limit.`, {
+      status: 413, code: "history_source_too_large",
+    });
+  }
+  if (Buffer.byteLength(content) > SOURCE_LIMIT) {
+    throw new HistoryRequestError(`The source exceeds the ${SOURCE_LIMIT / (1024 * 1024)} MiB history capture limit.`, {
+      status: 413, code: "history_source_too_large",
+    });
+  }
+  return {
+    content,
+    hash: hash(content),
+    mediaType: isMarkdown(page.file) ? "text/markdown" : "text/html",
+  };
+}
+
+export function createHistoryController({
+  store, sessions, currentRender, readBody, json, emit, pageState,
+}) {
+  const cache = new Map();
+  let cachedBytes = 0;
+
+  const revision = (id) => id ? store.revisions.get(id) : null;
+  const saveRevision = (value) => {
+    const provenance = {
+      pageKey: value.documentId,
+      ...(value.provenance.sessionId ? { sessionId: value.provenance.sessionId } : {}),
+      ...(value.provenance.renderGeneration !== undefined ? { generation: value.provenance.renderGeneration } : {}),
+      ...(value.source?.hash ? { sourceHash: value.source.hash } : {}),
+      ...(value.provenance.captureId ? { captureId: value.provenance.captureId } : {}),
+      feedbackOnlyEdits: value.provenance.feedbackOnly === true,
+      trustedInteractive: value.provenance.trustedInteractive === true,
+    };
+    return store.revisions.put({
+      documentId: value.documentId,
+      reason: value.provenance.captureReason,
+      limitations: value.limitations || [],
+      ...(value.source ? {
+        source: {
+          text: value.source.content, mediaType: value.source.mediaType,
+          capturedAt: value.capturedAt, provenance,
+        },
+      } : {}),
+      ...(value.semantic ? {
+        semantic: { snapshot: value.semantic, capturedAt: value.semanticCapturedAt ?? value.capturedAt, provenance, view: value.view },
+      } : {}),
+    });
+  };
+  const roundFor = (session, roundId) => store.getRound(session.entryKey, roundId);
+
+  function changed(entryKey, roundId) {
+    for (const session of sessions.values()) {
+      if (session.entryKey === entryKey) emit(session, "history", { roundId });
+    }
+  }
+
+  function currentFrame(session, input, key) {
+    const render = typeof input.renderId === "string" ? currentRender(input.renderId) : null;
+    if (
+      !render || render.sessionId !== session.id || render.pageKey !== key ||
+      render.generation !== input.generation || render.documentState !== "served" ||
+      session.activeKey !== key
+    ) {
+      throw new HistoryRequestError("The page changed or its current frame is unavailable. Recapture it.", {
+        status: 409, code: "history_frame_changed",
+      });
+    }
+    return render;
+  }
+
+  function checkedSource(page, render, expectedHash) {
+    const source = sourceFor(page);
+    if (source && (
+      typeof expectedHash !== "string" ||
+      source.hash !== expectedHash ||
+      render.sourceHash !== expectedHash
+    )) {
+      throw new HistoryRequestError("The source changed since this version was reviewed. Reload and recapture it.", {
+        status: 409, code: "history_source_changed",
+      });
+    }
+    return source;
+  }
+
+  function snapshot(session, key, input, reason) {
+    const page = store.page(key);
+    const render = currentFrame(session, input, key);
+    if (!input.semantic || typeof input.semantic !== "object" || Array.isArray(input.semantic)) {
+      throw new HistoryRequestError("The current page did not provide a content snapshot.", {
+        status: 409, code: "history_semantic_unavailable",
+      });
+    }
+    if (input.semanticCapturedAt !== undefined && (
+      !Number.isSafeInteger(input.semanticCapturedAt) ||
+      input.semanticCapturedAt < render.createdAt || input.semanticCapturedAt > Date.now() + 5000
+    )) {
+      throw new HistoryRequestError("The content capture timestamp does not belong to this rendered version.");
+    }
+    const source = checkedSource(page, render, input.expectedSourceHash);
+    return {
+      documentId: key,
+      capturedAt: Date.now(),
+      semanticCapturedAt: input.semanticCapturedAt,
+      source,
+      semantic: input.semantic,
+      view: normalizeView(input.view),
+      provenance: {
+        sessionId: session.id,
+        renderGeneration: render.generation,
+        renderId: render.renderId,
+        pageKey: key,
+        sourceHashAtRender: render.sourceHash ?? null,
+        captureReason: reason,
+        feedbackOnly: page.kind === "url" || isMarkdown(page.file) || render.feedbackOnly === true,
+        trustedInteractive: render.trustedInteractive === true,
+      },
+    };
+  }
+
+  function prepareBaseline(session, pages, input) {
+    if (input === undefined) return null;
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      throw new HistoryRequestError("Invalid history submission.");
+    }
+    if (input.allowUnavailable !== undefined && typeof input.allowUnavailable !== "boolean") {
+      throw new HistoryRequestError("Invalid missing-comparison choice.");
+    }
+    const keys = pages.length ? pages.map((page) => page.key) : [session.entryKey];
+    const pending = [];
+    const unavailable = [];
+    for (const key of keys) {
+      const page = store.page(key);
+      let value = null;
+      let reason = null;
+      try {
+        value = snapshot(session, key, input, "send");
+      } catch (error) {
+        if (!(error instanceof HistoryRequestError) && !["ENOENT", "EACCES", "EPERM"].includes(error.code)) throw error;
+        reason = error.message;
+        unavailable.push({ key, filename: pageState(key)?.filename || key, reason });
+        if (input.allowUnavailable) {
+          try {
+            const source = sourceFor(page);
+            if (source) {
+              value = {
+                documentId: key, capturedAt: Date.now(), source, semantic: null,
+                provenance: { captureReason: "send-source-only", pageKey: key },
+                limitations: ["semantic_before_unavailable"],
+              };
+            }
+          } catch (sourceError) {
+            if (!(sourceError instanceof HistoryRequestError) && !["ENOENT", "EACCES", "EPERM"].includes(sourceError.code)) {
+              throw sourceError;
+            }
+            reason = sourceError.message;
+          }
+        }
+      }
+      pending.push({ key, value, reason });
+    }
+    if (unavailable.length && !input.allowUnavailable) {
+      throw new HistoryRequestError("Some pages need to be recaptured before their comparison can be saved.", {
+        status: 409, code: "history_baseline_unavailable", targets: unavailable,
+      });
+    }
+    const targets = pending.map(({ key, value, reason }) => ({
+      key,
+      ...(value ? { baselineRevisionId: saveRevision(value).revisionId } : {
+        baselineUnavailable: reason || "The before snapshot is unavailable.",
+      }),
+      ownerSessionId: session.id,
+    }));
+    return { targets, unavailable };
+  }
+
+  function presentRound(round) {
+    return {
+      ...round,
+      sentAt: round.sentAt ?? round.createdAt,
+      targets: round.targets.map((target) => ({
+        ...target,
+        captureStatus: target.capture?.status || (target.resultRevisionId ? "ready" : "pending"),
+        filename: pageState(target.key)?.filename || target.key,
+        kind: store.page(target.key)?.kind === "url" ? "url" : "file",
+      })),
+    };
+  }
+
+  function list(session) {
+    return {
+      activeKey: session.activeKey,
+      rounds: store.listHistory(session.entryKey).map(presentRound),
+    };
+  }
+
+  function captureSources(entryKey, roundId) {
+    const rounds = roundId ? [store.getRound(entryKey, roundId)] : store.listHistory(entryKey);
+    for (const round of rounds) {
+      if (round?.feedbackStatus !== "acknowledged" || round.completedAt) continue;
+      for (const target of round.targets) {
+        if (
+          target.sourceResultRevisionId || target.resultRevisionId ||
+          target.capture?.status === "unavailable" || store.page(target.key)?.kind === "url"
+        ) continue;
+        try {
+          const saved = saveRevision({
+            documentId: target.key, capturedAt: Date.now(),
+            source: sourceFor(store.page(target.key)),
+            provenance: { captureReason: "acknowledged-source-result" },
+          });
+          store.recordSourceResult(entryKey, round.roundId, target.key, { revisionId: saved.revisionId });
+          console.info("[doc-review]", { event: "history-source-captured", roundId: round.roundId, key: target.key });
+        } catch (error) {
+          try {
+            store.recordSourceResult(entryKey, round.roundId, target.key, { unavailable: String(error.message).slice(0, 500) });
+          } catch (persistenceError) {
+            console.error("[doc-review]", { event: "history-source-failure-not-persisted", code: persistenceError.code || "history_storage_failed" });
+          }
+          console.error("[doc-review]", { event: "history-source-unavailable", roundId: round.roundId, key: target.key, code: error.code || "history_storage_failed" });
+        }
+      }
+    }
+  }
+
+  function comparison(round, key, mode) {
+    if (!["content", "source"].includes(mode)) throw new HistoryRequestError("Unknown comparison mode.");
+    const target = round.targets.find((item) => item.key === key);
+    if (!target) throw new HistoryRequestError("This target does not belong to the selected round.", { status: 404 });
+    const before = revision(target.baselineRevisionId);
+    const after = revision(mode === "source" ? target.sourceResultRevisionId || target.resultRevisionId : target.resultRevisionId);
+    const representation = mode === "content" ? "semantic" : "source";
+    if (!before?.[representation] || !after?.[representation]) {
+      return {
+        available: false,
+        mode,
+        reason: !before?.[representation]
+          ? target.baselineUnavailable || `The before ${mode} snapshot is unavailable.`
+          : (mode === "source" ? target.sourceResultUnavailable : target.resultUnavailable) || `The result ${mode} snapshot has not been captured.`,
+        changes: [],
+        limitations: [mode === "source" ? "source_unavailable" : "semantic_unavailable"],
+      };
+    }
+    const cacheKey = `${DIFF_VERSION}:${before.revisionId}:${after.revisionId}:${mode}`;
+    if (cache.has(cacheKey)) return cache.get(cacheKey).value;
+    const started = performance.now();
+    const differences = mode === "source"
+      ? compareSources(store.revisions.readSource(before.revisionId), store.revisions.readSource(after.revisionId))
+      : compareSemanticSnapshots(store.revisions.readSemantic(before.revisionId), store.revisions.readSemantic(after.revisionId));
+    const result = {
+      ...differences,
+      available: differences.status === "complete",
+      ...(differences.status !== "complete" ? {
+        reason: differences.status === "limited"
+          ? "This comparison exceeds its processing limits. Its contents have not been partially displayed."
+          : "The captured content cannot be compared.",
+      } : {}),
+      mode,
+      baselineRevisionId: before.revisionId,
+      resultRevisionId: after.revisionId,
+      beforeCapturedAt: before[representation].capturedAt,
+      afterCapturedAt: after[representation].capturedAt,
+      sourceHash: after.source?.provenance.sourceHash ?? null,
+      capturedSessionId: after.semantic?.provenance.sessionId ?? null,
+      capturedGeneration: after.semantic?.provenance.generation ?? null,
+      ...(mode === "content" ? { viewComparison: compareCapturedViews(before.semantic?.view, after.semantic?.view) } : {}),
+    };
+    const bytes = Buffer.byteLength(JSON.stringify(result));
+    while (cache.size && (cache.size >= 16 || cachedBytes + bytes > 8 * 1024 * 1024)) {
+      const oldest = cache.keys().next().value;
+      cachedBytes -= cache.get(oldest).bytes;
+      cache.delete(oldest);
+    }
+    if (bytes <= 8 * 1024 * 1024) {
+      cache.set(cacheKey, { value: result, bytes });
+      cachedBytes += bytes;
+    }
+    console.info("[doc-review]", {
+      event: "history-compared", roundId: round.roundId, key, mode,
+      durationMs: Math.round(performance.now() - started), changes: result.changes.length,
+    });
+    return result;
+  }
+
+  async function handle(req, res, url) {
+    const match = url.pathname.match(/^\/api\/session\/(\w+)\/history(?:\/([\w-]+))?(?:\/(compare|capture))?$/);
+    if (!match) return false;
+    const session = sessions.get(match[1]);
+    if (!session) {
+      json(res, 404, { error: "unknown session" });
+      return true;
+    }
+    try {
+      if (!match[2] && req.method === "GET") {
+        json(res, 200, list(session));
+        return true;
+      }
+      let round = roundFor(session, match[2]);
+      if (!round) throw new HistoryRequestError("Unknown round in this review history.", { status: 404 });
+      if (!match[3] && req.method === "GET") {
+        json(res, 200, { round: presentRound(round) });
+        return true;
+      }
+      if (match[3] === "compare" && req.method === "GET") {
+        json(res, 200, comparison(round, url.searchParams.get("key") || session.activeKey, url.searchParams.get("mode") || "content"));
+        return true;
+      }
+      if (match[3] === "capture" && req.method === "POST") {
+        const body = await readBody(req);
+        if (!body || typeof body !== "object" || Array.isArray(body)) {
+          throw new HistoryRequestError("Invalid capture request.");
+        }
+        round = roundFor(session, match[2]);
+        if (!round) throw new HistoryRequestError("Unknown round in this review history.", { status: 404 });
+        const key = typeof body.key === "string" ? body.key : session.activeKey;
+        const target = round.targets.find((item) => item.key === key);
+        if (!target) throw new HistoryRequestError("This target does not belong to the selected round.", { status: 404 });
+        if (round.feedbackStatus !== "acknowledged") {
+          throw new HistoryRequestError("The round has not been acknowledged.", { status: 409 });
+        }
+        if (target.resultRevisionId) {
+          json(res, 200, { ok: true, alreadyCaptured: true, round: presentRound(round) });
+          return true;
+        }
+        if (body.manual !== undefined && typeof body.manual !== "boolean") {
+          throw new HistoryRequestError("Invalid manual capture choice.");
+        }
+        if (body.finalUnavailable !== undefined && body.finalUnavailable !== true) {
+          throw new HistoryRequestError("Invalid final capture choice.");
+        }
+        if (body.finalUnavailable === true) {
+          if (body.manual !== true) throw new HistoryRequestError("Finishing without content capture must be an explicit choice.");
+          if (target.capture?.status === "unavailable") {
+            json(res, 200, { ok: true, alreadyFinalized: true, round: presentRound(round) });
+            return true;
+          }
+          captureSources(session.entryKey, round.roundId);
+          const claimed = store.claimCapture(session.entryKey, round.roundId, key, {
+            ownerSessionId: session.id, generation: 0,
+          });
+          const updated = store.markCaptureUnavailable(session.entryKey, round.roundId, key, {
+            captureId: claimed.captureId, ownerSessionId: session.id, generation: 0,
+            reason: "Content capture was explicitly finished with the available snapshots.", final: true,
+          });
+          changed(session.entryKey, round.roundId);
+          json(res, 200, { ok: true, round: presentRound(updated.round) });
+          return true;
+        }
+        const baseline = revision(target.baselineRevisionId);
+        const owner = target.ownerSessionId || baseline?.semantic?.provenance.sessionId;
+        if (owner && owner !== session.id && body.manual !== true) {
+          throw new HistoryRequestError("The review window that sent this round owns automatic capture. Use Capture result to capture here.", {
+            status: 409, code: "history_capture_owner",
+          });
+        }
+        const render = currentFrame(session, body, key);
+        if (!target.sourceResultRevisionId) captureSources(session.entryKey, round.roundId);
+        const claimed = store.claimCapture(session.entryKey, round.roundId, key, {
+          ownerSessionId: session.id, generation: render.generation,
+        });
+        const ownership = {
+          captureId: claimed.captureId, ownerSessionId: session.id, generation: render.generation,
+        };
+        let updated;
+        let saved;
+        try {
+          if (typeof body.error === "string" && body.error.trim()) {
+            if (body.error.length > 500) throw new HistoryRequestError("Capture failure reason is too long.");
+            updated = store.markCaptureUnavailable(session.entryKey, round.roundId, key, {
+              ...ownership, reason: body.error, final: false,
+            });
+          } else {
+            const value = snapshot(session, key, body, body.manual === true ? "manual-result" : "automatic-result");
+            const viewComparison = compareCapturedViews(baseline?.semantic?.view, value.view);
+            if (viewComparison.status === "mismatch") {
+              throw new HistoryRequestError(viewComparison.message, { status: 409, code: "history_view_mismatch" });
+            }
+            value.provenance.captureId = claimed.captureId;
+            saved = saveRevision(value);
+            updated = store.recordCaptureResult(session.entryKey, round.roundId, key, {
+              ...ownership, revisionId: saved.revisionId,
+            });
+          }
+        } catch (error) {
+          try {
+            store.markCaptureUnavailable(session.entryKey, round.roundId, key, {
+              ...ownership, reason: String(error.message).slice(0, 500), final: false,
+            });
+            changed(session.entryKey, round.roundId);
+          } catch (persistenceError) {
+            console.error("[doc-review]", { event: "history-failure-not-persisted", code: persistenceError.code || "history_failed" });
+          }
+          throw error;
+        }
+        changed(session.entryKey, round.roundId);
+        console.info("[doc-review]", {
+          event: saved ? "history-captured" : "history-capture-unavailable",
+          roundId: round.roundId, key, ...(saved ? { revisionId: saved.revisionId } : {}),
+        });
+        json(res, 200, { ok: !!saved, round: presentRound(updated.round) });
+        return true;
+      }
+      json(res, 405, { error: "method not allowed" });
+    } catch (error) {
+      const status = historyErrorStatus(error);
+      console.error("[doc-review]", { event: "history-failed", status, code: error.code || "history_failed" });
+      json(res, status, {
+        error: error.message,
+        code: error.code || "history_failed",
+        ...(error.targets?.length ? { targets: error.targets } : {}),
+      });
+    }
+    return true;
+  }
+
+  return { prepareBaseline, captureSources, list, handle, changed };
+}