@vela-science/canopus 0.4.0-rc.1

package/dist/src/vela/types.d.ts

@@ -0,0 +1,27 @@
+import type { LandRoute, MissionRoots } from "../contracts/mission.js";
+export interface VelaInspection {
+    version: string;
+    roots: MissionRoots;
+    check: Record<string, unknown>;
+    proof: Record<string, unknown>;
+}
+export interface VelaCommandResponse {
+    ok: true;
+    value: Record<string, unknown>;
+}
+export interface LandResult {
+    operationId: string;
+    receiptRoot: string;
+    recordId: string;
+    proposalId: string;
+    findingId: string;
+    route: LandRoute | "exact_retry";
+    originalRoute: LandRoute | null;
+    rawRoute: string;
+    detail: string;
+    acceptedEventCountBefore: number | null;
+    acceptedEventCountAfter: number | null;
+    acceptedEventDelta: number | null;
+    publication: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}

package/dist/src/vela/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,24 @@
+import type { TestRecord } from "../contracts/candidate.js";
+import type { Mission } from "../contracts/mission.js";
+import type { BudgetTracker } from "../budget/enforce.js";
+import { type FrozenArtifactLocation } from "../artifact/freeze.js";
+import { type CommandRunner } from "../util/command.js";
+import type { WorkspacePaths } from "../workspace/prepare.js";
+export declare class VerifierError extends Error {
+    constructor(message: string);
+}
+export interface VerifierOutcome {
+    status: "passed" | "failed" | "error";
+    record: TestRecord;
+    sandbox: "macos_sandbox" | "container_network_denied";
+    error?: string;
+}
+export declare function runVerifier(options: {
+    mission: Mission;
+    paths: WorkspacePaths;
+    artifacts: readonly FrozenArtifactLocation[];
+    budget: BudgetTracker;
+    bundleRoot?: string;
+    dockerBinary?: string;
+    runner?: CommandRunner;
+}): Promise<VerifierOutcome>;

package/dist/src/verifier/run.js

@@ -0,0 +1,315 @@
+import { constants } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import path from "node:path";
+import { relativePathAt } from "../contracts/validation.js";
+import { verifyFrozenArtifact, } from "../artifact/freeze.js";
+import { CommandFailure, isolatedEnvironment, runCommand, } from "../util/command.js";
+import { sha256Bytes } from "../util/canonical.js";
+import { readBoundedRegularFile } from "../util/files.js";
+export class VerifierError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VerifierError";
+    }
+}
+function safeDockerMount(value, label) {
+    const resolved = path.resolve(value);
+    if (resolved.includes(",") || resolved.includes("\n") || resolved.includes("\0")) {
+        throw new VerifierError(`${label} cannot be represented as a Docker mount`);
+    }
+    return resolved;
+}
+function dockerBind(source, target) {
+    return `type=bind,src=${safeDockerMount(source, target)},dst=${target},readonly`;
+}
+function sbpl(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+function macSandboxProfile(readRoots, executable) {
+    const lines = [
+        "(version 1)",
+        "(deny default)",
+        '(import "dyld-support.sb")',
+        "(deny file-link file-clone)",
+        "(allow process-info* (target same-sandbox))",
+        "(allow signal (target same-sandbox))",
+        '(allow sysctl-read (sysctl-name "hw.activecpu") (sysctl-name "hw.logicalcpu") (sysctl-name "hw.ncpu") (sysctl-name "hw.pagesize") (sysctl-name "kern.argmax") (sysctl-name "kern.osproductversion") (sysctl-name "kern.osrelease") (sysctl-name "kern.ostype"))',
+        '(allow mach-lookup (global-name "com.apple.system.opendirectoryd.libinfo"))',
+        `(allow process-exec (literal "${sbpl(executable)}"))`,
+        `(allow file-map-executable (literal "${sbpl(executable)}"))`,
+        '(allow file-read* (subpath "/Library/Apple") (subpath "/System") (subpath "/usr/lib") (subpath "/usr/share") (subpath "/private/var/db/timezone") (literal "/dev/null") (literal "/dev/urandom"))',
+    ];
+    for (const root of [...readRoots, executable]) {
+        const operation = root === executable ? "literal" : "subpath";
+        lines.push(`(allow file-read* (${operation} "${sbpl(root)}"))`);
+        lines.push(`(allow file-read-metadata (literal "${sbpl(root)}"))`);
+        for (let parent = path.dirname(root);; parent = path.dirname(parent)) {
+            lines.push(`(allow file-read-metadata (literal "${sbpl(parent)}"))`);
+            if (parent === "/")
+                break;
+        }
+    }
+    lines.push('(allow file-write* (literal "/dev/null"))', "(deny network*)");
+    return lines.join(" ");
+}
+function replaceArg(value, paths, artifacts) {
+    if (value === "{input}")
+        return paths.input;
+    const match = /^\{artifact:(.+)\}$/u.exec(value);
+    if (match === null)
+        return value;
+    const requested = relativePathAt(match[1], "verifier artifact placeholder");
+    const found = artifacts.find((entry) => entry.artifact.path === requested);
+    if (found === undefined)
+        throw new VerifierError(`verifier requested undeclared artifact ${requested}`);
+    return found.frozenPath;
+}
+function replaceContainerArg(value, artifacts) {
+    if (value === "{input}")
+        return "/input";
+    const match = /^\{artifact:(.+)\}$/u.exec(value);
+    if (match === null)
+        return value;
+    const requested = relativePathAt(match[1], "verifier artifact placeholder");
+    const index = artifacts.findIndex((entry) => entry.artifact.path === requested);
+    if (index < 0)
+        throw new VerifierError(`verifier requested undeclared artifact ${requested}`);
+    return `/artifacts/${index}`;
+}
+async function runContainerVerifier(options) {
+    const declaredCapsule = relativePathAt(options.mission.verifier.capsule_path, "mission.verifier.capsule_path");
+    const bundleRoot = await realpath(options.bundleRoot);
+    const capsule = await realpath(path.resolve(bundleRoot, declaredCapsule));
+    if (!capsule.startsWith(`${bundleRoot}${path.sep}`)) {
+        throw new VerifierError("verifier capsule escaped the mission bundle");
+    }
+    await access(capsule, constants.X_OK);
+    const capsuleBytes = await readBoundedRegularFile(capsule, 268_435_456);
+    const capsuleDigest = sha256Bytes(capsuleBytes);
+    if (capsuleDigest !== options.mission.verifier.capsule_sha256 ||
+        capsuleDigest !== options.mission.verifier.executable_sha256) {
+        throw new VerifierError("verifier capsule digest does not match the mission");
+    }
+    for (const artifact of options.artifacts) {
+        await verifyFrozenArtifact(artifact, options.mission.budgets.max_artifact_bytes);
+    }
+    options.budget.beginProcess();
+    const inspect = await options.runner({
+        argv: [
+            options.dockerBinary,
+            "image",
+            "inspect",
+            "--format={{.Id}}",
+            options.mission.verifier.image,
+        ],
+        cwd: options.paths.verifierHome,
+        env: isolatedEnvironment(options.paths.verifierHome),
+        timeoutMs: Math.min(30_000, options.budget.remainingTimeMs()),
+        maxOutputBytes: 4096,
+    });
+    if (inspect.exitCode !== 0 ||
+        inspect.stderr.length !== 0 ||
+        inspect.stdout.toString("utf8").trim() !== options.mission.verifier.image) {
+        throw new VerifierError("pinned verifier image is unavailable or changed");
+    }
+    options.budget.beginProcess();
+    const logicalArgv = options.mission.verifier.argv.map((item, index) => index === 0 ? "/capsule/verifier" : replaceContainerArg(item, options.artifacts));
+    const mounts = [
+        "--mount", dockerBind(options.paths.input, "/input"),
+        "--mount", dockerBind(capsule, "/capsule/verifier"),
+        ...options.artifacts.flatMap((entry, index) => [
+            "--mount",
+            dockerBind(entry.frozenPath, `/artifacts/${index}`),
+        ]),
+    ];
+    const argv = [
+        options.dockerBinary,
+        "run",
+        ...(options.mission.verifier.platform === undefined
+            ? []
+            : ["--platform", options.mission.verifier.platform]),
+        "--rm",
+        "--init",
+        "--read-only",
+        "--network=none",
+        "--cap-drop=ALL",
+        "--security-opt=no-new-privileges",
+        "--memory=1024m",
+        "--cpus=1",
+        "--pids-limit=64",
+        "--env",
+        "HOME=/nonexistent",
+        "--env",
+        "PYTHONDONTWRITEBYTECODE=1",
+        "--workdir",
+        `/input/${relativePathAt(options.mission.verifier.cwd, "mission.verifier.cwd")}`,
+        ...mounts,
+        options.mission.verifier.image,
+        ...logicalArgv,
+    ];
+    const started = performance.now();
+    try {
+        const result = await options.runner({
+            argv,
+            cwd: options.paths.verifierHome,
+            env: isolatedEnvironment(options.paths.verifierHome),
+            timeoutMs: Math.min(options.mission.verifier.timeout_ms, options.budget.remainingTimeMs()),
+            maxOutputBytes: Math.min(options.mission.verifier.max_output_bytes, options.budget.remainingOutputBytes()),
+        });
+        options.budget.addOutput(result.stdout.length + result.stderr.length);
+        for (const artifact of options.artifacts) {
+            await verifyFrozenArtifact(artifact, options.mission.budgets.max_artifact_bytes);
+        }
+        return {
+            status: result.exitCode === 0 ? "passed" : "failed",
+            record: {
+                argv: logicalArgv,
+                executable_digest: capsuleDigest,
+                exit_code: result.exitCode,
+                stdout_digest: sha256Bytes(result.stdout),
+                stderr_digest: sha256Bytes(result.stderr),
+                duration_ms: result.durationMs,
+            },
+            sandbox: "container_network_denied",
+        };
+    }
+    catch (error) {
+        for (const artifact of options.artifacts) {
+            await verifyFrozenArtifact(artifact, options.mission.budgets.max_artifact_bytes);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            status: "error",
+            record: {
+                argv: logicalArgv,
+                executable_digest: capsuleDigest,
+                exit_code: -1,
+                stdout_digest: sha256Bytes(""),
+                stderr_digest: sha256Bytes(message),
+                duration_ms: Math.max(0, Math.round(performance.now() - started)),
+            },
+            sandbox: "container_network_denied",
+            error: error instanceof CommandFailure ? `${error.kind}:${message}` : message,
+        };
+    }
+}
+export async function runVerifier(options) {
+    const runner = options.runner ?? runCommand;
+    if (options.mission.schema === "canopus.mission.v1") {
+        if (options.bundleRoot === undefined) {
+            throw new VerifierError("mission v1 requires its portable bundle root");
+        }
+        return await runContainerVerifier({
+            mission: options.mission,
+            paths: options.paths,
+            artifacts: options.artifacts,
+            budget: options.budget,
+            bundleRoot: options.bundleRoot,
+            dockerBinary: options.dockerBinary ?? "docker",
+            runner,
+        });
+    }
+    if (process.platform !== "darwin") {
+        throw new VerifierError("v0 requires the macOS sandbox backend; no permissive fallback exists");
+    }
+    const declaredExecutable = options.mission.verifier.argv[0];
+    if (declaredExecutable === undefined) {
+        throw new VerifierError("mission has no verifier executable");
+    }
+    let executable;
+    try {
+        const relativeExecutable = relativePathAt(declaredExecutable, "mission.verifier.argv[0]");
+        executable = await realpath(path.resolve(options.paths.input, relativeExecutable));
+        const input = await realpath(options.paths.input);
+        if (!executable.startsWith(`${input}${path.sep}`)) {
+            throw new Error("verifier capsule escaped the exact input checkout");
+        }
+        await access(executable, constants.X_OK);
+    }
+    catch {
+        throw new VerifierError("verifier executable is unavailable");
+    }
+    const executableBytes = await readBoundedRegularFile(executable, 268_435_456);
+    const executableDigest = sha256Bytes(executableBytes);
+    if (executableDigest !== options.mission.verifier.executable_sha256) {
+        throw new VerifierError("verifier executable digest does not match the mission");
+    }
+    // macOS exposes its temporary directory through the lexical `/var` symlink
+    // while `realpath` returns `/private/var`. Seatbelt matches both stages of
+    // that traversal, so authorize the declared roots in both spellings. This is
+    // still the same three bounded trees; it does not widen the readable set.
+    const declaredReadRoots = [
+        options.paths.input,
+        options.paths.artifacts,
+        options.paths.verifierHome,
+    ].map((entry) => path.resolve(entry));
+    const readRoots = [
+        ...new Set([
+            ...declaredReadRoots,
+            ...(await Promise.all(declaredReadRoots.map((entry) => realpath(entry)))),
+        ]),
+    ];
+    const cwdRelative = relativePathAt(options.mission.verifier.cwd, "mission.verifier.cwd");
+    const cwd = path.resolve(options.paths.input, cwdRelative);
+    if (!cwd.startsWith(`${path.resolve(options.paths.input)}${path.sep}`)) {
+        throw new VerifierError("verifier cwd escapes the exact input checkout");
+    }
+    for (const artifact of options.artifacts) {
+        await verifyFrozenArtifact(artifact, options.mission.budgets.max_artifact_bytes);
+    }
+    options.budget.beginProcess();
+    const argv = options.mission.verifier.argv.map((item, index) => index === 0 ? executable :
+        replaceArg(item, options.paths, options.artifacts));
+    const sandboxed = [
+        "/usr/bin/sandbox-exec",
+        "-p",
+        macSandboxProfile(readRoots, executable),
+        "--",
+        ...argv,
+    ];
+    const started = performance.now();
+    try {
+        const result = await runner({
+            argv: sandboxed,
+            cwd,
+            env: isolatedEnvironment(options.paths.verifierHome),
+            timeoutMs: Math.min(options.mission.verifier.timeout_ms, options.budget.remainingTimeMs()),
+            maxOutputBytes: Math.min(options.mission.verifier.max_output_bytes, options.budget.remainingOutputBytes()),
+        });
+        options.budget.addOutput(result.stdout.length + result.stderr.length);
+        for (const artifact of options.artifacts) {
+            await verifyFrozenArtifact(artifact, options.mission.budgets.max_artifact_bytes);
+        }
+        return {
+            status: result.exitCode === 0 ? "passed" : "failed",
+            record: {
+                argv,
+                executable_digest: executableDigest,
+                exit_code: result.exitCode,
+                stdout_digest: sha256Bytes(result.stdout),
+                stderr_digest: sha256Bytes(result.stderr),
+                duration_ms: result.durationMs,
+            },
+            sandbox: "macos_sandbox",
+        };
+    }
+    catch (error) {
+        for (const artifact of options.artifacts) {
+            await verifyFrozenArtifact(artifact, options.mission.budgets.max_artifact_bytes);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            status: "error",
+            record: {
+                argv,
+                executable_digest: executableDigest,
+                exit_code: -1,
+                stdout_digest: sha256Bytes(""),
+                stderr_digest: sha256Bytes(message),
+                duration_ms: Math.max(0, Math.round(performance.now() - started)),
+            },
+            sandbox: "macos_sandbox",
+            error: error instanceof CommandFailure ? `${error.kind}:${message}` : message,
+        };
+    }
+}

package/dist/src/workspace/prepare.d.ts

@@ -0,0 +1,30 @@
+import { type CommandRunner } from "../util/command.js";
+export declare class WorkspaceError extends Error {
+    constructor(message: string);
+}
+export interface WorkspacePaths {
+    root: string;
+    input: string;
+    landing: string;
+    work: string;
+    output: string;
+    artifacts: string;
+    /** Empty, isolated HOME for the untrusted synthesis worker. */
+    home: string;
+    /** Control-plane HOME where Vela may mint an agent-only session key. */
+    velaHome: string;
+    /** Empty HOME visible to the sandboxed verifier. */
+    verifierHome: string;
+}
+export interface PrepareWorkspaceOptions {
+    sourceRepo: string;
+    runRoot: string;
+    gitCommit: string;
+    gitTree: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    maxEntries?: number;
+    runner?: CommandRunner;
+}
+export declare function prepareWorkspace(options: PrepareWorkspaceOptions): Promise<WorkspacePaths>;
+export declare function cleanupWorkspace(paths: WorkspacePaths): Promise<void>;

package/dist/src/workspace/prepare.js

@@ -0,0 +1,183 @@
+import { chmod, lstat, mkdir, readdir, realpath, rm, } from "node:fs/promises";
+import path from "node:path";
+import { GIT_OBJECT_RE } from "../contracts/validation.js";
+import { isolatedEnvironment, runCommand } from "../util/command.js";
+export class WorkspaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkspaceError";
+    }
+}
+function isBelow(child, parent) {
+    const relative = path.relative(parent, child);
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+async function assertFreshOutsideRoot(sourceRepo, runRoot) {
+    const source = await realpath(sourceRepo);
+    const target = path.resolve(runRoot);
+    const missing = [];
+    let existing = target;
+    while (true) {
+        try {
+            existing = await realpath(existing);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = path.dirname(existing);
+            if (parent === existing)
+                throw error;
+            missing.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+    const stableTarget = path.join(existing, ...missing);
+    if (stableTarget === source || isBelow(stableTarget, source) || isBelow(source, stableTarget)) {
+        throw new WorkspaceError("run root and source repository must not overlap");
+    }
+    try {
+        await lstat(stableTarget);
+        throw new WorkspaceError("run root already exists");
+    }
+    catch (error) {
+        if (error instanceof WorkspaceError)
+            throw error;
+        const code = error.code;
+        if (code !== "ENOENT")
+            throw error;
+    }
+    return stableTarget;
+}
+async function sealTree(root, maxEntries) {
+    let entries = 0;
+    const visit = async (current) => {
+        const stat = await lstat(current);
+        entries += 1;
+        if (entries > maxEntries) {
+            throw new WorkspaceError(`checkout exceeds ${maxEntries} filesystem entries`);
+        }
+        if (stat.isSymbolicLink()) {
+            throw new WorkspaceError(`checkout contains a symbolic link: ${path.relative(root, current)}`);
+        }
+        if (stat.isFile()) {
+            if (stat.nlink !== 1) {
+                throw new WorkspaceError(`checkout contains a multiply linked file: ${path.relative(root, current)}`);
+            }
+            await chmod(current, stat.mode & 0o111 ? 0o555 : 0o444);
+            return;
+        }
+        if (!stat.isDirectory()) {
+            throw new WorkspaceError(`checkout contains a non-regular entry: ${path.relative(root, current)}`);
+        }
+        const children = await readdir(current);
+        for (const child of children) {
+            await visit(path.join(current, child));
+        }
+        await chmod(current, 0o555);
+    };
+    await visit(root);
+}
+async function makeWritableTree(root) {
+    const stat = await lstat(root);
+    if (stat.isDirectory()) {
+        await chmod(root, 0o700);
+        for (const child of await readdir(root)) {
+            await makeWritableTree(path.join(root, child));
+        }
+    }
+    else if (!stat.isSymbolicLink()) {
+        await chmod(root, 0o600);
+    }
+}
+async function gitText(runner, argv, cwd, home, timeoutMs, maxOutputBytes) {
+    const result = await runner({
+        argv,
+        cwd,
+        env: isolatedEnvironment(home),
+        timeoutMs,
+        maxOutputBytes,
+    });
+    if (result.exitCode !== 0) {
+        throw new WorkspaceError(`${argv.join(" ")} exited ${result.exitCode}: ${result.stderr.toString("utf8")}`);
+    }
+    return result.stdout.toString("utf8").trim();
+}
+export async function prepareWorkspace(options) {
+    if (!GIT_OBJECT_RE.test(options.gitCommit) || !GIT_OBJECT_RE.test(options.gitTree)) {
+        throw new WorkspaceError("workspace requires full Git commit and tree object IDs");
+    }
+    const root = await assertFreshOutsideRoot(options.sourceRepo, options.runRoot);
+    const input = path.join(root, "input");
+    const landing = path.join(root, "landing");
+    const work = path.join(root, "work");
+    const output = path.join(root, "output");
+    const artifacts = path.join(root, "artifacts");
+    const home = path.join(root, "home");
+    const velaHome = path.join(root, "vela-home");
+    const verifierHome = path.join(root, "verifier-home");
+    const runner = options.runner ?? runCommand;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    const maxOutputBytes = options.maxOutputBytes ?? 8 * 1024 * 1024;
+    await mkdir(root, { mode: 0o700 });
+    await Promise.all([
+        mkdir(work, { mode: 0o700 }),
+        mkdir(output, { mode: 0o700 }),
+        mkdir(artifacts, { mode: 0o700 }),
+        mkdir(home, { mode: 0o700 }),
+        mkdir(velaHome, { mode: 0o700 }),
+        mkdir(verifierHome, { mode: 0o700 }),
+    ]);
+    try {
+        await gitText(runner, ["git", "clone", "--no-hardlinks", "--no-checkout", "--", await realpath(options.sourceRepo), input], root, home, timeoutMs, maxOutputBytes);
+        await gitText(runner, ["git", "clone", "--no-hardlinks", "--no-checkout", "--", await realpath(options.sourceRepo), landing], root, home, timeoutMs, maxOutputBytes);
+        await gitText(runner, ["git", "checkout", "--detach", options.gitCommit], input, home, timeoutMs, maxOutputBytes);
+        // Vela publishes exact scientific deltas to the current ref. Keep the
+        // immutable input detached, but give the isolated landing clone its own
+        // disposable local branch so publication never depends on caller state.
+        await gitText(runner, ["git", "checkout", "-B", "canopus-landing", options.gitCommit], landing, home, timeoutMs, maxOutputBytes);
+        const [commit, tree, status, landingCommit, landingTree, landingStatus] = await Promise.all([
+            gitText(runner, ["git", "rev-parse", "--verify", "HEAD^{commit}"], input, home, timeoutMs, maxOutputBytes),
+            gitText(runner, ["git", "rev-parse", "--verify", "HEAD^{tree}"], input, home, timeoutMs, maxOutputBytes),
+            gitText(runner, ["git", "status", "--porcelain=v1", "--untracked-files=all"], input, home, timeoutMs, maxOutputBytes),
+            gitText(runner, ["git", "rev-parse", "--verify", "HEAD^{commit}"], landing, home, timeoutMs, maxOutputBytes),
+            gitText(runner, ["git", "rev-parse", "--verify", "HEAD^{tree}"], landing, home, timeoutMs, maxOutputBytes),
+            gitText(runner, ["git", "status", "--porcelain=v1", "--untracked-files=all"], landing, home, timeoutMs, maxOutputBytes),
+        ]);
+        if (commit !== options.gitCommit ||
+            tree !== options.gitTree ||
+            landingCommit !== options.gitCommit ||
+            landingTree !== options.gitTree) {
+            throw new WorkspaceError(`checkout root mismatch: expected ${options.gitCommit}/${options.gitTree}, observed ${commit}/${tree} and ${landingCommit}/${landingTree}`);
+        }
+        if (status !== "" || landingStatus !== "") {
+            throw new WorkspaceError("exact checkout is unexpectedly dirty");
+        }
+        await sealTree(input, options.maxEntries ?? 200_000);
+        return { root, input, landing, work, output, artifacts, home, velaHome, verifierHome };
+    }
+    catch (error) {
+        await cleanupWorkspace({
+            root,
+            input,
+            landing,
+            work,
+            output,
+            artifacts,
+            home,
+            velaHome,
+            verifierHome,
+        });
+        throw error;
+    }
+}
+export async function cleanupWorkspace(paths) {
+    try {
+        await makeWritableTree(paths.root);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await rm(paths.root, { recursive: true, force: true });
+}

package/docs/MISSIONS.md

@@ -0,0 +1,78 @@
+# Mission roles
+
+Canopus Mission v0 runs one explicit role per mission. The role changes the worker
+instruction, not the trust boundary:
+
+- `producer` constructs the smallest candidate or preserves a null result;
+- `adversary` seeks a concrete counterexample or narrows the claim;
+- `verifier` checks correspondence between the candidate and declared tests,
+  while the separate frozen executable remains the mechanical verifier;
+- `fidelity` checks that prose claims do not outrun frozen artifacts and
+  verifier facts.
+
+A research loop may fan these into separate missions against the same exact
+accepted roots. Each result lands its own Receipt and route. A repair mission
+names an immutable parent candidate, but a substantive downstream mission may
+inherit only state that Vela reports as accepted. Defer, a verifier pass, or a
+Canopus candidate digest is not an inheritance edge.
+
+This deliberately avoids a workflow DSL, agent society, or second graph. Git
+stores the bytes, Vela stores authority and accepted lineage, and Canopus is
+replaceable orchestration over those primitives.
+
+## Mission v1
+
+Mission v1 keeps the same four roles and authority boundary while adding a
+tool-enabled local worker. `mission prepare` selects the first ranked attack,
+derives the clean Git and Vela roots, registers the complete pre-existing
+strict blocker set, and copies the exact packet, native permission profile,
+structured-output schema, and verifier capsule into a portable bundle. The
+Codex binary, model, verifier image, exact Linux verifier platform, resource
+ceilings, and every copied byte are hash-pinned. Historical Mission v1 records
+without a platform retain their old replay behavior; newly prepared missions
+always bind one. Product-prepared missions also retain the selected profile's
+exact name and full root, including Defer-only runs; older Mission v1 records
+without that non-protocol field replay unchanged.
+
+The producer runs through the native Codex CLI under a default-deny platform
+profile: Seatbelt on macOS and Codex's Bubblewrap sandbox on Linux or WSL2. The
+writable workspace contains only the exact target packet; the full source
+checkout, Vela home, host home, and authentication file remain outside
+command-readable paths. Provider transport is available only to the Codex
+process. Shell commands have no network access.
+
+Worker status is producer completion, not verifier or scientific standing.
+`success` means the worker supplied every artifact byte required by the output
+contract and explicitly leaves verification pending. Only such a draft proceeds
+to the separate network-denied verifier. `null` means the bounded work produced
+no candidate; `failed` means the worker could not produce a contract-complete
+candidate or observed disqualifying evidence. Both are preserved in
+`engine-result.json` and stop before verification or Receipt landing. After a
+verifier pass, Canopus publishes exactly the frozen artifact sources in one
+unsigned non-authoritative Git commit and then calls `vela land`.
+The frozen verifier manifest reports the actual Docker boundary and bound Linux
+architecture; the older macOS-Seatbelt manifest remains only for Mission v0.
+`canopus inspect latest` includes safely stopped runs as well as completed runs;
+its failure projection distinguishes no landing attempt from an observed Vela
+effect that requires the retained landing-recovery evidence. Withdrawal's
+`latest` selector remains limited to completed, proposal-bearing runs.
+
+Defer-only Mission v1 bundles preserve their original zero-delta behavior. A
+profile may register `permit` only when it also freezes one closed positive
+`canopus.result-contract.v1` and a `vela.execution-binding.v1` over the full
+packet, profile, verifier-capsule, and result-contract roots. The worker result
+must be an exact computational success, the verifier must pass, its claim is
+replaced by the contract's exact canonical claim, and every required artifact
+kind must be present before Canopus authors the binding through Vela's Receipt
+builder. Any mismatch stops before landing. Vela alone evaluates the
+already-signed policy; Canopus then requires the registered route and
+accepted-event delta and reproduces the retained Receipt from a clean clone.
+Canopus does not treat its own Receipt verifier row as load-bearing Vela
+assurance.
+
+For exact construction profiles, prefer Vela-native `vela-witness` JSON and a
+packaged `vela-verify` executable. This gives the isolated producer verifier,
+Vela policy derivation, strict replay, and third-party reproduction one shared
+pure verifier and claim-fidelity contract. A target-specific wrapper is kept
+only when Vela has no suitable verifier; it is not duplicated for presentation
+or convenience.