ralph-research 0.1.0

package/dist/core/ports/decision-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=decision-store.js.map

package/dist/core/ports/decision-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-store.js","sourceRoot":"","sources":["../../../src/core/ports/decision-store.ts"],"names":[],"mappings":""}

package/dist/core/ports/frontier-store.d.ts

@@ -0,0 +1,5 @@
+import type { FrontierEntry } from "../model/frontier-entry.js";
+export interface FrontierStore {
+    save(entries: FrontierEntry[]): Promise<void>;
+    load(): Promise<FrontierEntry[]>;
+}

package/dist/core/ports/frontier-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=frontier-store.js.map

package/dist/core/ports/frontier-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontier-store.js","sourceRoot":"","sources":["../../../src/core/ports/frontier-store.ts"],"names":[],"mappings":""}

package/dist/core/ports/run-store.d.ts

@@ -0,0 +1,6 @@
+import type { RunRecord } from "../model/run-record.js";
+export interface RunStore {
+    put(record: RunRecord): Promise<void>;
+    get(runId: string): Promise<RunRecord | null>;
+    list(): Promise<RunRecord[]>;
+}

package/dist/core/ports/run-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-store.js.map

package/dist/core/ports/run-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-store.js","sourceRoot":"","sources":["../../../src/core/ports/run-store.ts"],"names":[],"mappings":""}

package/dist/core/state/constraint-engine.d.ts

@@ -0,0 +1,18 @@
+import type { z } from "zod";
+import { constraintSchema } from "../manifest/schema.js";
+import type { MetricResult } from "../model/metric.js";
+export type ConstraintDefinition = z.infer<typeof constraintSchema>;
+export interface ConstraintEvaluation {
+    metric: string;
+    passed: boolean;
+    actual: number;
+    expected: number;
+    op: ConstraintDefinition["op"];
+    reason: string;
+}
+export interface ConstraintEvaluationSummary {
+    passed: boolean;
+    results: ConstraintEvaluation[];
+    reason: string;
+}
+export declare function evaluateConstraints(constraints: ConstraintDefinition[], metrics: Record<string, MetricResult>): ConstraintEvaluationSummary;

package/dist/core/state/constraint-engine.js

@@ -0,0 +1,42 @@
+export function evaluateConstraints(constraints, metrics) {
+    const results = constraints.map((constraint) => {
+        const metric = metrics[constraint.metric];
+        if (!metric) {
+            throw new Error(`Missing metric result for constraint "${constraint.metric}"`);
+        }
+        const passed = compare(metric.value, constraint.op, constraint.value);
+        return {
+            metric: constraint.metric,
+            passed,
+            actual: metric.value,
+            expected: constraint.value,
+            op: constraint.op,
+            reason: passed
+                ? `constraint ${constraint.metric} satisfied: ${metric.value} ${constraint.op} ${constraint.value}`
+                : `constraint ${constraint.metric} failed: ${metric.value} ${constraint.op} ${constraint.value}`,
+        };
+    });
+    const failed = results.filter((result) => !result.passed);
+    return {
+        passed: failed.length === 0,
+        results,
+        reason: failed.length === 0
+            ? "all constraints satisfied"
+            : failed.map((result) => result.reason).join("; "),
+    };
+}
+function compare(actual, op, expected) {
+    switch (op) {
+        case ">=":
+            return actual >= expected;
+        case ">":
+            return actual > expected;
+        case "<=":
+            return actual <= expected;
+        case "<":
+            return actual < expected;
+        case "==":
+            return actual === expected;
+    }
+}
+//# sourceMappingURL=constraint-engine.js.map

package/dist/core/state/constraint-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraint-engine.js","sourceRoot":"","sources":["../../../src/core/state/constraint-engine.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,mBAAmB,CACjC,WAAmC,EACnC,OAAqC;IAErC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE;QAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,yCAAyC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;QACjF,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO;YACL,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,MAAM;YACN,MAAM,EAAE,MAAM,CAAC,KAAK;YACpB,QAAQ,EAAE,UAAU,CAAC,KAAK;YAC1B,EAAE,EAAE,UAAU,CAAC,EAAE;YACjB,MAAM,EAAE,MAAM;gBACZ,CAAC,CAAC,cAAc,UAAU,CAAC,MAAM,eAAe,MAAM,CAAC,KAAK,IAAI,UAAU,CAAC,EAAE,IAAI,UAAU,CAAC,KAAK,EAAE;gBACnG,CAAC,CAAC,cAAc,UAAU,CAAC,MAAM,YAAY,MAAM,CAAC,KAAK,IAAI,UAAU,CAAC,EAAE,IAAI,UAAU,CAAC,KAAK,EAAE;SACnG,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1D,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QAC3B,OAAO;QACP,MAAM,EACJ,MAAM,CAAC,MAAM,KAAK,CAAC;YACjB,CAAC,CAAC,2BAA2B;YAC7B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;KACvD,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,MAAc,EAAE,EAA8B,EAAE,QAAgB;IAC/E,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,IAAI;YACP,OAAO,MAAM,IAAI,QAAQ,CAAC;QAC5B,KAAK,GAAG;YACN,OAAO,MAAM,GAAG,QAAQ,CAAC;QAC3B,KAAK,IAAI;YACP,OAAO,MAAM,IAAI,QAAQ,CAAC;QAC5B,KAAK,GAAG;YACN,OAAO,MAAM,GAAG,QAAQ,CAAC;QAC3B,KAAK,IAAI;YACP,OAAO,MAAM,KAAK,QAAQ,CAAC;IAC/B,CAAC;AACH,CAAC"}

package/dist/core/state/frontier-engine.d.ts

@@ -0,0 +1,24 @@
+import type { FrontierEntry } from "../model/frontier-entry.js";
+import type { ParetoObjectiveConfig } from "../manifest/schema.js";
+import type { MetricResult } from "../model/metric.js";
+export interface FrontierComparison {
+    outcome: "accepted" | "rejected";
+    frontierChanged: boolean;
+    reason: string;
+    incumbent?: FrontierEntry;
+    delta?: number;
+}
+export interface FrontierUpdate {
+    entries: FrontierEntry[];
+    comparison: FrontierComparison;
+}
+export interface ParetoFrontierUpdate {
+    entries: FrontierEntry[];
+    comparison: FrontierComparison;
+}
+export declare function compareSingleBestFrontier(currentFrontier: FrontierEntry[], candidateEntry: FrontierEntry, primaryMetric: string): FrontierComparison;
+export declare function updateSingleBestFrontier(currentFrontier: FrontierEntry[], candidateEntry: FrontierEntry, primaryMetric: string): FrontierUpdate;
+export declare function compareParetoFrontier(currentFrontier: FrontierEntry[], candidateEntry: FrontierEntry, objectives: ParetoObjectiveConfig[]): FrontierComparison;
+export declare function updateParetoFrontier(currentFrontier: FrontierEntry[], candidateEntry: FrontierEntry, objectives: ParetoObjectiveConfig[], tieBreaker?: "hypervolume" | "none", referencePoint?: Record<string, number>): ParetoFrontierUpdate;
+export declare function directionalDelta(candidate: MetricResult, incumbent: MetricResult): number;
+export declare function buildMetricComparisonReason(metricId: string, candidate: MetricResult, incumbent: MetricResult, delta: number, verdict: "improved" | "not_improved"): string;

package/dist/core/state/frontier-engine.js

@@ -0,0 +1,178 @@
+export function compareSingleBestFrontier(currentFrontier, candidateEntry, primaryMetric) {
+    assertSingleBestShape(currentFrontier);
+    if (currentFrontier.length === 0) {
+        return {
+            outcome: "accepted",
+            frontierChanged: true,
+            reason: `frontier empty; candidate becomes best entry on metric ${primaryMetric}`,
+        };
+    }
+    const incumbent = currentFrontier[0];
+    if (!incumbent) {
+        throw new Error("single_best frontier invariant violated: incumbent missing");
+    }
+    const candidateMetric = getMetric(candidateEntry, primaryMetric);
+    const incumbentMetric = getMetric(incumbent, primaryMetric);
+    const delta = directionalDelta(candidateMetric, incumbentMetric);
+    if (delta > 0) {
+        return {
+            outcome: "accepted",
+            frontierChanged: true,
+            incumbent,
+            delta,
+            reason: buildMetricComparisonReason(primaryMetric, candidateMetric, incumbentMetric, delta, "improved"),
+        };
+    }
+    return {
+        outcome: "rejected",
+        frontierChanged: false,
+        incumbent,
+        delta,
+        reason: buildMetricComparisonReason(primaryMetric, candidateMetric, incumbentMetric, delta, "not_improved"),
+    };
+}
+export function updateSingleBestFrontier(currentFrontier, candidateEntry, primaryMetric) {
+    const comparison = compareSingleBestFrontier(currentFrontier, candidateEntry, primaryMetric);
+    return {
+        entries: comparison.frontierChanged ? [candidateEntry] : currentFrontier,
+        comparison,
+    };
+}
+export function compareParetoFrontier(currentFrontier, candidateEntry, objectives) {
+    if (currentFrontier.length === 0) {
+        return {
+            outcome: "accepted",
+            frontierChanged: true,
+            reason: `frontier empty; candidate added to pareto frontier on objectives ${describeObjectives(objectives)}`,
+        };
+    }
+    const dominatingIncumbent = currentFrontier.find((entry) => dominates(entry, candidateEntry, objectives));
+    if (dominatingIncumbent) {
+        return {
+            outcome: "rejected",
+            frontierChanged: false,
+            incumbent: dominatingIncumbent,
+            reason: `candidate is pareto-dominated by ${dominatingIncumbent.frontierId} on objectives ${describeObjectives(objectives)}`,
+        };
+    }
+    const dominatedEntries = currentFrontier.filter((entry) => dominates(candidateEntry, entry, objectives));
+    if (dominatedEntries.length > 0) {
+        return {
+            outcome: "accepted",
+            frontierChanged: true,
+            reason: `candidate dominates ${dominatedEntries.length} frontier entr${dominatedEntries.length === 1 ? "y" : "ies"} on objectives ${describeObjectives(objectives)}`,
+        };
+    }
+    if (containsEquivalentPoint(currentFrontier, candidateEntry, objectives)) {
+        return {
+            outcome: "rejected",
+            frontierChanged: false,
+            reason: `candidate matches an existing pareto point on objectives ${describeObjectives(objectives)}`,
+        };
+    }
+    return {
+        outcome: "accepted",
+        frontierChanged: true,
+        reason: `candidate is non-dominated and expands the pareto frontier on objectives ${describeObjectives(objectives)}`,
+    };
+}
+export function updateParetoFrontier(currentFrontier, candidateEntry, objectives, tieBreaker = "hypervolume", referencePoint) {
+    const comparison = compareParetoFrontier(currentFrontier, candidateEntry, objectives);
+    if (!comparison.frontierChanged) {
+        return {
+            entries: currentFrontier,
+            comparison,
+        };
+    }
+    const retained = currentFrontier.filter((entry) => !dominates(candidateEntry, entry, objectives));
+    const nextEntries = [...retained, candidateEntry];
+    return {
+        entries: tieBreaker === "hypervolume"
+            ? sortByHypervolumeContribution(nextEntries, objectives, referencePoint)
+            : nextEntries,
+        comparison,
+    };
+}
+export function directionalDelta(candidate, incumbent) {
+    if (candidate.direction !== incumbent.direction) {
+        throw new Error(`metric direction mismatch for ${candidate.metricId}: candidate=${candidate.direction}, incumbent=${incumbent.direction}`);
+    }
+    return candidate.direction === "maximize"
+        ? candidate.value - incumbent.value
+        : incumbent.value - candidate.value;
+}
+export function buildMetricComparisonReason(metricId, candidate, incumbent, delta, verdict) {
+    const candidateText = `${metricId} candidate=${candidate.value}`;
+    const incumbentText = `${metricId} incumbent=${incumbent.value}`;
+    const deltaText = `delta=${delta.toFixed(4)}`;
+    return verdict === "improved"
+        ? `${candidateText}; ${incumbentText}; ${deltaText}; candidate improved frontier`
+        : `${candidateText}; ${incumbentText}; ${deltaText}; candidate did not improve frontier`;
+}
+function getMetric(entry, metricId) {
+    const metric = entry.metrics[metricId];
+    if (!metric) {
+        throw new Error(`Frontier entry ${entry.frontierId} is missing primary metric "${metricId}"`);
+    }
+    return metric;
+}
+function assertSingleBestShape(currentFrontier) {
+    if (currentFrontier.length > 1) {
+        throw new Error(`single_best frontier expected at most one entry, received ${currentFrontier.length}`);
+    }
+}
+function dominates(candidate, incumbent, objectives) {
+    let strictlyBetter = false;
+    for (const objective of objectives) {
+        const candidateMetric = getMetric(candidate, objective.metric);
+        const incumbentMetric = getMetric(incumbent, objective.metric);
+        const delta = directionalDelta(candidateMetric, incumbentMetric);
+        if (delta < -objective.epsilon) {
+            return false;
+        }
+        if (delta > objective.epsilon) {
+            strictlyBetter = true;
+        }
+    }
+    return strictlyBetter;
+}
+function containsEquivalentPoint(frontier, candidate, objectives) {
+    return frontier.some((entry) => objectives.every((objective) => {
+        const candidateMetric = getMetric(candidate, objective.metric);
+        const incumbentMetric = getMetric(entry, objective.metric);
+        const delta = Math.abs(directionalDelta(candidateMetric, incumbentMetric));
+        return delta <= objective.epsilon;
+    }));
+}
+function sortByHypervolumeContribution(entries, objectives, referencePoint) {
+    const resolvedReferencePoint = referencePoint ??
+        Object.fromEntries(objectives.map((objective) => {
+            const values = entries.map((entry) => getMetric(entry, objective.metric).value);
+            const direction = getMetric(entries[0], objective.metric).direction;
+            const worstValue = direction === "maximize" ? Math.min(...values) - 1 : Math.max(...values) + 1;
+            return [objective.metric, worstValue];
+        }));
+    return [...entries].sort((left, right) => {
+        const contributionDelta = hypervolumeContribution(right, objectives, resolvedReferencePoint) -
+            hypervolumeContribution(left, objectives, resolvedReferencePoint);
+        if (contributionDelta !== 0) {
+            return contributionDelta;
+        }
+        return left.frontierId.localeCompare(right.frontierId);
+    });
+}
+function hypervolumeContribution(entry, objectives, referencePoint) {
+    return objectives.reduce((product, objective) => {
+        const metric = getMetric(entry, objective.metric);
+        const reference = referencePoint[objective.metric];
+        if (reference === undefined) {
+            throw new Error(`Missing reference point for pareto objective "${objective.metric}"`);
+        }
+        const contribution = metric.direction === "maximize" ? metric.value - reference : reference - metric.value;
+        return product * Math.max(contribution, 0);
+    }, 1);
+}
+function describeObjectives(objectives) {
+    return objectives.map((objective) => objective.metric).join(", ");
+}
+//# sourceMappingURL=frontier-engine.js.map

package/dist/core/state/frontier-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontier-engine.js","sourceRoot":"","sources":["../../../src/core/state/frontier-engine.ts"],"names":[],"mappings":"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"}

package/dist/core/state/ratchet-engine.d.ts

@@ -0,0 +1,28 @@
+import type { ParetoObjectiveConfig, RatchetConfig } from "../manifest/schema.js";
+import type { FrontierEntry } from "../model/frontier-entry.js";
+import type { MetricResult } from "../model/metric.js";
+export interface RatchetDecision {
+    outcome: "accepted" | "rejected" | "needs_human";
+    frontierChanged: boolean;
+    metricId: string;
+    policyType: RatchetConfig["type"];
+    reason: string;
+    delta?: number;
+    graduation?: {
+        activatedPolicy: "epsilon_improve";
+        consecutiveAccepts: number;
+        epsilon: number;
+        effectiveNextCycle: true;
+        reason: string;
+    };
+}
+export interface RatchetInput {
+    ratchet: RatchetConfig;
+    primaryMetric: string;
+    candidateMetrics: Record<string, MetricResult>;
+    currentFrontier: FrontierEntry[];
+    constraintFailureReason?: string;
+    priorConsecutiveAccepts?: number;
+    paretoObjectives?: ParetoObjectiveConfig[];
+}
+export declare function evaluateRatchet(input: RatchetInput): RatchetDecision;

package/dist/core/state/ratchet-engine.js

@@ -0,0 +1,177 @@
+import { buildMetricComparisonReason, compareParetoFrontier, directionalDelta } from "./frontier-engine.js";
+export function evaluateRatchet(input) {
+    const metricId = "metric" in input.ratchet ? input.ratchet.metric ?? input.primaryMetric : input.primaryMetric;
+    if (input.constraintFailureReason) {
+        return {
+            outcome: "rejected",
+            frontierChanged: false,
+            metricId,
+            policyType: input.ratchet.type,
+            reason: input.constraintFailureReason,
+        };
+    }
+    const candidateMetric = getCandidateMetric(input.candidateMetrics, metricId);
+    const incumbentMetric = input.currentFrontier[0]?.metrics[metricId];
+    const priorConsecutiveAccepts = input.priorConsecutiveAccepts ?? 0;
+    if (input.ratchet.type === "pareto_dominance") {
+        if (!input.paretoObjectives) {
+            throw new Error("pareto_dominance ratchet requires paretoObjectives");
+        }
+        return evaluateParetoDominance(metricId, input.currentFrontier, input.candidateMetrics, input.paretoObjectives);
+    }
+    if (input.ratchet.type === "epsilon_improve") {
+        return evaluateEpsilonImprove(metricId, input.ratchet.epsilon, candidateMetric, incumbentMetric);
+    }
+    if (input.ratchet.graduation && priorConsecutiveAccepts >= input.ratchet.graduation.consecutiveAccepts) {
+        const graduatedDecision = evaluateEpsilonImprove(metricId, input.ratchet.graduation.epsilon, candidateMetric, incumbentMetric);
+        return {
+            ...graduatedDecision,
+            reason: `graduated autonomy active after ${priorConsecutiveAccepts} consecutive accepts; ${graduatedDecision.reason}`,
+        };
+    }
+    return evaluateApprovalGate(metricId, input.ratchet.minConfidence, candidateMetric, incumbentMetric, input.ratchet.graduation, priorConsecutiveAccepts);
+}
+function evaluateParetoDominance(metricId, currentFrontier, candidateMetrics, objectives) {
+    const candidateEntry = {
+        frontierId: "candidate-preview",
+        runId: "candidate-preview",
+        candidateId: "candidate-preview",
+        acceptedAt: new Date(0).toISOString(),
+        metrics: candidateMetrics,
+        artifacts: [],
+    };
+    const comparison = compareParetoFrontier(currentFrontier, candidateEntry, objectives);
+    return {
+        outcome: comparison.outcome,
+        frontierChanged: comparison.frontierChanged,
+        metricId,
+        policyType: "pareto_dominance",
+        reason: comparison.reason,
+    };
+}
+function evaluateEpsilonImprove(metricId, epsilon, candidateMetric, incumbentMetric) {
+    if (!incumbentMetric) {
+        return {
+            outcome: "accepted",
+            frontierChanged: true,
+            metricId,
+            policyType: "epsilon_improve",
+            reason: `frontier empty; candidate accepted on metric ${metricId}`,
+        };
+    }
+    const delta = directionalDelta(candidateMetric, incumbentMetric);
+    if (delta > epsilon) {
+        return {
+            outcome: "accepted",
+            frontierChanged: true,
+            metricId,
+            policyType: "epsilon_improve",
+            delta,
+            reason: `${buildMetricComparisonReason(metricId, candidateMetric, incumbentMetric, delta, "improved")}; epsilon=${epsilon}`,
+        };
+    }
+    return {
+        outcome: "rejected",
+        frontierChanged: false,
+        metricId,
+        policyType: "epsilon_improve",
+        delta,
+        reason: `${buildMetricComparisonReason(metricId, candidateMetric, incumbentMetric, delta, "not_improved")}; epsilon=${epsilon}`,
+    };
+}
+function evaluateApprovalGate(metricId, minConfidence, candidateMetric, incumbentMetric, graduation, priorConsecutiveAccepts = 0) {
+    const confidence = candidateMetric.confidence;
+    if (!incumbentMetric) {
+        if (confidence === undefined) {
+            return {
+                outcome: "needs_human",
+                frontierChanged: false,
+                metricId,
+                policyType: "approval_gate",
+                reason: `frontier empty on metric ${metricId}, but candidate confidence is missing`,
+            };
+        }
+        if (confidence < minConfidence) {
+            return {
+                outcome: "needs_human",
+                frontierChanged: false,
+                metricId,
+                policyType: "approval_gate",
+                reason: `frontier empty on metric ${metricId}, but confidence ${confidence.toFixed(2)} is below threshold ${minConfidence.toFixed(2)}`,
+            };
+        }
+        return {
+            outcome: "accepted",
+            frontierChanged: true,
+            metricId,
+            policyType: "approval_gate",
+            reason: `frontier empty; candidate accepted on metric ${metricId} with confidence ${confidence.toFixed(2)}`,
+            ...(graduation && priorConsecutiveAccepts + 1 >= graduation.consecutiveAccepts
+                ? {
+                    graduation: buildGraduationEvent(metricId, graduation, priorConsecutiveAccepts + 1),
+                }
+                : {}),
+        };
+    }
+    const delta = directionalDelta(candidateMetric, incumbentMetric);
+    if (delta <= 0) {
+        return {
+            outcome: "rejected",
+            frontierChanged: false,
+            metricId,
+            policyType: "approval_gate",
+            delta,
+            reason: buildMetricComparisonReason(metricId, candidateMetric, incumbentMetric, delta, "not_improved"),
+        };
+    }
+    if (confidence === undefined) {
+        return {
+            outcome: "needs_human",
+            frontierChanged: false,
+            metricId,
+            policyType: "approval_gate",
+            delta,
+            reason: `${buildMetricComparisonReason(metricId, candidateMetric, incumbentMetric, delta, "improved")}; confidence missing`,
+        };
+    }
+    if (confidence < minConfidence) {
+        return {
+            outcome: "needs_human",
+            frontierChanged: false,
+            metricId,
+            policyType: "approval_gate",
+            delta,
+            reason: `${buildMetricComparisonReason(metricId, candidateMetric, incumbentMetric, delta, "improved")}; confidence ${confidence.toFixed(2)} below threshold ${minConfidence.toFixed(2)}`,
+        };
+    }
+    return {
+        outcome: "accepted",
+        frontierChanged: true,
+        metricId,
+        policyType: "approval_gate",
+        delta,
+        reason: `${buildMetricComparisonReason(metricId, candidateMetric, incumbentMetric, delta, "improved")}; confidence ${confidence.toFixed(2)} passed threshold ${minConfidence.toFixed(2)}`,
+        ...(graduation && priorConsecutiveAccepts + 1 >= graduation.consecutiveAccepts
+            ? {
+                graduation: buildGraduationEvent(metricId, graduation, priorConsecutiveAccepts + 1),
+            }
+            : {}),
+    };
+}
+function buildGraduationEvent(metricId, graduation, consecutiveAccepts) {
+    return {
+        activatedPolicy: "epsilon_improve",
+        consecutiveAccepts,
+        epsilon: graduation.epsilon,
+        effectiveNextCycle: true,
+        reason: `graduated autonomy unlocked for metric ${metricId} after ${consecutiveAccepts} consecutive accepts`,
+    };
+}
+function getCandidateMetric(metrics, metricId) {
+    const metric = metrics[metricId];
+    if (!metric) {
+        throw new Error(`Missing candidate metric "${metricId}" for ratchet evaluation`);
+    }
+    return metric;
+}
+//# sourceMappingURL=ratchet-engine.js.map

package/dist/core/state/ratchet-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratchet-engine.js","sourceRoot":"","sources":["../../../src/core/state/ratchet-engine.ts"],"names":[],"mappings":"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"}

package/dist/core/state/run-state-machine.d.ts

@@ -0,0 +1,17 @@
+import { type RunPhase, type RunRecord, type RunStatus } from "../model/run-record.js";
+export type PendingAction = RunRecord["pendingAction"];
+export interface AdvanceRunPhaseOptions {
+    at?: string;
+    status?: RunStatus;
+    decisionId?: string;
+    error?: RunRecord["error"];
+    pendingAction?: PendingAction;
+}
+export interface RecoveryPlan {
+    resumable: boolean;
+    nextAction: PendingAction;
+    reason: string;
+}
+export declare function advanceRunPhase(run: RunRecord, nextPhase: RunPhase, options?: AdvanceRunPhaseOptions): RunRecord;
+export declare function canResume(run: RunRecord): boolean;
+export declare function recoverRun(run: RunRecord): RecoveryPlan;

package/dist/core/state/run-state-machine.js

@@ -0,0 +1,94 @@
+import { pendingActionSchema, runRecordSchema, } from "../model/run-record.js";
+const phaseOrder = [
+    "proposed",
+    "executed",
+    "evaluated",
+    "decision_written",
+    "committed",
+    "frontier_updated",
+    "completed",
+    "failed",
+];
+export function advanceRunPhase(run, nextPhase, options = {}) {
+    const currentIndex = phaseOrder.indexOf(run.phase);
+    const nextIndex = phaseOrder.indexOf(nextPhase);
+    if (nextIndex < currentIndex) {
+        return runRecordSchema.parse(run);
+    }
+    const resolvedPhase = nextIndex === currentIndex ? run.phase : nextPhase;
+    const status = options.status ?? inferStatusForPhase(run.status, resolvedPhase);
+    const pendingAction = options.pendingAction ?? inferPendingAction({ ...run, status, phase: resolvedPhase });
+    const updated = runRecordSchema.parse({
+        ...run,
+        status,
+        phase: resolvedPhase,
+        pendingAction: pendingActionSchema.parse(pendingAction),
+        decisionId: options.decisionId ?? run.decisionId,
+        error: options.error ?? run.error,
+        endedAt: resolvedPhase === "completed" || resolvedPhase === "failed" ? options.at ?? run.endedAt ?? new Date().toISOString() : run.endedAt,
+    });
+    return updated;
+}
+export function canResume(run) {
+    return recoverRun(run).resumable;
+}
+export function recoverRun(run) {
+    if (run.phase === "completed") {
+        return {
+            resumable: false,
+            nextAction: "none",
+            reason: "run already completed",
+        };
+    }
+    if (run.phase === "failed") {
+        return {
+            resumable: false,
+            nextAction: "none",
+            reason: "run failed and requires explicit intervention",
+        };
+    }
+    const nextAction = run.pendingAction !== "none" ? run.pendingAction : inferPendingAction(run);
+    return {
+        resumable: nextAction !== "none",
+        nextAction,
+        reason: `resume from phase ${run.phase} with action ${nextAction}`,
+    };
+}
+function inferStatusForPhase(currentStatus, phase) {
+    switch (phase) {
+        case "proposed":
+        case "executed":
+            return "running";
+        case "evaluated":
+            return currentStatus === "rejected" || currentStatus === "needs_human" || currentStatus === "accepted"
+                ? currentStatus
+                : "evaluated";
+        case "decision_written":
+        case "committed":
+        case "frontier_updated":
+        case "completed":
+            return currentStatus;
+        case "failed":
+            return "failed";
+    }
+}
+function inferPendingAction(run) {
+    switch (run.phase) {
+        case "proposed":
+            return "execute_experiment";
+        case "executed":
+            return "evaluate_metrics";
+        case "evaluated":
+            return "write_decision";
+        case "decision_written":
+            return run.status === "accepted" ? "commit_candidate" : "cleanup_workspace";
+        case "committed":
+            return "update_frontier";
+        case "frontier_updated":
+            return "cleanup_workspace";
+        case "completed":
+        case "failed":
+            return "none";
+    }
+}
+//# sourceMappingURL=run-state-machine.js.map