@vela-science/canopus 0.4.0-rc.1

package/dist/src/product/profile.js

@@ -0,0 +1,251 @@
+import { constants } from "node:fs";
+import { access, chmod, copyFile, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { arrayAt, exactKeys, objectAt, relativePathAt, sha256At, stringAt, } from "../contracts/validation.js";
+import { parsePositiveResultContract, } from "../contracts/mission.js";
+import { contentDigest, sha256Bytes } from "../util/canonical.js";
+import { readBoundedRegularFile } from "../util/files.js";
+export const PROFILE_V1_SCHEMA = "canopus.profile.v1";
+export const PROFILE_SCHEMA = "canopus.profile.v2";
+export const SUPPORTED_PRODUCT_PLATFORMS = ["darwin-arm64", "linux-x86_64"];
+export function productPackageRoot() {
+    return fileURLToPath(new URL("../../../", import.meta.url));
+}
+export function currentProductPlatform() {
+    if (process.platform === "darwin" && process.arch === "arm64")
+        return "darwin-arm64";
+    if (process.platform === "linux" && process.arch === "x64")
+        return "linux-x86_64";
+    // Native Windows is a read-only control surface. Its tool-using mission must
+    // be launched inside WSL2, which consumes the exact Linux capsule binding.
+    if (process.platform === "win32" && process.arch === "x64")
+        return "linux-x86_64";
+    throw new Error(`tool-using missions are unsupported on ${process.platform}-${process.arch}; ` +
+        "supported workers are macOS arm64 and Linux/WSL2 x86-64; native Windows is read-only");
+}
+async function registeredProfileNames() {
+    const root = path.join(productPackageRoot(), "profiles");
+    const { readdir } = await import("node:fs/promises");
+    return (await readdir(root, { withFileTypes: true }))
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => entry.name.slice(0, -5))
+        .sort();
+}
+export function verifierImageAt(value, at = "verifier_image") {
+    return stringAt(value, at, {
+        min: 100,
+        max: 200,
+        pattern: /^ghcr\.io\/vela-science\/(?:canopus-verifier|canopus-formal-verifier)@sha256:[0-9a-f]{64}$/u,
+    });
+}
+export async function listProductProfiles() {
+    return registeredProfileNames();
+}
+function parsePlatformCapsule(value, at, defaultVerifierPlatform) {
+    const object = objectAt(value, at);
+    exactKeys(object, [
+        "worker_profile",
+        "worker_profile_sha256",
+        "verifier_capsule",
+        "verifier_capsule_sha256",
+        "verifier_image",
+    ], ["verifier_platform"], at);
+    return {
+        worker_profile: relativePathAt(object.worker_profile, `${at}.worker_profile`),
+        worker_profile_sha256: sha256At(object.worker_profile_sha256, `${at}.worker_profile_sha256`),
+        verifier_capsule: relativePathAt(object.verifier_capsule, `${at}.verifier_capsule`),
+        verifier_capsule_sha256: sha256At(object.verifier_capsule_sha256, `${at}.verifier_capsule_sha256`),
+        verifier_image: verifierImageAt(object.verifier_image, `${at}.verifier_image`),
+        verifier_platform: object.verifier_platform === undefined
+            ? defaultVerifierPlatform
+            : stringAt(object.verifier_platform, `${at}.verifier_platform`, {
+                min: 11,
+                max: 11,
+                pattern: /^linux\/(?:amd64|arm64)$/u,
+            }),
+    };
+}
+function parseV2(value, name, platform, profileSha256) {
+    exactKeys(value, [
+        "schema",
+        "name",
+        "target",
+        "target_packet_schema",
+        "draft",
+        "draft_sha256",
+        "objective_sha256",
+        "completion_condition_sha256",
+        "allowed_artifacts_sha256",
+        "budgets_sha256",
+        "replay_argv_sha256",
+        "landing",
+        "platforms",
+    ], ["result_contract", "result_contract_sha256"], "profile");
+    const platformsValue = objectAt(value.platforms, "profile.platforms");
+    exactKeys(platformsValue, [...SUPPORTED_PRODUCT_PLATFORMS], [], "profile.platforms");
+    const platforms = Object.fromEntries(SUPPORTED_PRODUCT_PLATFORMS.map((platform) => [
+        platform,
+        parsePlatformCapsule(platformsValue[platform], `profile.platforms.${platform}`, platform === "darwin-arm64" ? "linux/arm64" : "linux/amd64"),
+    ]));
+    const landingValue = objectAt(value.landing, "profile.landing");
+    exactKeys(landingValue, ["expected_routes", "max_accepted_delta"], [], "profile.landing");
+    const expectedRoutes = arrayAt(landingValue.expected_routes, "profile.landing.expected_routes", { min: 1, max: 1, unique: true }, (item, at) => stringAt(item, at, { min: 5, max: 6, pattern: /^(?:defer|permit)$/u }));
+    const route = expectedRoutes[0];
+    if (route !== "defer" && route !== "permit") {
+        throw new Error("profile landing route is unsupported");
+    }
+    const maxAcceptedDelta = route === "permit" ? 1 : 0;
+    if (landingValue.max_accepted_delta !== maxAcceptedDelta) {
+        throw new Error(`profile ${route} landing must register accepted delta ${maxAcceptedDelta}`);
+    }
+    if ((value.result_contract === undefined) !== (value.result_contract_sha256 === undefined)) {
+        throw new Error("profile result contract path and root must be supplied together");
+    }
+    if (route === "permit" && value.result_contract === undefined) {
+        throw new Error("profile Permit landing requires an exact positive result contract");
+    }
+    const selected = platforms[platform];
+    const parsed = {
+        schema: PROFILE_SCHEMA,
+        name: stringAt(value.name, "profile.name", { min: 1, max: 128 }),
+        target: stringAt(value.target, "profile.target", { min: 1, max: 256 }),
+        target_packet_schema: stringAt(value.target_packet_schema, "profile.target_packet_schema", {
+            min: 1,
+            max: 128,
+        }),
+        draft: relativePathAt(value.draft, "profile.draft"),
+        draft_sha256: sha256At(value.draft_sha256, "profile.draft_sha256"),
+        objective_sha256: sha256At(value.objective_sha256, "profile.objective_sha256"),
+        completion_condition_sha256: sha256At(value.completion_condition_sha256, "profile.completion_condition_sha256"),
+        allowed_artifacts_sha256: sha256At(value.allowed_artifacts_sha256, "profile.allowed_artifacts_sha256"),
+        budgets_sha256: sha256At(value.budgets_sha256, "profile.budgets_sha256"),
+        replay_argv_sha256: sha256At(value.replay_argv_sha256, "profile.replay_argv_sha256"),
+        landing: { expected_routes: [route], max_accepted_delta: maxAcceptedDelta },
+        profile_sha256: profileSha256,
+        ...(value.result_contract === undefined
+            ? {}
+            : {
+                result_contract: relativePathAt(value.result_contract, "profile.result_contract"),
+                result_contract_sha256: sha256At(value.result_contract_sha256, "profile.result_contract_sha256"),
+            }),
+        platforms,
+        platform,
+        capsule_binary: selected.verifier_capsule,
+        capsule_sha256: selected.verifier_capsule_sha256,
+        permission_profile: selected.worker_profile,
+        permission_profile_sha256: selected.worker_profile_sha256,
+        verifier_image: selected.verifier_image,
+        verifier_platform: selected.verifier_platform,
+    };
+    if (parsed.name !== name)
+        throw new Error("profile filename and registered name disagree");
+    return parsed;
+}
+export async function loadProductProfile(name, options = {}) {
+    if (!(await registeredProfileNames()).includes(name)) {
+        throw new Error(`unknown registered profile ${name}`);
+    }
+    const file = path.join(productPackageRoot(), "profiles", `${name}.json`);
+    const bytes = await readBoundedRegularFile(file, 1024 * 1024);
+    const value = objectAt(JSON.parse(bytes.toString("utf8")), "profile");
+    if (value.schema === PROFILE_V1_SCHEMA) {
+        if (options.allowLegacy !== true) {
+            throw new Error("canopus.profile.v1 is replay-only; prepare a closed v2 profile to run work");
+        }
+        return {
+            schema: PROFILE_V1_SCHEMA,
+            name: stringAt(value.name, "profile.name", { min: 1, max: 128 }),
+            target: stringAt(value.target, "profile.target", { min: 1, max: 256 }),
+        };
+    }
+    if (value.schema !== PROFILE_SCHEMA)
+        throw new Error("profile schema is not supported");
+    return parseV2(value, name, options.platform ?? currentProductPlatform(), sha256Bytes(bytes));
+}
+export async function loadProfileResultContract(profile) {
+    if (profile.result_contract === undefined || profile.result_contract_sha256 === undefined) {
+        return undefined;
+    }
+    const file = await packagedProfileResource(profile.result_contract, "profile result contract");
+    const bytes = await readBoundedRegularFile(file, 1024 * 1024);
+    const observed = sha256Bytes(bytes);
+    if (observed !== profile.result_contract_sha256) {
+        throw new Error(`profile result contract drifted: expected ${profile.result_contract_sha256}, observed ${observed}`);
+    }
+    const contract = parsePositiveResultContract(JSON.parse(bytes.toString("utf8")));
+    if (contentDigest(contract) !== observed) {
+        throw new Error("profile result contract file is not exact canonical Canopus JSON");
+    }
+    if (contract.target !== profile.target) {
+        throw new Error("profile and positive result contract target disagree");
+    }
+    return contract;
+}
+export async function packagedProfileResource(relative, label) {
+    const root = await realpath(productPackageRoot());
+    const file = await realpath(path.resolve(root, relative));
+    const fromRoot = path.relative(root, file);
+    if (fromRoot === "" || fromRoot === ".." || fromRoot.startsWith(`..${path.sep}`)) {
+        throw new Error(`${label} escapes the Canopus package`);
+    }
+    return file;
+}
+export async function loadProfileDraft(profile) {
+    const file = await packagedProfileResource(profile.draft, "profile draft");
+    const bytes = await readBoundedRegularFile(file, 1024 * 1024);
+    if (sha256Bytes(bytes) !== profile.draft_sha256)
+        throw new Error("profile draft root drifted");
+    const draft = objectAt(JSON.parse(bytes.toString("utf8")), "profile draft");
+    const assertions = [
+        [
+            sha256Bytes(Buffer.from(stringAt(draft.objective, "profile draft.objective", { min: 1, max: 8192 }))),
+            profile.objective_sha256,
+            "objective",
+        ],
+        [
+            sha256Bytes(Buffer.from(stringAt(draft.completion_condition, "profile draft.completion_condition", { min: 1, max: 8192 }))),
+            profile.completion_condition_sha256,
+            "completion condition",
+        ],
+        [contentDigest(draft.allowed_paths), profile.allowed_artifacts_sha256, "allowed artifacts"],
+        [contentDigest(draft.budgets), profile.budgets_sha256, "budgets"],
+        [
+            contentDigest(objectAt(draft.verifier, "profile draft.verifier").argv),
+            profile.replay_argv_sha256,
+            "replay argv",
+        ],
+    ];
+    for (const [observed, expected, label] of assertions) {
+        if (observed !== expected) {
+            throw new Error(`profile ${label} drifted from its frozen mission draft`);
+        }
+    }
+    return draft;
+}
+export async function stageProfileCapsule(options) {
+    const packaged = await packagedProfileResource(options.profile.capsule_binary, "profile capsule binary");
+    await access(packaged, constants.R_OK);
+    const packagedDigest = sha256Bytes(await readBoundedRegularFile(packaged, 268_435_456));
+    if (packagedDigest !== options.profile.capsule_sha256) {
+        throw new Error(`packaged capsule drifted: expected ${options.profile.capsule_sha256}, observed ${packagedDigest}`);
+    }
+    const capsule = path.join(options.stagingRoot, "capsule", "verifier");
+    await mkdir(path.dirname(capsule), { recursive: true, mode: 0o700 });
+    await copyFile(packaged, capsule, constants.COPYFILE_EXCL);
+    await chmod(capsule, 0o555);
+    const digest = sha256Bytes(await readBoundedRegularFile(capsule, 268_435_456));
+    if (digest !== options.profile.capsule_sha256) {
+        throw new Error(`staged capsule drifted: expected ${options.profile.capsule_sha256}, observed ${digest}`);
+    }
+    return { capsule, source: "packaged" };
+}
+export async function packagedWorkerProfile(profile) {
+    const file = await packagedProfileResource(profile.permission_profile, "worker permission profile");
+    const digest = sha256Bytes(await readBoundedRegularFile(file, 8 * 1024 * 1024));
+    if (digest !== profile.permission_profile_sha256) {
+        throw new Error("packaged worker permission profile drifted");
+    }
+    return file;
+}

package/dist/src/product/replay.d.ts

@@ -0,0 +1,10 @@
+export declare function replayProduct(runFile: string, dockerBinary?: string): Promise<{
+    schema: "canopus.replay.v1";
+    ok: true;
+    run_id: string;
+    mission_root: string;
+    verifier_status: "passed" | "failed" | "error";
+    stdout_digest: string;
+    stderr_digest: string;
+    matched: true;
+}>;

package/dist/src/product/replay.js

@@ -0,0 +1,71 @@
+import { mkdtemp, realpath, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { BudgetTracker } from "../budget/enforce.js";
+import { parseMission } from "../contracts/mission.js";
+import { validateMissionBundle } from "../mission/prepare.js";
+import { parseDiagnosticRunRecord } from "../projection/diagnostic.js";
+import { parseRunRecord } from "../projection/run.js";
+import { contentDigest } from "../util/canonical.js";
+import { readBoundedRegularFile } from "../util/files.js";
+import { runVerifier } from "../verifier/run.js";
+import { cleanupWorkspace, prepareWorkspace } from "../workspace/prepare.js";
+export async function replayProduct(runFile, dockerBinary = "docker") {
+    const absoluteRun = await realpath(runFile);
+    const runRoot = path.dirname(absoluteRun);
+    const raw = JSON.parse((await readBoundedRegularFile(absoluteRun, 8 * 1024 * 1024)).toString("utf8"));
+    const schema = typeof raw === "object" && raw !== null && !Array.isArray(raw)
+        ? raw.schema
+        : undefined;
+    const record = schema === "canopus.diagnostic-run.v1"
+        ? parseDiagnosticRunRecord(raw)
+        : parseRunRecord(raw);
+    const bundleRoot = await realpath(path.join(runRoot, "..", "mission"));
+    const mission = parseMission(JSON.parse((await readBoundedRegularFile(path.join(bundleRoot, "mission.json"), 8 * 1024 * 1024)).toString("utf8")));
+    if (mission.schema !== "canopus.mission.v1")
+        throw new Error("product replay requires Mission v1");
+    await validateMissionBundle(mission, bundleRoot);
+    if (contentDigest(mission) !== record.mission.digest)
+        throw new Error("run and mission roots disagree");
+    const artifacts = record.candidate.artifacts.map((artifact) => ({
+        artifact,
+        frozenPath: path.join(runRoot, "artifacts", artifact.digest.slice("sha256:".length)),
+    }));
+    const replayRoot = await mkdtemp(path.join(os.tmpdir(), "canopus-replay-root-"));
+    await rm(replayRoot, { recursive: true, force: true });
+    const source = path.join(runRoot, "input");
+    const paths = await prepareWorkspace({
+        sourceRepo: source,
+        runRoot: replayRoot,
+        gitCommit: mission.roots.git_commit,
+        gitTree: mission.roots.git_tree,
+    });
+    try {
+        const verifier = await runVerifier({
+            mission,
+            paths,
+            artifacts,
+            budget: new BudgetTracker(mission.budgets),
+            bundleRoot,
+            dockerBinary,
+        });
+        if (verifier.status !== record.verifier.status ||
+            verifier.record.stdout_digest !== record.verifier.record.stdout_digest ||
+            verifier.record.stderr_digest !== record.verifier.record.stderr_digest) {
+            throw new Error("verifier replay does not match the frozen run record");
+        }
+        return {
+            schema: "canopus.replay.v1",
+            ok: true,
+            run_id: record.run_id,
+            mission_root: record.mission.digest,
+            verifier_status: verifier.status,
+            stdout_digest: verifier.record.stdout_digest,
+            stderr_digest: verifier.record.stderr_digest,
+            matched: true,
+        };
+    }
+    finally {
+        await cleanupWorkspace(paths);
+    }
+}

package/dist/src/product/run.d.ts

@@ -0,0 +1,31 @@
+import { type CanopusDiagnosticRunResult, type CanopusRunResult } from "../run.js";
+import { type CommandRunner } from "../util/command.js";
+import { type ProductDoctorResult } from "./doctor.js";
+export interface ProductRunResult {
+    run: CanopusRunResult | CanopusDiagnosticRunResult;
+    doctor: ProductDoctorResult;
+    output_root: string;
+    bundle_root: string;
+    evidence_manifest: string;
+    evidence_root: string;
+    source_publication: {
+        state: "committed_local";
+        commit: string;
+        tree: string;
+    } | {
+        state: "unchanged_no_land";
+        commit: string;
+        tree: string;
+    };
+}
+export declare function defaultProductOutput(frontier: string): string;
+export declare function assertToolUsingMissionPlatform(platform?: NodeJS.Platform): void;
+export declare function runProduct(options: {
+    frontier: string;
+    profileName?: string;
+    requestedTarget?: string;
+    outputRoot?: string;
+    codexHome?: string;
+    noLand?: boolean;
+    runner?: CommandRunner;
+}): Promise<ProductRunResult>;

package/dist/src/product/run.js

@@ -0,0 +1,264 @@
+import { lstat, mkdir, realpath, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CodexToolsNativeEngine } from "../engines/codex-tools-native.js";
+import { prepareMission } from "../mission/prepare.js";
+import { runCanopus, } from "../run.js";
+import { canonicalJson, contentDigest, sha256Bytes } from "../util/canonical.js";
+import { isolatedEnvironment, runCommand } from "../util/command.js";
+import { readBoundedRegularFile } from "../util/files.js";
+import { VelaClient } from "../vela/cli.js";
+import { doctorProduct } from "./doctor.js";
+import { loadProfileDraft, loadProfileResultContract, packagedWorkerProfile, stageProfileCapsule, } from "./profile.js";
+import { retainWithdrawalCapability } from "../capability/withdrawal.js";
+function packageFile(relative) {
+    return fileURLToPath(new URL(`../../../${relative}`, import.meta.url));
+}
+async function assertFreshOutput(outputRoot, sourceRoot) {
+    const output = path.resolve(outputRoot);
+    const cloudBackedRoots = [
+        path.join(os.homedir(), "Desktop"),
+        path.join(os.homedir(), "Library", "Mobile Documents"),
+        path.join(os.homedir(), "Library", "CloudStorage"),
+    ];
+    if (cloudBackedRoots.some((root) => output === root || output.startsWith(`${root}${path.sep}`))) {
+        throw new Error("Canopus output must not use a cloud-synced path because Docker verifier bind mounts can stall; use the default ~/.canopus store or another local directory");
+    }
+    const relative = path.relative(sourceRoot, output);
+    if (relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..")) {
+        throw new Error("Canopus output must be outside the source frontier");
+    }
+    try {
+        await lstat(output);
+        throw new Error("Canopus output root already exists");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await mkdir(output, { recursive: true, mode: 0o700 });
+}
+async function gitText(options) {
+    const result = await options.runner({
+        argv: ["git", ...options.argv],
+        cwd: options.cwd,
+        env: isolatedEnvironment(options.home),
+        timeoutMs: 120_000,
+        maxOutputBytes: 8 * 1024 * 1024,
+    });
+    if (result.exitCode !== 0 || result.stderr.length !== 0) {
+        throw new Error(`git ${options.argv.join(" ")} failed: stdout_sha256=${sha256Bytes(result.stdout)}; ` +
+            `stderr_sha256=${sha256Bytes(result.stderr)}`);
+    }
+    return result.stdout.toString("utf8").trim();
+}
+async function publishVerifiedLanding(options) {
+    const [head, status] = await Promise.all([
+        gitText({ argv: ["rev-parse", "--verify", "HEAD^{commit}"], cwd: options.source, home: options.home, runner: options.runner }),
+        gitText({ argv: ["status", "--porcelain=v1", "--untracked-files=all"], cwd: options.source, home: options.home, runner: options.runner }),
+    ]);
+    if (head !== options.expectedStart || status !== "") {
+        throw new Error("source frontier changed while the bounded run was executing");
+    }
+    const landingHead = await gitText({
+        argv: ["rev-parse", "--verify", "canopus-landing^{commit}"],
+        cwd: options.landing,
+        home: options.home,
+        runner: options.runner,
+    });
+    if (landingHead !== options.expectedFinal)
+        throw new Error("landing clone final commit drifted");
+    await gitText({
+        argv: ["fetch", "--quiet", "--no-tags", options.landing, "canopus-landing"],
+        cwd: options.source,
+        home: options.home,
+        runner: options.runner,
+    });
+    await gitText({
+        argv: ["merge", "--ff-only", "--no-edit", "FETCH_HEAD"],
+        cwd: options.source,
+        home: options.home,
+        runner: options.runner,
+    });
+    const [commit, tree, finalStatus] = await Promise.all([
+        gitText({ argv: ["rev-parse", "--verify", "HEAD^{commit}"], cwd: options.source, home: options.home, runner: options.runner }),
+        gitText({ argv: ["rev-parse", "--verify", "HEAD^{tree}"], cwd: options.source, home: options.home, runner: options.runner }),
+        gitText({ argv: ["status", "--porcelain=v1", "--untracked-files=all"], cwd: options.source, home: options.home, runner: options.runner }),
+    ]);
+    if (commit !== options.expectedFinal || tree !== options.expectedTree || finalStatus !== "") {
+        throw new Error("source publication did not reproduce the verified landing roots");
+    }
+    return { state: "committed_local", commit, tree };
+}
+async function writeEvidenceManifest(run, missionDigest) {
+    const root = run.paths.root;
+    const files = {
+        activity: "activity.jsonl",
+        transcript: "worker-final.json",
+        tool_trace: "worker-events.jsonl",
+        worker_stderr: "worker-stderr.bin",
+        engine_result: "engine-result.json",
+        candidate: "candidate.json",
+        run: "run.json",
+    };
+    const digests = {};
+    for (const [name, relative] of Object.entries(files)) {
+        digests[name] = sha256Bytes(await readBoundedRegularFile(path.join(root, relative), 64 * 1024 * 1024));
+    }
+    const manifest = {
+        schema: "canopus.run-evidence.v1",
+        authority: "non_authoritative",
+        mission_root: missionDigest,
+        run_id: run.record.run_id,
+        target: run.record.mission.target,
+        files: digests,
+        artifact_roots: run.record.candidate.artifacts.map((artifact) => artifact.digest).sort(),
+        verifier_root: contentDigest(run.record.verifier),
+        receipt_root: run.record.landing?.receipt_root ?? null,
+        final_roots: "final_roots" in run.record
+            ? run.record.final_roots
+            : run.record.mission.starting_roots,
+    };
+    const file = path.join(root, "evidence-manifest.json");
+    await writeFile(file, canonicalJson(manifest), { flag: "wx", mode: 0o600 });
+    return { file, root: contentDigest(manifest) };
+}
+export function defaultProductOutput(frontier) {
+    const stamp = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+    return path.join(os.homedir(), ".canopus", "runs", path.basename(path.resolve(frontier)), stamp);
+}
+export function assertToolUsingMissionPlatform(platform = process.platform) {
+    if (platform === "win32") {
+        throw new Error("tool-using missions do not run in native Windows; open WSL2, enter the frontier through its Linux path, and rerun the same canopus command there");
+    }
+    if (platform !== "darwin" && platform !== "linux") {
+        throw new Error(`tool-using missions are unsupported on ${platform}; supported worker hosts are macOS and Linux/WSL2`);
+    }
+}
+export async function runProduct(options) {
+    // Refuse unsupported custody before creating an output directory or probing
+    // credentials. Native Windows retains doctor/inspect/replay only.
+    assertToolUsingMissionPlatform();
+    const runner = options.runner ?? runCommand;
+    const source = await realpath(options.frontier);
+    const outputRoot = path.resolve(options.outputRoot ?? defaultProductOutput(source));
+    await assertFreshOutput(outputRoot, source);
+    const controlHome = path.join(outputRoot, "control-home");
+    await mkdir(controlHome, { mode: 0o700 });
+    try {
+        const diagnosis = await doctorProduct({
+            frontier: source,
+            ...(options.profileName === undefined ? {} : { profileName: options.profileName }),
+            ...(options.requestedTarget === undefined ? {} : { requestedTarget: options.requestedTarget }),
+            runner,
+        });
+        const codexRuntime = diagnosis.public.runtimes.codex;
+        const dockerRuntime = diagnosis.public.runtimes.docker;
+        if (!diagnosis.public.worker.mission_ready || codexRuntime === null || dockerRuntime === null) {
+            throw new Error(diagnosis.public.next_action);
+        }
+        const staging = path.join(outputRoot, ".profile-staging");
+        await mkdir(staging, { mode: 0o700 });
+        await stageProfileCapsule({
+            profile: diagnosis.profile,
+            stagingRoot: staging,
+        });
+        const bundleRoot = path.join(outputRoot, "mission");
+        const draft = await loadProfileDraft(diagnosis.profile);
+        const resultContract = await loadProfileResultContract(diagnosis.profile);
+        const prepared = await prepareMission({
+            draft: options.requestedTarget === undefined
+                ? draft
+                : { ...draft, target: options.requestedTarget },
+            draftRoot: staging,
+            sourceRepo: source,
+            outputRoot: bundleRoot,
+            velaBinary: diagnosis.public.runtimes.vela.binary,
+            codexBinary: codexRuntime.binary,
+            dockerBinary: dockerRuntime.binary,
+            verifierImage: diagnosis.profile.verifier_image,
+            verifierPlatform: diagnosis.profile.verifier_platform,
+            outputSchema: packageFile("schemas/engine-output.v0.json"),
+            permissionProfile: await packagedWorkerProfile(diagnosis.profile),
+            targetPacket: {
+                target: diagnosis.profile.target,
+                schema: diagnosis.profile.target_packet_schema,
+            },
+            landing: diagnosis.profile.landing,
+            profileName: diagnosis.profile.name,
+            profileRoot: diagnosis.profile.profile_sha256,
+            ...(resultContract === undefined
+                ? {}
+                : {
+                    resultContract,
+                }),
+            runner,
+        });
+        await rm(staging, { recursive: true, force: true });
+        const runRoot = path.join(outputRoot, "run");
+        const vela = new VelaClient({
+            binary: diagnosis.public.runtimes.vela.binary,
+            expectedVersion: prepared.mission.vela_version,
+            expectedSha256: prepared.mission.vela_sha256,
+            home: path.join(runRoot, "vela-home"),
+            runner,
+        });
+        const engine = new CodexToolsNativeEngine({
+            binary: codexRuntime.binary,
+            authHome: path.resolve(options.codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex")),
+            outputSchema: path.join(bundleRoot, "contract", "engine-output.v0.json"),
+            permissionProfile: path.join(bundleRoot, prepared.mission.worker.permission_profile_path),
+            runner,
+        });
+        const commonRun = {
+            mission: prepared.mission,
+            sourceRepo: source,
+            runRoot,
+            vela,
+            engine,
+            bundleRoot,
+            dockerBinary: dockerRuntime.binary,
+            verifierRunner: runner,
+            retainWithdrawalCapability: async (context) => {
+                await retainWithdrawalCapability({
+                    ...context,
+                    velaBinary: diagnosis.public.runtimes.vela.binary,
+                });
+            },
+        };
+        const run = options.noLand === true
+            ? await runCanopus({ ...commonRun, noLand: true })
+            : await runCanopus(commonRun);
+        const evidence = await writeEvidenceManifest(run, contentDigest(prepared.mission));
+        const publication = options.noLand === true
+            ? {
+                state: "unchanged_no_land",
+                commit: prepared.mission.roots.git_commit,
+                tree: prepared.mission.roots.git_tree,
+            }
+            : await publishVerifiedLanding({
+                source,
+                landing: run.paths.landing,
+                expectedStart: prepared.mission.roots.git_commit,
+                expectedFinal: run.record.final_roots.git_commit,
+                expectedTree: run.record.final_roots.git_tree,
+                home: controlHome,
+                runner,
+            });
+        await rm(controlHome, { recursive: true, force: true });
+        return {
+            run,
+            doctor: diagnosis.public,
+            output_root: outputRoot,
+            bundle_root: bundleRoot,
+            evidence_manifest: evidence.file,
+            evidence_root: evidence.root,
+            source_publication: publication,
+        };
+    }
+    catch (error) {
+        // Preserve bounded failure evidence and the exact diagnostic inputs.
+        throw error;
+    }
+}

package/dist/src/product/runtime.d.ts

@@ -0,0 +1,18 @@
+import { type CommandRunner } from "../util/command.js";
+export interface RuntimeIdentity {
+    binary: string;
+    version: string;
+    sha256: string;
+}
+export declare function executableNames(name: string, platform: NodeJS.Platform, pathExt: string): string[];
+export declare function findExecutable(name: string, searchPath?: string, options?: {
+    platform?: NodeJS.Platform;
+    pathExt?: string;
+}): Promise<string>;
+export declare function runtimeIdentity(options: {
+    name: string;
+    versionArgs?: readonly string[];
+    cwd: string;
+    home: string;
+    runner?: CommandRunner;
+}): Promise<RuntimeIdentity>;