@ai-agent-forge/plugin-alignment 0.88.1

package/dist/engine.js

@@ -0,0 +1,634 @@
+/**
+ * Pure alignment state machine (设计 §5) — no host API access, no I/O.
+ *
+ * Every function takes JSON-safe state and returns the next state plus the
+ * audit transitions to persist; index.ts owns persistence (entries + events)
+ * and http-server.ts owns transport. Deterministic by construction: same
+ * inputs, same outputs, no clocks, no randomness.
+ */
+import { createHash } from "node:crypto";
+import { ALIGNMENT_LIMITS, AlignmentError, STEP_ORDER, } from "./types.js";
+// ---------------------------------------------------------------------------
+// Hashing & validation
+// ---------------------------------------------------------------------------
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function validAlignmentId(id) {
+    // 入参可能来自未校验的工具输入（空对象 → undefined）：test() 会把实参
+    // 字符串化为 "undefined" 而"通过"模式匹配，必须先做类型守卫。
+    return typeof id === "string" && ID_PATTERN.test(id) && id.length <= 128;
+}
+/** Fingerprint of the fields whose change must re-ask for approval (总则 3). */
+export function blockFingerprint(kind, content, rationale, impact) {
+    const canonical = JSON.stringify([kind, content, rationale ?? null, impact ?? null]);
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+function nonEmptyString(value, name, max) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new AlignmentError("invalid-input", `${name} must be a non-empty string`);
+    }
+    if (value.length > max) {
+        throw new AlignmentError("invalid-input", `${name} exceeds ${max} characters`);
+    }
+    return value;
+}
+function validateBlockInput(input) {
+    if (typeof input.id !== "string" || input.id.trim() === "" || input.id.length > 128) {
+        throw new AlignmentError("invalid-block", `block id must be a non-empty string (≤128 chars): ${String(input.id)}`);
+    }
+    if (!["fact", "assumption", "decision", "missing"].includes(input.kind)) {
+        throw new AlignmentError("invalid-block", `invalid block kind: ${String(input.kind)}`);
+    }
+    nonEmptyString(input.content, `block ${input.id} content`, ALIGNMENT_LIMITS.contentMaxLength);
+    if (input.rationale !== undefined && input.rationale.length > ALIGNMENT_LIMITS.rationaleMaxLength) {
+        throw new AlignmentError("invalid-block", `block ${input.id} rationale exceeds ${ALIGNMENT_LIMITS.rationaleMaxLength} characters`);
+    }
+    if (input.impact?.some((item) => typeof item !== "string" || item.trim() === "")) {
+        throw new AlignmentError("invalid-block", `block ${input.id} impact must be a non-empty string array`);
+    }
+    if ((input.comments?.length ?? 0) > ALIGNMENT_LIMITS.notesPerBlockMax) {
+        throw new AlignmentError("invalid-block", `block ${input.id} carries more than ${ALIGNMENT_LIMITS.notesPerBlockMax} comments`);
+    }
+    for (const comment of input.comments ?? []) {
+        if (typeof comment.id !== "string" || comment.id.trim() === "") {
+            throw new AlignmentError("invalid-comment", `comment id on block ${input.id} must be a non-empty string`);
+        }
+        nonEmptyString(comment.note, `comment ${comment.id} note`, ALIGNMENT_LIMITS.noteMaxLength);
+    }
+}
+// ---------------------------------------------------------------------------
+// State helpers
+// ---------------------------------------------------------------------------
+export function findRecord(state, id) {
+    return state.alignments.find((record) => record.id === id);
+}
+export function activeStep(record) {
+    const found = record.steps.find((candidate) => candidate.step === record.activeStep);
+    if (!found)
+        throw new AlignmentError("invalid-input", `active step missing: ${record.activeStep}`);
+    return found;
+}
+/**
+ * Gate facts (总则 2): the three server-checkable conditions. A missing block
+ * without a stored user answer counts as `missing-empty`; once answered it is
+ * just an unapproved block waiting for the model to restructure it.
+ */
+export function gate(record) {
+    const step = activeStep(record);
+    const pending = [];
+    let unapproved = 0;
+    for (const block of step.blocks) {
+        if (block.kind === "missing" && (block.draftAnswer ?? "").trim() === "") {
+            pending.push({ blockId: block.id, reason: "missing-empty" });
+            unapproved += 1;
+            continue;
+        }
+        if (block.status !== "approved") {
+            pending.push({ blockId: block.id, reason: "unapproved" });
+            unapproved += 1;
+        }
+    }
+    let openComments = 0;
+    for (const block of step.blocks) {
+        for (const comment of block.comments) {
+            if (comment.status !== "open")
+                continue;
+            openComments += 1;
+            if (comment.author === "assistant") {
+                pending.push({ blockId: block.id, reason: "assistant-question-open" });
+            }
+        }
+    }
+    const pendingAdditions = record.pendingFeedback?.additions.length ?? 0;
+    return {
+        unapproved,
+        openComments,
+        pendingAdditions,
+        allGreen: unapproved === 0 && openComments === 0 && pendingAdditions === 0,
+        pending,
+    };
+}
+function nextStep(step) {
+    const index = STEP_ORDER.indexOf(step);
+    return index >= 0 && index < STEP_ORDER.length - 1 ? STEP_ORDER[index + 1] : undefined;
+}
+// ---------------------------------------------------------------------------
+// alignment_set: create / update (总则 3 hash inheritance, 总则 5 comment merge)
+// ---------------------------------------------------------------------------
+function materializeBlock(input, previous, currentRound) {
+    const fingerprint = blockFingerprint(input.kind, input.content, input.rationale, input.impact);
+    const unchanged = previous !== undefined && previous.contentHash === fingerprint;
+    const block = {
+        id: input.id,
+        kind: input.kind,
+        content: input.content,
+        rationale: input.rationale,
+        impact: input.impact,
+        // Hash-identical resent blocks keep their approval (防确认疲劳); changed
+        // content resets to pending and flags the round it changed in.
+        status: unchanged ? previous.status : "pending",
+        contentHash: fingerprint,
+        ...(unchanged ? {} : { modifiedInRound: currentRound + 1 }),
+        ...(previous?.draftAnswer !== undefined ? { draftAnswer: previous.draftAnswer } : {}),
+        comments: [],
+    };
+    block.comments = mergeComments(previous?.comments ?? [], input, currentRound);
+    return block;
+}
+function mergeComments(existing, input, round) {
+    const merged = existing.map((comment) => ({ ...comment }));
+    const resolutions = new Map((input.commentResolutions ?? []).map((item) => [item.commentId, item]));
+    // Existing comments are append-only (总则 5): user text survives resends
+    // verbatim, open assistant questions cannot silently disappear; only an
+    // explicit resolution closes them.
+    for (const comment of merged) {
+        const resolution = resolutions.get(comment.id);
+        if (!resolution)
+            continue;
+        resolutions.delete(comment.id);
+        if (comment.status === "resolved") {
+            throw new AlignmentError("comment-ownership", `comment ${comment.id} is already resolved`);
+        }
+        comment.status = "resolved";
+        comment.resolution = { kind: resolution.kind, text: resolution.text, round };
+    }
+    if (resolutions.size > 0) {
+        const ids = [...resolutions.keys()].join(", ");
+        throw new AlignmentError("comment-ownership", `resolutions reference unknown comments: ${ids}`);
+    }
+    // New comments are assistant-only and deduped by note so a resent open
+    // question never duplicates itself.
+    for (const fresh of input.comments ?? []) {
+        if (merged.some((comment) => comment.author === "assistant" && comment.note === fresh.note))
+            continue;
+        merged.push({
+            id: fresh.id,
+            author: "assistant",
+            ...(fresh.quote !== undefined ? { quote: fresh.quote } : {}),
+            note: fresh.note,
+            status: "open",
+            createdAtRound: round,
+        });
+    }
+    return merged;
+}
+export function applyAlignmentSet(state, input) {
+    if (!validAlignmentId(input.id)) {
+        throw new AlignmentError("invalid-id", `alignment id must match [A-Za-z0-9][A-Za-z0-9._-]* (no leading dot): ${input.id}`);
+    }
+    if (!Array.isArray(input.blocks) || input.blocks.length === 0) {
+        throw new AlignmentError("invalid-input", "blocks must be a non-empty array");
+    }
+    if (input.blocks.length > ALIGNMENT_LIMITS.blocksPerStepMax) {
+        throw new AlignmentError("invalid-input", `a step may carry at most ${ALIGNMENT_LIMITS.blocksPerStepMax} blocks`);
+    }
+    const seen = new Set();
+    for (const block of input.blocks) {
+        validateBlockInput(block);
+        if (seen.has(block.id)) {
+            throw new AlignmentError("invalid-block", `duplicate block id within the step: ${block.id}`);
+        }
+        seen.add(block.id);
+    }
+    const existing = findRecord(state, input.id);
+    if (!existing) {
+        // Create: created-as-aligning (no draft state) and single-active (总则 9).
+        const active = state.alignments.find((record) => record.status === "aligning" || record.status === "finalizing");
+        if (active) {
+            throw new AlignmentError("active-alignment-exists", `an alignment is already in progress: ${active.id}; complete or cancel it first`);
+        }
+        const record = {
+            id: input.id,
+            title: input.title ?? input.id,
+            ...(input.goalId !== undefined ? { goalId: input.goalId } : {}),
+            status: "aligning",
+            revision: 0,
+            activeStep: "objective",
+            steps: [
+                {
+                    step: "objective",
+                    status: "active",
+                    blocks: input.blocks.map((block) => materializeBlock(block, undefined, 0)),
+                },
+                { step: "detail", status: "pending", blocks: [] },
+                { step: "design", status: "pending", blocks: [] },
+            ],
+            roundCount: 0,
+        };
+        return { state: { alignments: [...state.alignments, record] }, transitions: [] };
+    }
+    if (existing.status !== "aligning") {
+        throw new AlignmentError("terminal-state", `alignment is terminal and cannot be updated: ${input.id}`);
+    }
+    const revision = input.revision ?? 0;
+    if (revision <= existing.revision) {
+        throw new AlignmentError("stale-revision", `stale alignment revision: ${input.id} expects > ${existing.revision}, got ${revision}`);
+    }
+    const step = activeStep(existing);
+    if (step.status !== "active" && step.status !== "reset") {
+        throw new AlignmentError("step-not-writable", `step ${existing.activeStep} is ${step.status}; only the active step accepts blocks`);
+    }
+    // Deleting a block that still carries open comments is rejected (总则 3):
+    // deletion must not become a way to dodge unresolved objections.
+    for (const previous of step.blocks) {
+        if (input.blocks.some((block) => block.id === previous.id))
+            continue;
+        if (previous.comments.some((comment) => comment.status === "open")) {
+            throw new AlignmentError("block-has-open-comments", `block ${previous.id} carries open comments; resolve them before deleting it (edit the content instead)`);
+        }
+    }
+    const blocks = input.blocks.map((blockInput) => {
+        const previous = step.blocks.find((candidate) => candidate.id === blockInput.id);
+        return materializeBlock(blockInput, previous, existing.roundCount);
+    });
+    // Version snapshot (走查 2026-10-03): archive the outgoing step block set
+    // before it is replaced. Append-only, bounded rolling; the page views
+    // historical versions read-only — only the latest accepts interaction.
+    // An empty outgoing set has nothing to roll back to — skip it, otherwise
+    // the version bar fills with chips that render a blank view.
+    const archive = JSON.stringify(step.blocks);
+    const snapshot = {
+        revision: existing.revision,
+        round: existing.roundCount,
+        step: existing.activeStep,
+        blocks: archive.length <= ALIGNMENT_LIMITS.versionsSnapshotMaxBytes ? structuredClone(step.blocks) : [],
+        ...(archive.length > ALIGNMENT_LIMITS.versionsSnapshotMaxBytes ? { truncated: true } : {}),
+    };
+    const priorVersions = (step.blocks.length === 0 ? (existing.versions ?? []) : [...(existing.versions ?? []), snapshot]).slice(-ALIGNMENT_LIMITS.versionsMax);
+    const updated = {
+        ...existing,
+        title: input.title ?? existing.title,
+        goalId: input.goalId ?? existing.goalId,
+        revision,
+        steps: existing.steps.map((candidate) => candidate.step === existing.activeStep ? { ...candidate, blocks } : candidate),
+        pendingFeedback: undefined,
+        versions: priorVersions,
+    };
+    return {
+        state: { alignments: state.alignments.map((record) => (record.id === updated.id ? updated : record)) },
+        transitions: [],
+    };
+}
+// ---------------------------------------------------------------------------
+// POST /round: the user feedback round (§5 round flow, v3.2 audits)
+// ---------------------------------------------------------------------------
+export function applyRoundPost(record0, post) {
+    if (record0.status !== "aligning" && record0.status !== "finalizing") {
+        throw new AlignmentError("terminal-state", `alignment is terminal: ${record0.id}`);
+    }
+    // Anti-staleness gate (terminal audit D6): the page must confirm against
+    // the exact state it rendered.
+    if (post.baseRevision !== record0.revision) {
+        throw new AlignmentError("stale-state", `page snapshot is stale (base ${post.baseRevision}, current ${record0.revision}); reload and resubmit`);
+    }
+    const hasNewFeedback = post.comments.length > 0 || post.additions.length > 0 || post.answers.length > 0;
+    if (post.stepConfirmed && hasNewFeedback) {
+        throw new AlignmentError("confirmed-with-feedback", "step confirmation cannot carry new comments/additions/answers; submit the feedback first");
+    }
+    // 终审阶段唯一合法提交是终审确认（走查 2026-10-03）。此时所有步已锁定，
+    // 反馈字段没有落点——尤其 approvals 镜像会把已锁定的 design 块整体重置为
+    // pending，再被无门禁的终审分支带进 completed。显式拒绝，不做静默重置。
+    if (record0.status === "finalizing" &&
+        (hasNewFeedback || post.commentReplies.length > 0 || post.approvals.length > 0 || !post.stepConfirmed)) {
+        throw new AlignmentError("invalid-input", "finalizing accepts only the final confirm (stepConfirmed without feedback fields)");
+    }
+    const record = structuredClone(record0);
+    const step = record.steps.find((candidate) => candidate.step === record.activeStep);
+    if (!step)
+        throw new AlignmentError("invalid-input", "active step missing");
+    const blockById = new Map(step.blocks.map((block) => [block.id, block]));
+    const round = record.roundCount + 1;
+    // New user comments: the quote must match the block's current content.
+    for (const comment of post.comments) {
+        const block = blockById.get(comment.blockId);
+        if (!block) {
+            throw new AlignmentError("invalid-input", `comment targets unknown block: ${comment.blockId}`);
+        }
+        const note = nonEmptyString(comment.note, "comment note", ALIGNMENT_LIMITS.noteMaxLength);
+        if (typeof comment.quote !== "string" || !block.content.includes(comment.quote)) {
+            throw new AlignmentError("comment-quote-mismatch", `comment quote does not match block ${comment.blockId} content`);
+        }
+        block.comments.push({
+            id: `c${round}-${block.comments.length + 1}`,
+            author: "user",
+            quote: comment.quote,
+            note,
+            ...(comment.escalate === true ? { escalate: true } : {}),
+            status: "open",
+            createdAtRound: round,
+        });
+    }
+    // Replies to assistant comments (answer/dismiss are mutually exclusive).
+    for (const reply of post.commentReplies) {
+        const block = blockById.get(reply.blockId);
+        const comment = block?.comments.find((candidate) => candidate.id === reply.commentId);
+        if (!comment || comment.author !== "assistant") {
+            throw new AlignmentError("invalid-input", `reply targets unknown or non-assistant comment: ${reply.commentId}`);
+        }
+        if (comment.status !== "open")
+            continue; // idempotent resubmission
+        if ((reply.answer !== undefined) === (reply.dismiss === true)) {
+            throw new AlignmentError("invalid-input", `reply must carry exactly one of answer or dismiss: ${reply.commentId}`);
+        }
+        comment.status = "resolved";
+        comment.resolution = reply.dismiss
+            ? { kind: "dismissed", text: "user marked unimportant", round }
+            : {
+                kind: "answered",
+                text: nonEmptyString(reply.answer ?? "", "reply answer", ALIGNMENT_LIMITS.answerMaxLength),
+                round,
+            };
+    }
+    // Fill-in answers for missing blocks: stored verbatim as the user's words;
+    // the model restructures them into the block on its next alignment_set.
+    for (const answer of post.answers) {
+        const block = blockById.get(answer.blockId);
+        if (!block || block.kind !== "missing") {
+            throw new AlignmentError("invalid-input", `answer targets unknown or non-missing block: ${answer.blockId}`);
+        }
+        if ((block.draftAnswer ?? "").trim() !== "")
+            continue; // idempotent resubmission
+        block.draftAnswer = nonEmptyString(answer.value, "answer", ALIGNMENT_LIMITS.answerMaxLength);
+    }
+    // Approvals mirror the page's full approved set for the active step.
+    // Skipped in finalizing (走查 2026-10-03): the step is locked and the
+    // final confirm carries approvals=[] — mirroring would reopen its blocks.
+    if (record0.status !== "finalizing") {
+        const approvalSet = new Set(post.approvals);
+        for (const id of approvalSet) {
+            if (!blockById.has(id)) {
+                throw new AlignmentError("invalid-input", `approval references unknown block: ${id}`);
+            }
+        }
+        for (const block of step.blocks) {
+            block.status = approvalSet.has(block.id) ? "approved" : "pending";
+        }
+    }
+    // Additions queue as pendingFeedback — the server-side truth of gate
+    // condition three (terminal audit D7); cleared by the next alignment_set.
+    const additions = [...(record.pendingFeedback?.additions ?? [])];
+    for (const addition of post.additions) {
+        additions.push(nonEmptyString(addition, "addition", ALIGNMENT_LIMITS.additionMaxLength));
+    }
+    record.pendingFeedback = additions.length > 0 ? { round, additions } : undefined;
+    const transitions = [
+        {
+            alignmentId: record.id,
+            step: record.activeStep,
+            event: "round.submitted",
+            round,
+            reason: {
+                code: "round-submitted",
+                detail: `approvals=${post.approvals.length} comments=${post.comments.length} replies=${post.commentReplies.length} answers=${post.answers.length} additions=${post.additions.length}`,
+            },
+            revision: record.revision,
+        },
+    ];
+    record.roundCount = round;
+    let stepConfirmedNow = false;
+    if (post.stepConfirmed && record0.status === "finalizing") {
+        // 终审总览确认（走查 2026-10-03）: the user reviewed the full plan and
+        // confirmed it — the only path to `completed` + baseline write.
+        record.status = "completed";
+        record.revision += 1;
+        for (const locked of record.steps)
+            locked.baselineConfirmedAtRound ??= record.roundCount;
+        transitions.push({
+            alignmentId: record.id,
+            event: "alignment.completed",
+            reason: { code: "final-review-approved", detail: "final review confirmed the complete plan" },
+            revision: record.revision,
+        });
+        const result = {
+            alignmentId: record.id,
+            round: record.roundCount,
+            step: record.activeStep,
+            revision: record.revision,
+            approvals: post.approvals,
+            comments: post.comments,
+            commentReplies: post.commentReplies,
+            answers: post.answers,
+            additions: post.additions,
+            stepConfirmed: true,
+        };
+        return { record, transitions, result };
+    }
+    if (post.stepConfirmed) {
+        const snapshot = gate(record);
+        if (!snapshot.allGreen) {
+            throw new AlignmentError("gate-not-satisfied", `gate not satisfied: ${snapshot.unapproved} unapproved blocks, ${snapshot.openComments} open comments, ${snapshot.pendingAdditions} pending additions`);
+        }
+        step.status = "locked";
+        step.baselineConfirmedAtRound = round;
+        record.revision += 1;
+        transitions.push({
+            alignmentId: record.id,
+            step: record.activeStep,
+            event: "step.confirmed",
+            round,
+            reason: { code: "step-baseline-locked", detail: `${step.blocks.length} blocks frozen` },
+            revision: record.revision,
+        });
+        const upcoming = nextStep(record.activeStep);
+        if (upcoming) {
+            record.activeStep = upcoming;
+            const upcomingStep = record.steps.find((candidate) => candidate.step === upcoming);
+            if (upcomingStep)
+                upcomingStep.status = "active";
+            record.revision += 1;
+        }
+        else {
+            // Design locked (方案确认): enter the final-review overview instead
+            // of completing (走查 2026-10-03) — the baseline is written only
+            // after the user confirms the full plan on the 终审 tab.
+            record.status = "finalizing";
+            record.revision += 1;
+            transitions.push({
+                alignmentId: record.id,
+                event: "design.locked",
+                round,
+                reason: {
+                    code: "scheme-locked-awaiting-final-review",
+                    detail: "all three baselines locked; awaiting final review",
+                },
+                revision: record.revision,
+            });
+        }
+        stepConfirmedNow = true;
+    }
+    const result = {
+        alignmentId: record.id,
+        round,
+        step: record0.activeStep,
+        revision: record.revision,
+        approvals: post.approvals,
+        comments: post.comments,
+        commentReplies: post.commentReplies,
+        answers: post.answers,
+        additions: post.additions,
+        stepConfirmed: stepConfirmedNow,
+    };
+    return { record, transitions, result };
+}
+/** Injection succeeded — the delivered transition closes the round (terminal audit D1). */
+export function markDelivered(record, round) {
+    return [
+        {
+            alignmentId: record.id,
+            event: "round.delivered",
+            round,
+            reason: { code: "round-delivered", detail: "feedback injected into the session" },
+            revision: record.revision,
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// alignment_advance: inspect / retreat / cancel (总则 6)
+// ---------------------------------------------------------------------------
+export function applyAlignmentAdvance(state, input) {
+    const record = findRecord(state, input.alignmentId);
+    if (!record) {
+        throw new AlignmentError("not-found", `unknown alignment: ${input.alignmentId}`);
+    }
+    if (input.action === "inspect")
+        return { state, transitions: [] };
+    if (record.status === "completed" || record.status === "cancelled") {
+        throw new AlignmentError("terminal-state", `alignment is terminal: ${record.id}`);
+    }
+    if (input.action === "cancel") {
+        const cancelled = { ...record, status: "cancelled" };
+        return {
+            state: { alignments: state.alignments.map((item) => (item.id === record.id ? cancelled : item)) },
+            transitions: [
+                {
+                    alignmentId: record.id,
+                    event: "alignment.cancelled",
+                    reason: { code: "alignment-cancelled" },
+                    revision: record.revision,
+                },
+            ],
+        };
+    }
+    // retreat: comments survive the reset append-only (terminal audit D5); the
+    // escalate comments that triggered it are resolved here with the note.
+    const note = nonEmptyString(input.note ?? "", "retreat note", ALIGNMENT_LIMITS.noteMaxLength);
+    const target = input.step;
+    if (!target || STEP_ORDER.indexOf(target) >= STEP_ORDER.indexOf(record.activeStep)) {
+        throw new AlignmentError("retreat-target-invalid", `retreat target must be an earlier step than ${record.activeStep}`);
+    }
+    const affected = [];
+    const retreated = { ...record, steps: record.steps.map((step) => ({ ...step })) };
+    for (const step of retreated.steps) {
+        if (STEP_ORDER.indexOf(step.step) < STEP_ORDER.indexOf(target))
+            continue;
+        affected.push(step.step);
+        step.status = "reset";
+        step.baselineConfirmedAtRound = undefined;
+        for (const block of step.blocks) {
+            block.status = "pending";
+            for (const comment of block.comments) {
+                if (comment.status === "open" && comment.author === "user" && comment.escalate === true) {
+                    comment.status = "resolved";
+                    comment.resolution = { kind: "incorporated", text: note, round: record.roundCount };
+                }
+            }
+        }
+    }
+    retreated.activeStep = target;
+    // Finalizing → retreated: the final-review state is gone with the
+    // downstream resets; the task is writable at the target step again.
+    if (retreated.status === "finalizing")
+        retreated.status = "aligning";
+    retreated.revision += 1;
+    return {
+        state: { alignments: state.alignments.map((item) => (item.id === record.id ? retreated : item)) },
+        transitions: [
+            {
+                alignmentId: record.id,
+                event: "step.retreated",
+                reason: {
+                    code: "step-retreated",
+                    detail: `target=${target}; reset=${affected.join(",")}; note=${note}`,
+                },
+                revision: retreated.revision,
+            },
+        ],
+    };
+}
+/**
+ * Step-scoped version rollback (走查 2026-10-03): drop the current unconfirmed
+ * version (not archived), promote the target snapshot to live, engine-bump the
+ * revision (D4). Comments survive append-only — restored blocks carry the union
+ * of live and archived comments by comment id, live status winning (a
+ * resolution is irreversible). Only the active (unlocked) step accepts it;
+ * locked steps go through retreat. Other steps are never touched.
+ */
+export function applyVersionRollback(state, input) {
+    const record = findRecord(state, input.alignmentId);
+    if (!record) {
+        throw new AlignmentError("not-found", `unknown alignment: ${input.alignmentId}`);
+    }
+    if (record.status !== "aligning") {
+        throw new AlignmentError("terminal-state", `version rollback needs an aligning task: ${record.id}`);
+    }
+    const step = activeStep(record);
+    if (step.status !== "active" && step.status !== "reset") {
+        throw new AlignmentError("step-not-writable", `step ${record.activeStep} is ${step.status}; locked steps go through retreat`);
+    }
+    const versions = [...(record.versions ?? [])];
+    const index = versions.findIndex((snapshot) => snapshot.revision === input.targetRevision && snapshot.step === record.activeStep);
+    if (index < 0) {
+        throw new AlignmentError("invalid-input", `no snapshot of step ${record.activeStep} at revision ${input.targetRevision}`);
+    }
+    const snapshot = versions[index];
+    if (snapshot.truncated) {
+        throw new AlignmentError("invalid-input", `snapshot r${input.targetRevision} exceeded the size budget and has no blocks`);
+    }
+    const liveById = new Map(step.blocks.map((block) => [block.id, block]));
+    const restored = snapshot.blocks.map((archived) => {
+        const live = liveById.get(archived.id);
+        if (!live)
+            return structuredClone(archived);
+        const merged = new Map(archived.comments.map((comment) => [comment.id, comment]));
+        for (const comment of live.comments)
+            merged.set(comment.id, comment); // live status wins
+        return { ...structuredClone(archived), comments: [...merged.values()] };
+    });
+    // The current version is dropped, the target is promoted: remove it from
+    // the archive rather than re-archiving the live set.
+    versions.splice(index, 1);
+    const rolled = {
+        ...record,
+        revision: record.revision + 1,
+        steps: record.steps.map((candidate) => candidate.step === record.activeStep
+            ? { ...candidate, blocks: restored, status: candidate.status === "locked" ? "reset" : candidate.status }
+            : candidate),
+        versions,
+    };
+    return {
+        state: { alignments: state.alignments.map((item) => (item.id === rolled.id ? rolled : item)) },
+        transitions: [
+            {
+                alignmentId: rolled.id,
+                step: rolled.activeStep,
+                event: "version.rolled-back",
+                reason: { code: "version-rolled-back", detail: `target=r${input.targetRevision}` },
+                revision: rolled.revision,
+            },
+        ],
+    };
+}
+/** Compact final baseline listing (§5 round flow 4): one line per block, answers first. */
+export function finalBaselineLines(record) {
+    if (record.status !== "completed")
+        return undefined;
+    const lines = [];
+    for (const step of record.steps) {
+        for (const block of step.blocks) {
+            const confirmed = block.content.split("\n").find((line) => line.includes("→ 已确认"));
+            const text = (confirmed ? confirmed.replace(/^\s*→\s*/, "") : block.content.split("\n")[0]).slice(0, 120);
+            lines.push({ step: step.step, kind: block.kind, id: block.id, line: text });
+        }
+    }
+    return lines;
+}
+//# sourceMappingURL=engine.js.map