@erdemtuna/doc-review 0.12.0 → 0.14.0

package/lib/contracts/feedback.js

@@ -1 +1,369 @@
-export {};
+import { array, booleanValue, canonicalJson, CONTRACT_LIMITS, enumeration, id, integer, literal, nullable, object, optional, refine, reject, text, timestamp, union, unique, version, } from "./validation.js";
+export const intentSchema = enumeration(["discuss", "request-change"]);
+export const DEFAULT_REVIEWER_INTENT = "discuss";
+export function intentBadge(intent) {
+    return intentSchema.parse(intent) === "discuss" ? "Discussion" : "Change requested";
+}
+export const conversationTargetSchema = union(object({
+    kind: literal("selection"),
+    anchor: object({
+        quote: text(CONTRACT_LIMITS.quoteUnits),
+        prefix: optional(text(CONTRACT_LIMITS.contextUnits, false)),
+        suffix: optional(text(CONTRACT_LIMITS.contextUnits, false)),
+        selector: optional(text(CONTRACT_LIMITS.selectorUnits)),
+    }),
+}), object({
+    kind: literal("element"),
+    anchor: object({
+        selector: text(CONTRACT_LIMITS.selectorUnits),
+        label: optional(text(CONTRACT_LIMITS.labelUnits, false)),
+    }),
+}));
+export const overallNoteSchema = object({ body: text(), intent: intentSchema });
+export const messageOutcomeSchema = enumeration(["applied", "answered", "clarification-needed", "deferred"]);
+export const editOutcomeSchema = enumeration(["applied", "already-saved", "deferred"]);
+const messageFields = {
+    messageId: id, reviewId: id, threadId: id, version, sequence: integer(1),
+    createdAt: timestamp, updatedAt: timestamp, body: text(),
+};
+export const reviewerMessageSchema = object({
+    ...messageFields, author: literal("reviewer"), intent: intentSchema, submissionId: nullable(id),
+});
+export const agentMessageSchema = object({
+    ...messageFields, author: literal("agent"), submissionId: id, replyToMessageId: id,
+    outcome: messageOutcomeSchema,
+});
+export const conversationMessageSchema = union(reviewerMessageSchema, agentMessageSchema);
+export const conversationThreadSchema = object({
+    threadId: id, reviewId: id, pageKey: id, version, sequence: integer(1),
+    target: conversationTargetSchema, status: enumeration(["open", "resolved"]),
+    createdAt: timestamp, updatedAt: timestamp,
+});
+const editTextSchema = text(CONTRACT_LIMITS.editCodePoints, false, true);
+const editTextFields = ["before", "after", "before_html", "after_html", "moved_after", "moved_before"];
+const editContentFields = {
+    label: text(), before: optional(editTextSchema), after: optional(editTextSchema),
+    before_html: optional(editTextSchema), after_html: optional(editTextSchema),
+    truncated: booleanValue, truncated_fields: array(enumeration(editTextFields), editTextFields.length),
+    staged_assets: array(object({ id, preview_src: text() }), CONTRACT_LIMITS.editAssets),
+};
+export const directEditContentSchema = refine(union(object({ ...editContentFields, kind: literal("edited") }), object({ ...editContentFields, kind: literal("deleted") }), object({ ...editContentFields, kind: literal("moved"), moved_after: editTextSchema, moved_before: editTextSchema })), (edit) => {
+    unique(edit.truncated_fields);
+    unique(edit.staged_assets.map((asset) => asset.id));
+    if (edit.truncated !== (edit.truncated_fields.length > 0))
+        reject("INVALID_INPUT", "Inconsistent truncation metadata.");
+    for (const field of edit.truncated_fields) {
+        if (!(field in edit))
+            reject("INVALID_INPUT", "Truncated field must be preserved.");
+    }
+    if (edit.before === undefined && edit.before_html === undefined)
+        reject("INVALID_INPUT", "An edit requires its before content.");
+    if (edit.kind === "edited" && edit.after === undefined && edit.after_html === undefined) {
+        reject("INVALID_INPUT", "An edited block requires its after content.");
+    }
+});
+export const saveEvidenceSchema = object({
+    evidenceId: id, reviewId: id, pageKey: id, editId: id, editVersion: version,
+    sourceHash: id, savedAt: timestamp,
+});
+export const directEditSchema = refine(object({
+    editId: id, reviewId: id, pageKey: id, version, sequence: integer(1),
+    author: literal("reviewer"), createdAt: timestamp, updatedAt: timestamp,
+    content: directEditContentSchema,
+    source: union(object({ state: literal("pending") }), object({ state: literal("saved"), evidence: saveEvidenceSchema })),
+    assets: array(object({ id, path: text(), preview_src: text() }), CONTRACT_LIMITS.editAssets),
+}), (edit) => {
+    unique(edit.assets.map((asset) => asset.id));
+    if (canonicalJson(edit.assets.map(({ id: assetId, preview_src }) => ({ id: assetId, preview_src }))) !==
+        canonicalJson(edit.content.staged_assets))
+        reject("INVALID_INPUT", "Durable assets must match staged references.");
+    if (edit.source.state === "saved") {
+        const evidence = edit.source.evidence;
+        if (evidence.reviewId !== edit.reviewId || evidence.pageKey !== edit.pageKey ||
+            evidence.editId !== edit.editId || evidence.editVersion !== edit.version || edit.content.truncated) {
+            reject("SAVE_EVIDENCE_CONFLICT", "Save evidence does not describe this exact complete edit.");
+        }
+    }
+});
+export function validateSaveEvidence(edit, currentSourceHash, writable) {
+    directEditSchema.parse(edit);
+    if (edit.source.state !== "saved" || !writable || edit.source.evidence.sourceHash !== currentSourceHash) {
+        reject("SAVE_EVIDENCE_CONFLICT", "Current writable source does not match server-owned save evidence.");
+    }
+}
+export const messageSelectionSchema = object({ threadId: id, messageId: id, version });
+export const editSelectionSchema = object({ pageKey: id, editId: id, version });
+export const submittedMessageSchema = object({
+    pageKey: id, target: conversationTargetSchema, message: reviewerMessageSchema,
+});
+export const submissionSchema = refine(object({
+    submissionId: id, reviewId: id, entryKey: id, version, sequence: integer(1),
+    state: enumeration(["queued", "delivered", "handled", "abandoned"]),
+    createdAt: timestamp, deliveredAt: nullable(timestamp), completedAt: nullable(timestamp),
+    pageKeys: array(id), exclusionKeys: array(id),
+    messages: array(submittedMessageSchema), edits: array(directEditSchema),
+    overallNote: optional(overallNoteSchema),
+    resultId: nullable(id), abandonment: nullable(object({ requestId: id, at: timestamp, reason: text() })),
+}), (submission) => {
+    unique(submission.pageKeys);
+    unique(submission.exclusionKeys);
+    unique(submission.messages.map(({ message }) => message.messageId));
+    unique(submission.edits.map((edit) => edit.editId));
+    if (!submission.pageKeys.length ||
+        (!submission.messages.length && !submission.edits.length && !submission.overallNote)) {
+        reject("EMPTY_SUBMISSION", "Select known pages and at least one message, edit, or overall note.");
+    }
+    const expectedKeys = exclusionKeys(submission.entryKey, submission.pageKeys);
+    if (canonicalJson(expectedKeys) !== canonicalJson(submission.exclusionKeys)) {
+        reject("INVALID_INPUT", "Exclusions must be the sorted entry and submitted page target keys.");
+    }
+    for (const { pageKey, message } of submission.messages) {
+        if (message.reviewId !== submission.reviewId || message.submissionId !== submission.submissionId ||
+            !submission.pageKeys.includes(pageKey))
+            reject("SCOPE_MISMATCH", "Message is outside the submission.");
+    }
+    for (const edit of submission.edits) {
+        if (edit.reviewId !== submission.reviewId || !submission.pageKeys.includes(edit.pageKey)) {
+            reject("SCOPE_MISMATCH", "Edit is outside the submission.");
+        }
+    }
+    if ((submission.state === "queued" && submission.deliveredAt !== null) ||
+        ((submission.state === "delivered" || submission.state === "handled") && submission.deliveredAt === null) ||
+        ((submission.state === "handled" || submission.state === "abandoned") !== (submission.completedAt !== null)) ||
+        ((submission.state === "handled") !== (submission.resultId !== null)) ||
+        ((submission.state === "abandoned") !== (submission.abandonment !== null))) {
+        reject("INVALID_INPUT", "Inconsistent submission lifecycle evidence.");
+    }
+});
+export const inlineResponseSchema = object({
+    threadId: id, messageId: id, messageVersion: version, body: text(), outcome: messageOutcomeSchema,
+});
+export const directEditOutcomeSchema = object({
+    editId: id, editVersion: version, outcome: editOutcomeSchema, reason: text(),
+});
+export const completeResponseSchema = object({
+    operation: literal("respond"), reviewId: id, entryKey: id, submissionId: id,
+    requestId: id, expectedVersion: version,
+    responses: array(inlineResponseSchema), editOutcomes: array(directEditOutcomeSchema),
+    resultNote: text(), summary: optional(text()), overallOutcome: optional(messageOutcomeSchema),
+});
+export function validateResponseCoverage(input, delivered) {
+    const response = completeResponseSchema.parse(input);
+    const submission = submissionSchema.parse(delivered);
+    if (response.reviewId !== submission.reviewId || response.entryKey !== submission.entryKey ||
+        response.submissionId !== submission.submissionId)
+        reject("SCOPE_MISMATCH", "Response belongs to another submission.");
+    if (submission.state === "abandoned")
+        reject("SUBMISSION_ABANDONED", "Abandonment won; late completion is rejected.");
+    if (submission.state === "handled")
+        reject("ALREADY_HANDLED", "Use the original response request for replay.");
+    if (submission.state !== "delivered")
+        reject("RESPONSE_COVERAGE", "Only delivered work can be completed.");
+    if (response.expectedVersion !== submission.version)
+        reject("VERSION_CONFLICT", "Submission version changed.");
+    const messages = new Map(submission.messages.map(({ message }) => [message.messageId, message]));
+    const edits = new Map(submission.edits.map((edit) => [edit.editId, edit]));
+    if (response.responses.length !== messages.size || response.editOutcomes.length !== edits.size) {
+        reject("RESPONSE_COVERAGE", "Every submitted message and exact edit must have one outcome.");
+    }
+    for (const reply of response.responses) {
+        const message = messages.get(reply.messageId);
+        if (!message || reply.threadId !== message.threadId || reply.messageVersion !== message.version) {
+            reject("RESPONSE_COVERAGE", "Unknown, duplicate, or mismatched message response.");
+        }
+        if (message.intent === "discuss" && reply.outcome === "applied")
+            reject("RESPONSE_COVERAGE", "Discuss cannot authorize Applied.");
+        messages.delete(reply.messageId);
+    }
+    for (const outcome of response.editOutcomes) {
+        const edit = edits.get(outcome.editId);
+        if (!edit || outcome.editVersion !== edit.version)
+            reject("RESPONSE_COVERAGE", "Unknown, duplicate, or mismatched edit.");
+        if ((outcome.outcome === "already-saved" && edit.source.state !== "saved") ||
+            (outcome.outcome === "applied" && (edit.source.state === "saved" || edit.content.truncated))) {
+            reject("SAVE_EVIDENCE_CONFLICT", "Outcome cannot claim new work or saved evidence for this edit.");
+        }
+        edits.delete(outcome.editId);
+    }
+    if ((submission.overallNote !== undefined) !== (response.overallOutcome !== undefined) ||
+        (submission.overallNote?.intent === "discuss" && response.overallOutcome === "applied")) {
+        reject("RESPONSE_COVERAGE", "Overall outcome requires its own nonempty note and intent.");
+    }
+    return response;
+}
+export function responseEffect(response) {
+    completeResponseSchema.parse(response);
+    return response.responses.some((reply) => reply.outcome === "applied") ||
+        response.editOutcomes.some((edit) => edit.outcome === "applied") || response.overallOutcome === "applied"
+        ? "changes-reported" : "reply-only";
+}
+export const submissionResultSchema = object({
+    resultId: id, reviewId: id, submissionId: id, createdAt: timestamp, sequence: integer(1),
+    author: literal("agent"), body: text(), summary: optional(text()), title: enumeration(["What changed", "Agent response"]),
+    effect: enumeration(["reply-only", "changes-reported"]),
+    responses: array(agentMessageSchema), editOutcomes: array(directEditOutcomeSchema),
+    overallOutcome: optional(messageOutcomeSchema),
+});
+export function resultTitle(response) {
+    completeResponseSchema.parse(response);
+    return responseEffect(response) === "changes-reported" ||
+        response.editOutcomes.some((edit) => edit.outcome === "already-saved") ? "What changed" : "Agent response";
+}
+const mutationFields = { reviewId: id, entryKey: id, requestId: id, expectedVersion: version };
+export const joinReviewPageRequestSchema = object({
+    ...mutationFields, operation: literal("join-page"), target: text(),
+});
+export const sendRequestSchema = refine(object({
+    ...mutationFields, operation: literal("send"),
+    pageKeys: array(id), messages: array(messageSelectionSchema), edits: array(editSelectionSchema),
+    overallNote: optional(overallNoteSchema),
+}), (request) => {
+    unique(request.pageKeys);
+    unique(request.messages.map((message) => message.messageId));
+    unique(request.edits.map((edit) => edit.editId));
+    if (!request.pageKeys.length || (!request.messages.length && !request.edits.length && !request.overallNote)) {
+        reject("EMPTY_SUBMISSION", "Send requires selected known pages and feedback.");
+    }
+    if (request.edits.some((edit) => !request.pageKeys.includes(edit.pageKey)))
+        reject("SCOPE_MISMATCH", "Unselected edit page.");
+});
+export const reviewerMutationSchema = union(joinReviewPageRequestSchema, object({ ...mutationFields, operation: literal("create-thread"), pageKey: id, target: conversationTargetSchema,
+    body: text(), intent: intentSchema }), object({ ...mutationFields, operation: literal("reply"), threadId: id, body: text(), intent: intentSchema }), object({ ...mutationFields, operation: literal("update-message"), threadId: id, messageId: id,
+    messageVersion: version, body: text(), intent: intentSchema }), object({ ...mutationFields, operation: literal("set-thread-status"), threadId: id, status: enumeration(["open", "resolved"]) }), object({ ...mutationFields, operation: literal("delete-thread"), threadId: id }), object({ ...mutationFields, operation: literal("record-edit"), pageKey: id,
+    editId: optional(id), editVersion: optional(version), content: directEditContentSchema }), object({ ...mutationFields, operation: literal("save-edit"), pageKey: id, editId: id, editVersion: version,
+    expectedSourceHash: id, html: text(Infinity, false) }), object({ ...mutationFields, operation: literal("revert"), pageKey: id, expectedSourceHash: id, baselineRevisionId: id }), sendRequestSchema, object({ ...mutationFields, operation: literal("end"), confirmUnsentReadOnly: literal(true) }));
+export const abandonRequestSchema = object({
+    ...mutationFields, operation: literal("abandon"), submissionId: id,
+    confirmExternalWorkMayContinue: literal(true), reason: text(),
+});
+export const receiptValueSchema = object({
+    reviewVersion: version,
+    pageKey: optional(id), threadId: optional(id), messageId: optional(id), editId: optional(id),
+    submissionId: optional(id), resultId: optional(id),
+});
+export const mutationOperationSchema = enumeration([
+    "open", "join-page", "create-thread", "reply", "update-message", "set-thread-status", "delete-thread",
+    "record-edit", "save-edit", "revert", "send", "end", "abandon", "respond",
+]);
+export const handlingReceiptSchema = refine(object({
+    receiptId: id, requestId: id, reviewId: id, entryKey: id,
+    operation: mutationOperationSchema, acceptedAt: timestamp, value: receiptValueSchema,
+}), (receipt) => {
+    const required = {
+        "join-page": ["pageKey"],
+        "create-thread": ["threadId", "messageId"], reply: ["threadId", "messageId"],
+        "update-message": ["threadId", "messageId"], "set-thread-status": ["threadId"], "delete-thread": ["threadId"],
+        "record-edit": ["editId"], "save-edit": ["editId"], send: ["submissionId"],
+        abandon: ["submissionId"], respond: ["submissionId", "resultId"],
+    };
+    for (const field of required[receipt.operation] ?? []) {
+        if (receipt.value[field] === undefined)
+            reject("INVALID_INPUT", `Receipt requires ${field}.`);
+    }
+    const allowed = new Set(["reviewVersion", ...required[receipt.operation] ?? []]);
+    for (const field of Object.keys(receipt.value)) {
+        if (!allowed.has(field))
+            reject("INVALID_INPUT", `Receipt operation does not produce ${field}.`);
+    }
+});
+export const acceptedMutationSchema = object({ ok: literal(true), receipt: handlingReceiptSchema });
+export const receiptLookupSchema = union(object({ state: literal("accepted"), receipt: handlingReceiptSchema }), object({ state: literal("not-found"), requestId: id }));
+/** Call after authentication/scope checks, but before ANY version/lifecycle/exclusion check. */
+export function exactReplay(request, previous) {
+    if (!previous)
+        return null;
+    const receipt = handlingReceiptSchema.parse(previous.receipt);
+    if (request.requestId !== receipt.requestId || canonicalJson(request) !== previous.canonicalPayload) {
+        reject("REQUEST_CONFLICT", "Request identity was already used with different content.");
+    }
+    if (request.operation !== receipt.operation || (request.reviewId !== undefined && request.reviewId !== receipt.reviewId) ||
+        (request.entryKey !== undefined && request.entryKey !== receipt.entryKey)) {
+        reject("INVALID_INPUT", "Stored replay receipt does not match its request scope/operation.");
+    }
+    return receipt;
+}
+export function exclusionKeys(entryKey, pageKeys) {
+    id.parse(entryKey);
+    array(id).parse(pageKeys);
+    return [...new Set([entryKey, ...pageKeys])].sort();
+}
+export function outstandingSubmissions(targets, submissions) {
+    return submissions.filter((submission) => {
+        submissionSchema.parse(submission);
+        return (submission.state === "queued" || submission.state === "delivered") &&
+            submission.exclusionKeys.some((key) => targets.includes(key));
+    }).map((submission) => submission.submissionId);
+}
+export function assertNoOutstandingWork(targets, submissions) {
+    if (outstandingSubmissions(targets, submissions).length)
+        reject("WORK_OUTSTANDING", "A known canonical target has outstanding work.");
+}
+export function validateAbandonment(input, current) {
+    const request = abandonRequestSchema.parse(input);
+    submissionSchema.parse(current);
+    if (request.reviewId !== current.reviewId || request.entryKey !== current.entryKey ||
+        request.submissionId !== current.submissionId)
+        reject("SCOPE_MISMATCH", "Submission belongs to another review.");
+    if (current.state === "handled")
+        reject("ALREADY_HANDLED", "Response committed first; abandonment is inapplicable.");
+    if (current.state === "abandoned")
+        reject("SUBMISSION_ABANDONED", "Use the original abandonment request for replay.");
+    if (request.expectedVersion !== current.version)
+        reject("VERSION_CONFLICT", "Submission version changed.");
+    return request;
+}
+/** Validate the complete transaction's public artifacts, not an acknowledgement-only receipt. */
+export function validateResponseCommit(submission, input, resultInput, receiptInput) {
+    const response = validateResponseCoverage(input, submission);
+    const result = submissionResultSchema.parse(resultInput);
+    const receipt = handlingReceiptSchema.parse(receiptInput);
+    if (result.reviewId !== submission.reviewId || result.submissionId !== submission.submissionId ||
+        result.body !== response.resultNote || result.summary !== response.summary || result.title !== resultTitle(response) ||
+        result.effect !== responseEffect(response) || result.overallOutcome !== response.overallOutcome ||
+        canonicalJson(result.editOutcomes) !== canonicalJson(response.editOutcomes) ||
+        result.responses.length !== response.responses.length) {
+        reject("RESPONSE_COVERAGE", "Result does not represent the complete accepted response.");
+    }
+    unique(result.responses.map((reply) => reply.messageId));
+    for (let index = 0; index < response.responses.length; index++) {
+        const inputReply = response.responses[index];
+        const savedReply = result.responses[index];
+        if (savedReply.reviewId !== submission.reviewId || savedReply.submissionId !== submission.submissionId ||
+            savedReply.threadId !== inputReply.threadId || savedReply.replyToMessageId !== inputReply.messageId ||
+            savedReply.body !== inputReply.body || savedReply.outcome !== inputReply.outcome) {
+            reject("RESPONSE_COVERAGE", "Persisted reply association differs from accepted response.");
+        }
+    }
+    if (receipt.operation !== "respond" || receipt.requestId !== response.requestId ||
+        receipt.reviewId !== result.reviewId || receipt.entryKey !== submission.entryKey ||
+        receipt.value.submissionId !== result.submissionId || receipt.value.resultId !== result.resultId) {
+        reject("RESPONSE_COVERAGE", "Atomic result and handling receipt disagree.");
+    }
+    return { result, receipt };
+}
+export const submissionReadSchema = refine(object({
+    submission: submissionSchema, result: nullable(submissionResultSchema), receipt: nullable(handlingReceiptSchema),
+}), ({ submission, result, receipt }) => {
+    if (submission.state !== "handled") {
+        if (result !== null || receipt !== null)
+            reject("INVALID_INPUT", "Uncompleted work cannot claim a handling result.");
+        return;
+    }
+    if (!result || !receipt || result.resultId !== submission.resultId)
+        reject("RESPONSE_COVERAGE", "Handled submission requires its result and receipt.");
+    const responses = result.responses.map((reply) => {
+        const message = submission.messages.find((item) => item.message.messageId === reply.replyToMessageId)?.message;
+        if (!message)
+            reject("RESPONSE_COVERAGE", "Reply references an unknown submitted message.");
+        return { threadId: reply.threadId, messageId: message.messageId, messageVersion: message.version,
+            body: reply.body, outcome: reply.outcome };
+    });
+    const deliveredVersion = submission.version - 1;
+    validateResponseCommit({ ...submission, version: deliveredVersion, state: "delivered", completedAt: null, resultId: null }, {
+        operation: "respond", reviewId: submission.reviewId, entryKey: submission.entryKey, submissionId: submission.submissionId,
+        requestId: receipt.requestId, expectedVersion: deliveredVersion,
+        responses, editOutcomes: result.editOutcomes, resultNote: result.body,
+        ...(result.summary === undefined ? {} : { summary: result.summary }),
+        ...(result.overallOutcome === undefined ? {} : { overallOutcome: result.overallOutcome }),
+    }, result, receipt);
+});

package/lib/contracts/frame.js

@@ -1,3 +1,5 @@
+import { conversationTargetSchema } from "./feedback.js";
+import { array, booleanValue, enumeration, id, integer, literal, object, optional, refine, reject, schema, union, unique, } from "./validation.js";
 export function isThemePayload(value) {
     return typeof value === "object" && value !== null &&
         "theme" in value && (value.theme === "light" || value.theme === "dark") &&
@@ -11,3 +13,82 @@ export function isFrameIdentity(value) {
         "generation" in value && typeof value.generation === "number" &&
         "pageKey" in value && typeof value.pageKey === "string";
 }
+const finiteCoordinate = schema((value, path) => typeof value === "number" && Number.isFinite(value)
+    ? value : reject("INVALID_INPUT", "Expected finite geometry.", path));
+const dimension = refine(finiteCoordinate, (value) => {
+    if (value < 0)
+        reject("INVALID_INPUT", "Negative geometry dimension.");
+});
+export const conversationRectSchema = refine(object({
+    left: finiteCoordinate, top: finiteCoordinate, right: finiteCoordinate, bottom: finiteCoordinate,
+    width: dimension, height: dimension,
+}), (rect) => {
+    if (rect.right < rect.left || rect.bottom < rect.top)
+        reject("INVALID_INPUT", "Inverted geometry.");
+});
+const renderScopeFields = { capability: id, reviewId: id, pageKey: id, renderId: id, generation: integer(1) };
+const projectionScopeFields = { ...renderScopeFields, projectionRevision: integer(1) };
+export const anchorProjectionSchema = object({ threadId: id, target: conversationTargetSchema, resolved: optional(booleanValue) });
+export const frameAnchorsSchema = refine(object({
+    type: literal("eh:threadAnchors"), ...projectionScopeFields, anchors: array(anchorProjectionSchema),
+}), ({ anchors }) => unique(anchors.map((anchor) => anchor.threadId)));
+const anchorStateFields = { threadId: id };
+export const anchorStateSchema = union(object({
+    ...anchorStateFields, state: literal("found"),
+    rects: refine(array(conversationRectSchema), (rects) => {
+        if (!rects.length)
+            reject("INVALID_INPUT", "Found target needs geometry.");
+    }),
+    viewport: object({ width: dimension, height: dimension }),
+    relation: enumeration(["visible", "above", "below", "left", "right"]),
+}), object({ ...anchorStateFields, state: literal("missing") }), object({ ...anchorStateFields, state: literal("ambiguous"), candidateCount: integer(2) }), object({ ...anchorStateFields, state: literal("unavailable"),
+    reason: enumeration(["render-loading", "render-changed", "render-unavailable", "hidden", "not-measurable", "invalid-selector"]) }));
+export const frameAnchorStatesSchema = refine(object({
+    type: literal("eh:threadAnchorStates"), ...projectionScopeFields, anchors: array(anchorStateSchema),
+}), ({ anchors }) => unique(anchors.map((anchor) => anchor.threadId)));
+export const frameThreadActionSchema = object({
+    type: literal("eh:threadAction"), ...projectionScopeFields,
+    action: enumeration(["activate", "reveal", "dismiss"]), threadId: id,
+});
+function validateRenderScope(states, projection) {
+    if (states.reviewId !== projection.reviewId || states.pageKey !== projection.pageKey ||
+        states.renderId !== projection.renderId || states.generation !== projection.generation ||
+        states.capability !== projection.capability) {
+        reject("SCOPE_MISMATCH", "Stale or foreign render geometry/action.");
+    }
+}
+const renderScopeSchema = object(renderScopeFields);
+/** Classify only parsed messages; foreign scope and future revisions are errors. */
+export function isCurrentFrameProjection(value, projection) {
+    validateRenderScope(value, projection);
+    if (value.projectionRevision > projection.projectionRevision) {
+        reject("SCOPE_MISMATCH", "Unknown future anchor projection revision.");
+    }
+    return value.projectionRevision === projection.projectionRevision;
+}
+export function sameFrameAnchorProjection(left, right) {
+    return Object.keys(renderScopeFields).every((key) => left[key] === right[key]) &&
+        left.anchors.length === right.anchors.length && left.anchors.every((anchor) => right.anchors.some((other) => anchor.threadId === other.threadId && !!anchor.resolved === !!other.resolved &&
+        JSON.stringify(anchor.target) === JSON.stringify(other.target)));
+}
+export function validateFrameThreadAction(input, projectionInput) {
+    const action = frameThreadActionSchema.parse(input);
+    const projection = frameAnchorsSchema.parse(projectionInput);
+    if (!isCurrentFrameProjection(action, projection))
+        reject("SCOPE_MISMATCH", "Stale anchor projection action.");
+    if (!projection.anchors.some((anchor) => anchor.threadId === action.threadId)) {
+        reject("SCOPE_MISMATCH", "Thread action is outside the current projection.");
+    }
+    return action;
+}
+export function validateFrameAnchorStates(input, projectionInput) {
+    const states = frameAnchorStatesSchema.parse(input);
+    const projection = frameAnchorsSchema.parse(projectionInput);
+    if (!isCurrentFrameProjection(states, projection))
+        reject("SCOPE_MISMATCH", "Stale anchor projection geometry.");
+    if (states.anchors.length !== projection.anchors.length ||
+        states.anchors.some((state) => !projection.anchors.some((anchor) => anchor.threadId === state.threadId))) {
+        reject("SCOPE_MISMATCH", "Anchor states must cover exactly the projected threads.");
+    }
+    return states;
+}

package/lib/contracts/history.js

@@ -1 +1,189 @@
-export {};
+import { agentMessageSchema, conversationThreadSchema, directEditSchema, directEditOutcomeSchema, reviewerMessageSchema, } from "./feedback.js";
+import { array, canonicalJson, ContractError, CONTRACT_LIMITS, enumeration, id, integer, literal, nullable, object, optional, refine, reject, text, timestamp, } from "./validation.js";
+export const pagingScopeSchema = refine(object({
+    reviewId: id, entryKey: id,
+    collection: enumeration(["threads", "context", "history", "pages", "edits", "edit-attention", "comparisons"]),
+    pageKey: nullable(id), threadId: nullable(id), submissionId: nullable(id),
+    status: enumeration(["open", "resolved", "all"]),
+}), (scope) => {
+    if ((scope.collection === "context") !== (scope.threadId !== null))
+        reject("INVALID_INPUT", "Only context requires a thread.");
+    if ((scope.collection === "comparisons") !== (scope.submissionId !== null))
+        reject("INVALID_INPUT", "Only comparisons requires a submission.");
+    if (scope.collection !== "threads" && scope.status !== "all")
+        reject("INVALID_INPUT", "Status filter applies only to threads.");
+});
+export const pageQuerySchema = object({
+    limit: optional(integer(1, CONTRACT_LIMITS.pageMaximum)), cursor: optional(text()),
+});
+export const conversationListRequestSchema = object({
+    operation: literal("list"), scope: pagingScopeSchema, query: pageQuerySchema,
+});
+export const pageCursorSchema = object({
+    scope: pagingScopeSchema, highWater: integer(), before: integer(1),
+});
+export function encodePageCursor(cursor) {
+    return canonicalJson(pageCursorSchema.parse(cursor));
+}
+export function decodePageCursor(raw, scope) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return reject("INVALID_CURSOR", "Malformed cursor.");
+    }
+    let cursor;
+    try {
+        cursor = pageCursorSchema.parse(parsed);
+    }
+    catch (error) {
+        if (!(error instanceof ContractError))
+            throw error;
+        return reject("INVALID_CURSOR", "Invalid cursor shape.");
+    }
+    if (canonicalJson(cursor.scope) !== canonicalJson(pagingScopeSchema.parse(scope)) || cursor.before > cursor.highWater) {
+        reject("INVALID_CURSOR", "Cursor belongs to different filters/review or exceeds its high-water mark.");
+    }
+    return cursor;
+}
+export function pagedSchema(item) {
+    return refine(object({
+        items: array(item, CONTRACT_LIMITS.pageMaximum), nextCursor: nullable(text()), totalCount: integer(), highWater: integer(),
+    }), (page) => {
+        if (page.totalCount < page.items.length || (!page.items.length && page.nextCursor !== null)) {
+            reject("INVALID_INPUT", "Inconsistent page counts/cursor.");
+        }
+    });
+}
+export function validatePageOutput(input, item, scope, queryInput) {
+    const page = pagedSchema(item).parse(input);
+    const query = pageQuerySchema.parse(queryInput);
+    const cursor = query.cursor === undefined ? null : decodePageCursor(query.cursor, scope);
+    if (page.items.length > (query.limit ?? CONTRACT_LIMITS.pageDefault) ||
+        (cursor && page.highWater !== cursor.highWater))
+        reject("INVALID_INPUT", "Page exceeds requested window.");
+    const sequences = page.items.map((entry) => entry.sequence);
+    const ordered = [...sequences].sort((a, b) => scope.collection === "context" ? a - b : b - a);
+    if (new Set(sequences).size !== sequences.length || canonicalJson(ordered) !== canonicalJson(sequences) ||
+        sequences.some((sequence) => sequence > page.highWater || (cursor && sequence >= cursor.before))) {
+        reject("INVALID_INPUT", "Page order/high-water mismatch.");
+    }
+    if (page.nextCursor !== null) {
+        const next = decodePageCursor(page.nextCursor, scope);
+        if (next.highWater !== page.highWater || next.before !== Math.min(...sequences)) {
+            reject("INVALID_CURSOR", "Next cursor does not continue this page.");
+        }
+    }
+    return page;
+}
+/** Inputs are the authorized, filtered collection. Sequence is immutable and review-wide. */
+export function paginate(records, scopeInput, queryInput, currentSequence) {
+    const scope = pagingScopeSchema.parse(scopeInput);
+    const query = pageQuerySchema.parse(queryInput);
+    const limit = query.limit ?? CONTRACT_LIMITS.pageDefault;
+    const cursor = query.cursor === undefined ? null : decodePageCursor(query.cursor, scope);
+    const sequences = records.map((record) => integer(1).parse(record.sequence));
+    if (new Set(sequences).size !== sequences.length)
+        reject("INVALID_INPUT", "Duplicate creation sequence.");
+    integer().parse(currentSequence);
+    if (cursor && cursor.highWater > currentSequence)
+        reject("INVALID_CURSOR", "Cursor exceeds the review's current sequence.");
+    const highWater = cursor?.highWater ?? currentSequence;
+    const bounded = records.filter((record) => record.sequence <= highWater).sort((a, b) => b.sequence - a.sequence);
+    const remaining = bounded.filter((record) => !cursor || record.sequence < cursor.before);
+    const selected = remaining.slice(0, limit);
+    const nextCursor = remaining.length > selected.length
+        ? encodePageCursor({ scope, highWater, before: selected[selected.length - 1].sequence }) : null;
+    // Context windows load backwards but read chronologically.
+    return { items: scope.collection === "context" ? selected.reverse() : selected, nextCursor, totalCount: bounded.length, highWater };
+}
+export const exchangeSchema = refine(object({
+    sequence: integer(1), reviewer: reviewerMessageSchema, response: nullable(agentMessageSchema),
+}), ({ sequence, reviewer, response }) => {
+    if (sequence !== reviewer.sequence)
+        reject("INVALID_INPUT", "Exchange ordering belongs to its reviewer message.");
+    if (response && (response.replyToMessageId !== reviewer.messageId || response.threadId !== reviewer.threadId ||
+        response.reviewId !== reviewer.reviewId || response.submissionId !== reviewer.submissionId ||
+        (reviewer.intent === "discuss" && response.outcome === "applied"))) {
+        reject("INVALID_INPUT", "Reply is not associated with this reviewer message.");
+    }
+});
+export function latestExchange(messages, replies, highWater = Number.MAX_SAFE_INTEGER) {
+    const latest = messages.filter((message) => message.sequence <= highWater).sort((a, b) => b.sequence - a.sequence)[0];
+    if (!latest)
+        return null;
+    const matches = replies.filter((reply) => reply.replyToMessageId === latest.messageId && reply.sequence <= highWater);
+    if (matches.length > 1)
+        reject("INVALID_INPUT", "Multiple replies to one submitted message.");
+    return exchangeSchema.parse({ sequence: latest.sequence, reviewer: latest, response: matches[0] ?? null });
+}
+export const threadSummarySchema = refine(object({
+    thread: conversationThreadSchema, sequence: integer(1),
+    messageCount: integer(), pendingMessageCount: integer(),
+    latestExchange: nullable(exchangeSchema),
+}), (summary) => {
+    if (summary.sequence !== summary.thread.sequence || summary.pendingMessageCount > summary.messageCount ||
+        ((summary.messageCount === 0) !== (summary.latestExchange === null)) ||
+        (summary.latestExchange && (summary.latestExchange.reviewer.threadId !== summary.thread.threadId ||
+            summary.latestExchange.reviewer.reviewId !== summary.thread.reviewId))) {
+        reject("INVALID_INPUT", "Invalid thread summary association/counts.");
+    }
+});
+export const threadPageSchema = pagedSchema(threadSummarySchema);
+export const contextPageSchema = pagedSchema(exchangeSchema);
+export function contextWindow(messages, replies, scope, query, currentSequence) {
+    if (scope.collection !== "context" || scope.threadId === null)
+        reject("INVALID_INPUT", "Context requires one thread.");
+    for (const message of [...messages, ...replies]) {
+        if (message.reviewId !== scope.reviewId || message.threadId !== scope.threadId)
+            reject("SCOPE_MISMATCH", "Foreign context message.");
+    }
+    const parsedQuery = pageQuerySchema.parse(query);
+    const highWater = parsedQuery.cursor === undefined ? currentSequence : decodePageCursor(parsedQuery.cursor, scope).highWater;
+    const exchanges = messages.filter((message) => message.sequence <= highWater).map((message) => latestExchange([message], replies, highWater));
+    return validatePageOutput(paginate(exchanges, scope, query, currentSequence), exchangeSchema, scope, query);
+}
+export const resultSummarySchema = object({
+    resultId: id, body: text(), summary: optional(text()), createdAt: timestamp,
+    title: enumeration(["What changed", "Agent response"]), effect: enumeration(["reply-only", "changes-reported"]),
+});
+export const submissionHistoryItemSchema = refine(object({
+    sequence: integer(1), reviewId: id, submissionId: id, createdAt: timestamp,
+    state: enumeration(["queued", "delivered", "handled", "abandoned"]),
+    result: nullable(resultSummarySchema),
+    comparisonStatus: enumeration(["not-requested", "pending", "ready", "partial", "failed", "unavailable"]),
+    comparisonCount: integer(),
+}), (item) => {
+    if ((item.state === "handled") !== (item.result !== null))
+        reject("INVALID_INPUT", "Only handled history has a result.");
+});
+export const submissionHistoryPageSchema = pagedSchema(submissionHistoryItemSchema);
+export const comparisonReferenceSchema = object({
+    sequence: integer(1), reviewId: id, submissionId: id, pageKey: id,
+    baselineRevisionId: nullable(id), resultRevisionId: nullable(id),
+    status: enumeration(["not-requested", "pending", "ready", "partial", "failed", "unavailable"]),
+    reason: nullable(text()),
+});
+export const comparisonReferencePageSchema = pagedSchema(comparisonReferenceSchema);
+/** Only review-local unsubmitted edits; submitted versions remain in submission reads. */
+export const directEditPageSchema = pagedSchema(directEditSchema);
+export const editAttentionSchema = refine(object({
+    sequence: integer(1), edit: directEditSchema,
+    stage: enumeration(["unsent", "queued", "delivered", "deferred", "abandoned"]),
+    submissionId: nullable(id), outcome: nullable(directEditOutcomeSchema), reason: nullable(text()),
+}), (item) => {
+    if (item.sequence !== item.edit.sequence ||
+        (item.stage === "unsent") !== (item.submissionId === null) ||
+        (item.stage === "deferred") !== (item.outcome !== null) ||
+        (["deferred", "abandoned"].includes(item.stage)) !== (item.reason !== null)) {
+        reject("INVALID_INPUT", "Invalid edit attention lifecycle.");
+    }
+    if (item.outcome && (item.outcome.editId !== item.edit.editId || item.outcome.editVersion !== item.edit.version ||
+        item.outcome.outcome !== "deferred" || item.outcome.reason !== item.reason)) {
+        reject("INVALID_INPUT", "Attention outcome does not describe this exact edit.");
+    }
+});
+export const editAttentionPageSchema = pagedSchema(editAttentionSchema);