@erdemtuna/doc-review 0.12.0 → 0.13.0

package/lib/contracts/index.js

@@ -1,2 +1,7 @@
-export { isFrameIdentity, isThemePayload } from "./frame.js";
-export { isExecutionPolicy, isPageResponse, isRenderExecution } from "./page.js";
+export * from "./page.js";
+export * from "./page-boundary.js";
+export * from "./feedback.js";
+export * from "./history.js";
+export * from "./frame.js";
+export * from "./validation.js";
+export * from "./agent.js";

package/lib/contracts/page-boundary.js

@@ -0,0 +1,187 @@
+import { assertNoOutstandingWork, directEditSchema, reviewerMutationSchema, sendRequestSchema, submissionSchema, } from "./feedback.js";
+import { pagedSchema } from "./history.js";
+import { array, booleanValue, enumeration, id, integer, literal, nullable, object, refine, reject, rejectSave, text, timestamp, union, version, } from "./validation.js";
+export const CONVERSATION_STATE_FILE = "conversation-state.json";
+export const reviewSchema = refine(object({
+    reviewId: id, entryKey: id, version, state: enumeration(["open", "ended"]),
+    createdAt: timestamp, endedAt: nullable(timestamp),
+}), (review) => {
+    if ((review.state === "ended") !== (review.endedAt !== null))
+        reject("INVALID_INPUT", "End time must match review state.");
+});
+export const canonicalPageSchema = object({
+    pageKey: id,
+    target: union(object({ kind: literal("file"), path: text() }), object({ kind: literal("url"), url: text() })),
+    sourceHash: nullable(id),
+});
+export const reviewPageSchema = object({
+    reviewId: id, sequence: integer(1), page: canonicalPageSchema, joinedAt: timestamp,
+    savePolicy: enumeration(["writable", "feedback-only"]),
+    pendingMessageCount: integer(), pendingEditCount: integer(),
+    writeBlockedBy: array(object({ reviewId: id, submissionId: id })),
+    revert: nullable(object({ baselineRevisionId: id, sourceHash: id })),
+    canRevert: booleanValue,
+});
+export const reviewPageListSchema = pagedSchema(reviewPageSchema);
+export const openReviewRequestSchema = object({ operation: literal("open"), requestId: id, target: text() });
+export const reviewReadRequestSchema = union(object({ operation: literal("read-review"), reviewId: id, entryKey: id }), object({ operation: literal("read-page"), reviewId: id, entryKey: id, pageKey: id }), object({ operation: literal("status"), reviewId: id, entryKey: id }), object({ operation: literal("poll"), reviewId: id, entryKey: id }), object({ operation: literal("submission"), reviewId: id, entryKey: id, submissionId: id }), object({ operation: literal("receipt"), reviewId: id, entryKey: id, requestId: id }), object({ operation: literal("open-receipt"), target: text(), requestId: id }));
+export const pollResponseSchema = union(refine(object({ state: literal("work"), review: reviewSchema, submission: submissionSchema }), ({ review, submission }) => {
+    if (submission.state !== "delivered" || submission.reviewId !== review.reviewId || submission.entryKey !== review.entryKey) {
+        reject("INVALID_INPUT", "Poll must return delivered work from the exact review, including after End.");
+    }
+}), object({ state: literal("waiting"), review: refine(reviewSchema, (review) => {
+        if (review.state !== "open")
+            reject("INVALID_INPUT", "Ended review cannot wait without outstanding work.");
+    }) }), object({ state: literal("ended"), review: refine(reviewSchema, (review) => {
+        if (review.state !== "ended")
+            reject("INVALID_INPUT", "Open review cannot signal end.");
+    }) }));
+export const reviewStatusSchema = object({
+    review: reviewSchema,
+    openThreadCount: integer(), attentionEditCount: integer(),
+    pendingMessageCount: integer(), pendingEditCount: integer(),
+    work: nullable(object({ submissionId: id, state: enumeration(["queued", "delivered"]), version })),
+    blockers: array(object({ reviewId: id, submissionId: id, targetKeys: array(id) })),
+});
+export const statusObservationSchema = union(object({ state: literal("known"), status: reviewStatusSchema }), object({ state: literal("unknown"), reason: enumeration(["offline", "unavailable", "invalid-response"]) }));
+export function assertReviewScope(scope, reference, pageKeys = []) {
+    if (!scope.authenticated)
+        reject("UNAUTHORIZED", "Local API authentication required.");
+    reviewSchema.parse(scope.review);
+    if (scope.review.reviewId !== reference.reviewId || scope.review.entryKey !== reference.entryKey) {
+        reject("SCOPE_MISMATCH", "Wrong durable review or canonical entry.");
+    }
+    for (const key of pageKeys) {
+        if (!scope.pageKeys.includes(key))
+            reject("SCOPE_MISMATCH", "Page is not authorized in this review.");
+    }
+}
+function ownedThread(scope, items, threadId) {
+    const thread = items.threads.find((item) => item.threadId === threadId);
+    if (!thread)
+        return reject("NOT_FOUND", "Unknown thread.");
+    if (thread.reviewId !== scope.review.reviewId)
+        reject("SCOPE_MISMATCH", "Thread belongs to another review.");
+    assertReviewScope(scope, scope.review, [thread.pageKey]);
+    return thread;
+}
+function ownedEdit(scope, items, pageKey, editId) {
+    const edit = items.edits.find((item) => item.editId === editId);
+    if (!edit)
+        return reject("NOT_FOUND", "Unknown edit.");
+    directEditSchema.parse(edit);
+    if (edit.reviewId !== scope.review.reviewId || edit.pageKey !== pageKey)
+        reject("SCOPE_MISMATCH", "Edit belongs to another review/page.");
+    return edit;
+}
+export function validateSendSelection(input, scope, items) {
+    const request = sendRequestSchema.parse(input);
+    assertReviewScope(scope, request, request.pageKeys);
+    for (const selected of request.messages) {
+        const thread = ownedThread(scope, items, selected.threadId);
+        const message = items.messages.find((item) => item.messageId === selected.messageId);
+        if (!message)
+            reject("NOT_FOUND", "Unknown reviewer message.");
+        if (message.reviewId !== request.reviewId || message.threadId !== thread.threadId || !request.pageKeys.includes(thread.pageKey)) {
+            reject("SCOPE_MISMATCH", "Message does not belong to this selected thread/page.");
+        }
+        if (message.submissionId !== null)
+            reject("MESSAGE_IMMUTABLE", "Submitted messages cannot be queued again.");
+        if (thread.status !== "open")
+            reject("THREAD_BUSY", "Reopen the thread before sending.");
+        if (message.version !== selected.version)
+            reject("VERSION_CONFLICT", "Selected message changed.");
+    }
+    for (const selected of request.edits) {
+        const edit = ownedEdit(scope, items, selected.pageKey, selected.editId);
+        if (edit.version !== selected.version)
+            reject("VERSION_CONFLICT", "Selected edit changed.");
+        if (edit.source.state === "saved") {
+            const source = items.sources.find((item) => item.pageKey === edit.pageKey);
+            if (source && source.reviewId !== request.reviewId)
+                reject("SCOPE_MISMATCH", "Source evidence belongs to another review.");
+            if (!source || !source.writable || source.sourceHash !== edit.source.evidence.sourceHash) {
+                reject("SAVE_EVIDENCE_CONFLICT", "Save evidence no longer matches current writable source at Send.");
+            }
+        }
+    }
+}
+/** Pure preconditions only; the store must run these in its accepting transaction, after exact replay. */
+export function validateReviewerMutation(input, scope, items, submissions) {
+    const request = reviewerMutationSchema.parse(input);
+    assertReviewScope(scope, request, "pageKey" in request ? [request.pageKey] : []);
+    if (scope.review.state === "ended")
+        reject("REVIEW_ENDED", "Saved reviewer content is read-only.");
+    if (request.expectedVersion !== scope.review.version)
+        reject("VERSION_CONFLICT", "Review changed; refresh before a new mutation.");
+    if ("threadId" in request) {
+        const thread = ownedThread(scope, items, request.threadId);
+        const messages = items.messages.filter((message) => message.threadId === thread.threadId);
+        if (request.operation === "reply" && thread.status !== "open")
+            reject("THREAD_BUSY", "Reopen before replying.");
+        if (request.operation === "set-thread-status" && request.status === "resolved" &&
+            messages.some((message) => message.submissionId === null || submissions.some((submission) => submission.submissionId === message.submissionId && (submission.state === "queued" || submission.state === "delivered")))) {
+            reject("THREAD_BUSY", "Pending or outstanding messages prevent Resolve.");
+        }
+        if (request.operation === "delete-thread" && messages.some((message) => message.submissionId !== null)) {
+            reject("MESSAGE_IMMUTABLE", "Only never-submitted threads may be deleted.");
+        }
+        if (request.operation === "update-message") {
+            const message = items.messages.find((item) => item.messageId === request.messageId);
+            if (!message)
+                reject("NOT_FOUND", "Unknown reviewer message.");
+            if (message.reviewId !== request.reviewId || message.threadId !== thread.threadId)
+                reject("SCOPE_MISMATCH", "Wrong thread message.");
+            if (message.submissionId !== null)
+                reject("MESSAGE_IMMUTABLE", "Submitted instructions are immutable.");
+            if (message.version !== request.messageVersion)
+                reject("VERSION_CONFLICT", "Message changed.");
+        }
+    }
+    if (request.operation === "send") {
+        validateSendSelection(request, scope, items);
+        assertNoOutstandingWork([request.entryKey, ...request.pageKeys], submissions);
+        for (const selected of request.edits) {
+            if (submissions.some((submission) => submission.edits.some((edit) => edit.reviewId === request.reviewId && edit.editId === selected.editId && edit.version === selected.version))) {
+                reject("MESSAGE_IMMUTABLE", "Previously submitted edit versions require a deliberate new edit record.");
+            }
+        }
+    }
+    if (request.operation === "record-edit" || request.operation === "save-edit" || request.operation === "revert") {
+        assertNoOutstandingWork([request.entryKey, request.pageKey], submissions);
+        if (request.operation === "save-edit" || request.operation === "revert") {
+            const source = items.sources.find((item) => item.pageKey === request.pageKey);
+            if (source && source.reviewId !== request.reviewId)
+                reject("SCOPE_MISMATCH", "Source/revert ownership belongs to another review.");
+            if (!source?.writable)
+                rejectSave("source-unavailable", "Source is unavailable or no longer writable.");
+            if (source.sourceHash !== request.expectedSourceHash)
+                rejectSave("source-changed", "Writable source changed.");
+            if (request.operation === "revert" && (source.revert?.baselineRevisionId !== request.baselineRevisionId ||
+                source.revert.sourceHash !== source.sourceHash)) {
+                reject("SAVE_EVIDENCE_CONFLICT", "Revert baseline/write ownership does not belong to this review.");
+            }
+        }
+        if (request.operation === "record-edit" && (request.editId === undefined) !== (request.editVersion === undefined)) {
+            reject("INVALID_INPUT", "Updating an edit requires its identity and version together.");
+        }
+        if ("editId" in request && request.editId !== undefined) {
+            const edit = ownedEdit(scope, items, request.pageKey, request.editId);
+            if (edit.version !== request.editVersion)
+                reject("VERSION_CONFLICT", "Edit changed.");
+            if (submissions.some((submission) => submission.edits.some((saved) => saved.reviewId === edit.reviewId && saved.editId === edit.editId))) {
+                reject("MESSAGE_IMMUTABLE", "Submitted edits are immutable; create a new record.");
+            }
+        }
+    }
+    return request;
+}
+export function assertEntityScope(scope, reference, entity) {
+    assertReviewScope(scope, reference);
+    if (!entity)
+        reject("NOT_FOUND", "Unknown identity; do not substitute the newest review.");
+    if (entity.reviewId !== reference.reviewId)
+        reject("SCOPE_MISMATCH", "Identity belongs to another review.");
+    if (entity.pageKey !== undefined)
+        assertReviewScope(scope, reference, [entity.pageKey]);
+}

package/lib/contracts/validation.js

@@ -0,0 +1,200 @@
+/** Pure boundary decoders: strict objects, no coercion, stripping, or truncation. */
+export const CONTRACT_LIMITS = Object.freeze({
+    requestBytes: 24 * 1024 * 1024,
+    quoteUnits: 4_000, contextUnits: 1_000, selectorUnits: 2_000, labelUnits: 500,
+    editCodePoints: 200_000, editAssets: 20,
+    pageDefault: 50, pageMaximum: 100,
+});
+export const ERROR_STATUS = {
+    INVALID_INPUT: 400, MALFORMED_JSON: 400, INVALID_CURSOR: 400,
+    UNAUTHORIZED: 401, SCOPE_MISMATCH: 403, NOT_FOUND: 404,
+    REQUEST_CONFLICT: 409, VERSION_CONFLICT: 409, REVIEW_ENDED: 409,
+    WORK_OUTSTANDING: 409, MESSAGE_IMMUTABLE: 409, THREAD_BUSY: 409,
+    SUBMISSION_ABANDONED: 409, ALREADY_HANDLED: 409, RESPONSE_COVERAGE: 409,
+    SAVE_EVIDENCE_CONFLICT: 409, EMPTY_SUBMISSION: 400,
+    WORKFLOW_REMOVED: 410,
+    INPUT_TOO_LARGE: 413, SNAPSHOT_TOO_LARGE: 413,
+    INTERNAL_ERROR: 500, STATE_PERSIST_FAILED: 503,
+};
+export class ContractError extends Error {
+    code;
+    path;
+    saveReason;
+    status;
+    constructor(code, message, path = "$", saveReason) {
+        super(`${path}: ${message}`);
+        this.code = code;
+        this.path = path;
+        this.saveReason = saveReason;
+        this.name = "ContractError";
+        this.status = ERROR_STATUS[code];
+    }
+}
+export function reject(code, message, path = "$") {
+    throw new ContractError(code, message, path);
+}
+export function rejectSave(reason, message) {
+    throw new ContractError("SAVE_EVIDENCE_CONFLICT", message, "$", reason);
+}
+export function schema(parse) {
+    return { parse: (value, path = "$") => parse(value, path) };
+}
+export function object(shape) {
+    return { fields: shape, ...schema((value, path) => {
+            if (!value || typeof value !== "object" || Array.isArray(value) ||
+                (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+                return reject("INVALID_INPUT", "Expected a JSON object.", path);
+            }
+            const input = value;
+            for (const key of Object.keys(input)) {
+                if (!Object.hasOwn(shape, key))
+                    reject("INVALID_INPUT", `Unknown field ${key}.`, path);
+            }
+            const output = {};
+            for (const [key, decoder] of Object.entries(shape)) {
+                if (!Object.hasOwn(input, key) && "optional" in decoder)
+                    continue;
+                output[key] = decoder.parse(input[key], `${path}.${key}`);
+            }
+            return output;
+        }) };
+}
+export function optional(inner) {
+    return { ...inner, optional: true };
+}
+export function nullable(inner) {
+    return schema((value, path) => value === null ? null : inner.parse(value, path));
+}
+export function literal(expected) {
+    return { literalValue: expected, ...schema((value, path) => value === expected ? expected : reject("INVALID_INPUT", `Expected ${expected}.`, path)) };
+}
+export function enumeration(values) {
+    return schema((value, path) => typeof value === "string" && values.includes(value)
+        ? value : reject("INVALID_INPUT", `Expected ${values.join(" | ")}.`, path));
+}
+export const booleanValue = schema((value, path) => typeof value === "boolean"
+    ? value : reject("INVALID_INPUT", "Expected a boolean.", path));
+export function integer(min = 0, max = Number.MAX_SAFE_INTEGER) {
+    return schema((value, path) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max
+        ? value : reject("INVALID_INPUT", `Expected an integer in ${min}..${max}.`, path));
+}
+export function text(max = Infinity, nonempty = true, codePoints = false) {
+    return schema((value, path) => {
+        if (typeof value !== "string" || (nonempty && !value.trim()))
+            reject("INVALID_INPUT", "Expected nonempty text.", path);
+        const length = codePoints ? [...value].length : value.length;
+        if (length > max)
+            reject("INPUT_TOO_LARGE", `Text exceeds ${max} ${codePoints ? "code points" : "UTF-16 units"}.`, path);
+        return value;
+    });
+}
+export const id = text();
+export const version = integer(1);
+export const timestamp = integer();
+export function array(inner, max = Infinity) {
+    return schema((value, path) => {
+        if (!Array.isArray(value))
+            reject("INVALID_INPUT", "Expected an array.", path);
+        if (value.length > max)
+            reject("INPUT_TOO_LARGE", `Array exceeds ${max} entries.`, path);
+        return Array.from(value, (entry, index) => inner.parse(entry, `${path}[${index}]`));
+    });
+}
+export function union(...members) {
+    const discriminant = Object.keys(members[0]?.fields ?? {}).find((key) => members.every((member) => member.fields?.[key]?.literalValue !== undefined) &&
+        new Set(members.map((member) => member.fields?.[key]?.literalValue)).size === members.length);
+    return schema((value, path) => {
+        if (discriminant && value && typeof value === "object") {
+            const tag = value[discriminant];
+            const selected = members.find((member) => member.fields?.[discriminant]?.literalValue === tag);
+            if (!selected)
+                reject("INVALID_INPUT", `Unknown ${discriminant}.`, path);
+            return selected.parse(value, path);
+        }
+        const errors = [];
+        for (const member of members) {
+            try {
+                return member.parse(value, path);
+            }
+            catch (error) {
+                if (!(error instanceof ContractError))
+                    throw error;
+                errors.push(error);
+            }
+        }
+        throw errors.find((error) => error.code === "INPUT_TOO_LARGE") ??
+            new ContractError("INVALID_INPUT", "No matching contract variant.", path);
+    });
+}
+export function refine(inner, check) {
+    return { ...inner, ...schema((value, path) => {
+            const parsed = inner.parse(value, path);
+            check(parsed);
+            return parsed;
+        }) };
+}
+export function unique(values, path = "$") {
+    if (new Set(values).size !== values.length)
+        reject("INVALID_INPUT", "Duplicate identity.", path);
+}
+export function utf8Length(value) {
+    let bytes = 0;
+    for (const character of value) {
+        const point = character.codePointAt(0);
+        bytes += point <= 0x7f ? 1 : point <= 0x7ff ? 2 : point <= 0xffff ? 3 : 4;
+    }
+    return bytes;
+}
+export function parseContractJson(raw, decoder) {
+    if (utf8Length(raw) > CONTRACT_LIMITS.requestBytes)
+        reject("INPUT_TOO_LARGE", "Request exceeds 24 MiB UTF-8.");
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return reject("MALFORMED_JSON", "Expected a JSON document.");
+    }
+    return decoder.parse(value);
+}
+/** Key order is immaterial; array order and exact text are part of a request. */
+export function canonicalJson(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number" && Number.isFinite(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${Array.from(value, canonicalJson).join(",")}]`;
+    if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    return reject("INVALID_INPUT", "Expected JSON data.");
+}
+export const failureSchema = refine(object({
+    ok: literal(false),
+    error: object({
+        code: enumeration(Object.keys(ERROR_STATUS)),
+        message: text(), status: integer(400, 599), retryable: booleanValue,
+        saveReason: optional(enumeration(["source-changed", "source-unavailable", "evidence-mismatch", "unsafe-content"])),
+    }),
+}), ({ error }) => {
+    if (error.status !== ERROR_STATUS[error.code] || error.retryable !== (error.code === "STATE_PERSIST_FAILED")) {
+        reject("INVALID_INPUT", "Error code/status/retryability mismatch.");
+    }
+    if (error.saveReason && error.code !== "SAVE_EVIDENCE_CONFLICT")
+        reject("INVALID_INPUT", "Save reason requires a save conflict.");
+});
+export function contractFailure(error) {
+    return failureSchema.parse({ ok: false, error: {
+            code: error.code, message: error.message, status: error.status, retryable: error.code === "STATE_PERSIST_FAILED",
+            ...(error.saveReason ? { saveReason: error.saveReason } : {}),
+        } });
+}
+export function transportOutcomeSchema(accepted) {
+    return union(object({ state: literal("accepted"), value: accepted }), object({ state: literal("rejected"), failure: failureSchema }), object({ state: literal("unknown"), requestId: id, reason: enumeration([
+            "timeout", "disconnected", "invalid-response", "unavailable",
+        ]) }));
+}

package/lib/conversation-anchor-controller.js

@@ -0,0 +1,84 @@
+import { frameAnchorsSchema, frameAnchorStatesSchema, frameThreadActionSchema, isCurrentFrameProjection, sameFrameAnchorProjection, validateFrameAnchorStates, validateFrameThreadAction, } from "./contracts/frame.js";
+import { reject } from "./contracts/validation.js";
+import { sameThreadTarget } from "./comment-target.js";
+export function describeConversationAnchor(state) {
+    if (!state)
+        return { canJump: false, offscreen: false, reason: "Checking the target in the current render." };
+    if (state.state === "found")
+        return {
+            canJump: true, offscreen: state.relation !== "visible",
+            reason: "",
+        };
+    const reason = state.state === "missing" ? "The original target was not found. The conversation is still available."
+        : state.state === "ambiguous" ? "Multiple targets match. No highlight or jump was chosen."
+            : ({
+                hidden: "The target is hidden. Reveal it in the document before showing it.",
+                "not-measurable": "The target cannot currently be measured.",
+                "invalid-selector": "The original element selector is unavailable in this render.",
+                "render-loading": "The document is still loading; target availability is not known.",
+                "render-changed": "The render or element identity changed. No replacement target was chosen.",
+                "render-unavailable": "The document render is unavailable; this does not mean the source target is missing.",
+            }[state.reason]);
+    return { canJump: false, offscreen: false, reason };
+}
+/** Shell-side geometry only; the conversation owner retains all user state. */
+export function createConversationAnchorController() {
+    let projection = null;
+    let states = [];
+    let revision = 0;
+    return {
+        get projection() { return projection; },
+        get states() { return states; },
+        reset() { projection = null; states = []; },
+        project(input) {
+            const next = frameAnchorsSchema.parse({ ...input, projectionRevision: revision + 1 });
+            if (projection && sameFrameAnchorProjection(next, projection))
+                return false;
+            const sameRender = projection && ["capability", "reviewId", "pageKey", "renderId", "generation"].every((key) => projection[key] === next[key]);
+            states = sameRender ? states.filter((state) => next.anchors.some((anchor) => anchor.threadId === state.threadId &&
+                JSON.stringify(anchor.target) === JSON.stringify(projection.anchors.find((previous) => previous.threadId === state.threadId)?.target))) : [];
+            projection = next;
+            revision = next.projectionRevision;
+            return true;
+        },
+        receive(input) {
+            if (!projection)
+                return reject("SCOPE_MISMATCH", "No current conversation projection.");
+            const report = frameAnchorStatesSchema.parse(input);
+            if (!isCurrentFrameProjection(report, projection))
+                return false;
+            states = validateFrameAnchorStates(report, projection).anchors;
+            return true;
+        },
+        incoming(input) {
+            if (!projection)
+                return reject("SCOPE_MISMATCH", "No current conversation projection.");
+            const action = frameThreadActionSchema.parse(input);
+            if (action.action === "reveal")
+                reject("INVALID_INPUT", "Only the shell may request target reveal.");
+            if (!isCurrentFrameProjection(action, projection))
+                return null;
+            validateFrameThreadAction(action, projection);
+            if (action.action === "activate" && !states.some((state) => state.threadId === action.threadId && state.state === "found")) {
+                reject("INVALID_INPUT", "Activation requires a currently verified target.");
+            }
+            return action;
+        },
+        outgoing(action, threadId) {
+            if (!projection)
+                return reject("SCOPE_MISMATCH", "No current conversation projection.");
+            if (action !== "dismiss" && !states.some((state) => state.threadId === threadId && state.state === "found")) {
+                reject("INVALID_INPUT", "Target is not currently available. Continue in Feedback.");
+            }
+            const { anchors: _anchors, ...scope } = projection;
+            return validateFrameThreadAction({ ...scope, type: "eh:threadAction", action, threadId }, projection);
+        },
+        peers(threadId) {
+            const own = states.find((state) => state.threadId === threadId);
+            if (own?.state !== "found")
+                return [threadId];
+            return states.filter((state) => sameThreadTarget(state, own))
+                .map((state) => state.threadId);
+        },
+    };
+}

package/lib/conversation-capture.js

@@ -0,0 +1,81 @@
+import { ApiError, record } from "./chrome-api.js";
+import { normalizeView } from "./view-identity.js";
+export function resultCaptureKey(scope) {
+    const view = normalizeView(scope.view);
+    return JSON.stringify([scope.reviewId, scope.entryKey, scope.submissionId, scope.pageKey,
+        scope.sessionId, scope.renderId, scope.generation, scope.sourceHash,
+        view.status, view.tabs.map(({ groupId, tabId, panelId }) => [groupId, tabId, panelId])]);
+}
+export function decodeComparison(value, mode) {
+    const result = record(value);
+    if (typeof result.available !== "boolean" || result.mode !== mode)
+        throw new Error("Invalid comparison response.");
+    return result;
+}
+/** Automatic and explicit captures share one flight for the exact observed scope. */
+export function createResultCaptures(options) {
+    const flights = new Map();
+    const failures = new Map();
+    const resultKey = (scope) => JSON.stringify([scope.reviewId, scope.entryKey, scope.submissionId, scope.pageKey]);
+    const requireCurrent = (scope) => {
+        if (!options.current(scope))
+            throw new Error("The page or visible view changed during capture. Retry on the current page.");
+    };
+    const content = async (scope) => {
+        requireCurrent(scope);
+        const value = decodeComparison(await options.compare(scope), "content");
+        requireCurrent(scope);
+        return value;
+    };
+    function request(scope) {
+        const key = resultCaptureKey(scope), existing = flights.get(key);
+        if (existing)
+            return existing;
+        const flight = Promise.resolve().then(async () => {
+            try {
+                let value = await content(scope);
+                if (!value.available) {
+                    try {
+                        requireCurrent(scope);
+                        await options.capture(scope);
+                    }
+                    catch (error) {
+                        requireCurrent(scope);
+                        if (!(error instanceof ApiError && error.status === 409 && error.code === "VERSION_CONFLICT"))
+                            throw error;
+                        value = await content(scope);
+                        if (!value.available)
+                            throw error;
+                    }
+                    value = await content(scope);
+                    requireCurrent(scope);
+                    await options.refresh();
+                    requireCurrent(scope);
+                }
+                if (!value.available)
+                    throw new Error(typeof value.reason === "string" ? value.reason : "Rendered Content comparison is unavailable.");
+                failures.delete(resultKey(scope));
+            }
+            catch (error) {
+                if (options.current(scope))
+                    failures.set(resultKey(scope), {
+                        scope, message: error instanceof Error ? error.message : String(error),
+                    });
+                throw error;
+            }
+            finally {
+                options.changed();
+            }
+        }).finally(() => { flights.delete(key); });
+        flights.set(key, flight);
+        return flight;
+    }
+    return {
+        request,
+        confirmContent(scope, value) {
+            if (decodeComparison(value, "content").available && failures.delete(resultKey(scope)))
+                options.changed();
+        },
+        get failures() { return [...failures.values()]; },
+    };
+}