@erdemtuna/doc-review 0.8.0 → 0.9.0

package/src/setup-guidance.js

@@ -0,0 +1,128 @@
+export const GUIDANCE_BEGIN = "<!-- BEGIN doc-review -->";
+export const GUIDANCE_END = "<!-- END doc-review -->";
+
+// Historical generated text is deliberately independent of the current guidance.
+const LEGACY_TAIL = `
+\`npx -y @erdemtuna/doc-review <file.html>\`. For a locally running web page, open the real
+route with \`npx -y @erdemtuna/doc-review http://localhost:3000/path\` instead of recreating
+it as a static file. Then block on
+\`npx -y @erdemtuna/doc-review poll <target> --timeout 600\` until they send feedback.
+If it prints \`{"status":"timeout"}\`, no feedback arrived yet — run the same
+poll command again to keep waiting. When a \`{"status":"feedback"}\` batch
+arrives, apply it, then run the exact acknowledgement command in its
+\`next_step\`, which uses \`--ack <batch_id>\`.
+
+Keep the poll command in the foreground and do not end the turn while it waits.
+If the shell returns a process or session handle, keep waiting on that handle until
+the command exits. \`npx -y @erdemtuna/doc-review status <target>\` reports instantly
+whether feedback is already waiting, without blocking.
+
+The batch groups feedback by page under \`pages\`, so fix every page listed. Items
+under \`edits\` are changes the user already made: \`after\` is their exact wording,
+so carry it across verbatim and never revert it — and if the HTML was generated
+from MDX or Markdown, apply it to the source too. Markdown files open rendered
+and are never written by doc-review: apply their comments and edits to the
+Markdown source, keeping its syntax. There is no reply channel; the user sees
+your work when the page reloads. For a localhost page, direct edits and deletions
+arrive with \`kind: "url"\`; find and update the matching MDX, TSX, template, or
+component source. Never write the rendered HTTP response over project source.`;
+
+export const LEGACY_GUIDANCE = Object.freeze([
+  `## Reviewing files and localhost pages with doc-review
+
+After writing an HTML or Markdown file the user will read, open it for them with${LEGACY_TAIL}`,
+  `## Reviewing files and localhost pages with doc-review
+
+Start only when the user explicitly invokes /doc-review or requests an
+interactive browser review. Writing, updating, discussing, or generically reviewing
+content does not authorize opening a review or polling. Another skill's automatic
+review step is not user permission. Otherwise respond normally.
+
+After that explicit request, open the requested HTML or Markdown file with${LEGACY_TAIL}`,
+]);
+
+const migrationMessage = "AGENTS.md contains custom or unrecognized doc-review guidance — left it unchanged. " +
+  "Manually reconcile that guidance, then wrap only the setup-owned section in " +
+  `${GUIDANCE_BEGIN} and ${GUIDANCE_END}, or remove it and re-run setup.`;
+
+function invalidMarkers() {
+  throw new Error("AGENTS.md has malformed, duplicate, or ambiguous doc-review ownership markers. " +
+    "Keep exactly one standalone BEGIN/END pair in order, then re-run setup. No setup files were changed.");
+}
+
+function render(body, newline) {
+  return `${GUIDANCE_BEGIN}\n${body.trim()}\n${GUIDANCE_END}`.replaceAll("\n", newline);
+}
+
+/** Plan the complete edit before setup writes any files. Never normalize user text. */
+export function updateGuidance(existing, body) {
+  const lines = [...existing.matchAll(/[^\n]*(?:\n|$)/g)]
+    .filter((match) => match[0])
+    .map((match) => ({
+      text: match[0].replace(/\r?\n$/, ""),
+      start: match.index,
+      end: match.index + match[0].replace(/\r?\n$/, "").length,
+    }));
+  const markers = lines.filter(({ text }) => /doc-review/i.test(text) &&
+    (/\b(?:BEGIN|END)\b/i.test(text) && /<!--|-->|^\s*(?:BEGIN|END)\b/i.test(text)));
+
+  if (markers.length) {
+    if (markers.length !== 2 || markers[0].text !== GUIDANCE_BEGIN || markers[1].text !== GUIDANCE_END) {
+      invalidMarkers();
+    }
+    const [begin, end] = markers;
+    const newline = existing.slice(begin.end).startsWith("\r\n") ? "\r\n" : "\n";
+    return {
+      contents: existing.slice(0, begin.start) + render(body, newline) + existing.slice(end.end),
+      message: "Updated setup-owned AGENTS.md guidance   (Codex)",
+    };
+  }
+
+  const candidates = [];
+  for (const legacy of LEGACY_GUIDANCE) {
+    for (const command of ["npx -y @erdemtuna/doc-review", "doc-review"]) {
+      for (const newline of ["\n", "\r\n"]) {
+        const text = legacy.replaceAll("npx -y @erdemtuna/doc-review", command).replaceAll("\n", newline);
+        let start = existing.indexOf(text);
+        while (start !== -1) {
+          const end = start + text.length;
+          const before = existing.slice(0, start);
+          const after = existing.slice(end);
+          // A complete generated section, not a substring of customized prose.
+          if ((start === 0 || before.endsWith("\n") || before === "\uFEFF") &&
+              /^(?:\r?\n|$)/.test(after) &&
+              /^(?:\s*$|(?:\r?\n)+(?=#{1,2} ))/.test(after)) {
+            candidates.push({ start, end, newline });
+          }
+          start = existing.indexOf(text, start + text.length);
+        }
+      }
+    }
+  }
+  if (candidates.length > 1) {
+    throw new Error("AGENTS.md contains multiple legacy doc-review sections; ownership is ambiguous. " +
+      "Reconcile them before re-running setup. No setup files were changed.");
+  }
+  if (candidates.length === 1) {
+    const { start, end, newline } = candidates[0];
+    const surrounding = existing.slice(0, start) + existing.slice(end);
+    if (!/doc-review/i.test(surrounding)) {
+      return {
+        contents: existing.slice(0, start) + render(body, newline) + existing.slice(end),
+        message: "Migrated legacy AGENTS.md guidance to setup-owned markers   (Codex)",
+      };
+    }
+  }
+  if (/doc-review/i.test(existing)) {
+    return { contents: existing, message: migrationMessage };
+  }
+
+  const newline = existing.includes("\r\n") ? "\r\n" : "\n";
+  const separator = !existing || existing.endsWith(newline + newline)
+    ? ""
+    : existing.endsWith("\n") ? newline : newline + newline;
+  return {
+    contents: existing + separator + render(body, newline) + newline,
+    message: `${existing ? "Updated" : "Created"} AGENTS.md   (Codex)`,
+  };
+}

package/src/setup.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { updateGuidance } from "./setup-guidance.js";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_NAME = "@erdemtuna/doc-review";
@@ -50,15 +51,26 @@ export const skillFor = (cmd) => readSkill().replaceAll(NPX_COMMAND, cmd);
 const CODEX_BLOCK = `
 ## Reviewing files and localhost pages with doc-review
 
-After writing an HTML or Markdown file the user will read, open it for them with
+Start only when the user explicitly invokes /doc-review or requests an
+interactive browser review. Writing, updating, discussing, or generically reviewing
+content does not authorize opening a review or polling. Another skill's automatic
+review step is not user permission. Otherwise respond normally.
+
+After that explicit request, open the requested HTML or Markdown file with
 \`${NPX_COMMAND} <file.html>\`. For a locally running web page, open the real
 route with \`${NPX_COMMAND} http://localhost:3000/path\` instead of recreating
 it as a static file. Then block on
 \`${NPX_COMMAND} poll <target> --timeout 600\` until they send feedback.
 If it prints \`{"status":"timeout"}\`, no feedback arrived yet — run the same
 poll command again to keep waiting. When a \`{"status":"feedback"}\` batch
-arrives, apply it, then run the exact acknowledgement command in its
-\`next_step\`, which uses \`--ack <batch_id>\`.
+arrives, handle every item, then run the exact acknowledgement command in its
+\`next_step\`, which uses \`--ack <batch_id>\`. Keep that exact batch ID on retries;
+never acknowledge an unhandled batch.
+
+Without \`--timeout\`, the CLI defaults to a 12-hour cutoff. An explicit
+\`--timeout\` is one end-to-end deadline, including server discovery and reconnect
+attempts. Keep using the bounded foreground \`--timeout 600\` loop above;
+those polls do not wait 12 hours.
 
 Keep the poll command in the foreground and do not end the turn while it waits.
 If the shell returns a process or session handle, keep waiting on that handle until
@@ -66,9 +78,19 @@ the command exits. \`${NPX_COMMAND} status <target>\` reports instantly
 whether feedback is already waiting, without blocking.
 
 The batch groups feedback by page under \`pages\`, so fix every page listed. Items
-under \`edits\` are changes the user already made: \`after\` is their exact wording,
-so carry it across verbatim and never revert it — and if the HTML was generated
-from MDX or Markdown, apply it to the source too. Markdown files open rendered
+under \`edits\` are changes the user already made. For non-truncated edits,
+\`after\` is their exact wording: carry it across verbatim and never revert it.
+If the HTML was generated from MDX or Markdown, apply complete edits to the
+source too.
+
+Edit fields are limited to 200,000 Unicode code points each. An edit with
+\`truncated: true\` identifies clipped fields in the \`truncated_fields\` array.
+Never apply incomplete text or HTML as a complete replacement or invent missing
+text. Recover the full edit only from an authoritative source; otherwise ask the
+user for the complete edit. Do not acknowledge the batch until every item,
+including truncated edits, has been handled.
+
+Markdown files open rendered
 and are never written by doc-review: apply their comments and edits to the
 Markdown source, keeping its syntax. There is no reply channel; the user sees
 your work when the page reloads. For a localhost page, direct edits and deletions
@@ -79,6 +101,17 @@ component source. Never write the rendered HTTP response over project source.
 export function installSkills(cwd, { global: isGlobal = false, home = os.homedir(), command } = {}) {
   const done = [];
   const cmd = command || invocation();
+  const agents = path.join(cwd, "AGENTS.md");
+  let guidance;
+  let existing;
+  if (!isGlobal) {
+    const bytes = fs.existsSync(agents) ? fs.readFileSync(agents) : Buffer.alloc(0);
+    existing = bytes.toString("utf8");
+    if (!Buffer.from(existing, "utf8").equals(bytes)) {
+      throw new Error("AGENTS.md is not valid UTF-8; convert it before re-running setup. No setup files were changed.");
+    }
+    guidance = updateGuidance(existing, CODEX_BLOCK.replaceAll(NPX_COMMAND, cmd));
+  }
 
   const skillRoots = isGlobal
     ? [
@@ -96,15 +129,8 @@ export function installSkills(cwd, { global: isGlobal = false, home = os.homedir
   }
 
   if (!isGlobal) {
-    const agents = path.join(cwd, "AGENTS.md");
-    const existing = fs.existsSync(agents) ? fs.readFileSync(agents, "utf8") : "";
-    if (existing.includes("doc-review")) {
-      done.push("AGENTS.md already mentions doc-review — left it alone");
-    } else {
-      const block = CODEX_BLOCK.replaceAll(NPX_COMMAND, cmd);
-      fs.writeFileSync(agents, existing ? `${existing.trimEnd()}\n${block}` : block.trimStart());
-      done.push(`${existing ? "Updated" : "Created"} AGENTS.md   (Codex)`);
-    }
+    if (guidance.contents !== existing) fs.writeFileSync(agents, guidance.contents);
+    done.push(guidance.message);
   }
 
   done.push("", `Agents will be told to run: ${cmd}`);

package/src/state.js

@@ -3,6 +3,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { normalizeCommentAnchor } from "./comment-anchor.js";
 import { canonicalTarget, ensureStateDir, pageKey, realFile, statePath, targetKey } from "./paths.js";
+export { atomicWrite } from "./atomic-write.js";
+import { atomicWrite } from "./atomic-write.js";
+import { RevisionStore } from "./revision-store.js";
+import { CAPTURE_LEASE_MS, HISTORY_SCHEMA_VERSION, normalizeHistoryTargets, revisionError } from "./revision-schema.js";
+import { historyRevisionReferences, retainHistory } from "./history-policy.js";
 
 /** Anything untouched this long is review debris, not work in progress. */
 const PRUNE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
@@ -10,11 +15,50 @@ const DELIVERY_STATES = new Set(["queued", "possibly_delivered", "delivered"]);
 
 const fresh = (entry, now) => !!entry && now - (entry.updatedAt || 0) < PRUNE_AGE_MS;
 const batchId = () => `b_${crypto.randomBytes(12).toString("hex")}`;
-const emptyState = () => ({ pages: {}, batches: {}, receipts: {} });
+const emptyState = () => ({ pages: {}, batches: {}, receipts: {}, histories: {} });
+const historyId = (prefix) => `${prefix}_${crypto.randomBytes(12).toString("hex")}`;
+
+function historyRound(data, entryKey, roundId) {
+  return data.histories[entryKey]?.rounds.find((round) => round.roundId === roundId) || null;
+}
+
+function batchRound(data, entryKey, id) {
+  return data.histories[entryKey]?.rounds.find((round) => round.batchId === id) || null;
+}
+
+function publicRound(round) {
+  if (!round) return null;
+  const copy = structuredClone(round);
+  copy.sentAt ||= new Date(copy.createdAt).toISOString();
+  for (const target of copy.targets) {
+    target.captureStatus = target.capture?.status || "pending";
+    target.ownerSessionId = target.capture?.ownerSessionId || target.ownerSessionId || null;
+  }
+  return copy;
+}
+
+function finishCapture(round) {
+  const statuses = round.targets.map((target) => target.capture?.status || "pending");
+  if (statuses.every((status) => status === "ready" || status === "unavailable")) {
+    const fullContent = round.targets.every((target) => target.capture.status === "ready" &&
+      target.baselineCoverage?.semantic && target.resultCoverage?.semantic);
+    const anyResult = statuses.some((status) => status === "ready") ||
+      round.targets.some((target) => target.sourceResultRevisionId);
+    round.captureStatus = fullContent ? "ready" : anyResult ? "partial" : "failed";
+    round.completedAt ||= Date.now();
+  } else {
+    round.captureStatus = statuses.some((status) => status === "failed") ? "failed" : "pending";
+  }
+}
 
 function pruneData(data, now = Date.now()) {
-  let changed = false;
+  let changed = retainHistory(data);
   for (const [key, page] of Object.entries(data.pages)) {
+    const protectedPage = page.comments?.length || page.edits?.length || page.revisionRefs?.length ||
+      data.batches[key] || Object.values(data.batches).some((record) => record.cleanup.some((item) => item.key === key)) ||
+      Object.values(data.histories).some((history) => history.rounds.some((round) =>
+        round.targets.some((target) => target.key === key)));
+    if (protectedPage) continue;
     const missingFile = page.kind !== "url" && !fs.existsSync(page.file);
     if (!fresh(page, now) || missingFile) {
       delete data.pages[key];
@@ -22,13 +66,8 @@ function pruneData(data, now = Date.now()) {
       changed = true;
     }
   }
-  for (const [key, batch] of Object.entries(data.batches)) {
-    if (!fresh(batch, now)) {
-      delete data.batches[key];
-      changed = true;
-    }
-  }
   for (const [id, receipt] of Object.entries(data.receipts)) {
+    if (Object.values(data.histories).some((history) => history.rounds.some((round) => round.batchId === id))) continue;
     if (!fresh(receipt, now)) {
       delete data.receipts[id];
       changed = true;
@@ -45,8 +84,25 @@ function normalizeState(parsed, makeBatchId) {
     pages: parsed.pages,
     batches: parsed.batches && typeof parsed.batches === "object" ? parsed.batches : {},
     receipts: parsed.receipts && typeof parsed.receipts === "object" ? parsed.receipts : {},
+    histories: parsed.histories && typeof parsed.histories === "object" ? parsed.histories : {},
   };
   let changed = !parsed.batches || !parsed.receipts;
+  for (const history of Object.values(data.histories)) {
+    if (history?.version !== HISTORY_SCHEMA_VERSION || !Array.isArray(history.rounds) ||
+        !Number.isSafeInteger(history.nextOrdinal)) throw new Error("Invalid doc-review history.");
+    for (const round of history.rounds) {
+      if (!round?.roundId || !round.batchId || !Array.isArray(round.targets)) throw new Error("Invalid doc-review round.");
+      for (const target of round.targets) {
+        if (target.capture?.status === "running") {
+          target.capture = {
+            ...target.capture, captureId: historyId("cap"), status: "pending",
+            ownerSessionId: null, generation: null, leaseExpiresAt: 0, error: "context_lost",
+          };
+          changed = true;
+        }
+      }
+    }
+  }
   const normalizeAnchor = (comment) => {
     if (!comment || comment.anchor == null) return;
     const normalized = normalizeCommentAnchor(comment.kind === "element" ? "element" : "selection", comment.anchor);
@@ -92,24 +148,6 @@ function normalizeState(parsed, makeBatchId) {
   return { data, changed };
 }
 
-/**
- * Atomic write via a unique sibling tmp file. The name is unguessable and the
- * create is exclusive, so a pre-planted symlink can never redirect the write,
- * and a failed rename never leaves a predictable orphan behind.
- */
-export function atomicWrite(file, data) {
-  const tmp = `${file}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.doc-review.tmp`;
-  fs.writeFileSync(tmp, data, { flag: "wx" });
-  try {
-    fs.renameSync(tmp, file);
-  } catch (err) {
-    try {
-      fs.unlinkSync(tmp);
-    } catch {}
-    throw err;
-  }
-}
-
 /**
  * All durable state lives in one JSON file. No database, no network.
  *
@@ -125,10 +163,11 @@ export function atomicWrite(file, data) {
  * means "your feedback is safe" stays true across server restarts.
  */
 export class Store {
-  constructor({ write = atomicWrite, makeBatchId = batchId } = {}) {
+  constructor({ write = atomicWrite, makeBatchId = batchId, revisions = new RevisionStore() } = {}) {
     this.data = emptyState();
     this.write = write;
     this.makeBatchId = makeBatchId;
+    this.revisions = revisions;
     this.load();
   }
 
@@ -343,6 +382,19 @@ export class Store {
         if (afterHtml !== undefined) row.after_html = afterHtml;
         // A re-move of the same block replaces its landing spot.
         if (extra) {
+          if (Array.isArray(extra.truncated_fields)) {
+            const replaced = new Set([
+              ...(after !== undefined ? ["after"] : []),
+              ...(afterHtml !== undefined ? ["after_html"] : []),
+              ...["moved_after", "moved_before"].filter((field) => extra[field] !== undefined),
+            ]);
+            // Original before text is retained across edits, including its truncation.
+            const truncatedFields = [...new Set([
+              ...(row.truncated_fields || []).filter((field) => !replaced.has(field)),
+              ...extra.truncated_fields.filter((field) => replaced.has(field)),
+            ])];
+            extra = { ...extra, truncated: truncatedFields.length > 0, truncated_fields: truncatedFields };
+          }
           if (extra.staged_assets) {
             const assets = [...(row.staged_assets || []), ...extra.staged_assets];
             extra = { ...extra, staged_assets: [...new Map(assets.map((asset) => [asset.path, asset])).values()] };
@@ -363,10 +415,10 @@ export class Store {
   }
 
   /** After the agent writes, its version becomes the new revert target. */
-  setPristine(key, html) {
+  setPristine(key, html, { keepEdits = false } = {}) {
     return this.update(key, (page) => {
       page.pristine = html;
-      page.edits = [];
+      if (!keepEdits) page.edits = [];
     });
   }
 
@@ -395,27 +447,61 @@ export class Store {
     return this.data.batches;
   }
 
-  setBatch(entryKey, { batch, cleanup, deliveryState = "queued" }) {
+  setBatch(entryKey, { batch, cleanup, deliveryState = "queued", history } = {}, options = {}) {
+    const optionHistory = options.history || (options.targets ? options : undefined);
+    if (history && optionHistory) throw revisionError("Specify history context only once.");
+    history ||= optionHistory;
     if (!DELIVERY_STATES.has(deliveryState)) throw new Error(`Unknown delivery state: ${deliveryState}`);
+    const targets = history ? normalizeHistoryTargets(history.targets) : null;
+    for (const target of targets || []) {
+      if (!this.page(target.key)) throw revisionError("Unknown history document.");
+      if (target.baselineRevisionId) {
+        const manifest = this.revisions.verify(target.baselineRevisionId, target.key);
+        target.baselineCoverage = { source: !!manifest.source, semantic: !!manifest.semantic };
+      }
+    }
     return this.transaction((draft) => {
       const existing = draft.batches[entryKey];
+      const superseded = existing ? batchRound(draft, entryKey, existing.batch_id) : null;
+      if (superseded) {
+        superseded.feedbackStatus = "superseded";
+        superseded.supersededAt = Date.now();
+        superseded.captureStatus = "cancelled";
+      }
       if (existing && existing.delivery_state !== "queued") {
         draft.receipts[existing.batch_id] = {
           cleanup: existing.cleanup,
           delivery_state: existing.delivery_state,
+          batch: structuredClone(existing.batch),
           updatedAt: Date.now(),
         };
       }
       const id = batch.batch_id || this.makeBatchId();
-      const storedBatch = { ...batch, batch_id: id };
+      const storedBatch = { ...structuredClone(batch), batch_id: id };
       const record = {
         batch_id: id,
         batch: storedBatch,
-        cleanup,
+        cleanup: structuredClone(cleanup),
         delivery_state: deliveryState,
         updatedAt: Date.now(),
       };
       draft.batches[entryKey] = record;
+      if (targets) {
+        const historyState = draft.histories[entryKey] ||= {
+          version: HISTORY_SCHEMA_VERSION, entryKey, nextOrdinal: 1, rounds: [],
+        };
+        const round = {
+          roundId: historyId("round"), entryKey, ordinal: historyState.nextOrdinal++,
+          batchId: id, createdAt: Date.now(),
+          sentAt: new Date().toISOString(),
+          feedbackStatus: deliveryState === "delivered" ? "delivered" : "queued",
+          captureStatus: "pending",
+          targets: targets.map((target) => ({ ...target, resultRevisionId: null, capture: null })),
+        };
+        if (deliveryState === "delivered") round.deliveredFeedback = structuredClone(storedBatch);
+        historyState.rounds.push(round);
+        record.round_id = round.roundId;
+      }
       return record;
     });
   }
@@ -426,6 +512,12 @@ export class Store {
       const record = draft.batches[entryKey];
       record.delivery_state = "delivered";
       record.updatedAt = Date.now();
+      const round = batchRound(draft, entryKey, record.batch_id);
+      if (round) {
+        round.feedbackStatus = "delivered";
+        round.deliveredAt ||= Date.now();
+        round.deliveredFeedback ||= structuredClone(record.batch);
+      }
       return record;
     });
   }
@@ -445,13 +537,26 @@ export class Store {
       draft.receipts[id] = {
         cleanup: record.cleanup,
         delivery_state: "acknowledged",
+        batch: structuredClone(record.batch),
         updatedAt: Date.now(),
       };
+      const round = batchRound(draft, entryKey, id);
+      if (round) {
+        round.feedbackStatus = "acknowledged";
+        round.acknowledgedAt = Date.now();
+        round.deliveredFeedback ||= structuredClone(record.batch);
+        for (const target of round.targets) {
+          target.capture = {
+            captureId: historyId("cap"), status: "pending", ownerSessionId: null,
+            generation: null, attempt: 0, leaseExpiresAt: 0,
+          };
+        }
+      }
       const staged = [];
-      const keys = [];
+      const keys = round ? round.targets.map((target) => target.key) : [];
       for (const { key, ids, staged: assets = [], sentAt } of record.cleanup) {
         staged.push(...assets);
-        keys.push(key);
+        if (!keys.includes(key)) keys.push(key);
         const page = draft.pages[key];
         if (!page) continue;
         const drop = new Set(ids);
@@ -462,10 +567,127 @@ export class Store {
             : [];
         page.updatedAt = Date.now();
       }
-      return { acknowledged: true, staged, keys };
+      return { acknowledged: true, staged, keys, ...(round ? { roundId: round.roundId } : {}) };
     });
   }
 
+  listHistory(entryKey) {
+    return (this.data.histories[entryKey]?.rounds || []).map(publicRound).sort((a, b) => b.ordinal - a.ordinal);
+  }
+
+  getRound(entryKey, roundId) {
+    return publicRound(historyRound(this.data, entryKey, roundId));
+  }
+
+  recordSourceResult(entryKey, roundId, key, { revisionId, unavailable } = {}) {
+    if (revisionId && unavailable) throw revisionError("Source result availability is ambiguous.");
+    if (revisionId) {
+      const manifest = this.revisions.verify(revisionId, key);
+      if (!manifest.source) throw revisionError("Source result must contain a source snapshot.");
+    } else if (typeof unavailable !== "string" || !unavailable || unavailable.length > 500) {
+      throw revisionError("Source result needs a revision or unavailable reason.");
+    }
+    const existing = historyRound(this.data, entryKey, roundId);
+    const existingTarget = existing?.targets.find((target) => target.key === key);
+    if (existing?.feedbackStatus !== "acknowledged" || !existingTarget) throw revisionError("Source capture is not pending.");
+    if (existingTarget.sourceResultRevisionId) {
+      if (existingTarget.sourceResultRevisionId === revisionId) return { accepted: false, duplicate: true, round: publicRound(existing) };
+      throw revisionError("The source result is already frozen.", "CAPTURE_FINALIZED");
+    }
+    if (existing.completedAt || existingTarget.resultRevisionId || existingTarget.capture?.status === "unavailable") {
+      throw revisionError("The target capture is already finalized.", "CAPTURE_FINALIZED");
+    }
+    const result = this.transaction((draft) => {
+      const round = historyRound(draft, entryKey, roundId);
+      const target = round.targets.find((item) => item.key === key);
+      if (revisionId) {
+        target.sourceResultRevisionId = revisionId;
+        delete target.sourceResultUnavailable;
+      } else target.sourceResultUnavailable = unavailable;
+      return round;
+    });
+    return { accepted: true, round: publicRound(result) };
+  }
+
+  claimCapture(entryKey, roundId, key, { ownerSessionId, generation, leaseMs = CAPTURE_LEASE_MS } = {}) {
+    if (typeof ownerSessionId !== "string" || !ownerSessionId || ownerSessionId.length > 200 ||
+        !Number.isSafeInteger(generation) || generation < 0 ||
+        !Number.isSafeInteger(leaseMs) || leaseMs <= 0 || leaseMs > 5 * CAPTURE_LEASE_MS) {
+      throw revisionError("Invalid capture ownership.");
+    }
+    const result = this.transaction((draft) => {
+      const round = historyRound(draft, entryKey, roundId);
+      const target = round?.targets.find((item) => item.key === key);
+      if (round?.feedbackStatus !== "acknowledged" || !target?.capture) throw revisionError("Capture is not pending.");
+      if (target.capture.status === "ready" || target.capture.status === "unavailable") throw revisionError("Capture is already finalized.", "CAPTURE_FINALIZED");
+      if (target.capture.status === "running" && target.capture.leaseExpiresAt > Date.now()) {
+        if (target.capture.ownerSessionId === ownerSessionId && target.capture.generation === generation) return target.capture;
+        throw revisionError("Another frame owns this capture.", "CAPTURE_CONFLICT");
+      }
+      target.capture = {
+        captureId: historyId("cap"), status: "running", ownerSessionId, generation,
+        attempt: target.capture.attempt + 1, leaseExpiresAt: Date.now() + leaseMs,
+      };
+      round.captureStatus = "pending";
+      return target.capture;
+    });
+    return structuredClone(result);
+  }
+
+  recordCaptureResult(entryKey, roundId, key, { captureId, ownerSessionId, generation, revisionId } = {}) {
+    const manifest = this.revisions.verify(revisionId, key);
+    const result = this.transaction((draft) => {
+      const round = historyRound(draft, entryKey, roundId);
+      const target = round?.targets.find((item) => item.key === key);
+      const capture = target?.capture;
+      if (capture?.status === "ready" && capture.captureId === captureId &&
+          capture.ownerSessionId === ownerSessionId && capture.generation === generation &&
+          target.resultRevisionId === revisionId) return { accepted: false, duplicate: true, round };
+      this.assertCapture(round, capture, { captureId, ownerSessionId, generation });
+      target.resultRevisionId = revisionId;
+      target.resultCoverage = { source: !!manifest.source, semantic: !!manifest.semantic };
+      capture.status = "ready";
+      capture.capturedAt = Date.now();
+      capture.leaseExpiresAt = 0;
+      finishCapture(round);
+      return { accepted: true, round };
+    });
+    return structuredClone(result);
+  }
+
+  markCaptureUnavailable(entryKey, roundId, key, { captureId, ownerSessionId, generation, reason, final = false } = {}) {
+    if (typeof reason !== "string" || !reason || reason.length > 500) throw revisionError("Invalid capture failure reason.");
+    const result = this.transaction((draft) => {
+      const round = historyRound(draft, entryKey, roundId);
+      const target = round?.targets.find((item) => item.key === key);
+      const capture = target?.capture;
+      const unowned = round?.feedbackStatus === "acknowledged" &&
+        (capture?.status === "pending" || capture?.status === "failed") &&
+        !capture.ownerSessionId && capture.captureId === captureId &&
+        !ownerSessionId && generation == null;
+      if (!unowned) this.assertCapture(round, capture, { captureId, ownerSessionId, generation });
+      capture.status = final ? "unavailable" : "failed";
+      capture.error = reason;
+      capture.leaseExpiresAt = 0;
+      if (final) target.resultUnavailable = reason;
+      finishCapture(round);
+      return { accepted: true, round };
+    });
+    return structuredClone(result);
+  }
+
+  assertCapture(round, capture, { captureId, ownerSessionId, generation }) {
+    if (round?.feedbackStatus !== "acknowledged" || capture?.status !== "running" ||
+        capture.captureId !== captureId || capture.ownerSessionId !== ownerSessionId ||
+        capture.generation !== generation || capture.leaseExpiresAt <= Date.now()) {
+      throw revisionError("Capture response is stale or belongs to another frame.", "CAPTURE_CONFLICT");
+    }
+  }
+
+  collectHistoryGarbage(options) {
+    return this.revisions.collectGarbage(historyRevisionReferences(this.data), options);
+  }
+
   clearBatch(entryKey) {
     if (!this.batch(entryKey)) return null;
     return this.transaction((draft) => {