@osovv/vv-opencode 1.3.8 → 1.4.1

package/dist/plugins/workflow/checkpoints.js

@@ -0,0 +1,1067 @@
+// FILE: src/plugins/workflow/checkpoints.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Registered delegated plan runs with declared review checkpoints, generation-bound reviewer linkage, fingerprint-verified outcomes, and rework authorization.
+//   SCOPE: Atomic plan-run registration binding canonical task ids to stable delegated work items, idempotent re-registration with explicit drift rejection, checkpoint start with prerequisite acceptance and fresh fingerprints through linked review_only work items, reviewer launch/result recording bound to the current generation, verify deriving passed/failed/stale/stopped outcomes from recorded results plus recomputed fingerprints and approval-input hashes, final complete sealing, failed-checkpoint rework authorization, wave-barrier and overlapping-write gates, and read-only run views. No agent dispatch or command execution.
+//   DEPENDS: [node:crypto, src/plugins/workflow/checkpoint-io.ts, src/plugins/workflow/delegated.ts, src/plugins/workflow/snapshots.ts, src/plugins/workflow/state.ts]
+//   LINKS: [M-WORKFLOW-CHECKPOINTS, M-WORKFLOW-DELEGATED, M-WORKFLOW-SNAPSHOTS, M-WORKFLOW-STATE, M-SPEC-LINT, V-M-WORKFLOW-CHECKPOINTS]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   MAX_CHECKPOINT_REVIEW_ATTEMPTS - Maximum review generations per checkpoint (initial plus one correction).
+//   DelegatedReviewerOutcome - One reviewer's recorded outcome inside a generation.
+//   DelegatedCheckpointReview - Current in-flight review generation state.
+//   DelegatedCheckpointHistoryEntry - One settled generation outcome as historical evidence.
+//   DelegatedRunCheckpoint - Registered checkpoint runtime state.
+//   DelegatedRunTask - Canonical task to work-item binding.
+//   DelegatedPlanRun - Registered plan-run registry entry.
+//   RegisterDelegatedPlanInput - Registration input carrying the loaded approved plan.
+//   RegisterDelegatedPlanResult - Registration outcome including idempotent reuse.
+//   StartDelegatedCheckpointInput - Checkpoint start input identities.
+//   StartDelegatedCheckpointResult - Checkpoint start outcome with launch instructions.
+//   RecordReviewerLaunchResult - Reviewer launch binding outcome.
+//   RecordReviewerResultResult - Reviewer result recording outcome with round completeness.
+//   VerifyDelegatedCheckpointInput - Verify request with optional final complete flag.
+//   VerifyDelegatedCheckpointResult - Derived verify outcome and optional sealed completion.
+//   AuthorizeReworkInput - Failed-checkpoint rework authorization request.
+//   AuthorizeReworkResult - Rework authorization outcome delegating to the guarded reducer.
+//   checkpointBarrierUnsatisfied - Unsatisfied barriers blocking a wave's task launches.
+//   findOverlappingInFlightReview - In-flight checkpoint scope overlap detection for declared writes.
+//   getDelegatedRunView - Read-only run serialization for tooling output.
+//   registerDelegatedPlan - Atomically register a validated approved delegated plan.
+//   registerDelegatedPlanInStore - Store-level registration used by the plugin and tests.
+//   startDelegatedCheckpoint - Start a due checkpoint generation with a fresh fingerprint.
+//   startDelegatedCheckpointInStore - Store-level checkpoint start.
+//   recordCheckpointReviewerLaunch - Bind one reviewer launch call to the current generation.
+//   recordCheckpointReviewerLaunchInStore - Store-level reviewer launch binding.
+//   recordCheckpointReviewerResult - Record one reviewer outcome for the current generation.
+//   recordCheckpointReviewerResultInStore - Store-level reviewer result recording.
+//   verifyDelegatedCheckpoint - Derive the checkpoint outcome from results and fresh fingerprints.
+//   verifyDelegatedCheckpointInStore - Store-level verify used by the plugin and tests.
+//   authorizeReworkFromFailedCheckpoint - Validate failed-checkpoint rework authorization.
+//   authorizeReworkFromFailedCheckpointInStore - Store-level rework authorization.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [C-DELEGATED-WORKFLOW-ASTRA-PRESETS - Initial registry: registration, generations, fingerprint verification, final sealing, rework authorization, and barrier gates.]
+// END_CHANGE_SUMMARY
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { contentSha256 } from "./checkpoint-io.js";
+import { currentDelegatedAcceptance, reworkDelegatedWorkItem, validateDelegatedWriteScope, } from "./delegated.js";
+import { captureWorkflowSnapshot } from "./snapshots.js";
+import { cloneRecord, createRecordLookupKey, } from "./state.js";
+// START_BLOCK_REGISTRY_TYPES
+export const MAX_CHECKPOINT_REVIEW_ATTEMPTS = 2;
+// END_BLOCK_REGISTRY_TYPES
+// START_BLOCK_REGISTRY_HELPERS
+function toIsoNow() {
+    return new Date().toISOString();
+}
+function findRun(data, runId) {
+    return data.planRuns.get(runId);
+}
+function findRecord(data, sessionId, workItemId) {
+    return data.records.get(createRecordLookupKey(sessionId, workItemId));
+}
+function runIdFor(plan) {
+    return `run-${createHash("sha256")
+        .update(`${plan.planPath}\n${plan.planSha256}\n${plan.specSha256}`)
+        .digest("hex")
+        .slice(0, 16)}`;
+}
+function definitionsEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function cloneCheckpoint(checkpoint) {
+    return {
+        ...checkpoint,
+        covers: [...checkpoint.covers],
+        scope: [...checkpoint.scope],
+        reviewers: [...checkpoint.reviewers],
+        history: checkpoint.history.map((entry) => ({ ...entry })),
+        ...(checkpoint.currentReview
+            ? {
+                currentReview: {
+                    ...checkpoint.currentReview,
+                    coveredAttemptIds: [...checkpoint.currentReview.coveredAttemptIds],
+                    reviewerCallIds: { ...checkpoint.currentReview.reviewerCallIds },
+                    results: { ...checkpoint.currentReview.results },
+                },
+            }
+            : {}),
+    };
+}
+function cloneRun(run) {
+    return {
+        ...run,
+        tasks: new Map([...run.tasks].map(([taskId, task]) => [taskId, { ...task }])),
+        checkpoints: new Map([...run.checkpoints].map(([id, checkpoint]) => [id, cloneCheckpoint(checkpoint)])),
+    };
+}
+function waveIndexOf(run, wave) {
+    return run.definition.waves.indexOf(wave);
+}
+/** Covered-attempt identities for the currently accepted attempts of covered tasks. */
+function currentCoveredAttemptIds(data, run, checkpoint) {
+    const ids = [];
+    for (const taskId of checkpoint.covers) {
+        const task = run.tasks.get(taskId);
+        if (!task)
+            return { ok: false, taskId };
+        const record = findRecord(data, run.sessionId, task.workItemId);
+        const acceptance = record ? currentDelegatedAcceptance(record) : undefined;
+        if (!acceptance)
+            return { ok: false, taskId };
+        ids.push(`${task.workItemId}#${acceptance.attempt}`);
+    }
+    return { ok: true, ids };
+}
+// START_CONTRACT: registerDelegatedPlan
+//   PURPOSE: Atomically register all declared tasks and checkpoints of a validated approved delegated plan without launching agents.
+//   INPUTS: { store: WorkItemStore - backing store, input: RegisterDelegatedPlanInput - session and loaded approved plan }
+//   OUTPUTS: { RegisterDelegatedPlanResult - created or idempotently reused run, or an explicit drift/binding rejection }
+//   SIDE_EFFECTS: [Creates the registry entry and bound delegated work items; rolls back created items on failure]
+//   LINKS: [M-WORKFLOW-CHECKPOINTS, M-WORKFLOW-DELEGATED, loadApprovedDelegatedPlan]
+// END_CONTRACT: registerDelegatedPlan
+export function registerDelegatedPlan(store, input) {
+    return registerDelegatedPlanInStore(store.getStoreData(), input);
+}
+export function registerDelegatedPlanInStore(data, input) {
+    if (typeof input.sessionId !== "string" || input.sessionId.trim() === "") {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: "sessionId must be a non-empty string",
+        };
+    }
+    const runId = runIdFor(input.plan);
+    const existing = findRun(data, runId);
+    if (existing) {
+        if (existing.sessionId !== input.sessionId) {
+            return {
+                ok: false,
+                errorCode: "SESSION_MISMATCH",
+                message: `run ${runId} belongs to session ${existing.sessionId}`,
+            };
+        }
+        const identical = existing.planPath === input.plan.planPath &&
+            existing.specPath === input.plan.specPath &&
+            existing.workspaceRoot === input.plan.workspaceRoot &&
+            existing.planSha256 === input.plan.planSha256 &&
+            existing.specSha256 === input.plan.specSha256 &&
+            definitionsEqual(existing.definition, input.plan.definition);
+        if (!identical) {
+            return {
+                ok: false,
+                errorCode: "PLAN_DRIFT",
+                message: `run ${runId} was registered from different approved inputs; supersede or replan instead of resetting progress`,
+            };
+        }
+        return { ok: true, runId, reused: true, run: cloneRun(existing) };
+    }
+    const samePlanPath = [...data.planRuns.values()].find((run) => run.planPath === input.plan.planPath && run.sessionId === input.sessionId);
+    if (samePlanPath) {
+        return {
+            ok: false,
+            errorCode: "PLAN_DRIFT",
+            message: `plan ${input.plan.planPath} is already registered as run ${samePlanPath.runId} with different content; explicit plan amendment is required`,
+        };
+    }
+    // Stage all bound delegated work items before committing the registry entry.
+    // Write scopes are validated with the same normalizer the runtime snapshots
+    // use, so a plan that reaches registration can never declare a scope the
+    // snapshot normalizer or the persistence validator would reject later.
+    const createdWorkItemIds = [];
+    const tasks = new Map();
+    for (const task of input.plan.definition.tasks) {
+        const key = `delegated-${runId}-${task.taskId}`;
+        const scopeValidation = validateDelegatedWriteScope(task.writeScope);
+        if (!scopeValidation.ok) {
+            rollbackCreatedItems(data, input.sessionId, createdWorkItemIds);
+            return {
+                ok: false,
+                errorCode: "TASK_BINDING_FAILED",
+                message: `binding task ${task.taskId} failed: write scope rejected (${scopeValidation.message ?? "invalid scope"})`,
+            };
+        }
+        const opened = openInStore(data, {
+            sessionId: input.sessionId,
+            key,
+            title: `Delegated ${task.taskId}: ${task.taskElement}`,
+            mode: "delegated",
+            requiredReviewers: [],
+            writeScope: scopeValidation.paths ?? [],
+            planRunId: runId,
+            planTaskId: task.taskId,
+        });
+        if (!opened || !opened.ok) {
+            rollbackCreatedItems(data, input.sessionId, createdWorkItemIds);
+            return {
+                ok: false,
+                errorCode: "TASK_BINDING_FAILED",
+                message: `binding task ${task.taskId} failed: ${opened && !opened.ok ? opened.message : "unknown"}`,
+            };
+        }
+        createdWorkItemIds.push(opened.record.workItemId);
+        tasks.set(task.taskId, { taskId: task.taskId, workItemId: opened.record.workItemId });
+    }
+    const checkpoints = new Map();
+    for (const checkpoint of input.plan.definition.checkpoints) {
+        checkpoints.set(checkpoint.checkpointId, {
+            checkpointId: checkpoint.checkpointId,
+            kind: checkpoint.kind,
+            afterWave: checkpoint.afterWave,
+            covers: [...checkpoint.covers],
+            scope: [...checkpoint.scope],
+            reviewers: [...checkpoint.reviewers],
+            status: "pending",
+            attempts: 0,
+            history: [],
+        });
+    }
+    const finalCheckpoint = input.plan.definition.checkpoints.find((c) => c.kind === "final");
+    const run = {
+        runId,
+        sessionId: input.sessionId,
+        planPath: input.plan.planPath,
+        specPath: input.plan.specPath,
+        workspaceRoot: input.plan.workspaceRoot,
+        planSha256: input.plan.planSha256,
+        specSha256: input.plan.specSha256,
+        definition: input.plan.definition,
+        registeredAt: toIsoNow(),
+        status: "active",
+        ...(finalCheckpoint ? { finalCheckpointId: finalCheckpoint.checkpointId } : {}),
+        tasks,
+        checkpoints,
+    };
+    data.planRuns.set(runId, run);
+    return { ok: true, runId, reused: false, run: cloneRun(run) };
+}
+function openInStore(data, input) {
+    const sessionIndex = data.keyIndexBySession.get(input.sessionId) ??
+        (() => {
+            const index = new Map();
+            data.keyIndexBySession.set(input.sessionId, index);
+            return index;
+        })();
+    const existingId = sessionIndex.get(input.key);
+    if (existingId) {
+        const existing = data.records.get(createRecordLookupKey(input.sessionId, existingId));
+        if (existing) {
+            const sameIntent = existing.title === input.title &&
+                existing.mode === input.mode &&
+                existing.delegated?.planRunId === input.planRunId &&
+                existing.delegated?.planTaskId === input.planTaskId &&
+                JSON.stringify(existing.delegated?.writeScope ?? []) ===
+                    JSON.stringify([...(input.writeScope ?? [])]);
+            if (!sameIntent) {
+                return {
+                    ok: false,
+                    errorCode: "WORK_ITEM_KEY_CONFLICT",
+                    message: `WORK_ITEM_KEY_CONFLICT: key ${input.key} is already associated with different workflow intent`,
+                    existingWorkItemId: existing.workItemId,
+                };
+            }
+            return {
+                ok: true,
+                reused: true,
+                record: cloneRecord(existing),
+                header: `VVOC_WORK_ITEM_ID: ${existing.workItemId}`,
+            };
+        }
+        sessionIndex.delete(input.key);
+    }
+    const workItemId = `wi-${data.nextId}`;
+    data.nextId += 1;
+    const now = toIsoNow();
+    const record = {
+        sessionId: input.sessionId,
+        workItemId,
+        key: input.key,
+        title: input.title,
+        mode: input.mode,
+        requiredReviewers: [],
+        state: "open",
+        delegated: {
+            writeScope: [...(input.writeScope ?? [])],
+            ...(input.planRunId && input.planTaskId
+                ? { planRunId: input.planRunId, planTaskId: input.planTaskId }
+                : {}),
+            attempts: [],
+            decisions: [],
+            acceptances: [],
+            reworkHistory: [],
+        },
+        completedReviewRoundCount: 0,
+        specReviewCount: 0,
+        codeReviewCount: 0,
+        createdAt: now,
+        updatedAt: now,
+    };
+    sessionIndex.set(input.key, workItemId);
+    data.records.set(createRecordLookupKey(input.sessionId, workItemId), record);
+    return {
+        ok: true,
+        reused: false,
+        record: cloneRecord(record),
+        header: `VVOC_WORK_ITEM_ID: ${workItemId}`,
+    };
+}
+function rollbackCreatedItems(data, sessionId, workItemIds) {
+    for (const workItemId of workItemIds) {
+        const record = data.records.get(createRecordLookupKey(sessionId, workItemId));
+        if (!record)
+            continue;
+        if (record.state !== "open")
+            continue; // never roll back items that progressed
+        data.records.delete(createRecordLookupKey(sessionId, workItemId));
+        const sessionIndex = data.keyIndexBySession.get(sessionId);
+        if (sessionIndex?.get(record.key) === workItemId) {
+            sessionIndex.delete(record.key);
+        }
+    }
+}
+// START_CONTRACT: startDelegatedCheckpoint
+//   PURPOSE: Start a due checkpoint generation after prerequisite acceptance, capturing a fresh scope fingerprint and opening the declared reviewer set.
+//   INPUTS: { store: WorkItemStore - backing store, input: StartDelegatedCheckpointInput - session, run, and checkpoint identity }
+//   OUTPUTS: { StartDelegatedCheckpointResult - launch instructions for the linked review_only item or a coded rejection }
+//   SIDE_EFFECTS: [Mutates checkpoint state and creates the linked review_only work item]
+//   LINKS: [M-WORKFLOW-CHECKPOINTS, M-WORKFLOW-STATE, captureWorkflowSnapshot]
+// END_CONTRACT: startDelegatedCheckpoint
+export async function startDelegatedCheckpoint(store, input) {
+    return startDelegatedCheckpointInStore(store.getStoreData(), input);
+}
+export async function startDelegatedCheckpointInStore(data, input) {
+    const run = findRun(data, input.runId);
+    if (!run) {
+        return { ok: false, errorCode: "RUN_NOT_FOUND", message: `RUN_NOT_FOUND: ${input.runId}` };
+    }
+    if (run.sessionId !== input.sessionId) {
+        return {
+            ok: false,
+            errorCode: "SESSION_MISMATCH",
+            message: `SESSION_MISMATCH: run ${input.runId} belongs to session ${run.sessionId}`,
+        };
+    }
+    if (run.status === "sealed") {
+        return {
+            ok: false,
+            errorCode: "RUN_SEALED",
+            message: `RUN_SEALED: run ${input.runId} is complete`,
+        };
+    }
+    const checkpoint = run.checkpoints.get(input.checkpointId);
+    if (!checkpoint) {
+        return {
+            ok: false,
+            errorCode: "CHECKPOINT_NOT_FOUND",
+            message: `CHECKPOINT_NOT_FOUND: ${input.checkpointId} is not declared in run ${input.runId}`,
+        };
+    }
+    if (checkpoint.status === "passed") {
+        return {
+            ok: false,
+            errorCode: "ALREADY_PASSED",
+            message: `ALREADY_PASSED: ${input.checkpointId} passed at generation ${checkpoint.attempts}`,
+        };
+    }
+    if (checkpoint.status === "in_review") {
+        return {
+            ok: false,
+            errorCode: "ALREADY_IN_REVIEW",
+            message: `ALREADY_IN_REVIEW: ${input.checkpointId} generation ${checkpoint.currentReview?.generation} is in flight`,
+        };
+    }
+    if (checkpoint.attempts >= MAX_CHECKPOINT_REVIEW_ATTEMPTS) {
+        return {
+            ok: false,
+            errorCode: "ATTEMPTS_EXHAUSTED",
+            message: `ATTEMPTS_EXHAUSTED: ${input.checkpointId} consumed ${checkpoint.attempts} review generations; explicit recovery is required`,
+        };
+    }
+    const covered = currentCoveredAttemptIds(data, run, checkpoint);
+    if (!covered.ok) {
+        return {
+            ok: false,
+            errorCode: "PREREQUISITES_NOT_ACCEPTED",
+            message: `PREREQUISITES_NOT_ACCEPTED: covered task ${covered.taskId} has no currently accepted attempt`,
+        };
+    }
+    const overlapping = [...run.checkpoints.values()].find((other) => other.checkpointId !== checkpoint.checkpointId &&
+        other.status === "in_review" &&
+        other.scope.some((file) => checkpoint.scope.includes(file)));
+    if (overlapping) {
+        return {
+            ok: false,
+            errorCode: "OVERLAPPING_SCOPE",
+            message: `OVERLAPPING_SCOPE: checkpoint ${overlapping.checkpointId} is in review and shares declared scope files`,
+        };
+    }
+    const snapshot = await captureWorkflowSnapshot({
+        workspaceRoot: run.workspaceRoot,
+        declaredPaths: checkpoint.scope,
+        coveredAttemptIds: covered.ids,
+    });
+    if (!snapshot.ok) {
+        return {
+            ok: false,
+            errorCode: "SNAPSHOT_FAILED",
+            message: `SNAPSHOT_FAILED: ${snapshot.message}`,
+        };
+    }
+    const generation = checkpoint.attempts + 1;
+    const now = toIsoNow();
+    const reviewKey = `checkpoint-${input.runId}-${input.checkpointId}-g${generation}`;
+    const reviewItem = openReviewItem(data, run.sessionId, reviewKey, checkpoint.reviewers);
+    if (!reviewItem.ok) {
+        return {
+            ok: false,
+            errorCode: "SNAPSHOT_FAILED",
+            message: `failed to open linked review item: ${reviewItem.message}`,
+        };
+    }
+    const updated = {
+        ...checkpoint,
+        status: "in_review",
+        attempts: generation,
+        lastOutcome: undefined,
+        currentReview: {
+            reviewWorkItemId: reviewItem.record.workItemId,
+            generation,
+            startedAt: now,
+            startFingerprint: snapshot.snapshot.fingerprint,
+            coveredAttemptIds: covered.ids,
+            reviewerCallIds: {},
+            results: {},
+        },
+    };
+    run.checkpoints.set(input.checkpointId, updated);
+    return {
+        ok: true,
+        checkpoint: cloneCheckpoint(updated),
+        reviewWorkItemId: reviewItem.record.workItemId,
+        header: reviewItem.header,
+        reviewersToLaunch: [...updated.reviewers],
+        generation,
+    };
+}
+function openReviewItem(data, sessionId, key, reviewers) {
+    const sessionIndex = data.keyIndexBySession.get(sessionId) ??
+        (() => {
+            const index = new Map();
+            data.keyIndexBySession.set(sessionId, index);
+            return index;
+        })();
+    const existingId = sessionIndex.get(key);
+    if (existingId) {
+        const existing = data.records.get(createRecordLookupKey(sessionId, existingId));
+        if (existing) {
+            return {
+                ok: true,
+                record: cloneRecord(existing),
+                header: `VVOC_WORK_ITEM_ID: ${existing.workItemId}`,
+            };
+        }
+        sessionIndex.delete(key);
+    }
+    const workItemId = `wi-${data.nextId}`;
+    data.nextId += 1;
+    const now = toIsoNow();
+    const sortedReviewers = [...reviewers].sort((left, right) => left === right ? 0 : left === "spec" ? -1 : 1);
+    const record = {
+        sessionId,
+        workItemId,
+        key,
+        title: `Checkpoint review ${key}`,
+        mode: "review_only",
+        requiredReviewers: sortedReviewers,
+        state: "awaiting_reviews",
+        currentRound: {
+            round: 1,
+            requiredReviewers: sortedReviewers,
+            pendingReviewers: sortedReviewers,
+            inFlightReviewers: [],
+            completedReviewers: [],
+            results: {},
+            status: "active",
+            createdAt: now,
+        },
+        completedReviewRoundCount: 0,
+        specReviewCount: 0,
+        codeReviewCount: 0,
+        createdAt: now,
+        updatedAt: now,
+    };
+    sessionIndex.set(key, workItemId);
+    data.records.set(createRecordLookupKey(sessionId, workItemId), record);
+    return { ok: true, record: cloneRecord(record), header: `VVOC_WORK_ITEM_ID: ${workItemId}` };
+}
+function resolveActiveReview(data, runId, checkpointId) {
+    const run = findRun(data, runId);
+    if (!run) {
+        return { ok: false, errorCode: "RUN_NOT_FOUND", message: `RUN_NOT_FOUND: ${runId}` };
+    }
+    const checkpoint = run.checkpoints.get(checkpointId);
+    if (!checkpoint) {
+        return {
+            ok: false,
+            errorCode: "CHECKPOINT_NOT_FOUND",
+            message: `CHECKPOINT_NOT_FOUND: ${checkpointId}`,
+        };
+    }
+    if (checkpoint.status !== "in_review" || !checkpoint.currentReview) {
+        return {
+            ok: false,
+            errorCode: "NOT_IN_REVIEW",
+            message: `NOT_IN_REVIEW: ${checkpointId} is ${checkpoint.status}`,
+        };
+    }
+    return { ok: true, run, checkpoint, review: checkpoint.currentReview };
+}
+// START_CONTRACT: recordCheckpointReviewerLaunch
+//   PURPOSE: Bind one reviewer launch call identity to the current checkpoint generation.
+//   INPUTS: { store: WorkItemStore - backing store, input: { runId, checkpointId, reviewer, callId } }
+//   OUTPUTS: { RecordReviewerLaunchResult - binding outcome }
+//   SIDE_EFFECTS: [Mutates the current generation's reviewer call map]
+//   LINKS: [M-WORKFLOW-CHECKPOINTS, M-PLUGIN-WORKFLOW]
+// END_CONTRACT: recordCheckpointReviewerLaunch
+export function recordCheckpointReviewerLaunch(store, input) {
+    return recordCheckpointReviewerLaunchInStore(store.getStoreData(), input);
+}
+export function recordCheckpointReviewerLaunchInStore(data, input) {
+    const active = resolveActiveReview(data, input.runId, input.checkpointId);
+    if (!active.ok)
+        return active;
+    if (!active.checkpoint.reviewers.includes(input.reviewer)) {
+        return {
+            ok: false,
+            errorCode: "REVIEWER_NOT_DECLARED",
+            message: `REVIEWER_NOT_DECLARED: ${input.reviewer} is not declared for ${input.checkpointId}`,
+        };
+    }
+    if (active.review.reviewerCallIds[input.reviewer]) {
+        return {
+            ok: false,
+            errorCode: "ALREADY_LAUNCHED",
+            message: `ALREADY_LAUNCHED: ${input.reviewer} already launched for generation ${active.review.generation}`,
+        };
+    }
+    if (active.review.results[input.reviewer]) {
+        return {
+            ok: false,
+            errorCode: "ALREADY_RECORDED",
+            message: `ALREADY_RECORDED: ${input.reviewer} already recorded a result`,
+        };
+    }
+    const callId = input.callId?.trim() ?? "";
+    if (!callId) {
+        return {
+            ok: false,
+            errorCode: "REVIEWER_NOT_DECLARED",
+            message: "callId must be a non-empty string",
+        };
+    }
+    active.review.reviewerCallIds[input.reviewer] = callId;
+    return { ok: true };
+}
+// START_CONTRACT: recordCheckpointReviewerResult
+//   PURPOSE: Record one reviewer outcome for the current generation, rejecting stale or mismatched callbacks.
+//   INPUTS: { store: WorkItemStore - backing store, input: { runId, checkpointId, reviewer, callId, status } }
+//   OUTPUTS: { RecordReviewerResultResult - recording outcome and round completeness }
+//   SIDE_EFFECTS: [Mutates the current generation's recorded results]
+//   LINKS: [M-WORKFLOW-CHECKPOINTS, M-PLUGIN-WORKFLOW]
+// END_CONTRACT: recordCheckpointReviewerResult
+export function recordCheckpointReviewerResult(store, input) {
+    return recordCheckpointReviewerResultInStore(store.getStoreData(), input);
+}
+export function recordCheckpointReviewerResultInStore(data, input) {
+    const active = resolveActiveReview(data, input.runId, input.checkpointId);
+    if (!active.ok)
+        return active;
+    if (!active.checkpoint.reviewers.includes(input.reviewer)) {
+        return {
+            ok: false,
+            errorCode: "REVIEWER_NOT_DECLARED",
+            message: `REVIEWER_NOT_DECLARED: ${input.reviewer} is not declared for ${input.checkpointId}`,
+        };
+    }
+    if (active.review.results[input.reviewer]) {
+        return {
+            ok: false,
+            errorCode: "ALREADY_RECORDED",
+            message: `ALREADY_RECORDED: ${input.reviewer} already recorded a result for generation ${active.review.generation}`,
+        };
+    }
+    const boundCallId = active.review.reviewerCallIds[input.reviewer];
+    if (boundCallId && input.callId !== boundCallId) {
+        return {
+            ok: false,
+            errorCode: "CALLBACK_MISMATCH",
+            message: `CALLBACK_MISMATCH: ${input.reviewer} result call ${String(input.callId)} does not match launch call ${boundCallId}`,
+        };
+    }
+    active.review.results[input.reviewer] = {
+        status: input.status,
+        recordedAt: toIsoNow(),
+    };
+    const roundComplete = active.checkpoint.reviewers.every((reviewer) => active.review.results[reviewer] !== undefined);
+    return { ok: true, roundComplete };
+}
+async function approvalInputsCurrent(run) {
+    try {
+        const planContent = await readFile(run.planPath, "utf8");
+        const specContent = await readFile(run.specPath, "utf8");
+        return (contentSha256(planContent) === run.planSha256 && contentSha256(specContent) === run.specSha256);
+    }
+    catch {
+        return false;
+    }
+}
+// START_CONTRACT: verifyDelegatedCheckpoint
+//   PURPOSE: Derive the checkpoint outcome from recorded reviewer results and freshly recomputed fingerprints and approval-input hashes.
+//   INPUTS: { store: WorkItemStore - backing store, input: VerifyDelegatedCheckpointInput - verify request with optional final complete }
+//   OUTPUTS: { VerifyDelegatedCheckpointResult - derived outcome and optional sealed completion, or a coded rejection }
+//   SIDE_EFFECTS: [Settles generations and seals completed runs; read-only for already-passed checkpoints]
+//   LINKS: [M-WORKFLOW-CHECKPOINTS, M-WORKFLOW-SNAPSHOTS, captureWorkflowSnapshot]
+// END_CONTRACT: verifyDelegatedCheckpoint
+export async function verifyDelegatedCheckpoint(store, input) {
+    return verifyDelegatedCheckpointInStore(store.getStoreData(), input);
+}
+export async function verifyDelegatedCheckpointInStore(data, input) {
+    const run = findRun(data, input.runId);
+    if (!run) {
+        return { ok: false, errorCode: "RUN_NOT_FOUND", message: `RUN_NOT_FOUND: ${input.runId}` };
+    }
+    const checkpoint = run.checkpoints.get(input.checkpointId);
+    if (!checkpoint) {
+        return {
+            ok: false,
+            errorCode: "CHECKPOINT_NOT_FOUND",
+            message: `CHECKPOINT_NOT_FOUND: ${input.checkpointId}`,
+        };
+    }
+    if (input.complete === true && checkpoint.kind !== "final") {
+        return {
+            ok: false,
+            errorCode: "FINAL_COMPLETE_ON_NON_FINAL",
+            message: `FINAL_COMPLETE_ON_NON_FINAL: complete is only permitted for the final checkpoint, not ${input.checkpointId}`,
+        };
+    }
+    // Historical milestones stay passed; rechecking only reports snapshot currency.
+    // A passed FINAL checkpoint may still seal its run through an explicit
+    // complete request, provided completion conditions and approval inputs are
+    // freshly satisfied (bounded rework stays possible before this succeeds).
+    if (checkpoint.status === "passed") {
+        if (input.complete === true) {
+            if (checkpoint.kind !== "final") {
+                return {
+                    ok: false,
+                    errorCode: "FINAL_COMPLETE_ON_NON_FINAL",
+                    message: `FINAL_COMPLETE_ON_NON_FINAL: complete is only permitted for the final checkpoint, not ${input.checkpointId}`,
+                };
+            }
+            if (!(await approvalInputsCurrent(run))) {
+                return {
+                    ok: false,
+                    errorCode: "PLAN_DRIFT",
+                    message: `PLAN_DRIFT: approved plan or spec content changed after registration of run ${input.runId}`,
+                };
+            }
+            const coveredForCompletion = currentCoveredAttemptIds(data, run, checkpoint);
+            if (!coveredForCompletion.ok) {
+                return {
+                    ok: false,
+                    errorCode: "COMPLETE_REQUIREMENTS_UNMET",
+                    message: `COMPLETE_REQUIREMENTS_UNMET: covered task ${coveredForCompletion.taskId} lost its current acceptance`,
+                };
+            }
+            const completion = evaluateRunCompletion(data, run, checkpoint);
+            if (!completion.ok) {
+                return { ok: false, errorCode: "COMPLETE_REQUIREMENTS_UNMET", message: completion.message };
+            }
+            run.status = "sealed";
+            run.sealedAt = toIsoNow();
+            return {
+                ok: true,
+                checkpoint: cloneCheckpoint(checkpoint),
+                outcome: "passed",
+                snapshotCurrent: true,
+                sealedRun: true,
+            };
+        }
+        const covered = currentCoveredAttemptIds(data, run, checkpoint);
+        const coveredIds = covered.ok ? covered.ids : [];
+        const snapshot = await captureWorkflowSnapshot({
+            workspaceRoot: run.workspaceRoot,
+            declaredPaths: checkpoint.scope,
+            coveredAttemptIds: coveredIds,
+        });
+        if (!snapshot.ok) {
+            return {
+                ok: false,
+                errorCode: "SNAPSHOT_FAILED",
+                message: `SNAPSHOT_FAILED: ${snapshot.message}`,
+            };
+        }
+        const historicalFingerprint = checkpoint.history[checkpoint.history.length - 1]?.fingerprint;
+        return {
+            ok: true,
+            checkpoint: cloneCheckpoint(checkpoint),
+            outcome: "already-passed",
+            snapshotCurrent: snapshot.snapshot.fingerprint === historicalFingerprint,
+        };
+    }
+    if (checkpoint.status !== "in_review" || !checkpoint.currentReview) {
+        return {
+            ok: false,
+            errorCode: "COMPLETE_REQUIREMENTS_UNMET",
+            message: `COMPLETE_REQUIREMENTS_UNMET: ${input.checkpointId} is ${checkpoint.status}; start it before verifying`,
+        };
+    }
+    const review = checkpoint.currentReview;
+    if (!(await approvalInputsCurrent(run))) {
+        return {
+            ok: false,
+            errorCode: "PLAN_DRIFT",
+            message: `PLAN_DRIFT: approved plan or spec content changed after registration of run ${input.runId}`,
+        };
+    }
+    const covered = currentCoveredAttemptIds(data, run, checkpoint);
+    if (!covered.ok) {
+        return {
+            ok: false,
+            errorCode: "COMPLETE_REQUIREMENTS_UNMET",
+            message: `COMPLETE_REQUIREMENTS_UNMET: covered task ${covered.taskId} lost its current acceptance`,
+        };
+    }
+    const snapshot = await captureWorkflowSnapshot({
+        workspaceRoot: run.workspaceRoot,
+        declaredPaths: checkpoint.scope,
+        coveredAttemptIds: covered.ids,
+    });
+    if (!snapshot.ok) {
+        return {
+            ok: false,
+            errorCode: "SNAPSHOT_FAILED",
+            message: `SNAPSHOT_FAILED: ${snapshot.message}`,
+        };
+    }
+    const snapshotCurrent = snapshot.snapshot.fingerprint === review.startFingerprint &&
+        JSON.stringify(covered.ids) === JSON.stringify(review.coveredAttemptIds);
+    const anyNeedsContext = checkpoint.reviewers.some((reviewer) => review.results[reviewer]?.status === "NEEDS_CONTEXT");
+    if (anyNeedsContext) {
+        const updated = { ...checkpoint, lastOutcome: "stopped" };
+        run.checkpoints.set(input.checkpointId, updated);
+        return {
+            ok: true,
+            checkpoint: cloneCheckpoint(updated),
+            outcome: "stopped",
+            snapshotCurrent,
+        };
+    }
+    const allRecorded = checkpoint.reviewers.every((reviewer) => review.results[reviewer] !== undefined);
+    if (!allRecorded) {
+        const updated = { ...checkpoint, lastOutcome: "incomplete" };
+        run.checkpoints.set(input.checkpointId, updated);
+        return {
+            ok: true,
+            checkpoint: cloneCheckpoint(updated),
+            outcome: "incomplete",
+            snapshotCurrent,
+        };
+    }
+    const allPass = checkpoint.reviewers.every((reviewer) => review.results[reviewer]?.status === "PASS");
+    const now = toIsoNow();
+    if (!snapshotCurrent) {
+        const settled = {
+            ...checkpoint,
+            status: "failed",
+            lastOutcome: "stale",
+            currentReview: undefined,
+            history: [
+                ...checkpoint.history,
+                {
+                    generation: review.generation,
+                    outcome: "stale",
+                    fingerprint: snapshot.snapshot.fingerprint,
+                    completedAt: now,
+                },
+            ],
+        };
+        run.checkpoints.set(input.checkpointId, settled);
+        return {
+            ok: true,
+            checkpoint: cloneCheckpoint(settled),
+            outcome: "stale",
+            snapshotCurrent: false,
+        };
+    }
+    if (allPass) {
+        const settled = {
+            ...checkpoint,
+            status: "passed",
+            lastOutcome: "passed",
+            currentReview: undefined,
+            history: [
+                ...checkpoint.history,
+                {
+                    generation: review.generation,
+                    outcome: "passed",
+                    fingerprint: review.startFingerprint,
+                    completedAt: now,
+                },
+            ],
+        };
+        run.checkpoints.set(input.checkpointId, settled);
+        if (input.complete === true) {
+            const completion = evaluateRunCompletion(data, run, settled);
+            if (!completion.ok) {
+                return { ok: false, errorCode: "COMPLETE_REQUIREMENTS_UNMET", message: completion.message };
+            }
+            run.status = "sealed";
+            run.sealedAt = now;
+            return {
+                ok: true,
+                checkpoint: cloneCheckpoint(settled),
+                outcome: "passed",
+                snapshotCurrent: true,
+                sealedRun: true,
+            };
+        }
+        return {
+            ok: true,
+            checkpoint: cloneCheckpoint(settled),
+            outcome: "passed",
+            snapshotCurrent: true,
+        };
+    }
+    const failed = {
+        ...checkpoint,
+        status: "failed",
+        lastOutcome: "failed",
+        currentReview: undefined,
+        history: [
+            ...checkpoint.history,
+            {
+                generation: review.generation,
+                outcome: "failed",
+                fingerprint: review.startFingerprint,
+                completedAt: now,
+            },
+        ],
+    };
+    run.checkpoints.set(input.checkpointId, failed);
+    return {
+        ok: true,
+        checkpoint: cloneCheckpoint(failed),
+        outcome: "failed",
+        snapshotCurrent: true,
+    };
+}
+function evaluateRunCompletion(data, run, finalCheckpoint) {
+    for (const task of run.definition.tasks) {
+        const binding = run.tasks.get(task.taskId);
+        if (!binding) {
+            return { ok: false, message: `task ${task.taskId} has no bound work item` };
+        }
+        const record = findRecord(data, run.sessionId, binding.workItemId);
+        const acceptance = record ? currentDelegatedAcceptance(record) : undefined;
+        if (!acceptance) {
+            return { ok: false, message: `task ${task.taskId} has no currently accepted attempt` };
+        }
+    }
+    for (const checkpoint of run.checkpoints.values()) {
+        if (checkpoint.checkpointId === finalCheckpoint.checkpointId)
+            continue;
+        if (checkpoint.status !== "passed") {
+            return {
+                ok: false,
+                message: `milestone ${checkpoint.checkpointId} is ${checkpoint.status}, not passed`,
+            };
+        }
+    }
+    const coveredScope = new Set(run.definition.tasks.flatMap((task) => task.writeScope));
+    for (const scopeFile of coveredScope) {
+        if (!finalCheckpoint.scope.includes(scopeFile)) {
+            return {
+                ok: false,
+                message: `final checkpoint scope does not cover declared write scope file ${scopeFile}`,
+            };
+        }
+    }
+    return { ok: true };
+}
+// START_CONTRACT: authorizeReworkFromFailedCheckpoint
+//   PURPOSE: Validate a failed-checkpoint rework authorization for a covered accepted task and apply the guarded rework reducer.
+//   INPUTS: { store: WorkItemStore - backing store, input: AuthorizeReworkInput - run, checkpoint, work item, and bounded reason }
+//   OUTPUTS: { AuthorizeReworkResult - applied rework or a coded rejection }
+//   SIDE_EFFECTS: [Reopens the covered delegated item via reworkDelegatedWorkItem]
+//   LINKS: [M-WORKFLOW-CHECKPOINTS, M-WORKFLOW-DELEGATED, reworkDelegatedWorkItem]
+// END_CONTRACT: authorizeReworkFromFailedCheckpoint
+export function authorizeReworkFromFailedCheckpoint(store, input) {
+    return authorizeReworkFromFailedCheckpointInStore(store.getStoreData(), input);
+}
+export function authorizeReworkFromFailedCheckpointInStore(data, input) {
+    const run = findRun(data, input.runId);
+    if (!run) {
+        return { ok: false, errorCode: "RUN_NOT_FOUND", message: `RUN_NOT_FOUND: ${input.runId}` };
+    }
+    if (run.sessionId !== input.sessionId) {
+        return {
+            ok: false,
+            errorCode: "SESSION_MISMATCH",
+            message: `SESSION_MISMATCH: run ${input.runId} belongs to session ${run.sessionId}`,
+        };
+    }
+    if (run.status === "sealed") {
+        return {
+            ok: false,
+            errorCode: "RUN_SEALED",
+            message: `RUN_SEALED: run ${input.runId} is complete; rework requires a new change`,
+        };
+    }
+    const checkpoint = run.checkpoints.get(input.checkpointId);
+    if (!checkpoint) {
+        return {
+            ok: false,
+            errorCode: "CHECKPOINT_NOT_FOUND",
+            message: `CHECKPOINT_NOT_FOUND: ${input.checkpointId}`,
+        };
+    }
+    if (checkpoint.status !== "failed") {
+        return {
+            ok: false,
+            errorCode: "CHECKPOINT_NOT_FAILED",
+            message: `CHECKPOINT_NOT_FAILED: ${input.checkpointId} is ${checkpoint.status}`,
+        };
+    }
+    if (checkpoint.lastOutcome === "stopped") {
+        return {
+            ok: false,
+            errorCode: "HARD_STOP_CHECKPOINT",
+            message: `HARD_STOP_CHECKPOINT: ${input.checkpointId} stopped on NEEDS_CONTEXT; resolve the hard stop first`,
+        };
+    }
+    const record = findRecord(data, input.sessionId, input.workItemId);
+    if (!record || record.mode !== "delegated" || !record.delegated) {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_NOT_BOUND",
+            message: `WORK_ITEM_NOT_BOUND: ${input.workItemId} is not a delegated work item`,
+        };
+    }
+    if (record.delegated.planRunId !== input.runId || !record.delegated.planTaskId) {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_NOT_BOUND",
+            message: `WORK_ITEM_NOT_BOUND: ${input.workItemId} is not bound to run ${input.runId}`,
+        };
+    }
+    if (!checkpoint.covers.includes(record.delegated.planTaskId)) {
+        return {
+            ok: false,
+            errorCode: "TASK_NOT_COVERED",
+            message: `TASK_NOT_COVERED: ${input.checkpointId} does not cover task ${record.delegated.planTaskId}`,
+        };
+    }
+    const reworked = reworkDelegatedWorkItem({ getStoreData: () => data }, {
+        sessionId: input.sessionId,
+        workItemId: input.workItemId,
+        planRunId: input.runId,
+        failedCheckpointId: input.checkpointId,
+        reason: input.reason,
+    });
+    if (!reworked.ok) {
+        return {
+            ok: false,
+            errorCode: "REWORK_REJECTED",
+            message: `REWORK_REJECTED: ${reworked.message}`,
+        };
+    }
+    return { ok: true, reworkId: reworked.reworkId, grantedAttempts: reworked.grantedAttempts };
+}
+// START_BLOCK_BARRIER_GATES
+/** Unsatisfied checkpoint barriers blocking task launches for the given wave, in declaration order. */
+export function checkpointBarrierUnsatisfied(data, runId, wave) {
+    const run = findRun(data, runId);
+    if (!run)
+        return { ok: false, message: `RUN_NOT_FOUND: ${runId}` };
+    const waveIndex = waveIndexOf(run, wave);
+    if (waveIndex < 0)
+        return { ok: false, message: `wave ${wave} is not declared in run ${runId}` };
+    const blockers = [];
+    for (const checkpoint of run.checkpoints.values()) {
+        if (checkpoint.kind !== "milestone")
+            continue;
+        const afterIndex = waveIndexOf(run, checkpoint.afterWave);
+        if (afterIndex < waveIndex && checkpoint.status !== "passed") {
+            blockers.push(checkpoint.checkpointId);
+        }
+    }
+    return { ok: true, blockers };
+}
+/** In-flight checkpoint review whose scope intersects the declared write scope. */
+export function findOverlappingInFlightReview(data, runId, writeScope) {
+    const run = findRun(data, runId);
+    if (!run)
+        return undefined;
+    for (const checkpoint of run.checkpoints.values()) {
+        if (checkpoint.status !== "in_review")
+            continue;
+        if (checkpoint.scope.some((file) => writeScope.includes(file))) {
+            return checkpoint.checkpointId;
+        }
+    }
+    return undefined;
+}
+// END_BLOCK_BARRIER_GATES
+// START_BLOCK_RUN_VIEW
+/** Read-only run serialization for tooling output and persistence consumers. */
+export function getDelegatedRunView(data, runId) {
+    const run = findRun(data, runId);
+    if (!run)
+        return undefined;
+    return {
+        runId: run.runId,
+        sessionId: run.sessionId,
+        planPath: run.planPath,
+        specPath: run.specPath,
+        workspaceRoot: run.workspaceRoot,
+        status: run.status,
+        registeredAt: run.registeredAt,
+        ...(run.sealedAt ? { sealedAt: run.sealedAt } : {}),
+        finalCheckpointId: run.finalCheckpointId,
+        tasks: [...run.tasks.values()].map((task) => ({
+            taskId: task.taskId,
+            workItemId: task.workItemId,
+        })),
+        checkpoints: [...run.checkpoints.values()].map((checkpoint) => ({
+            checkpointId: checkpoint.checkpointId,
+            kind: checkpoint.kind,
+            afterWave: checkpoint.afterWave,
+            covers: checkpoint.covers,
+            scope: checkpoint.scope,
+            reviewers: checkpoint.reviewers,
+            status: checkpoint.status,
+            attempts: checkpoint.attempts,
+            ...(checkpoint.lastOutcome ? { lastOutcome: checkpoint.lastOutcome } : {}),
+            ...(checkpoint.currentReview
+                ? {
+                    currentReview: {
+                        reviewWorkItemId: checkpoint.currentReview.reviewWorkItemId,
+                        generation: checkpoint.currentReview.generation,
+                        coveredAttemptIds: checkpoint.currentReview.coveredAttemptIds,
+                        recordedReviewers: Object.keys(checkpoint.currentReview.results),
+                    },
+                }
+                : {}),
+            history: checkpoint.history,
+        })),
+    };
+}
+// END_BLOCK_RUN_VIEW
+//# sourceMappingURL=checkpoints.js.map