ralph-research 0.1.0 → 0.1.2

package/dist/core/engine/cycle-runner.js

@@ -1,20 +1,29 @@
 import { createHash } from "node:crypto";
 import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, extname, join, resolve } from "node:path";
+import { summarizeMetricDiagnostics } from "../model/metric-diagnostics.js";
 import { evaluateAnchorAgreement, applyAnchorAgreementGate, loadAnchorRecords } from "./anchor-checker.js";
 import { sampleAuditQueue } from "./audit-sampler.js";
 import { evaluateChangeBudget } from "./change-budget.js";
 import { compactRecentHistory, countConsecutiveAutoAccepts } from "./history-compactor.js";
+import { preparePromotionArtifact, requirePromotionPatch, requirePromotionPaths } from "./promotion-artifact.js";
 import { runExperiment } from "./experiment-runner.js";
 import { runLlmJudgeMetric } from "./judge-pack.js";
 import { runParallelProposers } from "./parallel-proposer.js";
 import { extractCommandMetric } from "../../adapters/extractor/command-extractor.js";
 import { runCommandProposer } from "../../adapters/proposer/command-proposer.js";
 import { evaluateConstraints } from "../state/constraint-engine.js";
-import { updateParetoFrontier, updateSingleBestFrontier } from "../state/frontier-engine.js";
+import { attachCommitShaToFrontierEntries, buildAcceptedFrontierEntry, updateAcceptedFrontier, } from "../state/frontier-semantics.js";
 import { evaluateRatchet } from "../state/ratchet-engine.js";
 import { advanceRunPhase } from "../state/run-state-machine.js";
+import { derivePendingAction } from "../state/recovery-classifier.js";
 export async function runCycle(input, dependencies) {
+    if (input.manifest.proposer.type !== "parallel") {
+        return runCommandCycle(input, dependencies);
+    }
+    if (input.resumeRun) {
+        throw new Error("parallel proposer runs cannot be resumed truthfully yet");
+    }
     const now = dependencies.now ?? (() => new Date());
     const context = await createRunContext(input.repoRoot, input.manifest, dependencies.runStore, now);
     const manifestDir = dirname(input.manifestPath);
@@ -24,7 +33,7 @@ export async function runCycle(input, dependencies) {
     const priorConsecutiveAccepts = countConsecutiveAutoAccepts(priorDecisions, {
         metricId: "metric" in input.manifest.ratchet ? input.manifest.ratchet.metric ?? referenceMetric : referenceMetric,
     });
-    let runRecord = createInitialRunRecord(input.manifest, undefined, context);
+    let runRecord = createInitialRunRecord(input.manifest, input.resolvedBaselineRef, undefined, context);
     await dependencies.runStore.put(runRecord);
     let frontier = input.currentFrontier;
     try {
@@ -39,6 +48,7 @@ export async function runCycle(input, dependencies) {
             repoRoot: input.repoRoot,
             manifestDir,
             manifest: input.manifest,
+            resolvedBaselineRef: input.resolvedBaselineRef,
             runDir: context.runDir,
             workspaceManager: dependencies.workspaceManager,
             currentFrontier: frontier,
@@ -103,9 +113,16 @@ export async function runCycle(input, dependencies) {
         });
         await dependencies.runStore.put(runRecord);
         const decisionId = `decision-${context.runId}`;
-        const candidateFrontierEntry = buildFrontierEntry(context.runId, selectedCandidate.candidateId, now, selectedCandidate.metrics, selectedCandidate.artifacts);
+        const decisionCreatedAt = now().toISOString();
+        const candidateFrontierEntry = buildAcceptedFrontierEntry({
+            runId: context.runId,
+            candidateId: selectedCandidate.candidateId,
+            acceptedAt: decisionCreatedAt,
+            metrics: selectedCandidate.metrics,
+            artifacts: selectedCandidate.artifacts,
+        });
         const frontierUpdate = ratchetDecision.outcome === "accepted"
-            ? updateFrontier(input.manifest, frontier, candidateFrontierEntry)
+            ? updateAcceptedFrontier(input.manifest, frontier, candidateFrontierEntry)
             : null;
         let decisionRecord = {
             decisionId,
@@ -116,13 +133,33 @@ export async function runCycle(input, dependencies) {
             metricId: ratchetDecision.metricId,
             ...(ratchetDecision.delta === undefined ? {} : { delta: ratchetDecision.delta }),
             reason: ratchetDecision.reason,
-            createdAt: now().toISOString(),
+            createdAt: decisionCreatedAt,
             frontierChanged: frontierUpdate?.comparison.frontierChanged ?? false,
             beforeFrontierIds: frontier.map((entry) => entry.frontierId),
             afterFrontierIds: (frontierUpdate?.entries ?? frontier).map((entry) => entry.frontierId),
             auditRequired: false,
+            ...(buildDecisionDiagnostics(selectedCandidate.metrics[ratchetDecision.metricId])
+                ? { diagnostics: buildDecisionDiagnostics(selectedCandidate.metrics[ratchetDecision.metricId]) }
+                : {}),
             ...(ratchetDecision.graduation ? { graduation: ratchetDecision.graduation } : {}),
         };
+        if (ratchetDecision.outcome === "accepted") {
+            const promotion = await preparePromotionArtifact({
+                candidateId: selectedCandidate.candidateId,
+                runDir: context.runDir,
+                manifest: input.manifest,
+                workspaceManager: dependencies.workspaceManager,
+            });
+            runRecord = {
+                ...runRecord,
+                proposal: {
+                    ...runRecord.proposal,
+                    patchPath: promotion.patchPath,
+                    changedPaths: promotion.changedPaths,
+                    filesChanged: promotion.changedPaths.length,
+                },
+            };
+        }
         let auditQueue = buildAuditQueue(ratchetDecision.metricId, decisionRecord, input.manifest, selectedCandidate.packByMetricId);
         decisionRecord = {
             ...decisionRecord,
@@ -135,19 +172,14 @@ export async function runCycle(input, dependencies) {
         });
         await dependencies.runStore.put(runRecord);
         if (ratchetDecision.outcome === "accepted" && frontierUpdate) {
-            const promoted = await dependencies.workspaceManager.promoteWorkspace(selectedCandidate.candidateId, {
-                excludePaths: input.manifest.experiment.outputs.map((output) => output.path),
-            });
-            const commitResult = await dependencies.gitClient.stageAndCommitPaths([...promoted.copiedPaths, ...promoted.deletedPaths], `rrx: accept ${context.runId}`);
+            await dependencies.gitClient.applyPatchIfNeeded(requirePromotionPatch(runRecord));
+            const commitResult = await dependencies.gitClient.stageAndCommitPaths(requirePromotionPaths(runRecord), `rrx: accept ${context.runId}`);
             decisionRecord = {
                 ...decisionRecord,
                 commitSha: commitResult.commitSha,
             };
             await dependencies.decisionStore.put(decisionRecord);
-            frontier = frontierUpdate.entries.map((entry) => ({
-                ...entry,
-                commitSha: commitResult.commitSha,
-            }));
+            frontier = attachCommitShaToFrontierEntries(frontierUpdate.entries, context.runId, commitResult.commitSha);
             runRecord = advanceRunPhase(runRecord, "committed");
             await dependencies.runStore.put(runRecord);
             await dependencies.frontierStore.save(frontier);
@@ -188,6 +220,443 @@ export async function runCycle(input, dependencies) {
         };
     }
 }
+async function runCommandCycle(input, dependencies) {
+    const now = dependencies.now ?? (() => new Date());
+    const manifestDir = dirname(input.manifestPath);
+    const referenceMetric = getReferenceMetric(input.manifest);
+    const priorRuns = await dependencies.runStore.list();
+    const priorDecisions = await dependencies.decisionStore.list();
+    const priorConsecutiveAccepts = countConsecutiveAutoAccepts(priorDecisions, {
+        metricId: "metric" in input.manifest.ratchet ? input.manifest.ratchet.metric ?? referenceMetric : referenceMetric,
+    });
+    const context = input.resumeRun
+        ? createRunContextFromRecord(input.repoRoot, input.manifest, input.resumeRun)
+        : await createRunContext(input.repoRoot, input.manifest, dependencies.runStore, now);
+    let runRecord = input.resumeRun
+        ? input.resumeRun
+        : createInitialRunRecord(input.manifest, input.resolvedBaselineRef, undefined, context);
+    if (!input.resumeRun) {
+        await dependencies.runStore.put(runRecord);
+    }
+    let frontier = input.currentFrontier;
+    let decisionRecord = runRecord.decisionId
+        ? await dependencies.decisionStore.get(runRecord.decisionId)
+        : null;
+    let auditQueue = [];
+    let lastChangeBudget;
+    let lastAnchorCheck;
+    try {
+        while (true) {
+            const nextAction = runRecord.pendingAction !== "none"
+                ? runRecord.pendingAction
+                : derivePendingAction(runRecord);
+            switch (nextAction) {
+                case "prepare_proposal": {
+                    const proposerHistory = await buildProposerHistoryContext({
+                        manifest: input.manifest,
+                        runDir: context.runDir,
+                        runs: priorRuns,
+                        decisions: priorDecisions,
+                        primaryMetric: referenceMetric,
+                    });
+                    const workspacePath = runRecord.workspacePath
+                        ?? (await dependencies.workspaceManager.createWorkspace(runRecord.candidateId, input.resolvedBaselineRef)).workspacePath;
+                    const proposal = await executeProposal(input.manifest.proposer, workspacePath, proposerHistory);
+                    const proposeStdoutPath = await persistText(join(context.runDir, "logs", `${runRecord.candidateId}.propose.stdout.log`), proposal.stdout);
+                    runRecord = advanceRunPhase({
+                        ...runRecord,
+                        workspacePath,
+                        proposal: {
+                            ...runRecord.proposal,
+                            proposerType: input.manifest.proposer.type,
+                            summary: proposerHistory ? `${proposal.summary}; history_context=enabled` : proposal.summary,
+                            operators: [],
+                        },
+                        logs: {
+                            ...runRecord.logs,
+                            proposeStdoutPath,
+                        },
+                    }, "proposed");
+                    await dependencies.runStore.put(runRecord);
+                    break;
+                }
+                case "execute_experiment": {
+                    const workspacePath = requireWorkspacePath(runRecord);
+                    const experiment = await runExperiment(input.manifest.experiment.run, {
+                        workspacePath,
+                    });
+                    const runStdoutPath = await persistText(join(context.runDir, "logs", `${runRecord.candidateId}.experiment.stdout.log`), experiment.stdout);
+                    runRecord = advanceRunPhase({
+                        ...runRecord,
+                        logs: {
+                            ...runRecord.logs,
+                            runStdoutPath,
+                        },
+                    }, "executed");
+                    await dependencies.runStore.put(runRecord);
+                    break;
+                }
+                case "evaluate_metrics": {
+                    const workspacePath = requireWorkspacePath(runRecord);
+                    const metricEvaluation = await evaluateMetrics({
+                        repoRoot: input.repoRoot,
+                        manifestDir,
+                        manifest: input.manifest,
+                        currentFrontier: frontier,
+                        workspacePath,
+                        runDir: join(context.runDir, "judge", runRecord.candidateId),
+                        ...(dependencies.judgeProvider ? { judgeProvider: dependencies.judgeProvider } : {}),
+                    });
+                    const artifacts = await snapshotArtifacts(input.manifest.experiment.outputs, workspacePath, join(context.runDir, "artifacts", runRecord.candidateId));
+                    const constraints = evaluateConstraints(input.manifest.constraints, metricEvaluation.metrics);
+                    const changeBudget = await evaluateChangeBudget({
+                        workspacePath,
+                        scope: input.manifest.scope,
+                    });
+                    lastChangeBudget = changeBudget;
+                    let ratchetDecision = resolveDecision({
+                        manifest: input.manifest,
+                        metrics: metricEvaluation.metrics,
+                        currentFrontier: frontier,
+                        constraints,
+                        changeBudget,
+                        priorConsecutiveAccepts,
+                    });
+                    lastAnchorCheck = undefined;
+                    if (ratchetDecision.outcome === "accepted") {
+                        lastAnchorCheck = metricEvaluation.anchorChecks.get(ratchetDecision.metricId);
+                        if (lastAnchorCheck) {
+                            const gated = applyAnchorAgreementGate(ratchetDecision.outcome, lastAnchorCheck);
+                            ratchetDecision = {
+                                ...ratchetDecision,
+                                outcome: gated.outcome,
+                                frontierChanged: gated.outcome === "accepted",
+                                reason: `${ratchetDecision.reason}; ${gated.reason}`,
+                            };
+                        }
+                    }
+                    runRecord = advanceRunPhase({
+                        ...runRecord,
+                        proposal: {
+                            ...runRecord.proposal,
+                            diffLines: changeBudget.summary.totalLineDelta,
+                            filesChanged: changeBudget.summary.filesChanged,
+                            changedPaths: changeBudget.summary.entries.map((entry) => entry.path),
+                            withinBudget: changeBudget.withinBudget,
+                        },
+                        metrics: metricEvaluation.metrics,
+                        constraints: constraints.results.map(stripConstraintReason),
+                        artifacts,
+                    }, "evaluated", {
+                        status: ratchetDecision.outcome,
+                    });
+                    await dependencies.runStore.put(runRecord);
+                    break;
+                }
+                case "write_decision": {
+                    const decisionState = await buildDecisionState({
+                        input,
+                        dependencies,
+                        runRecord,
+                        frontier,
+                        priorConsecutiveAccepts,
+                        manifestDir,
+                        runDir: context.runDir,
+                    });
+                    lastChangeBudget = decisionState.changeBudget;
+                    lastAnchorCheck = decisionState.anchorCheck;
+                    const decisionId = `decision-${runRecord.runId}`;
+                    const decisionCreatedAt = now().toISOString();
+                    const candidateFrontierEntry = buildAcceptedFrontierEntry({
+                        runId: runRecord.runId,
+                        candidateId: runRecord.candidateId,
+                        acceptedAt: decisionCreatedAt,
+                        metrics: runRecord.metrics,
+                        artifacts: runRecord.artifacts,
+                    });
+                    const frontierUpdate = decisionState.ratchetDecision.outcome === "accepted"
+                        ? updateAcceptedFrontier(input.manifest, frontier, candidateFrontierEntry)
+                        : null;
+                    decisionRecord = {
+                        decisionId,
+                        runId: runRecord.runId,
+                        outcome: decisionState.ratchetDecision.outcome,
+                        actorType: "system",
+                        policyType: decisionState.ratchetDecision.policyType,
+                        metricId: decisionState.ratchetDecision.metricId,
+                        ...(decisionState.ratchetDecision.delta === undefined ? {} : { delta: decisionState.ratchetDecision.delta }),
+                        reason: decisionState.ratchetDecision.reason,
+                        createdAt: decisionCreatedAt,
+                        frontierChanged: frontierUpdate?.comparison.frontierChanged ?? false,
+                        beforeFrontierIds: frontier.map((entry) => entry.frontierId),
+                        afterFrontierIds: (frontierUpdate?.entries ?? frontier).map((entry) => entry.frontierId),
+                        auditRequired: false,
+                        ...(buildDecisionDiagnostics(runRecord.metrics[decisionState.ratchetDecision.metricId])
+                            ? { diagnostics: buildDecisionDiagnostics(runRecord.metrics[decisionState.ratchetDecision.metricId]) }
+                            : {}),
+                        ...(decisionState.ratchetDecision.graduation ? { graduation: decisionState.ratchetDecision.graduation } : {}),
+                    };
+                    if (decisionState.ratchetDecision.outcome === "accepted") {
+                        const promotion = await preparePromotionArtifact({
+                            candidateId: runRecord.candidateId,
+                            runDir: context.runDir,
+                            manifest: input.manifest,
+                            workspaceManager: dependencies.workspaceManager,
+                        });
+                        runRecord = {
+                            ...runRecord,
+                            proposal: {
+                                ...runRecord.proposal,
+                                patchPath: promotion.patchPath,
+                                changedPaths: promotion.changedPaths,
+                                filesChanged: promotion.changedPaths.length,
+                            },
+                        };
+                    }
+                    auditQueue = buildAuditQueue(decisionState.ratchetDecision.metricId, decisionRecord, input.manifest, decisionState.packByMetricId);
+                    decisionRecord = {
+                        ...decisionRecord,
+                        auditRequired: auditQueue.length > 0,
+                    };
+                    await dependencies.decisionStore.put(decisionRecord);
+                    runRecord = advanceRunPhase(runRecord, "decision_written", {
+                        status: decisionState.ratchetDecision.outcome,
+                        decisionId,
+                    });
+                    await dependencies.runStore.put(runRecord);
+                    if (decisionState.ratchetDecision.outcome === "needs_human") {
+                        return {
+                            status: "needs_human",
+                            run: runRecord,
+                            decision: decisionRecord,
+                            frontier,
+                            auditQueue,
+                            ...(lastChangeBudget ? { changeBudget: lastChangeBudget } : {}),
+                            ...(lastAnchorCheck ? { anchorCheck: lastAnchorCheck } : {}),
+                        };
+                    }
+                    break;
+                }
+                case "commit_candidate": {
+                    if (runRecord.status !== "accepted") {
+                        throw new Error(`cannot commit candidate for non-accepted run ${runRecord.runId}`);
+                    }
+                    if (!decisionRecord) {
+                        decisionRecord = await requireDecisionRecord(dependencies.decisionStore, runRecord);
+                    }
+                    await dependencies.gitClient.applyPatchIfNeeded(requirePromotionPatch(runRecord));
+                    const commitResult = await dependencies.gitClient.stageAndCommitPaths(requirePromotionPaths(runRecord), `rrx: accept ${runRecord.runId}`);
+                    decisionRecord = {
+                        ...decisionRecord,
+                        commitSha: commitResult.commitSha,
+                    };
+                    await dependencies.decisionStore.put(decisionRecord);
+                    runRecord = advanceRunPhase(runRecord, "committed");
+                    await dependencies.runStore.put(runRecord);
+                    break;
+                }
+                case "update_frontier": {
+                    if (!decisionRecord) {
+                        decisionRecord = await requireDecisionRecord(dependencies.decisionStore, runRecord);
+                    }
+                    if (!decisionRecord.commitSha) {
+                        throw new Error(`cannot update frontier for ${runRecord.runId}: missing commit sha`);
+                    }
+                    const candidateFrontierEntry = {
+                        ...buildAcceptedFrontierEntry({
+                            runId: runRecord.runId,
+                            candidateId: runRecord.candidateId,
+                            acceptedAt: decisionRecord.createdAt,
+                            metrics: runRecord.metrics,
+                            artifacts: runRecord.artifacts,
+                        }),
+                        commitSha: decisionRecord.commitSha,
+                    };
+                    frontier = updateAcceptedFrontier(input.manifest, frontier, candidateFrontierEntry).entries;
+                    await dependencies.frontierStore.save(frontier);
+                    runRecord = advanceRunPhase(runRecord, "frontier_updated");
+                    await dependencies.runStore.put(runRecord);
+                    break;
+                }
+                case "cleanup_workspace": {
+                    await dependencies.workspaceManager.cleanupWorkspace(runRecord.candidateId);
+                    runRecord = advanceRunPhase(runRecord, "completed", {
+                        status: runRecord.status,
+                    });
+                    await dependencies.runStore.put(runRecord);
+                    return {
+                        status: toCycleRunStatus(runRecord.status),
+                        run: runRecord,
+                        ...(decisionRecord ? { decision: decisionRecord } : {}),
+                        frontier,
+                        auditQueue,
+                        ...(lastChangeBudget ? { changeBudget: lastChangeBudget } : {}),
+                        ...(lastAnchorCheck ? { anchorCheck: lastAnchorCheck } : {}),
+                    };
+                }
+                case "none": {
+                    if (runRecord.status === "needs_human") {
+                        return {
+                            status: "needs_human",
+                            run: runRecord,
+                            ...(decisionRecord ? { decision: decisionRecord } : {}),
+                            frontier,
+                            auditQueue,
+                            ...(lastChangeBudget ? { changeBudget: lastChangeBudget } : {}),
+                            ...(lastAnchorCheck ? { anchorCheck: lastAnchorCheck } : {}),
+                        };
+                    }
+                    if (runRecord.phase === "completed") {
+                        return {
+                            status: toCycleRunStatus(runRecord.status),
+                            run: runRecord,
+                            ...(decisionRecord ? { decision: decisionRecord } : {}),
+                            frontier,
+                            auditQueue,
+                            ...(lastChangeBudget ? { changeBudget: lastChangeBudget } : {}),
+                            ...(lastAnchorCheck ? { anchorCheck: lastAnchorCheck } : {}),
+                        };
+                    }
+                    throw new Error(`run ${runRecord.runId} is missing a resumable next action`);
+                }
+            }
+        }
+    }
+    catch (error) {
+        runRecord = advanceRunPhase(runRecord, "failed", {
+            error: {
+                message: error instanceof Error ? error.message : String(error),
+                ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+            },
+            status: "failed",
+        });
+        await dependencies.runStore.put(runRecord);
+        return {
+            status: "failed",
+            run: runRecord,
+            frontier,
+            auditQueue: [],
+        };
+    }
+}
+function createRunContextFromRecord(repoRoot, manifest, run) {
+    return {
+        runId: run.runId,
+        cycle: run.cycle,
+        candidateId: run.candidateId,
+        runDir: join(resolve(repoRoot), manifest.storage.root, "runs", run.runId),
+        startedAt: run.startedAt,
+        manifestHash: run.manifestHash,
+    };
+}
+async function buildDecisionState(input) {
+    const workspacePath = requireWorkspacePath(input.runRecord);
+    const changeBudget = await evaluateChangeBudget({
+        workspacePath,
+        scope: input.input.manifest.scope,
+    });
+    const constraints = summarizeStoredConstraints(input.runRecord.constraints);
+    const { anchorChecks, packByMetricId } = await evaluateStoredAnchorChecks({
+        manifest: input.input.manifest,
+        manifestDir: input.manifestDir,
+        runDir: input.runDir,
+        ...(input.dependencies.judgeProvider ? { judgeProvider: input.dependencies.judgeProvider } : {}),
+    });
+    let ratchetDecision = resolveDecision({
+        manifest: input.input.manifest,
+        metrics: input.runRecord.metrics,
+        currentFrontier: input.frontier,
+        constraints,
+        changeBudget,
+        priorConsecutiveAccepts: input.priorConsecutiveAccepts,
+    });
+    let anchorCheck;
+    if (ratchetDecision.outcome === "accepted") {
+        anchorCheck = anchorChecks.get(ratchetDecision.metricId);
+        if (anchorCheck) {
+            const gated = applyAnchorAgreementGate(ratchetDecision.outcome, anchorCheck);
+            ratchetDecision = {
+                ...ratchetDecision,
+                outcome: gated.outcome,
+                frontierChanged: gated.outcome === "accepted",
+                reason: `${ratchetDecision.reason}; ${gated.reason}`,
+            };
+        }
+    }
+    return {
+        ratchetDecision,
+        changeBudget,
+        ...(anchorCheck ? { anchorCheck } : {}),
+        packByMetricId,
+    };
+}
+async function evaluateStoredAnchorChecks(input) {
+    const anchorChecks = new Map();
+    const packByMetricId = new Map();
+    const anchorCache = new Map();
+    for (const metricDefinition of input.manifest.metrics.catalog) {
+        if (metricDefinition.extractor.type !== "llm_judge") {
+            continue;
+        }
+        if (!input.judgeProvider) {
+            throw new Error(`metric ${metricDefinition.id} requires a judge provider`);
+        }
+        const extractor = metricDefinition.extractor;
+        const pack = getJudgePack(input.manifest, extractor.judgePack);
+        packByMetricId.set(metricDefinition.id, pack);
+        if (!anchorCache.has(pack.id)) {
+            const anchors = pack.anchors
+                ? await loadAnchorRecords(resolve(input.manifestDir, pack.anchors.path))
+                : [];
+            anchorCache.set(pack.id, await evaluateAnchorAgreement({
+                pack,
+                extractor,
+                provider: input.judgeProvider,
+                anchors,
+            }));
+        }
+        anchorChecks.set(metricDefinition.id, anchorCache.get(pack.id));
+    }
+    return {
+        anchorChecks,
+        packByMetricId,
+    };
+}
+function summarizeStoredConstraints(constraints) {
+    const failing = constraints.find((constraint) => !constraint.passed);
+    if (!failing) {
+        return {
+            passed: true,
+            reason: "all constraints satisfied",
+        };
+    }
+    return {
+        passed: false,
+        reason: `constraint ${failing.metric} failed`,
+    };
+}
+async function requireDecisionRecord(decisionStore, run) {
+    if (!run.decisionId) {
+        throw new Error(`run ${run.runId} is missing a decision id`);
+    }
+    const decision = await decisionStore.get(run.decisionId);
+    if (!decision) {
+        throw new Error(`decision ${run.decisionId} was not found`);
+    }
+    return decision;
+}
+function requireWorkspacePath(run) {
+    if (!run.workspacePath) {
+        throw new Error(`run ${run.runId} is missing a durable workspace path`);
+    }
+    return run.workspacePath;
+}
+function toCycleRunStatus(status) {
+    if (status === "accepted" || status === "rejected" || status === "needs_human" || status === "failed") {
+        return status;
+    }
+    throw new Error(`run ended without a terminal cycle status: ${status}`);
+}
 async function createRunContext(repoRoot, manifest, runStore, now) {
     const runs = await runStore.list();
     const nextCycle = runs.reduce((highest, run) => Math.max(highest, run.cycle), 0) + 1;
@@ -205,17 +674,19 @@ async function createRunContext(repoRoot, manifest, runStore, now) {
         manifestHash,
     };
 }
-function createInitialRunRecord(manifest, workspacePath, context) {
+function createInitialRunRecord(manifest, resolvedBaselineRef, workspacePath, context) {
     return {
         runId: context.runId,
         cycle: context.cycle,
         candidateId: context.candidateId,
         status: "running",
-        phase: "proposed",
-        pendingAction: "execute_experiment",
+        phase: "started",
+        pendingAction: "prepare_proposal",
         startedAt: context.startedAt,
+        updatedAt: context.startedAt,
+        currentStepStartedAt: context.startedAt,
         manifestHash: context.manifestHash,
-        workspaceRef: manifest.project.baselineRef,
+        workspaceRef: resolvedBaselineRef,
         ...(workspacePath ? { workspacePath } : {}),
         proposal: {
             proposerType: manifest.proposer.type,
@@ -244,6 +715,7 @@ async function prepareCandidateAttempt(input) {
                     repoRoot: input.repoRoot,
                     manifestDir: input.manifestDir,
                     manifest: input.manifest,
+                    resolvedBaselineRef: input.resolvedBaselineRef,
                     proposer: strategy,
                     candidateId,
                     runDir: input.runDir,
@@ -293,6 +765,7 @@ async function prepareCandidateAttempt(input) {
         repoRoot: input.repoRoot,
         manifestDir: input.manifestDir,
         manifest: input.manifest,
+        resolvedBaselineRef: input.resolvedBaselineRef,
         proposer: input.manifest.proposer,
         candidateId: input.baseCandidateId,
         runDir: input.runDir,
@@ -303,7 +776,7 @@ async function prepareCandidateAttempt(input) {
     });
 }
 async function executeCandidateStrategy(input) {
-    const workspace = await input.workspaceManager.createWorkspace(input.candidateId);
+    const workspace = await input.workspaceManager.createWorkspace(input.candidateId, input.resolvedBaselineRef);
     const proposal = await executeProposal(input.proposer, workspace.workspacePath, input.historyContext);
     const proposeStdoutPath = await persistText(join(input.runDir, "logs", `${input.candidateId}.propose.stdout.log`), proposal.stdout);
     const experiment = await runExperiment(input.manifest.experiment.run, {
@@ -533,16 +1006,6 @@ function resolveDecision(input) {
         ...(input.constraints.passed ? {} : { constraintFailureReason: input.constraints.reason }),
     });
 }
-function buildFrontierEntry(runId, candidateId, now, metrics, artifacts) {
-    return {
-        frontierId: `frontier-${runId}`,
-        runId,
-        candidateId,
-        acceptedAt: now().toISOString(),
-        metrics,
-        artifacts,
-    };
-}
 function buildAuditQueue(metricId, decision, manifest, packByMetricId) {
     const pack = packByMetricId.get(metricId);
     if (!pack) {
@@ -620,6 +1083,19 @@ function stripConstraintReason(constraint) {
         op: constraint.op,
     };
 }
+function buildDecisionDiagnostics(metric) {
+    if (!metric) {
+        return undefined;
+    }
+    const diagnostics = summarizeMetricDiagnostics(metric);
+    if (!diagnostics) {
+        return undefined;
+    }
+    return {
+        reasons: diagnostics.reasons,
+        ...(diagnostics.sourceMetricId ? { sourceMetricId: diagnostics.sourceMetricId } : {}),
+    };
+}
 async function persistText(path, value) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, value, "utf8");
@@ -643,10 +1119,4 @@ function getReferenceMetric(manifest) {
     }
     return manifest.frontier.objectives[0].metric;
 }
-function updateFrontier(manifest, currentFrontier, candidateEntry) {
-    if (manifest.frontier.strategy === "single_best") {
-        return updateSingleBestFrontier(currentFrontier, candidateEntry, manifest.frontier.primaryMetric);
-    }
-    return updateParetoFrontier(currentFrontier, candidateEntry, manifest.frontier.objectives, manifest.frontier.tieBreaker, manifest.frontier.referencePoint);
-}
 //# sourceMappingURL=cycle-runner.js.map