@erdemtuna/doc-review 0.12.0 → 0.13.0

package/lib/references/context-and-recovery.md

@@ -0,0 +1,130 @@
+# Bounded reads and recovery
+
+One agent interface limits final JSON stdout to 16 KiB UTF-8 including escaping
+and newline. No compact/full or raw fallback exists. Durable evidence is not
+truncated for delivery. Large values carry exact scoped references with
+version/field identity, encoding, byte length and SHA-256. Previews are explicitly
+incomplete. Original edit capture truncation is a separate fact.
+
+Inventory/history/context/status blocker pages report `totalCount`,
+`returnedCount`, `complete` and `nextCursor`. Continue the same command with
+`--cursor <opaque-token>` until complete where full coverage is necessary.
+Never assume the first page is the complete response obligation. The generated
+template covers all items even when the inventory is paged.
+
+## Deliberate historical context
+
+For a follow-up, start with the closest relevant earlier exchange using the
+message item's `contextCommand` (default generated `--limit 1`):
+
+```sh
+npx -y @erdemtuna/doc-review context --review <reviewId> --entry <entryKey> --submission <currentSubmissionId> --thread <threadId> --limit 1
+```
+
+The producer reads immutable submissions, excludes current and later work and
+saved-unsent replies before pagination, and provides historical lifecycle
+evidence. Browser context intentionally still shows pending replies.
+Do not load all threads' history speculatively.
+
+For earlier overall notes, results, edits or lost chat context, use the
+submission's `handoff.historyCommand`:
+
+```sh
+npx -y @erdemtuna/doc-review history --review <reviewId> --entry <entryKey> --before <currentSubmissionId> --limit 1
+npx -y @erdemtuna/doc-review submission --review <reviewId> --entry <entryKey> --submission <priorSubmissionId>
+```
+
+History retains note intent, result notes and handled/abandoned evidence.
+Submission reads include exact paged messages/edits, inline responses, edit
+outcomes and receipt. Ended reviews and terminal submissions remain readable.
+Earlier request-change intent is historical evidence, never new permission.
+
+## Exact content
+
+Copy the reference's generated command. `field` is a scoped artifact path, not
+a filesystem path. Never transplant a cursor into another scope/field/version.
+
+```sh
+npx -y @erdemtuna/doc-review content --review <reviewId> --entry <entryKey> --submission <submissionId> --field submission/edits/0/content/after_html
+```
+
+A content read gives exact `text`, encoding (`utf8` or serialized `json`),
+UTF-8 byte `offset`, `returnedBytes`, complete-field byte length/hash,
+`complete`, and `nextCursor`. Concatenate chunks in order until complete;
+Unicode characters and line endings are preserved. Parse JSON only after
+reconstruction. A continuation identity/content change is an error, not a splice.
+
+For a complete field, append `--output-file <new-path>`. Omit `--field` to export
+the whole submitted artifact (submission, result, receipt and canonical pages).
+The receipt gives path/identity/encoding/bytes/hash. Writing is atomic/exclusive;
+existing files and reviewed source are never overwritten. Read exported content
+before using it. A file receipt alone does not prove inspection.
+
+## Identity, retries and End
+
+Keep reviewId, entryKey, submissionId, delivered version, response file and stable
+requestId across compaction. `status` reads lifecycle evidence without starting a
+server or mutating offline state. It deliberately provides only result previews/
+references; explicit content/history reads return requested prose when it fits.
+
+```sh
+npx -y @erdemtuna/doc-review status --review <reviewId> --entry <entryKey>
+npx -y @erdemtuna/doc-review receipt --review <reviewId> --entry <entryKey> --request-id <requestId>
+```
+
+Status reports queued/delivered work, pending counts and predecessor/overlapping
+blockers; `source:"disk"` means validated offline evidence, not agent liveness.
+Corrupt/unsupported state fails explicitly, without legacy fallback.
+
+Semantic rejection (exit 1), uncertain acceptance (exit 2), and accepted receipt
+are different. `not-found` from receipt is not proof of rejection. Retry an
+uncertain response with exactly the same file/requestId; do not regenerate the
+template or repeat source edits. Inspect source and receipts before considering
+any further filesystem work. One cooperating handler is assumed; no worker
+leases or filesystem exactly-once guarantees exist.
+
+End freezes reviewer content, not accepted work. Complete non-abandoned work
+after End/restart; keep polling that review until `ended`. Saved-unsent content
+does not transfer to a new review. Abandonment releases work exclusion but does
+not cancel the external handler or undo source writes. `SUBMISSION_ABANDONED`
+means stop handling, never retry as a new completion.
+
+## Reviewer interaction
+
+The page starts in View. Feedback is nonmodal: it docks on roomy desktops and
+floats on narrow PC windows, without dimming or disabling the document. Show in document
+reveals the exact passage, hiding a floating panel only when it would obscure the
+target. Focus and secondary thread actions are in the conversation menu.
+Resolve/Reopen sits opposite Reply below an expanded conversation and remains in
+Conversation actions when collapsed or a local draft is open. Resolve refuses unfinished drafts,
+unsent messages and outstanding agent work. Resolve/Reopen do not show notifications.
+Review-state transitions, especially receipt of an agent response, appear for five
+seconds at the top left below the toolbar. Hover, notification focus or a hidden
+tab pauses expiry; reading the document iframe does not. Focus includes a visible
+Back to Feedback action; Open/Resolved are separate independent filters.
+Sidebar headers end with Locate, More and Collapse; adjacent headers use Open in
+Feedback (a right-pointing arrow), More and Close. Edit belongs beside each eligible
+message's timestamp. The far-right delivery icon changes from Not sent to Sent,
+then Received when the agent picks up the message or replies.
+Resolved conversations automatically collapse and show a subdued check-circle
+**Resolved** informational icon with a keyboard-visible explanation; they remain expandable
+for reading. Reopen expands them again. Resolution from another tab never
+hides a local draft.
+
+Add comment / Add reply / Update comment queue a message;
+**Send to agent (N)** dispatches a deliberate batch.
+Send includes all saved pending messages and edits. **Your edits** contains exact
+human edit evidence. **Note to agent** opens separately with its own unchecked
+change permission. Unsaved comment drafts are not sent.
+Send freezes the selected versions and note at activation; feedback arriving
+during preparation stays pending. A changed selected version requires reviewing
+the selection again.
+
+Expanded conversations retain two recent sent exchanges and all unsent replies.
+The preceding answer remains visible while composing a follow-up; **Show earlier
+replies** loads older context. Closing Feedback or changing hosts preserves the
+mounted editor and its local draft, but reloading a tab loses unsaved drafts.
+Long result summaries expand with **Read more / Show less**. **Replies (N)**
+lists source labels and comment excerpts. The reply reader retains the
+Feedback/History tabs, **Previous/Next** and **Back to replies**, restoring the
+originating list, scroll and keyboard focus without discarding drafts.

package/lib/references/response-contract.md

@@ -0,0 +1,108 @@
+# Complete responses
+
+Generate a new response file using the actual submission handoff:
+
+```sh
+npx -y @erdemtuna/doc-review response-template --review <reviewId> --entry <entryKey> --submission <submissionId> --output-file response.json
+```
+
+This reads the authoritative immutable submission, not just the first inventory
+page. It includes every message/edit and exact version, delivered expectedVersion,
+and a stable requestId. The file is exclusive: an existing response is never
+overwritten. Inspect/reuse it for recovery; do not generate a new ID for a retry.
+All blank prose/outcomes deliberately fail validation until filled. The command
+does not edit source or assert that anything was applied.
+
+The JSON contract is strict (unknown fields are rejected):
+
+```json
+{
+  "operation": "respond",
+  "reviewId": "review-id",
+  "entryKey": "entry-key",
+  "submissionId": "submission-id",
+  "expectedVersion": 2,
+  "requestId": "stable-request-id",
+  "responses": [{
+    "threadId": "thread-id",
+    "messageId": "message-id",
+    "messageVersion": 1,
+    "body": "The explanation preserves the original meaning.",
+    "outcome": "answered"
+  }],
+  "editOutcomes": [{
+    "editId": "edit-id",
+    "editVersion": 1,
+    "outcome": "deferred",
+    "reason": "The source target is ambiguous; please identify the component."
+  }],
+  "overallOutcome": "answered",
+  "summary": "Answered the questions; one edit needs a clearer target.",
+  "resultNote": "Answered the discussion and overall note; deferred the ambiguous edit."
+}
+```
+
+Keep the generated IDs, versions and requestId. `responses` must cover every
+submitted message exactly once, not just visible inventory items. Each response
+has a nonempty body and scalar outcome: `answered`, `applied`,
+`clarification-needed`, or `deferred`. Only that message's request-change permits
+`applied`; another message or overall note cannot grant it permission.
+
+`editOutcomes` covers each exact edit version once. Outcome is `applied`,
+`already-saved`, or `deferred`, with nonempty `reason`. `already-saved` requires
+server save evidence. Saved or capture-truncated edits cannot be newly `applied`.
+Use truthful deferrals instead of fabricated success to satisfy coverage.
+
+`overallOutcome` is a **scalar string**, not an object. Include it if and only if
+the submission has an overall note. Its enum is `applied`, `answered`,
+`clarification-needed`, `deferred`; `applied` requires that note's request-change.
+The overall answer's prose belongs in `resultNote`. That independent, nonempty
+result note is always required, even without an overall note.
+
+`summary` is an authored orientation sentence or two, separate from the full
+`resultNote`. Fill it in new templates. Older responses and records may omit it;
+when present it must be nonempty. It grants no permission and replaces neither
+message coverage nor edit outcomes. Its exact text participates in receipt replay:
+do not revise it under an accepted requestId. Long summaries use the usual scoped
+content references and export, including `--field result/summary`.
+
+Write answer/outcome first. Routine replies usually need one or two sentences
+and at most three useful bullets (roughly 40-90 words is guidance, not a limit).
+Lead clarification with the exact question. Use Markdown for readable saved
+prose, but avoid IDs/hashes, repetitive preservation boilerplate, or duplicating
+all replies in the summary. Edit reasons explain the outcome, not the full evidence.
+
+A note-only response has empty `responses` and `editOutcomes` arrays, for example:
+
+```json
+{
+  "operation": "respond",
+  "reviewId": "review-id",
+  "entryKey": "entry-key",
+  "submissionId": "submission-id",
+  "expectedVersion": 2,
+  "requestId": "stable-request-id",
+  "responses": [],
+  "editOutcomes": [],
+  "overallOutcome": "answered",
+  "summary": "Explained the tradeoff; no source change was requested.",
+  "resultNote": "The earlier result explained the tradeoff; no new source change was requested."
+}
+```
+
+Submit the filled file:
+
+```sh
+npx -y @erdemtuna/doc-review respond --review <reviewId> --entry <entryKey> --response-file response.json --timeout 600
+```
+
+`{ok:true,receipt}` means the complete response persisted atomically. Comparison
+capture does not gate acceptance. Reply-only work does not fabricate a version or
+reload; saved human changes can display "What changed" without new agent edits.
+Then poll the original review again.
+
+Exit 1 is a semantic/explicit failure. Correct a rejected response deliberately;
+do not turn a rejection into success. Exit 2 (`state:"unknown"`) means acceptance
+is uncertain. The CLI already retries the same logical body within its deadline.
+Retry the identical response file, not source work or a newly minted requestId.
+See [context-and-recovery](context-and-recovery.md) before recovering uncertainty.

package/lib/references/source-edits.md

@@ -0,0 +1,47 @@
+# Exact source edits
+
+Before source work, inspect every necessary inventory/content page and the actual
+authoritative source. A downloaded/exported file is not evidence you inspected it.
+`inline.value` is the complete retained object; a `reference` is only a delivery
+pointer. Follow its command or export and read the artifact. A preview is never an
+`after` replacement. Fields remain exact, including line endings and Unicode.
+
+Every submitted message carries independent `discuss` or `request-change` intent.
+Discuss is answered without editing for that message. Request-change permits,
+but does not require, only its specific change. An overall note is independent;
+neither it nor a historical request grants blanket permission.
+
+Human direct edits are exact requested content separate from message intent.
+Preserve non-truncated `after` wording verbatim. Translate HTML formatting into
+the true source syntax, retain insertion points/assets, honor moves'
+`moved_after`/`moved_before` boundaries and explicit deletions. Read all
+representations needed to understand the edit, not merely a convenient preview.
+
+The edit's `source` data contains `state:"pending"` or `state:"saved"` plus
+server-owned evidence: review, page, edit ID/version, source hash and saved time.
+Never reapply a saved edit. Use `already-saved` only with that exact evidence.
+Report inconsistent source/evidence instead of guessing that a write succeeded.
+
+Inventory page entries identify real files/URLs. For source-pending Markdown,
+scripted HTML and localhost pages, find actual Markdown/MDX/TSX/template/component
+source; do not replace source with rendered Markdown, fetched HTTP, or
+script-generated DOM. Plain HTML alone supports the reviewer's direct save.
+Disabling scripts is not permission to write source.
+
+Use exact target anchors and authoritative source to identify the intended
+location. Missing/ambiguous targets require safe identification or a
+clarification/deferred outcome; never guess a destructive replacement.
+Copy authoritative staged assets from their retained paths into the correct
+project asset location and replace temporary preview references without losing
+the original insertion point.
+
+`captureTruncated` and `truncatedFields` mirror original `content.truncated` and
+`content.truncated_fields`. These mean evidence was clipped during capture
+(currently 200,000 Unicode code points per text/HTML/move field), not during
+delivery. Delivery references do NOT clear those flags. Never apply incomplete
+text/HTML as a complete replacement or invent missing text. Recover only from an
+authoritative source or defer and request the complete edit.
+
+Inspect current source and durable evidence after a restart or uncertain
+response. Receipt replay protects durable responses, not filesystem operations;
+never repeat source writes simply because an HTTP connection failed.

package/lib/revision-store.js

@@ -14,7 +14,7 @@ function captureTime(value, now) {
     return time;
 }
 export class RevisionStore {
-    constructor({ root = path.join(stateDir(), "history"), write = atomicWrite, limits = REVISION_LIMITS } = {}) {
+    constructor({ root = path.join(stateDir(), "conversation-history"), write = atomicWrite, limits = REVISION_LIMITS } = {}) {
         this.root = root;
         this.write = write;
         this.limits = normalizeRevisionLimits(limits);

package/lib/save-controller.js

@@ -1,8 +1,8 @@
-import { decodePage, record } from "./chrome-api.js";
+import { ApiError, decodePage, record, saveFailureMessage } from "./chrome-api.js";
 import { createControllerStore } from "./controller-store.js";
-export function createSaveController({ sessionId, current, policy, request, flush, send, sourceHash, pageChanged, conflict, failed, diagnostic, sending, clock = () => new Date().toLocaleTimeString([], { hour: "numeric", minute: "2-digit" }), setTimer = globalThis.setTimeout, clearTimer = globalThis.clearTimeout, }) {
+export function createSaveController({ sessionId, current, policy, request, flush, send, sourceHash, pageChanged, conflict, failed, diagnostic, sending, conversation, clock = () => new Date().toLocaleTimeString([], { hour: "numeric", minute: "2-digit" }), setTimer = globalThis.setTimeout, clearTimer = globalThis.clearTimeout, }) {
     const state = {
-        status: "idle", savedAt: "", baseHash: null, conflict: false, dirty: false, dynamic: false,
+        status: "idle", savedAt: "", baseHash: null, conflict: false, conflictMessage: "", dirty: false, dynamic: false,
     };
     const store = createControllerStore(() => state);
     const pipelines = new Map();
@@ -67,14 +67,14 @@ export function createSaveController({ sessionId, current, policy, request, flus
             if (disposed)
                 return false;
             try {
-                const result = record(await request(`/api/page/${key}/edit`, {
+                const result = conversation ? await conversation.record(key, original) : record(await request(`/api/page/${key}/edit`, {
                     method: "POST", body: JSON.stringify(payload),
                 }));
                 if (ownedBacklog.get(id) === payload)
                     ownedBacklog.delete(id);
                 errors.delete(key);
-                if (matches(identity))
-                    pageChanged(decodePage(result.page));
+                if (!conversation && matches(identity))
+                    pageChanged(decodePage(record(result).page));
                 return true;
             }
             catch (error) {
@@ -100,6 +100,8 @@ export function createSaveController({ sessionId, current, policy, request, flus
         if (disposed)
             throw new Error("Review ended");
         if (backlogs.get(key)?.size) {
+            if (conversation)
+                throw errors.get(key) || new Error("Reconcile the failed edit before continuing.");
             const retry = [...(backlogs.get(key)?.values() || [])];
             errors.delete(key);
             for (const payload of retry)
@@ -122,7 +124,9 @@ export function createSaveController({ sessionId, current, policy, request, flus
             return false;
         }
         try {
-            const result = record(await request(`/api/page/${identity.key}/save`, {
+            if (conversation)
+                await settleEdits(identity.key);
+            const result = conversation ? await conversation.save(identity.key, html, state.baseHash) : record(await request(`/api/page/${identity.key}/save`, {
                 method: "POST",
                 body: JSON.stringify({
                     html, baseHash: state.baseHash, renderId: identity.renderId,
@@ -149,19 +153,20 @@ export function createSaveController({ sessionId, current, policy, request, flus
                 state.baseHash = null;
                 state.status = "idle";
                 state.conflict = true;
+                state.conflictMessage = saveFailureMessage(error instanceof ApiError ? error.saveReason : undefined);
                 publish();
-                conflict();
+                conflict(state.conflictMessage);
                 diagnostic("save-conflict");
                 return false;
             }
             state.status = "failed";
             publish();
-            if (attempts < 2) {
+            if (!conversation && attempts < 2) {
                 await delay(500);
                 return saveHtml(html, identity, attempts + 1);
             }
             if (!sending())
-                failed("Couldn't save. Retry before sending feedback; your edits remain on this page.");
+                failed(conversation && error instanceof Error ? error.message : "Couldn't save. Retry before sending feedback; your edits remain on this page.");
             return false;
         }
     }
@@ -192,7 +197,7 @@ export function createSaveController({ sessionId, current, policy, request, flus
         const identity = current();
         await flushEdits(true);
         await activeSave;
-        if (state.status === "failed" && !state.conflict && lastSave && matches(lastSave.identity)) {
+        if (!conversation && state.status === "failed" && !state.conflict && lastSave && matches(lastSave.identity)) {
             await save(lastSave.html);
         }
         await settleEdits(identity.key);
@@ -200,7 +205,7 @@ export function createSaveController({ sessionId, current, policy, request, flus
         if (!matches(identity))
             throw new Error("The page changed while saving. Retry on the latest page.");
         if (state.conflict)
-            throw new Error("Resolve the save conflict: the source changed outside this review. Reload latest; your comment drafts will be kept.");
+            throw new Error(`Resolve the save conflict: ${state.conflictMessage || saveFailureMessage()}`);
         if (state.status === "failed" || (policy() === "writable" && !state.dynamic && state.dirty)) {
             throw new Error("Your page edits have not finished saving. They have not been sent.");
         }
@@ -233,9 +238,18 @@ export function createSaveController({ sessionId, current, policy, request, flus
         save, persistEdit, settleEdits, flush: flushEdits, barrier, captureStable,
         applyClean, queued, cancelRetries,
         async settled() { await activeSave; },
+        async discardLocal(key) {
+            if (!key)
+                return;
+            await pipelines.get(key);
+            await activeSave;
+            backlogs.delete(key);
+            errors.delete(key);
+        },
         markEdit() { editSequence++; },
         markSaving() { state.dirty = true; state.status = "saving"; publish(); },
-        markDynamic() { state.dynamic = true; publish(); },
+        markDynamic() { state.dynamic = true; if (state.status === "saving" && !pending)
+            state.status = "idle"; publish(); },
         observeClean() { clean = { identity: current(), sequence, editSequence }; applyClean(); },
         baseline(hash) { state.baseHash = hash; publish(); },
         hold() {
@@ -252,7 +266,7 @@ export function createSaveController({ sessionId, current, policy, request, flus
             clean = null;
             lastSave = null;
             sequence++;
-            Object.assign(state, { status: "idle", savedAt: "", baseHash: null, conflict: false, dirty: false, dynamic: false });
+            Object.assign(state, { status: "idle", savedAt: "", baseHash: null, conflict: false, conflictMessage: "", dirty: false, dynamic: false });
             publish();
         },
         async revert() {