@vela-science/canopus 0.4.0-rc.1

package/dist/src/cli.js

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { readdir, stat } from "node:fs/promises";
+import { parseMission } from "./contracts/mission.js";
+import { CodexExecEngine } from "./engines/codex-exec.js";
+import { CodexToolsNativeEngine } from "./engines/codex-tools-native.js";
+import { prepareMission, validateMissionBundle } from "./mission/prepare.js";
+import { parseDiagnosticRunRecord, projectDiagnosticRun } from "./projection/diagnostic.js";
+import { parseFailureRecord, projectFailure } from "./projection/failure.js";
+import { parseRunRecord, projectRun } from "./projection/run.js";
+import { doctorProduct } from "./product/doctor.js";
+import { replayProduct } from "./product/replay.js";
+import { runProduct } from "./product/run.js";
+import { withdrawProduct } from "./product/withdraw.js";
+import { listProductProfiles, packProductProfile, validateProductProfile, } from "./product/profile-bundle.js";
+import { loadProductProfile } from "./product/profile.js";
+import { runCanopus } from "./run.js";
+import { readBoundedRegularFile } from "./util/files.js";
+import { VelaClient } from "./vela/cli.js";
+import { withdrawalCapabilityStatus } from "./capability/withdrawal.js";
+function usage() {
+    return `Canopus — bounded Vela research harness
+
+Primary workflow:
+  canopus doctor [frontier]
+  canopus run [frontier] [--first | --target <id>] [--profile <name>] \\
+    [--output <dir>] [--no-land]
+  canopus inspect [run.json | latest]
+  canopus replay <run.json>
+  canopus withdraw [frontier] [--run <run.json|latest>] --reason <text>
+
+Mission v1 prepare/validate remains available under advanced help.
+
+Canopus may land a Receipt v1 as an agent after verifier success. It cannot
+sign, accept, or make a human scientific decision.`;
+}
+function missionUsage() {
+    return `Usage:
+  canopus mission prepare <draft.json> --source <clean-repo> --output <new-bundle> \\
+    --vela <binary> --codex <binary> --verifier-image <image> [--docker <binary>]
+  canopus mission validate <bundle/mission.json>
+
+prepare derives exact Git, Vela, packet, native permission-profile,
+verifier-image, Codex, capsule, and strict-baseline roots. validate is read-only
+and checks the closed contract and portable bundle bytes.`;
+}
+function profileUsage() {
+    return `Usage:
+  canopus profile list
+  canopus profile show <name>
+  canopus profile validate <name>
+  canopus profile pack <name> --output <new-directory>
+
+Profiles are closed, content-addressed producer contracts. Version 1 profiles
+remain replay-only; new tool-using missions require a validated version 2 profile.`;
+}
+function runUsage() {
+    return `Usage:
+  canopus run [frontier] [--first | --target <id>] [--profile <name>] \\
+    [--output <dir>] [--no-land]
+
+Discovers and binds Vela, Codex, Git, Docker, the exact frontier roots, and the
+registered verifier profile. --no-land runs the worker and verifier in disposable
+clones and leaves the source frontier unchanged.`;
+}
+function inspectUsage() {
+    return `Usage:
+  canopus inspect [run.json | failure.json | latest]
+
+Projects the newest completed or safely stopped non-authoritative run record
+without mutating Vela. A failed run never implies that landing was unchanged;
+inspect reports whether retained landing-recovery evidence is required.`;
+}
+function doctorUsage() {
+    return `Usage:
+  canopus doctor [frontier]
+
+Checks the compact Vela contract, exact runtimes, first offer, registered
+profile, packaged capsule root, real native custody boundary, and verifier
+isolation prerequisites.`;
+}
+function replayUsage() {
+    return `Usage:
+  canopus replay <run.json>
+
+Re-runs the frozen verifier over the content-addressed candidate without a
+model call, Vela mutation, network, or authority action.`;
+}
+function withdrawUsage() {
+    return `Usage:
+  canopus withdraw [frontier] [--run <run.json|latest>] --reason <text>
+
+Uses only the retained proposal-scoped producer capability. The operation runs
+in a disposable exact-head clone, verifies strict and clean-clone replay, then
+fast-forwards the clean source. It never mounts a worker or human key.`;
+}
+function isHelp(value) {
+    return value === "--help" || value === "-h" || value === "help";
+}
+async function jsonFile(file) {
+    const bytes = await readBoundedRegularFile(path.resolve(file), 8 * 1024 * 1024);
+    return JSON.parse(bytes.toString("utf8"));
+}
+function options(args, allowed) {
+    const result = new Map();
+    const allow = new Set(allowed);
+    for (let index = 0; index < args.length; index += 2) {
+        const key = args[index];
+        const value = args[index + 1];
+        if (key === undefined || value === undefined || !allow.has(key) || result.has(key)) {
+            throw new Error(`invalid or duplicate option near ${key ?? "end of arguments"}`);
+        }
+        result.set(key, value);
+    }
+    return result;
+}
+function productOptions(args, valueOptions, booleanOptions) {
+    const valueAllow = new Set(valueOptions);
+    const flagAllow = new Set(booleanOptions);
+    const positional = [];
+    const values = new Map();
+    const flags = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const item = args[index];
+        if (!item.startsWith("--")) {
+            positional.push(item);
+            continue;
+        }
+        if (flagAllow.has(item)) {
+            if (flags.has(item))
+                throw new Error(`duplicate option ${item}`);
+            flags.add(item);
+            continue;
+        }
+        if (!valueAllow.has(item) || values.has(item)) {
+            throw new Error(`unknown or duplicate option ${item}`);
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--"))
+            throw new Error(`${item} requires a value`);
+        values.set(item, value);
+        index += 1;
+    }
+    return { positional, values, flags };
+}
+function required(values, key) {
+    const value = values.get(key);
+    if (value === undefined || value === "")
+        throw new Error(`${key} is required`);
+    return value;
+}
+function authHome(values) {
+    return path.resolve(values.get("--codex-home") ?? process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex"));
+}
+function packagedOutputSchema() {
+    return fileURLToPath(new URL("../../schemas/engine-output.v0.json", import.meta.url));
+}
+function packagedNativeWorkerProfile() {
+    const file = process.platform === "linux" ? "config-linux.toml" : "config.toml";
+    return fileURLToPath(new URL(`../../runtime/native-worker/${file}`, import.meta.url));
+}
+async function missionCommand(args) {
+    const [subcommand, file, ...rest] = args;
+    if (subcommand === undefined || isHelp(subcommand)) {
+        process.stdout.write(`${missionUsage()}\n`);
+        return;
+    }
+    if (isHelp(file)) {
+        process.stdout.write(`${missionUsage()}\n`);
+        return;
+    }
+    if (file === undefined)
+        throw new Error(`mission ${subcommand} requires a JSON file`);
+    if (subcommand === "validate") {
+        if (rest.length !== 0)
+            throw new Error("mission validate accepts only one mission file");
+        const mission = parseMission(await jsonFile(file));
+        if (mission.schema === "canopus.mission.v1") {
+            await validateMissionBundle(mission, path.dirname(path.resolve(file)));
+        }
+        process.stdout.write(`${JSON.stringify({ ok: true, command: "mission validate", mission_id: mission.id, schema: mission.schema })}\n`);
+        return;
+    }
+    if (subcommand !== "prepare")
+        throw new Error(`unknown mission command ${subcommand}`);
+    const values = options(rest, [
+        "--source",
+        "--output",
+        "--vela",
+        "--codex",
+        "--verifier-image",
+        "--docker",
+    ]);
+    const prepared = await prepareMission({
+        draft: await jsonFile(file),
+        draftRoot: path.dirname(path.resolve(file)),
+        sourceRepo: path.resolve(required(values, "--source")),
+        outputRoot: path.resolve(required(values, "--output")),
+        velaBinary: path.resolve(required(values, "--vela")),
+        codexBinary: path.resolve(required(values, "--codex")),
+        dockerBinary: values.get("--docker") ?? "docker",
+        verifierImage: required(values, "--verifier-image"),
+        outputSchema: packagedOutputSchema(),
+        permissionProfile: packagedNativeWorkerProfile(),
+    });
+    process.stdout.write(`${JSON.stringify({
+        ok: true,
+        command: "mission prepare",
+        mission_id: prepared.mission.id,
+        target: prepared.mission.target,
+        mission: prepared.missionPath,
+        manifest: prepared.manifestPath,
+    })}\n`);
+}
+async function profileCommand(args) {
+    const [subcommand, name, ...rest] = args;
+    if (subcommand === undefined || isHelp(subcommand) || isHelp(name)) {
+        process.stdout.write(`${profileUsage()}\n`);
+        return;
+    }
+    if (subcommand === "list") {
+        if (name !== undefined || rest.length !== 0)
+            throw new Error("profile list accepts no arguments");
+        process.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "profile list",
+            profiles: await listProductProfiles(),
+        })}\n`);
+        return;
+    }
+    if (name === undefined)
+        throw new Error(`profile ${subcommand} requires a profile name`);
+    if (subcommand === "show") {
+        if (rest.length !== 0)
+            throw new Error("profile show accepts exactly one profile name");
+        const profile = await loadProductProfile(name);
+        process.stdout.write(`${JSON.stringify({ ok: true, command: "profile show", profile })}\n`);
+        return;
+    }
+    if (subcommand === "validate") {
+        if (rest.length !== 0)
+            throw new Error("profile validate accepts exactly one profile name");
+        process.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "profile validate",
+            validation: await validateProductProfile(name),
+        })}\n`);
+        return;
+    }
+    if (subcommand === "pack") {
+        const values = options(rest, ["--output"]);
+        const result = await packProductProfile(name, path.resolve(required(values, "--output")));
+        process.stdout.write(`${JSON.stringify({ ok: true, command: "profile pack", ...result })}\n`);
+        return;
+    }
+    throw new Error(`unknown profile command ${subcommand}`);
+}
+async function runMission(file, rest) {
+    const values = options(rest, [
+        "--source",
+        "--run-root",
+        "--vela",
+        "--docker",
+        "--codex",
+        "--codex-version",
+        "--codex-sha256",
+        "--model",
+        "--codex-home",
+    ]);
+    const mission = parseMission(await jsonFile(file));
+    const sourceRepo = path.resolve(required(values, "--source"));
+    const runRoot = path.resolve(required(values, "--run-root"));
+    const velaBinary = path.resolve(required(values, "--vela"));
+    const outputSchema = mission.schema === "canopus.mission.v1"
+        ? path.join(path.dirname(path.resolve(file)), "contract", "engine-output.v0.json")
+        : packagedOutputSchema();
+    const vela = new VelaClient({
+        binary: velaBinary,
+        expectedVersion: mission.vela_version,
+        expectedSha256: mission.vela_sha256,
+        home: path.join(runRoot, "vela-home"),
+    });
+    const engine = mission.schema === "canopus.mission.v1"
+        ? new CodexToolsNativeEngine({
+            binary: path.resolve(required(values, "--codex")),
+            authHome: authHome(values),
+            outputSchema,
+            permissionProfile: path.join(path.dirname(path.resolve(file)), mission.worker.permission_profile_path),
+        })
+        : new CodexExecEngine({
+            binary: path.resolve(required(values, "--codex")),
+            expectedSha256: required(values, "--codex-sha256"),
+            expectedVersion: required(values, "--codex-version"),
+            model: required(values, "--model"),
+            authHome: authHome(values),
+            outputSchema,
+        });
+    const result = await runCanopus({
+        mission,
+        sourceRepo,
+        runRoot,
+        vela,
+        engine,
+        bundleRoot: path.dirname(path.resolve(file)),
+        dockerBinary: values.get("--docker") ?? "docker",
+    });
+    process.stdout.write(`${JSON.stringify({
+        ok: true,
+        command: "run",
+        run_id: result.record.run_id,
+        candidate_digest: result.record.candidate.digest,
+        receipt_root: result.record.landing.receipt_root,
+        route: result.record.landing.route,
+        accepted_event_delta: result.record.landing.accepted_event_delta,
+        clean_clone_reproduced: result.record.reproduction.matched,
+        run_file: path.join(result.paths.root, "run.json"),
+    })}\n`);
+}
+async function doctorCommand(args) {
+    const parsed = productOptions(args, [], []);
+    if (parsed.positional.length > 1)
+        throw new Error("doctor accepts at most one frontier");
+    const result = await doctorProduct({ frontier: path.resolve(parsed.positional[0] ?? ".") });
+    process.stdout.write(`${JSON.stringify(result.public)}\n`);
+}
+async function productRunCommand(args) {
+    const parsed = productOptions(args, ["--target", "--profile", "--output", "--codex-home"], ["--first", "--no-land"]);
+    if (parsed.positional.length > 1)
+        throw new Error("run accepts at most one frontier");
+    if (parsed.flags.has("--first") && parsed.values.has("--target")) {
+        throw new Error("--first and --target are mutually exclusive");
+    }
+    const frontier = path.resolve(parsed.positional[0] ?? ".");
+    const requested = parsed.values.get("--target");
+    const profileName = parsed.values.get("--profile");
+    const outputRoot = parsed.values.get("--output");
+    const codexHome = parsed.values.get("--codex-home");
+    const result = await runProduct({
+        frontier,
+        ...(profileName === undefined ? {} : { profileName }),
+        ...(requested === undefined ? {} : { requestedTarget: requested }),
+        ...(outputRoot === undefined ? {} : { outputRoot: path.resolve(outputRoot) }),
+        ...(codexHome === undefined ? {} : { codexHome: path.resolve(codexHome) }),
+        noLand: parsed.flags.has("--no-land"),
+    });
+    const landing = result.run.record.landing;
+    process.stdout.write(`${JSON.stringify({
+        ok: true,
+        command: "run",
+        mode: landing === null ? "no_land" : "land",
+        run_id: result.run.record.run_id,
+        target: result.run.record.mission.target,
+        candidate_digest: result.run.record.candidate.digest,
+        verifier_status: result.run.record.verifier.status,
+        observed_tokens: result.run.record.budget.observed_tokens,
+        receipt_root: landing?.receipt_root ?? null,
+        proposal_id: landing?.proposal_id ?? null,
+        route: landing?.route ?? null,
+        accepted_event_delta: landing?.accepted_event_delta ?? null,
+        clean_clone_reproduced: result.run.record.reproduction.matched,
+        evidence_root: result.evidence_root,
+        source_publication: result.source_publication,
+        run_file: path.join(result.run.paths.root, "run.json"),
+    })}\n`);
+}
+async function latestRunFile() {
+    const root = path.join(os.homedir(), ".canopus", "runs");
+    const entries = await readdir(root, { recursive: true });
+    const candidates = entries
+        .filter((entry) => entry.endsWith(`${path.sep}run${path.sep}run.json`) || entry === path.join("run", "run.json"))
+        .map((entry) => path.join(root, entry));
+    if (candidates.length === 0)
+        throw new Error("no completed Canopus product run was found");
+    const ranked = await Promise.all(candidates.map(async (file) => ({
+        file,
+        modified: (await stat(file)).mtimeMs,
+    })));
+    ranked.sort((left, right) => right.modified - left.modified || left.file.localeCompare(right.file));
+    return ranked[0]?.file ?? (() => { throw new Error("no completed Canopus product run was found"); })();
+}
+async function latestInspectionFile() {
+    const root = path.join(os.homedir(), ".canopus", "runs");
+    const entries = await readdir(root, { recursive: true });
+    const candidates = entries
+        .filter((entry) => entry.endsWith(`${path.sep}run${path.sep}run.json`) ||
+        entry === path.join("run", "run.json") ||
+        entry.endsWith(`${path.sep}run${path.sep}failure.json`) ||
+        entry === path.join("run", "failure.json"))
+        .map((entry) => path.join(root, entry));
+    if (candidates.length === 0)
+        throw new Error("no inspectable Canopus product run was found");
+    const ranked = await Promise.all(candidates.map(async (file) => ({
+        file,
+        modified: (await stat(file)).mtimeMs,
+    })));
+    ranked.sort((left, right) => right.modified - left.modified || left.file.localeCompare(right.file));
+    return ranked[0]?.file ?? (() => { throw new Error("no inspectable Canopus product run was found"); })();
+}
+async function inspectCommand(value, rest) {
+    if (rest.length !== 0)
+        throw new Error("inspect accepts at most one run file");
+    const file = value === undefined || value === "latest"
+        ? await latestInspectionFile()
+        : path.resolve(value);
+    const raw = await jsonFile(file);
+    const schema = typeof raw === "object" && raw !== null && !Array.isArray(raw)
+        ? raw.schema
+        : undefined;
+    const projection = schema === "canopus.diagnostic-run.v1"
+        ? projectDiagnosticRun(parseDiagnosticRunRecord(raw))
+        : schema === "canopus.failure.v0"
+            ? projectFailure(parseFailureRecord(raw))
+            : projectRun(parseRunRecord(raw));
+    const withdrawal = "proposal_id" in projection
+        ? await withdrawalCapabilityStatus(projection.proposal_id)
+        : { state: "not_applicable", available: false };
+    process.stdout.write(`${JSON.stringify({ ok: true, command: "inspect", run_file: file, projection, withdrawal })}\n`);
+}
+async function replayCommand(file, rest) {
+    if (file === undefined || rest.length !== 0)
+        throw new Error("replay requires exactly one run file");
+    process.stdout.write(`${JSON.stringify(await replayProduct(path.resolve(file)))}\n`);
+}
+async function withdrawCommand(args) {
+    const parsed = productOptions(args, ["--run", "--reason"], []);
+    if (parsed.positional.length > 1)
+        throw new Error("withdraw accepts at most one frontier");
+    const reason = parsed.values.get("--reason");
+    if (reason === undefined || reason.trim().length === 0)
+        throw new Error("withdraw requires --reason");
+    const runValue = parsed.values.get("--run") ?? "latest";
+    const runFile = runValue === "latest" ? await latestRunFile() : path.resolve(runValue);
+    const result = await withdrawProduct({
+        frontier: path.resolve(parsed.positional[0] ?? "."),
+        runFile,
+        reason,
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+async function main(argv) {
+    const [command, file, ...rest] = argv;
+    if (command === undefined || isHelp(command)) {
+        process.stdout.write(`${usage()}\n`);
+        return;
+    }
+    if (command === "mission") {
+        await missionCommand(argv.slice(1));
+        return;
+    }
+    if (command === "profile") {
+        await profileCommand(argv.slice(1));
+        return;
+    }
+    if (isHelp(file)) {
+        process.stdout.write(`${command === "run" ? runUsage()
+            : command === "inspect" ? inspectUsage()
+                : command === "doctor" ? doctorUsage()
+                    : command === "replay" ? replayUsage()
+                        : command === "withdraw" ? withdrawUsage()
+                            : usage()}\n`);
+        return;
+    }
+    if (command === "doctor") {
+        await doctorCommand(argv.slice(1));
+        return;
+    }
+    if (command === "replay") {
+        await replayCommand(file, rest);
+        return;
+    }
+    if (command === "withdraw") {
+        await withdrawCommand(argv.slice(1));
+        return;
+    }
+    if (command === "validate") {
+        if (file === undefined)
+            throw new Error("validate requires a mission file");
+        await missionCommand(["validate", file, ...rest]);
+        return;
+    }
+    if (command === "inspect") {
+        await inspectCommand(file, rest);
+        return;
+    }
+    if (command === "run") {
+        if (file !== undefined && (file.endsWith(".json") || rest.includes("--source"))) {
+            await runMission(file, rest);
+        }
+        else {
+            await productRunCommand(argv.slice(1));
+        }
+        return;
+    }
+    throw new Error(`unknown command ${command}`);
+}
+main(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${JSON.stringify({ ok: false, error: message })}\n`);
+    process.exitCode = 1;
+});

package/dist/src/contracts/candidate.d.ts

@@ -0,0 +1,50 @@
+export declare const CANDIDATE_SCHEMA: "canopus.candidate.v0";
+export declare const CANDIDATE_STATUSES: readonly ["success", "null", "failed"];
+export declare const MAX_CANDIDATE_ARTIFACTS = 10;
+export declare const MAX_CANDIDATE_OBSERVATIONS = 16;
+export declare const MAX_CANDIDATE_TESTS = 2;
+export declare const MAX_CANDIDATE_CAVEATS = 10;
+export type CandidateStatus = (typeof CANDIDATE_STATUSES)[number];
+export interface FrozenArtifact {
+    path: string;
+    kind: string;
+    digest: string;
+    bytes: number;
+}
+export interface TestRecord {
+    argv: string[];
+    executable_digest: string;
+    exit_code: number;
+    stdout_digest: string;
+    stderr_digest: string;
+    duration_ms: number;
+}
+export interface CandidateCosts {
+    wall_time_ms: number;
+    attempt: number;
+    input_tokens: number;
+    output_tokens: number;
+}
+export interface Candidate {
+    schema: typeof CANDIDATE_SCHEMA;
+    mission_id: string;
+    status: CandidateStatus;
+    claim: string;
+    artifacts: FrozenArtifact[];
+    observations: string[];
+    tests: TestRecord[];
+    costs: CandidateCosts;
+    caveats: string[];
+    engine: {
+        name: string;
+        version: string;
+        binary_sha256: string | null;
+        model: string | null;
+        configuration_sha256: string;
+    };
+    repair?: {
+        parent_candidate: string;
+        reason: string;
+    };
+}
+export declare function parseCandidate(value: unknown): Candidate;

package/dist/src/contracts/candidate.js

@@ -0,0 +1,93 @@
+import { MISSION_ID_RE, arrayAt, enumAt, exactKeys, integerAt, objectAt, relativePathAt, sha256At, stringAt, } from "./validation.js";
+export const CANDIDATE_SCHEMA = "canopus.candidate.v0";
+export const CANDIDATE_STATUSES = ["success", "null", "failed"];
+export const MAX_CANDIDATE_ARTIFACTS = 10;
+export const MAX_CANDIDATE_OBSERVATIONS = 16;
+export const MAX_CANDIDATE_TESTS = 2;
+export const MAX_CANDIDATE_CAVEATS = 10;
+function parseArtifact(value, at) {
+    const object = objectAt(value, at);
+    exactKeys(object, ["path", "kind", "digest", "bytes"], [], at);
+    return {
+        path: relativePathAt(object.path, `${at}.path`),
+        kind: stringAt(object.kind, `${at}.kind`, { min: 1, max: 128 }),
+        digest: sha256At(object.digest, `${at}.digest`),
+        bytes: integerAt(object.bytes, `${at}.bytes`, 0, 1_073_741_824),
+    };
+}
+function parseTest(value, at) {
+    const object = objectAt(value, at);
+    exactKeys(object, ["argv", "executable_digest", "exit_code", "stdout_digest", "stderr_digest", "duration_ms"], [], at);
+    return {
+        argv: arrayAt(object.argv, `${at}.argv`, { min: 1, max: 64 }, (item, itemAt) => stringAt(item, itemAt, { max: 4096 })),
+        executable_digest: sha256At(object.executable_digest, `${at}.executable_digest`),
+        exit_code: integerAt(object.exit_code, `${at}.exit_code`, -1, 255),
+        stdout_digest: sha256At(object.stdout_digest, `${at}.stdout_digest`),
+        stderr_digest: sha256At(object.stderr_digest, `${at}.stderr_digest`),
+        duration_ms: integerAt(object.duration_ms, `${at}.duration_ms`, 0, 3_600_000),
+    };
+}
+function parseCosts(value) {
+    const object = objectAt(value, "candidate.costs");
+    exactKeys(object, ["wall_time_ms", "attempt", "input_tokens", "output_tokens"], [], "candidate.costs");
+    return {
+        wall_time_ms: integerAt(object.wall_time_ms, "candidate.costs.wall_time_ms", 0, 3_600_000),
+        attempt: integerAt(object.attempt, "candidate.costs.attempt", 1, 8),
+        input_tokens: integerAt(object.input_tokens, "candidate.costs.input_tokens", 0, 1_000_000),
+        output_tokens: integerAt(object.output_tokens, "candidate.costs.output_tokens", 0, 1_000_000),
+    };
+}
+export function parseCandidate(value) {
+    const object = objectAt(value, "candidate");
+    exactKeys(object, [
+        "schema",
+        "mission_id",
+        "status",
+        "claim",
+        "artifacts",
+        "observations",
+        "tests",
+        "costs",
+        "caveats",
+        "engine",
+    ], ["repair"], "candidate");
+    const engine = objectAt(object.engine, "candidate.engine");
+    exactKeys(engine, ["name", "version", "binary_sha256", "model", "configuration_sha256"], [], "candidate.engine");
+    const base = {
+        schema: enumAt(object.schema, "candidate.schema", [CANDIDATE_SCHEMA]),
+        mission_id: stringAt(object.mission_id, "candidate.mission_id", {
+            max: 134,
+            pattern: MISSION_ID_RE,
+        }),
+        status: enumAt(object.status, "candidate.status", CANDIDATE_STATUSES),
+        claim: stringAt(object.claim, "candidate.claim", { min: 1, max: 8192 }),
+        artifacts: arrayAt(object.artifacts, "candidate.artifacts", { max: MAX_CANDIDATE_ARTIFACTS }, parseArtifact),
+        observations: arrayAt(object.observations, "candidate.observations", { max: MAX_CANDIDATE_OBSERVATIONS }, (item, at) => stringAt(item, at, { min: 1, max: 4096 })),
+        tests: arrayAt(object.tests, "candidate.tests", { max: MAX_CANDIDATE_TESTS }, parseTest),
+        costs: parseCosts(object.costs),
+        caveats: arrayAt(object.caveats, "candidate.caveats", { max: MAX_CANDIDATE_CAVEATS }, (item, at) => stringAt(item, at, { min: 1, max: 4096 })),
+        engine: {
+            name: stringAt(engine.name, "candidate.engine.name", { min: 1, max: 128 }),
+            version: stringAt(engine.version, "candidate.engine.version", { min: 1, max: 256 }),
+            binary_sha256: engine.binary_sha256 === null
+                ? null
+                : sha256At(engine.binary_sha256, "candidate.engine.binary_sha256"),
+            model: engine.model === null
+                ? null
+                : stringAt(engine.model, "candidate.engine.model", { min: 1, max: 256 }),
+            configuration_sha256: sha256At(engine.configuration_sha256, "candidate.engine.configuration_sha256"),
+        },
+    };
+    if (object.repair === undefined) {
+        return base;
+    }
+    const repair = objectAt(object.repair, "candidate.repair");
+    exactKeys(repair, ["parent_candidate", "reason"], [], "candidate.repair");
+    return {
+        ...base,
+        repair: {
+            parent_candidate: sha256At(repair.parent_candidate, "candidate.repair.parent_candidate"),
+            reason: stringAt(repair.reason, "candidate.repair.reason", { min: 1, max: 4096 }),
+        },
+    };
+}