@zq-silk/yui 0.8.2 → 0.8.6

package/dist/review/reviewOutcomeClassifier.js

@@ -1,61 +1,259 @@
+import { matchYieldReceipt } from "../run/yieldReceipt.js";
 const INFRA_SIGNATURES = [
-    {
-        kind: "session-not-stopped",
-        pattern: /session must be stopped before workspace migration/iu
-    },
-    {
-        kind: "run-start",
-        pattern: /role run could not start|could not start (?:the )?(?:reviewer|role) run/iu
-    },
-    {
-        kind: "storage-lock",
-        pattern: /\.state\.lock|state lock|lock timeout|storage lock/iu
-    },
-    {
-        kind: "tmux-exit",
-        pattern: /tmux[^\n]{0,80}(?:exited|exit|died|vanished)|pane (?:exited|died)/iu
-    },
-    {
-        kind: "yield-timeout",
-        pattern: /yield timeout|controller yield timeout|yield timed out/iu
-    },
-    {
-        kind: "run-identity",
-        pattern: /wrong run id|unknown run id|run id (?:is )?(?:invalid|unknown|mismatch)/iu
-    },
-    {
-        kind: "policy",
-        pattern: /cyber_?policy|policy denial|permission denied by policy/iu
-    },
-    {
-        kind: "baseline-contamination",
-        pattern: /cross[-\s]?baseline|baseline pollution|contaminated baseline|wrong base sha/iu
-    }
+    { kind: "session-not-stopped", pattern: /session must be stopped before workspace migration/iu },
+    { kind: "run-start", pattern: /role run could not start|could not start (?:the )?(?:reviewer|role) run/iu },
+    { kind: "storage-lock", pattern: /\.state\.lock|state lock|lock timeout|storage lock/iu },
+    { kind: "tmux-exit", pattern: /tmux[^\n]{0,80}(?:exited|exit|died|vanished)|pane (?:exited|died)/iu },
+    { kind: "yield-timeout", pattern: /yield timeout|controller yield timeout|yield timed out/iu },
+    { kind: "run-identity", pattern: /wrong run id|unknown run id|run id (?:is )?(?:invalid|unknown|mismatch)/iu },
+    { kind: "policy", pattern: /cyber_?policy|policy denial|permission denied by policy/iu },
+    { kind: "baseline-contamination", pattern: /cross[-\s]?baseline|baseline pollution|contaminated baseline|wrong base sha/iu },
+    { kind: "context-load", pattern: /(?:run )?(?:context|context pack) load (?:failed|unavailable|unauthorized|stale|mismatched|malformed)/iu },
+    { kind: "workspace-binding", pattern: /workspace is not the durable owner|workspace-binding failure/iu }
 ];
-/**
- * Classifies a terminal Round.  `completed` is always semantic (the reviewer
- * delivered a report); `failed` is always infra.  Non-terminal Rounds have no
- * outcome yet.
- */
-export function classifyReviewRoundOutcome(round) {
-    if (round.status === "completed") {
-        return { kind: "semantic", reason: "Reviewer delivered a report." };
-    }
-    if (round.status !== "failed")
+/** Classify one terminal Round without rewriting it. */
+export function classifyReviewRoundOutcome(round, evidence) {
+    if (round.status !== "completed" && round.status !== "failed")
         return null;
-    const text = `${round.summary ?? ""}\n${round.report ?? ""}`;
-    for (const { kind, pattern } of INFRA_SIGNATURES) {
-        if (pattern.test(text)) {
-            return { kind: "infra", infraKind: kind, reason: `Review execution attempt failed (${kind}).` };
+    const infraKind = classifyInfraKind(`${round.summary ?? ""}\n${round.report ?? ""}`);
+    if (round.status === "failed") {
+        const semanticEvidence = failedRoundSemanticEvidence(round, evidence);
+        return semanticEvidence === null
+            ? {
+                kind: "non-semantic",
+                infraKind,
+                reason: "Failed Review execution carries no semantic report evidence."
+            }
+            : {
+                kind: "ambiguous",
+                infraKind,
+                reason: semanticEvidence
+            };
+    }
+    if (!explicitCompletedReviewInfrastructureFailure(round.summary ?? "", round)) {
+        return { kind: "semantic", reason: "Reviewer delivered a terminal report." };
+    }
+    if (evidence === undefined) {
+        return {
+            kind: "ambiguous",
+            infraKind,
+            reason: "Completed Round claims an infrastructure failure but corroborating Run/Event evidence was not supplied."
+        };
+    }
+    const corroborationFailure = completedInfrastructureCorroborationFailure(round, evidence);
+    return corroborationFailure === null
+        ? {
+            kind: "non-semantic",
+            infraKind,
+            reason: "Completed Round and yielded Run agree on an explicit pre-review infrastructure failure."
+        }
+        : {
+            kind: "ambiguous",
+            infraKind,
+            reason: corroborationFailure
+        };
+}
+/** True only when a Round may consume semantic Review budget or feed findings. */
+export function isSemanticReviewRound(round, evidence) {
+    return classifyReviewRoundOutcome(round, evidence)?.kind === "semantic";
+}
+function classifyInfraKind(text) {
+    return INFRA_SIGNATURES.find(({ pattern }) => pattern.test(text))?.kind ?? "other-infra";
+}
+function failedRoundSemanticEvidence(round, evidence) {
+    if ((round.checks ?? []).length > 0)
+        return "Failed Round records review checks.";
+    if (round.evidenceCommit !== undefined)
+        return "Failed Round records a review evidence commit.";
+    if (round.deltaRecheck?.disposition !== undefined || round.deltaRecheck?.reasoning !== undefined) {
+        return "Failed Round records a semantic delta-recheck disposition.";
+    }
+    if (round.report !== round.summary)
+        return "Failed Round stores a report distinct from its terminal summary.";
+    if (runtimeFailureSummaryHasReviewerOutput(round.report ?? "")) {
+        return "Failed Round stores non-empty Reviewer output in its runtime failure summary.";
+    }
+    if (looksLikeStructuredReviewReport(round.report ?? "")) {
+        return "Failed Round stores a structured Reviewer report.";
+    }
+    const semanticLane = (round.executionGroup?.lanes ?? []).find((lane) => ((lane.result?.checks ?? []).length > 0
+        || (lane.result?.findings ?? []).length > 0
+        || (lane.result?.evidence ?? []).length > 0
+        || lane.result?.evidenceCommit !== undefined
+        || lane.result?.gitSnapshot !== undefined
+        || lane.status === "yielded"
+        || lane.status === "completed"));
+    if (semanticLane !== undefined)
+        return `Reviewer Lane ${semanticLane.id} delivered semantic evidence.`;
+    if (evidence !== undefined) {
+        const reviewRun = evidence.listAgentRuns(round.taskId).find((run) => (run.purpose === "review"
+            && run.reviewRoundId === round.id
+            && (run.status === "yielded" || runtimeFailureSummaryHasReviewerOutput(run.summary ?? ""))));
+        if (reviewRun !== undefined)
+            return `Reviewer Run ${reviewRun.id} records Reviewer output.`;
+        const finding = evidence.listReviewFindings(round.taskId).find((entry) => (entry.firstReviewRoundId === round.id || entry.lastReviewRoundId === round.id));
+        if (finding !== undefined)
+            return `Review finding ${finding.id} references the Round.`;
+        const completion = evidence.listEvents(round.taskId).find((event) => (event.type === "review.completed" && event.payload.reviewRoundId === round.id));
+        if (completion !== undefined)
+            return `Review completion Event ${completion.id} exists.`;
+    }
+    return null;
+}
+function completedInfrastructureCorroborationFailure(round, store) {
+    if ((round.checks ?? []).length > 0)
+        return "Completed Round records review checks.";
+    if (round.evidenceCommit !== round.reviewBaseCommit) {
+        return "Completed Round lacks an exact frozen-head evidence commit.";
+    }
+    if (round.report !== round.summary) {
+        return "Completed Round stores a report distinct from its terminal summary.";
+    }
+    if (runtimeFailureSummaryHasReviewerOutput(round.report ?? "")) {
+        return "Completed Round stores non-empty Reviewer output in its runtime failure summary.";
+    }
+    if (round.deltaRecheck?.disposition !== undefined || round.deltaRecheck?.reasoning !== undefined) {
+        return "Completed Round records a semantic delta-recheck disposition.";
+    }
+    if (looksLikeStructuredReviewReport(round.report ?? "")) {
+        return "Completed Round stores a structured Reviewer report.";
+    }
+    for (const lane of round.executionGroup?.lanes ?? []) {
+        if (lane.status === "pending" || lane.status === "running") {
+            return `Reviewer Lane ${lane.id} is still active.`;
+        }
+        if ((lane.result?.checks ?? []).length > 0
+            || (lane.result?.findings ?? []).length > 0
+            || (lane.result?.evidence ?? []).length > 0
+            || (lane.result?.evidenceCommit !== undefined
+                && lane.result.evidenceCommit !== round.reviewBaseCommit)
+            || lane.result?.gitSnapshot !== undefined) {
+            return `Reviewer Lane ${lane.id} delivered semantic evidence.`;
+        }
+        if (lane.status === "yielded" || lane.status === "completed") {
+            if (lane.result === undefined
+                || lane.result.summary !== round.summary
+                || lane.result.report !== round.report
+                || lane.result.evidenceCommit !== round.reviewBaseCommit) {
+                return `Reviewer Lane ${lane.id} output is absent or differs from the Round.`;
+            }
+        }
+        else {
+            return `Completed Round has non-completed Reviewer Lane ${lane.id}/${lane.status}.`;
+        }
+    }
+    const runs = store.listAgentRuns(round.taskId).filter((run) => (run.purpose === "review" && run.reviewRoundId === round.id));
+    const active = runs.find(({ status }) => status === "active");
+    if (active !== undefined)
+        return `Reviewer Run ${active.id} is still active.`;
+    const output = runs.find((run) => (run.status === "failed" && runtimeFailureSummaryHasReviewerOutput(run.summary ?? "")));
+    if (output !== undefined)
+        return `Reviewer Run ${output.id} records Reviewer output.`;
+    const yielded = runs.filter(({ status }) => status === "yielded");
+    if (round.reviewerRunId === undefined
+        || yielded.length !== 1
+        || yielded[0].id !== round.reviewerRunId) {
+        return "Completed Round lacks one exact yielded Reviewer Run.";
+    }
+    const run = yielded[0];
+    if (run.roleName !== round.reviewerRoleName
+        || run.summary !== round.summary
+        || run.yieldReceipt === undefined) {
+        return `Reviewer Run ${run.id} does not match the non-semantic Round receipt.`;
+    }
+    const receiptMatch = matchYieldReceipt(run.yieldReceipt, {
+        status: "yielded",
+        summary: round.summary ?? "",
+        reviewResult: {
+            report: round.report ?? "",
+            checks: round.checks ?? [],
+            evidenceCommit: round.reviewBaseCommit
         }
+    });
+    if (receiptMatch?.kind !== "replayed") {
+        return `Reviewer Run ${run.id} yield receipt does not cover the Round outcome.`;
+    }
+    const finding = store.listReviewFindings(round.taskId).find((entry) => (entry.firstReviewRoundId === round.id || entry.lastReviewRoundId === round.id));
+    if (finding !== undefined)
+        return `Review finding ${finding.id} references the Round.`;
+    const events = store.listEvents(round.taskId).filter((event) => (event.type === "review.completed" && event.payload.reviewRoundId === round.id));
+    if (events.length !== 1)
+        return "Completed Round lacks one exact completion Event.";
+    const event = events[0];
+    if (event.payload.workItemId !== round.workItemId
+        || event.payload.candidateId !== round.candidateId
+        || event.payload.reviewBaseCommit !== round.reviewBaseCommit
+        || event.payload.evidenceCommit !== round.reviewBaseCommit
+        || event.payload.checks !== "none") {
+        return `Review completion Event ${event.id} carries mismatched or semantic evidence.`;
+    }
+    return null;
+}
+function explicitCompletedReviewInfrastructureFailure(summary, round) {
+    if (exactCompletedReviewInfrastructureFailureReport(summary))
+        return true;
+    const report = summary.trim();
+    if (report === `Role Run workspace is not the durable owner: ${round.taskId}/${round.reviewerRoleName}.`
+        || (round.reviewerRunId !== undefined
+            && report === `Review Run workspace is not the durable owner: ${round.reviewerRunId}.`)) {
+        return true;
     }
-    return {
-        kind: "infra",
-        infraKind: "other-infra",
-        reason: "Review execution attempt failed before a semantic report."
-    };
+    return /^(?:Run )?(?:Context|Context Pack) load (?:failed|unavailable|unauthorized|stale|mismatched|malformed)(?:: (?:failure|mismatch|unavailable|unauthorized|stale|mismatched|malformed))?\.?$/iu
+        .test(report);
 }
-/** True when this Round may feed the finding ledger. */
-export function isSemanticReviewRound(round) {
-    return classifyReviewRoundOutcome(round)?.kind === "semantic";
+function exactCompletedReviewInfrastructureFailureReport(summary) {
+    const lines = summary.trim().split(/\r?\n/u);
+    const envelope = [
+        /^# Review result: (?:context-load|workspace-binding) failure$/u,
+        /^$/u,
+        /^The assigned Run context could not be safely matched to this native session, so no candidate review was performed\.$/u,
+        /^$/u,
+        /^- Run: `[^`\r\n]+`$/u,
+        /^- ReviewRound: `[^`\r\n]+`$/u,
+        /^- Review base commit: `[0-9a-f]{40}`$/u,
+        /^- Frozen target: `[^`\r\n]+`$/u,
+        /^- Authorized workspace from the exact Context Pack: `[^`\r\n]+`$/u,
+        /^- Session-attached workspace: `[^`\r\n]+`$/u,
+        /^- Verification: both paths resolve distinctly and have different filesystem inodes \(`[^`\r\n]+` vs `[^`\r\n]+`\)\.$/u,
+        /^$/u,
+        /^## Findings$/u,
+        /^$/u,
+        /^- Verified-fixed findings: none; review did not start\.$/u,
+        /^- New findings: none; candidate sources were intentionally not inspected\.$/u,
+        /^- Accepted risks: none accepted\.$/u,
+        /^- Residual verification gaps: the complete frozen diff, changed control-flow paths, callers, data-integrity behavior, and required deterministic checks remain unreviewed because the Review workspace binding is mismatched\.$/u,
+        /^$/u,
+        /^## Checks actually run$/u,
+        /^$/u,
+        /^- Exact Context API load: passed for Task\/Run\/Role\/purpose\/subject\/snapshot\/adapter\.$/u,
+        /^- Workspace binding verification: failed\.$/u,
+        /^- Candidate build\/tests\/package checks: not run\.$/u,
+        /^- Real-provider E2E: not run and not authorized\.$/u,
+        /^$/u,
+        /^## Required next action$/u,
+        /^$/u,
+        /^Attach the native Reviewer session to the exact workspace recorded by the Context Pack, or issue a fresh internally consistent Review Run\/Context Pack\. Then perform the complete bounded Task-final review at the frozen head\.$/u
+    ];
+    return lines.length === envelope.length
+        && envelope.every((pattern, index) => pattern.test(lines[index]));
+}
+function runtimeFailureSummaryHasReviewerOutput(summary) {
+    const output = /(?:^|\n)last_assistant_message:[ \t]*([\s\S]*)$/u.exec(summary)?.[1];
+    return output !== undefined && output.trim().length > 0;
+}
+function looksLikeStructuredReviewReport(report) {
+    let parsed;
+    try {
+        parsed = JSON.parse(report);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return false;
+    const record = parsed;
+    return [
+        "summary", "report", "checks", "findings", "evidence", "evidenceCommit",
+        "deltaDisposition", "deltaReasoning"
+    ].some((key) => Object.hasOwn(record, key));
 }

package/dist/review/taskFinalReviewContractEvent.js

@@ -0,0 +1 @@
+export const TASK_FINAL_REVIEW_CONTRACT_REBOUND_EVENT = "review.task-final-contract-rebound";

package/dist/review/taskFinalReviewContractRebind.js

@@ -0,0 +1,350 @@
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { requireIdentity, requireTimestamp } from "../domain/validation.js";
+import { readActiveReleasePointer, readHandoverFence, readHandoverReceipt, releaseDirectoryName, releasesDirectory, verifyReleaseIntegrity } from "../release/runtimeRelease.js";
+import { exactControlPlaneDigest, parseExactControlPlaneDescriptor } from "../runtime/exactControlPlane.js";
+import { createTaskFinalReviewContract, sameTaskFinalReviewContract, validateTaskFinalReviewContract } from "./taskFinalReviewContract.js";
+import { governingWorkItemCandidate } from "../workItem/workItem.js";
+import { TASK_FINAL_REVIEW_CONTRACT_REBOUND_EVENT } from "./taskFinalReviewContractEvent.js";
+export { TASK_FINAL_REVIEW_CONTRACT_REBOUND_EVENT } from "./taskFinalReviewContractEvent.js";
+/**
+ * Resolves the effective Task-final Review contract from its immutable Task
+ * records. Mutation and read-model callers share this adapter so a legal
+ * release rebind cannot be interpreted differently by the two paths.
+ */
+export function resolveRecordedTaskFinalReviewContract(taskId, workItems, reviewRounds, events) {
+    const candidateObservations = workItems.flatMap((item) => {
+        const candidate = governingWorkItemCandidate(item);
+        return candidate?.taskFinalReviewContract === undefined
+            ? []
+            : [{
+                    contract: candidate.taskFinalReviewContract,
+                    createdAt: candidate.createdAt,
+                    source: `Candidate ${item.id}/${candidate.id}`
+                }];
+    });
+    const reviewObservations = reviewRounds.flatMap((round) => ((round.scope ?? "work-item") !== "task"
+        || round.taskFinalReviewContract === undefined
+        ? []
+        : [{
+                contract: round.taskFinalReviewContract,
+                createdAt: round.createdAt,
+                source: `ReviewRound ${round.id}`
+            }]));
+    return resolveTaskFinalReviewContract(taskId, [...candidateObservations, ...reviewObservations], events);
+}
+export function createTaskFinalReviewContractRebind(input) {
+    const taskId = requireIdentity(input.taskId, "Task final-review rebind Task id");
+    const reviewerRoleName = requireIdentity(input.reviewerRoleName, "Task final-review rebind Reviewer Role");
+    const fromContract = validateTaskFinalReviewContract(input.fromContract);
+    if (fromContract.taskId !== taskId) {
+        throw new Error("Task final-review rebind contract belongs to another Task.");
+    }
+    if (fromContract.reviewerRoleName !== reviewerRoleName) {
+        throw new Error("Task final-review rebind changes the Reviewer identity.");
+    }
+    const toContract = createTaskFinalReviewContract({
+        taskId,
+        reviewerRoleName,
+        controlPlaneDigest: requireDigest(input.toControlPlaneDigest, "Task final-review rebind target control-plane digest")
+    });
+    if (fromContract.controlPlaneDigest === toContract.controlPlaneDigest) {
+        throw new Error("Task final-review rebind must change the control-plane digest.");
+    }
+    const fromRelease = validateReleaseIdentity(input.fromRelease, "source");
+    const toRelease = validateReleaseIdentity(input.toRelease, "target");
+    if (fromRelease.releaseId === toRelease.releaseId) {
+        throw new Error("Task final-review rebind must cross an immutable release handover.");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        taskId,
+        reviewerRoleName,
+        fromContract,
+        toContract,
+        fromRelease,
+        toRelease,
+        handoverId: requireIdentity(input.handoverId, "Task final-review rebind handover id"),
+        authorizedBy: requireText(input.authorizedBy, "Task final-review rebind authorizer")
+    });
+}
+export function taskFinalReviewContractRebindPayload(rebind) {
+    const validated = createTaskFinalReviewContractRebind({
+        ...rebind,
+        toControlPlaneDigest: rebind.toContract.controlPlaneDigest
+    });
+    return {
+        schemaVersion: "1",
+        taskId: validated.taskId,
+        reviewerRoleName: validated.reviewerRoleName,
+        fromContractDigest: validated.fromContract.digest,
+        toContractDigest: validated.toContract.digest,
+        fromControlPlaneDigest: validated.fromContract.controlPlaneDigest,
+        toControlPlaneDigest: validated.toContract.controlPlaneDigest,
+        fromReleaseId: validated.fromRelease.releaseId,
+        fromReleaseVersion: validated.fromRelease.version,
+        fromReleaseBuildId: validated.fromRelease.buildId,
+        fromReleasePackageDigest: validated.fromRelease.packageDigest,
+        ...(validated.fromRelease.sourceCommit === undefined
+            ? {}
+            : { fromReleaseSourceCommit: validated.fromRelease.sourceCommit }),
+        toReleaseId: validated.toRelease.releaseId,
+        toReleaseVersion: validated.toRelease.version,
+        toReleaseBuildId: validated.toRelease.buildId,
+        toReleasePackageDigest: validated.toRelease.packageDigest,
+        ...(validated.toRelease.sourceCommit === undefined
+            ? {}
+            : { toReleaseSourceCommit: validated.toRelease.sourceCommit }),
+        handoverId: validated.handoverId,
+        authorizedBy: validated.authorizedBy
+    };
+}
+export function taskFinalReviewContractRebindFromEvent(event) {
+    if (event.type !== TASK_FINAL_REVIEW_CONTRACT_REBOUND_EVENT) {
+        throw new Error(`Task event is not a final-review contract rebind: ${event.id}.`);
+    }
+    const payload = event.payload;
+    if (payload.schemaVersion !== "1") {
+        throw new Error(`Task final-review rebind event schema is invalid: ${event.id}.`);
+    }
+    if (payload.taskId !== event.taskId) {
+        throw new Error(`Task final-review rebind event belongs to another Task: ${event.id}.`);
+    }
+    const fromContract = createTaskFinalReviewContract({
+        taskId: payload.taskId,
+        reviewerRoleName: payload.reviewerRoleName,
+        controlPlaneDigest: payload.fromControlPlaneDigest
+    });
+    if (fromContract.digest !== payload.fromContractDigest) {
+        throw new Error(`Task final-review rebind source digest is invalid: ${event.id}.`);
+    }
+    const rebind = createTaskFinalReviewContractRebind({
+        taskId: payload.taskId,
+        reviewerRoleName: payload.reviewerRoleName,
+        fromContract,
+        toControlPlaneDigest: payload.toControlPlaneDigest,
+        fromRelease: releaseIdentityFromPayload(payload, "from"),
+        toRelease: releaseIdentityFromPayload(payload, "to"),
+        handoverId: payload.handoverId,
+        authorizedBy: payload.authorizedBy
+    });
+    if (rebind.toContract.digest !== payload.toContractDigest) {
+        throw new Error(`Task final-review rebind target digest is invalid: ${event.id}.`);
+    }
+    return rebind;
+}
+/**
+ * Historical Candidate and Review records remain immutable. Before the first
+ * explicit rebind event, older Yui releases may have emitted successive
+ * control-plane contracts without a rebind event. Preserve that legacy prefix
+ * as a forward-only sequence, then require one strict append-only rebind chain.
+ * Any Reviewer change, reversion, fork, or post-rebind drift fails closed.
+ */
+export function resolveTaskFinalReviewContract(taskId, observations, events) {
+    const normalizedTaskId = requireIdentity(taskId, "Task final-review contract Task id");
+    const orderedObservations = [...observations]
+        .map((observation) => ({
+        contract: validateTaskFinalReviewContract(observation.contract),
+        createdAt: requireTimestamp(observation.createdAt, "Task final-review observation createdAt"),
+        source: requireText(observation.source, "Task final-review observation source")
+    }))
+        .sort(compareCreatedAt);
+    const orderedEvents = events
+        .filter(({ type }) => type === TASK_FINAL_REVIEW_CONTRACT_REBOUND_EVENT)
+        .map((event) => ({
+        event,
+        createdAt: requireTimestamp(event.createdAt, "Task final-review rebind event createdAt"),
+        rebind: taskFinalReviewContractRebindFromEvent(event)
+    }))
+        .sort((left, right) => compareCreatedAt(left, right)
+        || left.event.id.localeCompare(right.event.id, undefined, { numeric: true }));
+    if (orderedObservations.length === 0) {
+        if (orderedEvents.length > 0) {
+            throw new Error(`Task ${normalizedTaskId} has a final-review rebind without a stored contract.`);
+        }
+        return undefined;
+    }
+    for (const observation of orderedObservations) {
+        if (observation.contract.taskId !== normalizedTaskId) {
+            throw new Error(`${observation.source} carries a final-review contract for another Task.`);
+        }
+    }
+    const initial = orderedObservations[0].contract;
+    const reviewerRoleName = initial.reviewerRoleName;
+    const firstRebindAt = orderedEvents[0]?.createdAt;
+    const legacyObservations = firstRebindAt === undefined
+        ? orderedObservations
+        : orderedObservations.filter(({ createdAt }) => createdAt < firstRebindAt);
+    if (legacyObservations.length === 0) {
+        throw new Error(`Task ${normalizedTaskId} has a final-review rebind without an established source contract.`);
+    }
+    let effective = initial;
+    const legacyContractDigests = new Set([initial.digest]);
+    for (const observation of legacyObservations) {
+        if (observation.contract.reviewerRoleName !== reviewerRoleName) {
+            throw new Error(`${observation.source} changes the Task final-review Reviewer identity.`);
+        }
+        if (sameTaskFinalReviewContract(observation.contract, effective))
+            continue;
+        if (legacyContractDigests.has(observation.contract.digest)) {
+            throw new Error(`${observation.source} reverts a legacy Task final-review contract.`);
+        }
+        legacyContractDigests.add(observation.contract.digest);
+        effective = observation.contract;
+    }
+    for (const entry of orderedEvents) {
+        const { rebind } = entry;
+        if (!sameTaskFinalReviewContract(effective, rebind.fromContract)) {
+            throw new Error(`Task final-review rebind chain forks at ${entry.event.id}.`);
+        }
+        if (rebind.reviewerRoleName !== initial.reviewerRoleName) {
+            throw new Error(`Task final-review rebind changes Reviewer identity at ${entry.event.id}.`);
+        }
+        effective = rebind.toContract;
+    }
+    for (const observation of orderedObservations) {
+        if (firstRebindAt === undefined || observation.createdAt < firstRebindAt)
+            continue;
+        let expected = legacyObservations.at(-1).contract;
+        for (const entry of orderedEvents) {
+            if (entry.createdAt > observation.createdAt)
+                break;
+            expected = entry.rebind.toContract;
+        }
+        if (!sameTaskFinalReviewContract(observation.contract, expected)) {
+            throw new Error(`${observation.source} does not match the effective Task final-review contract at creation.`);
+        }
+    }
+    return Object.freeze({
+        initial,
+        effective,
+        rebinds: Object.freeze(orderedEvents.map(({ rebind }) => rebind))
+    });
+}
+/**
+ * Builds the immutable release proof while the caller holds the release
+ * handover lock. The current exact control descriptor is supplied only by the
+ * CLI preflight; caller-provided target identities are checked against it.
+ */
+export function prepareTaskFinalReviewContractRebindProof(input) {
+    const home = resolve(input.home);
+    const taskId = requireIdentity(input.taskId, "Task final-review rebind Task id");
+    const fromControlPlaneDigest = requireDigest(input.fromControlPlaneDigest, "Task final-review rebind source control-plane digest");
+    const toControlPlaneDigest = requireDigest(input.toControlPlaneDigest, "Task final-review rebind target control-plane digest");
+    if (fromControlPlaneDigest === toControlPlaneDigest) {
+        throw new Error("Task final-review rebind source and target control planes are identical.");
+    }
+    if (exactControlPlaneDigest(input.currentControlPlane) !== toControlPlaneDigest) {
+        throw new Error("Task final-review rebind target is not the current exact control plane.");
+    }
+    if (resolve(input.currentControlPlane.yuiHome) !== home) {
+        throw new Error("Task final-review rebind target control plane belongs to another Home.");
+    }
+    const fromReleaseId = requireText(input.fromReleaseId, "Source release id");
+    const toReleaseId = requireText(input.toReleaseId, "Target release id");
+    if (fromReleaseId === toReleaseId) {
+        throw new Error("Task final-review rebind source and target releases are identical.");
+    }
+    if (readHandoverFence(home) !== null) {
+        throw new Error("Task final-review rebind is blocked by an unfinished release handover.");
+    }
+    const active = readActiveReleasePointer(home);
+    if (active === null
+        || active.releaseId !== toReleaseId
+        || active.buildId !== input.currentControlPlane.buildId
+        || active.packageDigest !== input.currentControlPlane.activeReleaseDigest) {
+        throw new Error("The active release does not match the requested target release and exact control plane.");
+    }
+    const sourcePath = join(home, "runtime", "control-plane", `${fromControlPlaneDigest}.json`);
+    const sourceControl = parseExactControlPlaneDescriptor(readFileSync(sourcePath, "utf8"));
+    if (exactControlPlaneDigest(sourceControl) !== fromControlPlaneDigest) {
+        throw new Error("Task final-review rebind source control-plane descriptor digest is invalid.");
+    }
+    if (resolve(sourceControl.yuiHome) !== home) {
+        throw new Error("Task final-review rebind source control plane belongs to another Home.");
+    }
+    const fromRelease = installedReleaseIdentity(home, fromReleaseId, sourceControl, "source");
+    const toRelease = installedReleaseIdentity(home, toReleaseId, input.currentControlPlane, "target");
+    const handover = readHandoverReceipt(home);
+    if (handover === null
+        || handover.outcome !== "completed"
+        || handover.activatedReleaseId !== toReleaseId
+        || typeof handover.handoverId !== "string"
+        || handover.handoverId.length === 0) {
+        throw new Error("Task final-review rebind requires the completed release handover that activated the target.");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        taskId,
+        fromControlPlaneDigest,
+        toControlPlaneDigest,
+        fromRelease,
+        toRelease,
+        handoverId: handover.handoverId
+    });
+}
+function installedReleaseIdentity(home, releaseId, control, label) {
+    if (control.buildId === undefined || control.activeReleaseDigest === undefined) {
+        throw new Error(`Task final-review rebind ${label} control plane is not an immutable release.`);
+    }
+    let manifest;
+    try {
+        manifest = verifyReleaseIntegrity(join(releasesDirectory(home), releaseId));
+    }
+    catch (error) {
+        throw new Error(`Task final-review rebind ${label} release is unknown or invalid: ${releaseId}.`, { cause: error });
+    }
+    if (releaseDirectoryName(manifest) !== releaseId
+        || manifest.buildId !== control.buildId
+        || manifest.packageDigest !== control.activeReleaseDigest) {
+        throw new Error(`Task final-review rebind ${label} release does not match its control plane.`);
+    }
+    return validateReleaseIdentity({
+        releaseId,
+        version: manifest.version,
+        buildId: manifest.buildId,
+        packageDigest: manifest.packageDigest,
+        ...(manifest.sourceCommit === undefined ? {} : { sourceCommit: manifest.sourceCommit })
+    }, label);
+}
+function releaseIdentityFromPayload(payload, prefix) {
+    const title = prefix === "from" ? "From" : "To";
+    return validateReleaseIdentity({
+        releaseId: payload[`${prefix}ReleaseId`],
+        version: payload[`${prefix}ReleaseVersion`],
+        buildId: payload[`${prefix}ReleaseBuildId`],
+        packageDigest: payload[`${prefix}ReleasePackageDigest`],
+        ...(payload[`${prefix}ReleaseSourceCommit`] === undefined
+            ? {}
+            : { sourceCommit: payload[`${prefix}ReleaseSourceCommit`] })
+    }, title);
+}
+function validateReleaseIdentity(value, label) {
+    return Object.freeze({
+        releaseId: requireText(value.releaseId, `Task final-review rebind ${label} release id`),
+        version: requireText(value.version, `Task final-review rebind ${label} release version`),
+        buildId: requireText(value.buildId, `Task final-review rebind ${label} release build id`),
+        packageDigest: requireDigest(value.packageDigest, `Task final-review rebind ${label} release package digest`),
+        ...(value.sourceCommit === undefined
+            ? {}
+            : { sourceCommit: requireText(value.sourceCommit, `Task final-review rebind ${label} source commit`) })
+    });
+}
+function compareCreatedAt(left, right) {
+    return left.createdAt.localeCompare(right.createdAt);
+}
+function requireDigest(value, label) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}