@erdemtuna/doc-review 0.8.0 → 0.9.0

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 };
+}

package/src/paths.js

@@ -5,7 +5,7 @@ import fs from "node:fs";
 
 // Bump this when the CLI and detached server no longer share the same request
 // contract. A new CLI must not silently reuse an older background server.
-export const SERVER_PROTOCOL = 12;
+export const SERVER_PROTOCOL = 17;
 
 export function serverProtocolMatches(protocol) {
   return Number(protocol) === SERVER_PROTOCOL;

package/src/poll-transport.js

@@ -0,0 +1,222 @@
+import http from "node:http";
+import { performance } from "node:perf_hooks";
+
+export const DEFAULT_POLL_SECONDS = 12 * 60 * 60;
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const clock = {
+  now: () => performance.now(),
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (timer) => clearTimeout(timer),
+};
+
+function codedError(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+
+export function createDeadline(seconds = DEFAULT_POLL_SECONDS, time = clock) {
+  const end = time.now() + seconds * 1000;
+  const remaining = () => Math.max(0, end - time.now());
+  const check = () => {
+    if (remaining() <= 0) throw codedError("Polling deadline reached.", "POLL_DEADLINE");
+  };
+  return {
+    seconds,
+    time,
+    remaining,
+    check,
+    async sleep(ms) {
+      check();
+      await new Promise((resolve) => time.setTimeout(resolve, Math.min(ms, remaining(), MAX_TIMER_MS)));
+      check();
+    },
+  };
+}
+
+export function isRecoverableTransportError(err) {
+  return new Set([
+    "ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EHOSTUNREACH",
+    "ENETUNREACH", "ENETDOWN", "ECONNABORTED", "ERR_STREAM_PREMATURE_CLOSE",
+    "SERVER_START_PENDING",
+  ]).has(err?.code);
+}
+
+/**
+ * An absolute response deadline, not a socket-idle timeout: heartbeats and
+ * partially received JSON must not extend the caller's waiting budget.
+ */
+export function requestRaw(server, options, body, {
+  timeoutMs = options.timeout,
+  time = clock,
+  signal,
+  timeoutCode = "ETIMEDOUT",
+  makeRequest = http.request,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    let req;
+    let res;
+    let timer;
+    let done = false;
+    let ended = false;
+    let raw = "";
+    const expires = timeoutMs == null ? null : time.now() + timeoutMs;
+    const premature = () => codedError("The server closed an incomplete response.", "ERR_STREAM_PREMATURE_CLOSE");
+    const cleanupResponse = () => {
+      res?.removeListener("data", onData);
+      res?.removeListener("end", onEnd);
+      res?.removeListener("aborted", onAborted);
+    };
+    const settle = (err, value) => {
+      if (done) return;
+      done = true;
+      time.clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      cleanupResponse();
+      // Keep error handlers until close: destroying a socket may emit one last
+      // error asynchronously. Close removes the remaining owned listeners.
+      res?.destroy();
+      req?.destroy();
+      if (err) reject(err);
+      else resolve(value);
+    };
+    const onError = (err) => settle(err);
+    const onData = (chunk) => { raw += chunk; };
+    const onEnd = () => {
+      ended = true;
+      if (!res.complete) return settle(premature());
+      settle(null, { status: res.statusCode, raw });
+    };
+    const onAborted = () => settle(premature());
+    const onResponseClose = () => {
+      if (!ended) settle(premature());
+      cleanupResponse();
+      res.removeListener("error", onError);
+      res.removeListener("close", onResponseClose);
+    };
+    const onRequestClose = () => {
+      if (!done) settle(premature());
+      req.removeListener("error", onError);
+      req.removeListener("close", onRequestClose);
+      req.removeListener("response", onResponse);
+    };
+    const onAbort = () => settle(codedError("Polling cancelled.", "ABORT_ERR"));
+    const armTimer = () => {
+      const left = expires - time.now();
+      if (left <= 0) return settle(codedError("Polling request timed out.", timeoutCode));
+      timer = time.setTimeout(armTimer, Math.min(left, MAX_TIMER_MS));
+    };
+    const onResponse = (response) => {
+      res = response;
+      if (done) {
+        res.destroy();
+        return;
+      }
+      res.setEncoding("utf8");
+      res.on("data", onData);
+      res.on("end", onEnd);
+      res.on("error", onError);
+      res.on("aborted", onAborted);
+      res.on("close", onResponseClose);
+    };
+    try {
+      if (signal?.aborted) return onAbort();
+      const port = typeof server === "number" ? server : server.port;
+      const token = typeof server === "number" ? "" : server.token || "";
+      const { timeout: _timeout, ...requestOptions } = options;
+      req = makeRequest({
+        host: "127.0.0.1",
+        port,
+        ...requestOptions,
+        headers: { ...(token ? { "x-doc-review-token": token } : {}), ...(options.headers || {}) },
+      });
+      req.on("response", onResponse);
+      req.on("error", onError);
+      req.on("close", onRequestClose);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (expires !== null) armTimer();
+      if (done) return;
+      if (body) req.write(JSON.stringify(body));
+      req.end();
+    } catch (err) {
+      settle(err);
+    }
+  });
+}
+
+export function parseServerResponse(response) {
+  if (response.status !== 200) {
+    let detail = "";
+    try { detail = JSON.parse(response.raw).error || ""; } catch { /* HTTP status is sufficient. */ }
+    throw codedError(
+      `Doc-review server returned HTTP ${response.status}${detail ? `: ${detail}` : "."}`,
+      "SERVER_RESPONSE_ERROR",
+    );
+  }
+  try {
+    const parsed = JSON.parse(response.raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+    return parsed;
+  } catch {
+    throw codedError("Malformed response from the doc-review server. End the review and restart the server.", "SERVER_RESPONSE_INVALID");
+  }
+}
+
+export async function pollOnce(server, target, ackId, deadline) {
+  deadline.check();
+  const query = `target=${encodeURIComponent(target)}${ackId ? `&ack=${encodeURIComponent(ackId)}` : ""}`;
+  const response = await requestRaw(server, {
+    method: "GET",
+    path: `/api/poll?${query}`,
+  }, undefined, {
+    timeoutMs: deadline.remaining(),
+    time: deadline.time,
+    timeoutCode: "POLL_DEADLINE",
+  });
+  // Graceful server disposal ends the space heartbeats without a JSON payload.
+  // HTTP is complete, but this poll was interrupted just like a dropped socket.
+  if (response.status === 200 && /^ +$/.test(response.raw)) {
+    throw codedError("The server ended the poll before sending feedback.", "ERR_STREAM_PREMATURE_CLOSE");
+  }
+  const batch = parseServerResponse(response);
+  if (!["feedback", "closed", "timeout"].includes(batch.status) ||
+      (batch.status === "feedback" && (typeof batch.batch_id !== "string" || !batch.batch_id || !Array.isArray(batch.pages)))) {
+    throw codedError("Malformed polling response from the doc-review server.", "SERVER_RESPONSE_INVALID");
+  }
+  return batch;
+}
+
+export async function pollUntilDeadline({
+  target,
+  ackId = "",
+  deadline = createDeadline(),
+  discover,
+  poll = pollOnce,
+  diagnostic = () => {},
+}) {
+  let failures = 0;
+  for (;;) {
+    try {
+      deadline.check();
+      const server = await discover(deadline);
+      deadline.check();
+      // An uncertain send must repeat the supplied receipt, never a newer ID.
+      const batch = await poll(server, target, ackId, deadline);
+      deadline.check();
+      return batch;
+    } catch (err) {
+      if (err.code === "POLL_DEADLINE" || deadline.remaining() <= 0) {
+        return {
+          status: "timeout",
+          waited_seconds: deadline.seconds,
+          next_step: "No feedback yet. Run the same poll command again to keep waiting, or `doc-review status <target>` to check without blocking.",
+        };
+      }
+      if (!isRecoverableTransportError(err)) throw err;
+      diagnostic(`Lost the connection (${err.message}); retrying.\n`);
+      try {
+        await deadline.sleep(Math.min(250 * 2 ** Math.min(failures++, 5), 5000));
+      } catch (sleepError) {
+        if (sleepError.code !== "POLL_DEADLINE") throw sleepError;
+      }
+    }
+  }
+}