@erdemtuna/doc-review 0.12.0 → 0.14.0

package/lib/conversation-controller.js

@@ -0,0 +1,798 @@
+import { createControllerStore } from "./controller-store.js";
+import { ApiError } from "./chrome-api.js";
+import { acceptedMutationSchema, abandonRequestSchema, contextPageSchema, conversationListRequestSchema, directEditPageSchema, editAttentionPageSchema, directEditContentSchema, receiptLookupSchema, reviewPageListSchema, reviewPageSchema, validateSaveEvidence, reviewerMutationSchema, reviewStatusSchema, submissionHistoryPageSchema, submissionReadSchema, threadPageSchema, } from "./contracts/index.js";
+export const conversationDraft = () => ({
+    text: "", intent: "discuss", selectionStart: 0, selectionEnd: 0, composing: false, messageId: null, messageVersion: null,
+});
+const reviewStage = (status) => status.review.state === "ended" ? "ended" : status.work ? "waiting" : "reviewing";
+export function createConversationController(options) {
+    const reference = { reviewId: options.reviewId, entryKey: options.entryKey };
+    let review = null;
+    let status = null;
+    let pages = [], threads = [], edits = [], history = [];
+    let attentionEdits = [];
+    let historyCursor = null, historyDepth = 50;
+    let historyLoading = null;
+    const contexts = new Map(), drafts = new Map();
+    const editBaselines = new Map();
+    let draftCancellation = null;
+    const savingDrafts = new Set();
+    const historyOpened = new Set();
+    const contextLoads = new Map(), contextErrors = new Map();
+    const submissions = new Map(), collapsed = new Set(), attention = new Set();
+    const fingerprints = new Map();
+    const lastRecorded = new Map();
+    const readingPositions = new Map();
+    const readingAnchors = new Map();
+    let revealedMessage = null;
+    let revealRequest = 0;
+    let resolutionGuardId = null;
+    let notification = null;
+    let note = conversationDraft();
+    let newMessage = null;
+    let filters = { open: true, resolved: false };
+    let revealedThreadId = null;
+    let focusId = null, open = false, error = "", notice = "", captureNotice = "", connected = true;
+    let host = "feedback";
+    let confirmation = null, uncertain = null;
+    let busy = false, confirming = false, dispatching = false, loading = false, disposed = false;
+    let serial = Promise.resolve(), refreshing = null, refreshAgain = false;
+    let selectionKnown = false;
+    const writable = () => !!review && review.state === "open" && !uncertain;
+    const displayExchanges = (thread) => {
+        const items = contexts.get(thread.thread.threadId)?.items ?? (thread.latestExchange ? [thread.latestExchange] : []);
+        if (historyOpened.has(thread.thread.threadId))
+            return items;
+        const recent = new Set(items.filter(item => item.reviewer.submissionId !== null).slice(-2).map(item => item.reviewer.messageId));
+        return items.filter(item => recent.has(item.reviewer.messageId) || item.reviewer.submissionId === null);
+    };
+    function pendingSelection() {
+        if (!selectionKnown || !status)
+            return null;
+        const messages = [], selectedEdits = [];
+        const keys = new Set();
+        let pendingMessages = 0;
+        for (const thread of threads) {
+            if (!thread.pendingMessageCount)
+                continue;
+            const pending = contexts.get(thread.thread.threadId)?.items.filter(({ reviewer }) => reviewer.submissionId === null);
+            if (!pending || pending.length !== thread.pendingMessageCount)
+                return null;
+            pendingMessages += pending.length;
+            for (const { reviewer } of pending) {
+                messages.push({ threadId: reviewer.threadId, messageId: reviewer.messageId, version: reviewer.version });
+                keys.add(thread.thread.pageKey);
+            }
+        }
+        if (pendingMessages !== status.pendingMessageCount || edits.length !== status.pendingEditCount)
+            return null;
+        for (const edit of edits) {
+            selectedEdits.push({ pageKey: edit.pageKey, editId: edit.editId, version: edit.version });
+            keys.add(edit.pageKey);
+        }
+        const overallNote = note.text.trim() ? { body: note.text, intent: note.intent } : undefined;
+        if (overallNote)
+            keys.add(reference.entryKey);
+        return { pageKeys: [...keys], messages, edits: selectedEdits, ...(overallNote ? { overallNote } : {}),
+            pendingCount: pendingMessages + edits.length };
+    }
+    const sendBlocked = () => {
+        const keys = new Set([reference.entryKey, ...(pendingSelection()?.pageKeys ?? [])]);
+        return status?.blockers.some((blocker) => blocker.targetKeys.some((key) => keys.has(key))) ?? false;
+    };
+    function selectionSummary() {
+        const selected = !loading && connected && !uncertain ? pendingSelection() : null;
+        return selected ? { pendingCount: selected.pendingCount, messages: selected.messages.length, edits: selected.edits.length,
+            note: !!selected.overallNote, total: selected.messages.length + selected.edits.length + (selected.overallNote ? 1 : 0) } : null;
+    }
+    const draftCount = () => [...drafts.values(), note, ...(newMessage ? [newMessage.draft] : [])].filter((draft) => draft.text.length > 0).length;
+    const store = createControllerStore(() => ({
+        review, status, pages, edits, attentionEdits, history, historyCursor,
+        inventory: selectionKnown && !loading && connected && !uncertain && status
+            ? { openThreads: status.openThreadCount, edits: status.attentionEditCount } : null,
+        threads: threads.map((thread) => ({
+            ...thread, exchanges: displayExchanges(thread), context: contexts.get(thread.thread.threadId) ?? null,
+            draft: drafts.get(thread.thread.threadId) ?? null, expanded: !collapsed.has(thread.thread.threadId),
+            attention: attention.has(thread.thread.threadId),
+            contextLoading: contextLoads.has(thread.thread.threadId), contextError: contextErrors.get(thread.thread.threadId) ?? "",
+        })),
+        submissions: [...submissions.entries()].map(([id, value]) => ({ id, value })),
+        note, newMessage, filters, focusId, host, open, error, notice, notification, captureNotice, connected, revealedMessage, revealedThreadId,
+        resolutionGuard: currentResolutionGuard(),
+        confirmation, draftCancellation, uncertain: uncertain ? { operation: uncertain.body.operation, requestId: uncertain.body.requestId, message: uncertain.message } : null,
+        busy: busy || confirming || dispatching, loading, savingDraftIds: [...savingDrafts], sendBlocked: sendBlocked(), draftCount: draftCount(), attentionCount: attention.size,
+        selection: selectionSummary(), canComment: writable(),
+        unsavedMessageDraftCount: [...drafts.values(), ...(newMessage ? [newMessage.draft] : [])].filter((draft) => draft.text.length > 0).length,
+    }));
+    function publish() { if (!disposed)
+        store.publish(); }
+    function revealFocusedThread() {
+        const current = threads.find((item) => item.thread.threadId === focusId);
+        revealedThreadId = current && !filters[current.thread.status] ? current.thread.threadId : null;
+    }
+    function fail(value) { error = value instanceof Error ? value.message : String(value); publish(); }
+    async function post(body, decoder) {
+        return decoder.parse(await options.request("/api/conversation", { method: "POST", body: JSON.stringify(body) }));
+    }
+    function scope(collection, threadId = null) {
+        return { ...reference, collection, pageKey: null, threadId, submissionId: null, status: "all" };
+    }
+    async function page(collection, decoder, query = {}, threadId = null) {
+        return post(conversationListRequestSchema.parse({ operation: "list", scope: scope(collection, threadId), query }), decoder);
+    }
+    async function all(collection, decoder) {
+        const items = [];
+        let cursor;
+        let total, highWater;
+        const cursors = new Set();
+        do {
+            const result = await page(collection, decoder, { limit: 100, ...(cursor ? { cursor } : {}) });
+            total ??= result.totalCount;
+            highWater ??= result.highWater;
+            if (result.totalCount !== total || result.highWater !== highWater || (result.nextCursor && cursors.has(result.nextCursor))) {
+                throw new Error(`The ${collection} inventory changed while paging. Refresh the review.`);
+            }
+            if (result.nextCursor)
+                cursors.add(result.nextCursor);
+            items.push(...result.items);
+            cursor = result.nextCursor ?? undefined;
+        } while (cursor);
+        if (items.length !== total)
+            throw new Error(`The ${collection} inventory is incomplete. Refresh the review.`);
+        return items;
+    }
+    async function readContext(id, minimum = 1, pending = 0, messageId) {
+        const latest = await page("context", contextPageSchema, {}, id);
+        let result = latest;
+        let items = [...latest.items];
+        while (result.nextCursor && (items.length < minimum || items.filter((item) => item.reviewer.submissionId === null).length < pending ||
+            (messageId && !items.some(item => item.reviewer.messageId === messageId)))) {
+            result = await page("context", contextPageSchema, { cursor: result.nextCursor }, id);
+            items = [...result.items, ...items];
+        }
+        return { ...latest, items, nextCursor: result.nextCursor };
+    }
+    async function readHistory() {
+        const oldestLoaded = history.at(-1)?.sequence;
+        let result = await page("history", submissionHistoryPageSchema);
+        const items = [...result.items];
+        // Rebuild a continuous high-water window through every previously loaded item.
+        // This bridges missed pages and refreshes older result/comparison summaries too.
+        while (result.nextCursor && (items.length < historyDepth ||
+            (oldestLoaded !== undefined && items.at(-1).sequence > oldestLoaded))) {
+            result = await page("history", submissionHistoryPageSchema, { cursor: result.nextCursor });
+            items.push(...result.items);
+        }
+        return { items: [...new Map(items.map((item) => [item.submissionId, item])).values()]
+                .sort((a, b) => b.sequence - a.sequence), nextCursor: result.nextCursor };
+    }
+    async function refreshOnce() {
+        const nextStatus = await post({ operation: "status", ...reference }, reviewStatusSchema);
+        if (nextStatus.review.reviewId !== reference.reviewId || nextStatus.review.entryKey !== reference.entryKey)
+            throw new Error("Status belongs to another review.");
+        const [nextPages, nextThreads, nextEdits, nextHistory, nextAttentionEdits] = await Promise.all([
+            all("pages", reviewPageListSchema), all("threads", threadPageSchema), all("edits", directEditPageSchema),
+            readHistory(), all("edit-attention", editAttentionPageSchema),
+        ]);
+        const nextContexts = new Map();
+        await Promise.all(nextThreads.map(async (thread) => {
+            const id = thread.thread.threadId;
+            if (contexts.has(id) || thread.messageCount > 1 || thread.pendingMessageCount > 0) {
+                const cached = contexts.get(id), previous = threads.find(item => item.thread.threadId === id);
+                const minimum = Math.min(thread.messageCount, thread.pendingMessageCount + 2);
+                if (cached && cached.items.length >= minimum && JSON.stringify(previous) === JSON.stringify(thread))
+                    nextContexts.set(id, cached);
+                else
+                    nextContexts.set(id, await readContext(id, Math.max(cached?.items.length ?? 0, minimum), thread.pendingMessageCount));
+            }
+        }));
+        const nextSubmissions = new Map();
+        await Promise.all(nextHistory.items.map(async (item) => {
+            const id = item.submissionId, cached = submissions.get(id);
+            // Submitted instructions are immutable; delivery/completion changes state.
+            // Comparison capture is refreshed independently through history.
+            const unchanged = cached && cached.submission.state === item.state &&
+                cached.submission.resultId === (item.result?.resultId ?? null);
+            nextSubmissions.set(id, unchanged ? cached : await post({ operation: "submission", ...reference, submissionId: id }, submissionReadSchema));
+        }));
+        const confirmed = await post({ operation: "status", ...reference }, reviewStatusSchema);
+        if (JSON.stringify(nextStatus) !== JSON.stringify(confirmed)) {
+            refreshAgain = true;
+            return;
+        }
+        if (nextAttentionEdits.length !== nextStatus.attentionEditCount ||
+            new Set(nextAttentionEdits.map(item => JSON.stringify([item.edit.editId, item.edit.version]))).size !== nextAttentionEdits.length ||
+            nextThreads.filter(item => item.thread.status === "open").length !== nextStatus.openThreadCount) {
+            throw new Error("Feedback inventory is incomplete. Refresh to reload the review.");
+        }
+        if (disposed)
+            return;
+        const nextStage = reviewStage(nextStatus);
+        if (status && reviewStage(status) !== nextStage) {
+            const completed = status.work && nextSubmissions.get(status.work.submissionId)?.submission.state === "handled";
+            notification = { id: `${nextStatus.review.version}:${nextStage}`,
+                message: nextStage === "ended" ? "Review ended." : nextStage === "waiting" ? "Waiting for agent."
+                    : completed ? "Agent response received. Ready to review." : "Reviewing resumed." };
+        }
+        review = nextStatus.review;
+        status = nextStatus;
+        pages = nextPages;
+        edits = nextEdits;
+        attentionEdits = nextAttentionEdits;
+        for (const thread of nextThreads) {
+            const id = thread.thread.threadId;
+            const exchange = thread.latestExchange;
+            // Submission bookkeeping and resolution are not new conversation content.
+            const fingerprint = JSON.stringify([thread.messageCount, exchange?.reviewer.messageId,
+                exchange?.reviewer.version, exchange?.response]);
+            if (fingerprints.has(id) && fingerprints.get(id) !== fingerprint)
+                attention.add(id);
+            fingerprints.set(id, fingerprint);
+            const previous = threads.find(item => item.thread.threadId === id);
+            if (thread.thread.status === "resolved" && previous?.thread.status !== "resolved") {
+                if (!drafts.has(id)) {
+                    collapsed.add(id);
+                    if (host === "adjacent" && focusId === id) {
+                        revealRequest++;
+                        open = false;
+                        focusId = null;
+                        host = "feedback";
+                    }
+                }
+                attention.delete(id);
+            }
+            else if (thread.thread.status === "open" && previous?.thread.status === "resolved") {
+                collapsed.delete(id);
+            }
+        }
+        threads = nextThreads;
+        const revealed = threads.find(item => item.thread.threadId === revealedThreadId);
+        if (!revealed || filters[revealed.thread.status])
+            revealedThreadId = null;
+        for (const [id, value] of nextContexts)
+            contexts.set(id, value);
+        for (const [id, value] of nextSubmissions)
+            submissions.set(id, value);
+        history = nextHistory.items;
+        historyCursor = nextHistory.nextCursor;
+        selectionKnown = true;
+        publish();
+    }
+    function refresh() {
+        if (refreshing) {
+            refreshAgain = true;
+            return refreshing;
+        }
+        loading = true;
+        publish();
+        refreshing = (async () => {
+            do {
+                refreshAgain = false;
+                await refreshOnce();
+            } while (refreshAgain && !disposed);
+        })().catch((cause) => { selectionKnown = false; fail(cause); throw cause; }).finally(() => { refreshing = null; loading = false; publish(); });
+        return refreshing;
+    }
+    const draftEqual = (a, b) => a.text === b.text && a.intent === b.intent && a.messageId === b.messageId && !a.composing;
+    const getDraft = (id) => id === "new" ? newMessage?.draft : drafts.get(id);
+    function dirtyDraft(id, draft) {
+        const baseline = editBaselines.get(id);
+        return draft.messageId ? !baseline || draft.text !== baseline.text || draft.intent !== baseline.intent : !!draft.text.trim();
+    }
+    function resolutionBlocker(thread) {
+        if (thread.thread.status === "resolved")
+            return "";
+        const id = thread.thread.threadId;
+        if (drafts.has(id))
+            return "Finish or close your draft before resolving. Your text and change permission are kept.";
+        if (thread.pendingMessageCount)
+            return "This conversation has comments that have not been sent. Send them or remove them before resolving.";
+        const outstanding = [...submissions.values()].some(({ submission }) => (submission.state === "queued" || submission.state === "delivered") &&
+            submission.messages.some(({ message }) => message.threadId === id));
+        return outstanding ? "Wait for the agent response before resolving. Resolving cannot cancel accepted work." : "";
+    }
+    function currentResolutionGuard() {
+        const thread = threads.find(item => item.thread.threadId === resolutionGuardId);
+        if (!thread)
+            return null;
+        const message = resolutionBlocker(thread);
+        return message ? { threadId: thread.thread.threadId, message } : null;
+    }
+    function canCancelDraft(id) {
+        return writable() && !busy && !confirming && !dispatching && !savingDrafts.has(id) && !getDraft(id)?.composing;
+    }
+    function discardDraft(id) {
+        if (id === "new") {
+            newMessage = null;
+            if (host === "compose")
+                open = false;
+        }
+        else
+            drafts.delete(id);
+        editBaselines.delete(id);
+        draftCancellation = null;
+        publish();
+    }
+    async function accept(pending) {
+        const result = await post(pending.body, acceptedMutationSchema);
+        if (result.receipt.reviewId !== reference.reviewId || result.receipt.entryKey !== reference.entryKey ||
+            result.receipt.requestId !== pending.body.requestId || result.receipt.operation !== pending.body.operation) {
+            throw new Error("Mutation receipt does not match this review and request.");
+        }
+        if (review)
+            review = { ...review, version: result.receipt.value.reviewVersion };
+        pending.accepted(result.receipt);
+        if (pending.draftId)
+            savingDrafts.delete(pending.draftId);
+        uncertain = null;
+        notice = "";
+        // Acceptance is independent of whether the subsequent read succeeds.
+        try {
+            await refresh();
+        }
+        catch {
+            notice = "Refresh failed; do not repeat accepted work.";
+        }
+        return result.receipt;
+    }
+    function mutate(operation, fields = {}, accepted = () => { }, expectedVersion, draftId) {
+        const task = serial.then(async () => {
+            if (disposed)
+                throw new Error("Review connection closed.");
+            if (uncertain)
+                throw new Error("Reconcile the unconfirmed request before another mutation.");
+            if (!review)
+                throw new Error("Review has not loaded.");
+            const input = { operation, ...reference, requestId: (options.id ?? (() => crypto.randomUUID()))(),
+                expectedVersion: expectedVersion ?? review.version, ...fields };
+            const body = operation === "abandon" ? abandonRequestSchema.parse(input) : reviewerMutationSchema.parse(input);
+            busy = true;
+            error = "";
+            publish();
+            const pending = { body, accepted, draftId, message: "Acceptance is unknown. Check the receipt or retry this exact request; a lookup miss is not rejection." };
+            try {
+                return await accept(pending);
+            }
+            catch (cause) {
+                if (!(cause instanceof ApiError) || cause.status >= 500)
+                    uncertain = pending;
+                fail(cause);
+                if (!uncertain) {
+                    try {
+                        await refresh();
+                    }
+                    catch { /* Visible refresh error is retained. */ }
+                }
+                throw cause;
+            }
+            finally {
+                busy = false;
+                publish();
+            }
+        });
+        serial = task.then(() => { }, () => { });
+        return task;
+    }
+    async function saveDraft(id) {
+        const draft = id === "new" ? newMessage?.draft : drafts.get(id);
+        if (!writable() || !draft || draft.composing || !draft.text.trim() || savingDrafts.has(id))
+            return;
+        savingDrafts.add(id);
+        const saved = { ...draft }, target = newMessage;
+        const operation = id === "new" ? "create-thread" : draft.messageId ? "update-message" : "reply";
+        const fields = {
+            body: saved.text, intent: saved.intent,
+            ...(id === "new" && target ? { pageKey: target.pageKey, target: target.target } : { threadId: id }),
+            ...(saved.messageId ? { messageId: saved.messageId, messageVersion: saved.messageVersion } : {}),
+        };
+        publish();
+        try {
+            await mutate(operation, fields, () => {
+                const current = id === "new" ? newMessage?.draft : drafts.get(id);
+                if (current === draft && draftEqual(draft, saved)) {
+                    if (id === "new")
+                        newMessage = null;
+                    else
+                        drafts.delete(id);
+                    editBaselines.delete(id);
+                }
+                else if (current === draft && saved.messageVersion !== null) {
+                    draft.messageVersion = saved.messageVersion + 1;
+                    editBaselines.set(id, { text: saved.text, intent: saved.intent });
+                }
+            }, undefined, id);
+        }
+        finally {
+            if (uncertain?.draftId !== id)
+                savingDrafts.delete(id);
+            publish();
+        }
+    }
+    async function send() {
+        if (!writable() || busy || confirming || dispatching || note.composing)
+            return;
+        const selected = pendingSelection();
+        if (!selected)
+            throw new Error("Pending feedback selection is incomplete. Refresh the review before sending.");
+        const sentNote = { ...note };
+        dispatching = true;
+        publish();
+        try {
+            await options.barrier();
+            await refresh();
+            for (const thread of threads) {
+                if (!thread.pendingMessageCount)
+                    continue;
+                const context = await readContext(thread.thread.threadId, 1, thread.pendingMessageCount);
+                contexts.set(thread.thread.threadId, context);
+            }
+            const currentSelection = pendingSelection();
+            if (!currentSelection || selected.messages.some(message => !currentSelection.messages.some(current => current.threadId === message.threadId && current.messageId === message.messageId && current.version === message.version)) ||
+                selected.edits.some(edit => !currentSelection.edits.some(current => current.pageKey === edit.pageKey && current.editId === edit.editId && current.version === edit.version))) {
+                throw new Error("Selected feedback changed while preparing Send. Review selection and send again.");
+            }
+            if (status?.blockers.some((blocker) => blocker.targetKeys.some((key) => key === reference.entryKey || selected.pageKeys.includes(key)))) {
+                throw new Error("Send is blocked by outstanding work on this entry or a selected page.");
+            }
+            if (!selected.messages.length && !selected.edits.length && !selected.overallNote)
+                throw new Error("Select saved pending messages or edits, or write an overall note.");
+            captureNotice = "";
+            try {
+                await options.baseline();
+            }
+            catch (cause) {
+                captureNotice = `Comparison baseline unavailable: ${cause instanceof Error ? cause.message : cause}. Feedback delivery is independent.`;
+                publish();
+            }
+            await mutate("send", {
+                pageKeys: selected.pageKeys, messages: selected.messages, edits: selected.edits,
+                ...(selected.overallNote ? { overallNote: selected.overallNote } : {}),
+            }, () => { if (draftEqual(note, sentNote))
+                note = conversationDraft(); });
+        }
+        finally {
+            dispatching = false;
+            publish();
+        }
+    }
+    async function recordEdit(pageKey, contentInput) {
+        let content = directEditContentSchema.parse(contentInput);
+        const candidates = edits.filter((edit) => edit.pageKey === pageKey && edit.content.label === content.label && edit.content.kind === content.kind &&
+            edit.content.before === content.before && edit.content.before_html === content.before_html);
+        if (candidates.length > 1)
+            throw new Error("This edit matches multiple pending records. Source identification is required.");
+        const prior = candidates[0];
+        const retained = [...edits.filter((edit) => edit.pageKey === pageKey),
+            ...[...submissions.values()].flatMap((item) => item.submission.edits.filter((edit) => edit.pageKey === pageKey))]
+            .flatMap((edit) => edit.content.staged_assets)
+            .filter((asset) => content.before_html?.includes(asset.preview_src) || content.after_html?.includes(asset.preview_src));
+        content = directEditContentSchema.parse({ ...content,
+            staged_assets: [...new Map([...retained, ...content.staged_assets].map((asset) => [asset.id, asset])).values()] });
+        return mutate("record-edit", { pageKey, content, ...(prior ? { editId: prior.editId, editVersion: prior.version } : {}) }, (receipt) => { if (receipt.value.editId)
+            lastRecorded.set(pageKey, receipt.value.editId); });
+    }
+    async function saveHtml(pageKey, html, expectedSourceHash) {
+        const pending = edits.filter((edit) => edit.pageKey === pageKey && edit.source.state !== "saved");
+        const edit = pending.find((item) => item.editId === lastRecorded.get(pageKey));
+        if (!edit)
+            throw new Error("HTML cannot be saved without an exact pending edit record.");
+        const receipt = await mutate("save-edit", { pageKey, editId: edit.editId, editVersion: edit.version, html, expectedSourceHash });
+        try {
+            const exact = (await all("edits", directEditPageSchema)).find((item) => item.editId === edit.editId &&
+                item.pageKey === pageKey && item.reviewId === reference.reviewId && item.version === edit.version);
+            const current = await post({ operation: "read-page", ...reference, pageKey }, reviewPageSchema);
+            if (!exact || current.page.pageKey !== pageKey || current.reviewId !== reference.reviewId)
+                throw new Error("Exact saved edit or page is unavailable.");
+            validateSaveEvidence(exact, current.page.sourceHash, current.savePolicy === "writable");
+            if (exact.source.state !== "saved")
+                throw new Error("Exact save evidence is unavailable.");
+            return { hash: exact.source.evidence.sourceHash };
+        }
+        catch (cause) {
+            throw new Error(`Source save accepted (${receipt.requestId}), but current source verification failed. Reload source; do not repeat the write. ${cause instanceof Error ? cause.message : cause}`);
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, refresh, mutate, recordEdit, saveHtml,
+        readingAnchor(id) { return readingAnchors.get(id); },
+        rememberReadingAnchor(id, value) {
+            if (Number.isFinite(value.offset))
+                readingAnchors.set(id, value);
+        },
+        readingPosition(id, host) { return readingPositions.get(id)?.[host] ?? 0; },
+        rememberReadingPosition(id, host, top) {
+            if (!Number.isFinite(top) || top < 0)
+                return;
+            readingPositions.set(id, { feedback: 0, focus: 0, ...readingPositions.get(id), [host]: top });
+        },
+        reference, get review() { return review; }, get pages() { return pages; },
+        get draftsPresent() { return draftCount() > 0; },
+        report: fail,
+        commands: {
+            open(value = true) { revealRequest++; open = value; if (!value)
+                revealedThreadId = null; publish(); },
+            connected(value) { connected = value; publish(); },
+            filter(kind) { revealedThreadId = null; filters = { ...filters, [kind]: !filters[kind] }; publish(); },
+            dismissReveal() { revealedThreadId = null; publish(); },
+            dismissNotification(id) { if (notification?.id === id) {
+                notification = null;
+                publish();
+            } },
+            collapse(id) { if (collapsed.has(id))
+                collapsed.delete(id);
+            else
+                collapsed.add(id); publish(); },
+            focus(id) {
+                revealRequest++;
+                if (!id)
+                    revealFocusedThread();
+                else
+                    revealedThreadId = null;
+                focusId = id;
+                host = id ? "focus" : "feedback";
+                open = true;
+                publish();
+            },
+            async revealMessage(threadId, messageId) {
+                revealedThreadId = null;
+                const request = ++revealRequest;
+                if (!threads.some(item => item.thread.threadId === threadId))
+                    throw new Error("This conversation is no longer available in this review.");
+                let context = contexts.get(threadId);
+                if (!context?.items.some(item => item.reviewer.messageId === messageId)) {
+                    const previous = context;
+                    context = await readContext(threadId, 1, 0, messageId);
+                    if (disposed || request !== revealRequest)
+                        return;
+                    if (contexts.get(threadId) !== previous)
+                        throw new Error("Conversation changed while loading the reply. Try again.");
+                    contexts.set(threadId, context);
+                }
+                if (!context.items.some(item => item.reviewer.messageId === messageId))
+                    throw new Error("The requested reply is unavailable.");
+                historyOpened.add(threadId);
+                collapsed.delete(threadId);
+                readingAnchors.set(threadId, { messageId, offset: 0 });
+                revealedMessage = { threadId, messageId };
+                focusId = threadId;
+                host = "focus";
+                open = true;
+                attention.delete(threadId);
+                publish();
+            },
+            adjacent(id) {
+                revealedThreadId = null;
+                revealRequest++;
+                if (!threads.some((item) => item.thread.threadId === id))
+                    throw new Error("Conversation is not in this review.");
+                focusId = id;
+                host = "adjacent";
+                open = true;
+                collapsed.delete(id);
+                publish();
+            },
+            fallback() {
+                if (host !== "adjacent")
+                    return;
+                revealFocusedThread();
+                host = "feedback";
+                focusId = null;
+                publish();
+            },
+            markRead(id) { attention.delete(id); publish(); },
+            dismissResolutionGuard() { resolutionGuardId = null; publish(); },
+            async resolve(id) {
+                if (!writable() || busy || confirming || dispatching)
+                    return;
+                const thread = threads.find(item => item.thread.threadId === id);
+                if (!thread)
+                    throw new Error("This conversation is no longer available.");
+                if (resolutionBlocker(thread)) {
+                    resolutionGuardId = id;
+                    publish();
+                    return;
+                }
+                resolutionGuardId = null;
+                confirming = true;
+                publish();
+                const status = thread.thread.status === "open" ? "resolved" : "open";
+                try {
+                    await mutate("set-thread-status", { threadId: id, status }, undefined, review.version);
+                }
+                finally {
+                    confirming = false;
+                    publish();
+                }
+            },
+            compose() { revealRequest++; revealedThreadId = null; if (newMessage) {
+                open = true;
+                focusId = null;
+                host = "compose";
+                publish();
+            } },
+            begin(pageKey, target, contextual = false) {
+                revealRequest++;
+                if (!writable())
+                    return false;
+                if (newMessage && (dirtyDraft("new", newMessage.draft) || newMessage.draft.composing || savingDrafts.has("new") || draftCancellation === "new")) {
+                    throw new Error("Save or cancel the existing new-message draft first.");
+                }
+                revealedThreadId = null;
+                newMessage = { pageKey, target, draft: conversationDraft() };
+                open = true;
+                focusId = null;
+                host = contextual ? "compose" : "feedback";
+                publish();
+                return true;
+            },
+            reply(id) { if (writable() && !drafts.has(id)) {
+                drafts.set(id, conversationDraft());
+                collapsed.delete(id);
+                publish();
+            } },
+            edit(message) {
+                if (!writable() || message.submissionId !== null)
+                    return;
+                const current = drafts.get(message.threadId);
+                if (current && (dirtyDraft(message.threadId, current) || current.composing || savingDrafts.has(message.threadId) || draftCancellation === message.threadId))
+                    throw new Error("Save or cancel this thread's draft first.");
+                editBaselines.set(message.threadId, { text: message.body, intent: message.intent });
+                drafts.set(message.threadId, { ...conversationDraft(), text: message.body, intent: message.intent,
+                    selectionStart: message.body.length, selectionEnd: message.body.length, messageId: message.messageId, messageVersion: message.version });
+                publish();
+            },
+            update(id, value) {
+                const draft = id === "note" ? note : id === "new" ? newMessage?.draft : drafts.get(id);
+                if (review?.state === "open" && draft) {
+                    Object.assign(draft, value);
+                    publish();
+                }
+            },
+            cancelDraft(id) {
+                const draft = getDraft(id);
+                if (!draft || !canCancelDraft(id))
+                    return;
+                if (dirtyDraft(id, draft)) {
+                    draftCancellation = id;
+                    publish();
+                }
+                else
+                    discardDraft(id);
+            },
+            keepEditing() { draftCancellation = null; publish(); },
+            discardDraft() {
+                if (draftCancellation !== null && canCancelDraft(draftCancellation))
+                    discardDraft(draftCancellation);
+            },
+            saveDraft, send, refresh,
+            earlier(id) {
+                const running = contextLoads.get(id);
+                if (running)
+                    return running;
+                contextErrors.delete(id);
+                const work = (async () => {
+                    const current = contexts.get(id);
+                    if (!current) {
+                        const context = await readContext(id, 50);
+                        if (contexts.has(id))
+                            throw new Error("Conversation changed while loading earlier replies. Try again.");
+                        contexts.set(id, context);
+                    }
+                    else if (historyOpened.has(id) || current.items.length === displayExchanges(threads.find(thread => thread.thread.threadId === id)).length) {
+                        if (current.nextCursor) {
+                            const next = await page("context", contextPageSchema, { cursor: current.nextCursor }, id);
+                            if (contexts.get(id) !== current)
+                                throw new Error("Conversation changed while loading earlier replies. Try again.");
+                            contexts.set(id, { ...current, items: [...new Map([...next.items, ...current.items].map(item => [item.reviewer.messageId, item])).values()],
+                                nextCursor: next.nextCursor });
+                        }
+                    }
+                    historyOpened.add(id);
+                })().catch(cause => {
+                    contextErrors.set(id, cause instanceof Error ? cause.message : String(cause));
+                    throw cause;
+                }).finally(() => { contextLoads.delete(id); publish(); });
+                contextLoads.set(id, work);
+                publish();
+                return work;
+            },
+            historyEarlier() {
+                if (historyLoading)
+                    return historyLoading;
+                if (!historyCursor)
+                    return Promise.resolve();
+                historyDepth = history.length + 50;
+                historyLoading = refresh().finally(() => { historyLoading = null; });
+                return historyLoading;
+            },
+            navigate: options.navigate, jump: options.jump,
+            confirm(action, id = "") {
+                if (!review || busy || confirming || dispatching || uncertain)
+                    return;
+                if (action !== "abandon" && !writable())
+                    return;
+                const thread = threads.find((item) => item.thread.threadId === id);
+                const work = submissions.get(id)?.submission;
+                if ((action === "resolve" || action === "delete") && drafts.get(id)?.text)
+                    throw new Error("Save or cancel this thread's local draft before changing its status.");
+                confirmation = { action, id, version: action === "abandon" ? work?.version ?? 0 : review.version,
+                    description: action === "end" ? `End review ${review.reviewId} for every tab. Accepted source work continues. Saved-unsent items stay read-only here and never transfer to a new review. ${draftCount()} local drafts are not durable.`
+                        : action === "abandon" ? `Abandon submission ${id} in review ${review.reviewId}. Stop the old agent and check source before proceeding. This stops redelivery and releases exclusion; it cannot cancel external work or undo file writes.`
+                            : action === "revert" ? "Revert only source writes owned by this review. Exact saved-unsent edit records remain as source-pending feedback."
+                                : action === "delete" ? "Delete this never-submitted thread? Saved messages in it will be removed."
+                                    : `${thread?.thread.status === "resolved" ? "Reopen" : "Resolve"} this thread? Closing or collapsing a thread never resolves it.` };
+                publish();
+            },
+            cancelConfirmation() { if (!busy && !confirming) {
+                confirmation = null;
+                publish();
+            } },
+            async confirmAction() {
+                const owned = confirmation;
+                if (!owned || busy || confirming || dispatching || uncertain || !review)
+                    return;
+                confirming = true;
+                publish();
+                try {
+                    if (owned.action === "end") {
+                        await options.barrier();
+                        await mutate("end", { confirmUnsentReadOnly: true }, () => { confirmation = null; }, owned.version);
+                    }
+                    else if (owned.action === "abandon") {
+                        await mutate("abandon", { submissionId: owned.id, confirmExternalWorkMayContinue: true, reason: owned.description }, () => { confirmation = null; }, owned.version);
+                    }
+                    else if (owned.action === "revert") {
+                        await options.revert();
+                        confirmation = null;
+                        publish();
+                    }
+                    else {
+                        if (drafts.get(owned.id)?.text)
+                            throw new Error("Save or cancel the local draft first.");
+                        const thread = threads.find((item) => item.thread.threadId === owned.id);
+                        await mutate(owned.action === "delete" ? "delete-thread" : "set-thread-status", { threadId: owned.id, ...(owned.action === "resolve" ? { status: thread?.thread.status === "open" ? "resolved" : "open" } : {}) }, () => { confirmation = null; }, owned.version);
+                    }
+                }
+                finally {
+                    confirming = false;
+                    publish();
+                }
+            },
+            async reconcile(retry) {
+                const pending = uncertain;
+                if (!pending || busy)
+                    return;
+                busy = true;
+                publish();
+                let retrying = false;
+                try {
+                    const lookup = await post({ operation: "receipt", ...reference, requestId: pending.body.requestId }, receiptLookupSchema);
+                    if (lookup.state === "not-found" && !retry) {
+                        pending.message = "Receipt not found. Acceptance remains unknown; do not create a new request or repeat source work.";
+                        return;
+                    }
+                    retrying = true;
+                    await accept(pending);
+                }
+                catch (cause) {
+                    fail(cause);
+                    if (retrying && cause instanceof ApiError && cause.status < 500 && cause.status !== 401 && cause.status !== 403) {
+                        if (pending.draftId)
+                            savingDrafts.delete(pending.draftId);
+                        uncertain = null;
+                        notice = "The exact retry was rejected. Local conversation drafts are retained; inspect source separately before retrying a failed write.";
+                        try {
+                            await refresh();
+                        }
+                        catch { /* The authoritative read error remains visible. */ }
+                    }
+                }
+                finally {
+                    busy = false;
+                    publish();
+                }
+            },
+        },
+        dispose() { disposed = true; store.dispose(); },
+    };
+}