@vela-science/canopus 0.4.0-rc.1

package/dist/src/projection/run.js

@@ -0,0 +1,159 @@
+import { arrayAt, enumAt, exactKeys, gitObjectAt, integerAt, objectAt, relativePathAt, sha256At, stringAt, } from "../contracts/validation.js";
+export const RUN_RECORD_SCHEMA = "canopus.run.v0";
+export const RUN_PROJECTION_SCHEMA = "canopus.run-projection.v0";
+function literal(value, expected, at) {
+    if (value !== expected)
+        throw new Error(`${at} must be ${String(expected)}`);
+    return expected;
+}
+function rootsAt(value, at) {
+    const object = objectAt(value, at);
+    exactKeys(object, ["git_commit", "git_tree", "vela_event_log", "vela_snapshot"], [], at);
+    return {
+        git_commit: gitObjectAt(object.git_commit, `${at}.git_commit`),
+        git_tree: gitObjectAt(object.git_tree, `${at}.git_tree`),
+        vela_event_log: sha256At(object.vela_event_log, `${at}.vela_event_log`),
+        vela_snapshot: sha256At(object.vela_snapshot, `${at}.vela_snapshot`),
+    };
+}
+function nullableRoute(value, at) {
+    return value === null ? null : enumAt(value, at, ["permit", "defer"]);
+}
+function nullableCount(value, at) {
+    return value === null ? null : integerAt(value, at, 0, Number.MAX_SAFE_INTEGER);
+}
+export function parseRunRecord(value) {
+    const record = objectAt(value, "run");
+    exactKeys(record, [
+        "schema", "run_id", "status", "authority", "external_gate_credit", "mission",
+        "candidate", "verifier", "landing", "final_roots", "reproduction", "budget",
+    ], [], "run");
+    const mission = objectAt(record.mission, "run.mission");
+    exactKeys(mission, ["id", "target", "digest", "starting_roots"], [], "run.mission");
+    const candidate = objectAt(record.candidate, "run.candidate");
+    exactKeys(candidate, ["digest", "status", "claim", "artifacts", "caveats"], [], "run.candidate");
+    const verifier = objectAt(record.verifier, "run.verifier");
+    exactKeys(verifier, ["status", "sandbox", "record"], [], "run.verifier");
+    const testRecord = objectAt(verifier.record, "run.verifier.record");
+    exactKeys(testRecord, ["argv", "executable_digest", "exit_code", "stdout_digest", "stderr_digest", "duration_ms"], [], "run.verifier.record");
+    const landing = objectAt(record.landing, "run.landing");
+    exactKeys(landing, [
+        "operation_id", "receipt_root", "proposal_id", "route", "original_route",
+        "accepted_event_delta", "publication_state",
+    ], [], "run.landing");
+    const reproduction = objectAt(record.reproduction, "run.reproduction");
+    exactKeys(reproduction, ["matched", "roots", "verifier_status", "stdout_digest", "stderr_digest"], [], "run.reproduction");
+    const budget = objectAt(record.budget, "run.budget");
+    exactKeys(budget, [
+        "research_elapsed_ms", "research_processes", "research_output_bytes", "prompt_bytes",
+        "artifact_bytes", "attempts", "observed_tokens",
+    ], [], "run.budget");
+    return {
+        schema: literal(record.schema, RUN_RECORD_SCHEMA, "run.schema"),
+        run_id: stringAt(record.run_id, "run.run_id", { min: 5, max: 128 }),
+        status: literal(record.status, "completed", "run.status"),
+        authority: literal(record.authority, "non_authoritative", "run.authority"),
+        external_gate_credit: literal(record.external_gate_credit, false, "run.external_gate_credit"),
+        mission: {
+            id: stringAt(mission.id, "run.mission.id", { min: 1, max: 134 }),
+            target: stringAt(mission.target, "run.mission.target", { min: 1, max: 256 }),
+            digest: sha256At(mission.digest, "run.mission.digest"),
+            starting_roots: rootsAt(mission.starting_roots, "run.mission.starting_roots"),
+        },
+        candidate: {
+            digest: sha256At(candidate.digest, "run.candidate.digest"),
+            status: enumAt(candidate.status, "run.candidate.status", ["success", "null", "failed"]),
+            claim: stringAt(candidate.claim, "run.candidate.claim", { min: 1, max: 8192 }),
+            artifacts: arrayAt(candidate.artifacts, "run.candidate.artifacts", { max: 10 }, (item, at) => {
+                const artifact = objectAt(item, at);
+                exactKeys(artifact, ["path", "kind", "digest", "bytes"], [], at);
+                return {
+                    path: relativePathAt(artifact.path, `${at}.path`),
+                    kind: stringAt(artifact.kind, `${at}.kind`, { min: 1, max: 128 }),
+                    digest: sha256At(artifact.digest, `${at}.digest`),
+                    bytes: integerAt(artifact.bytes, `${at}.bytes`, 0, 1_073_741_824),
+                };
+            }),
+            caveats: arrayAt(candidate.caveats, "run.candidate.caveats", { max: 10 }, (item, at) => stringAt(item, at, { min: 1, max: 4096 })),
+        },
+        verifier: {
+            status: enumAt(verifier.status, "run.verifier.status", ["passed", "failed", "error"]),
+            sandbox: enumAt(verifier.sandbox, "run.verifier.sandbox", ["macos_sandbox", "container_network_denied"]),
+            record: {
+                argv: arrayAt(testRecord.argv, "run.verifier.record.argv", { min: 1, max: 64 }, (item, at) => stringAt(item, at, { max: 4096 })),
+                executable_digest: sha256At(testRecord.executable_digest, "run.verifier.record.executable_digest"),
+                exit_code: integerAt(testRecord.exit_code, "run.verifier.record.exit_code", -1, 255),
+                stdout_digest: sha256At(testRecord.stdout_digest, "run.verifier.record.stdout_digest"),
+                stderr_digest: sha256At(testRecord.stderr_digest, "run.verifier.record.stderr_digest"),
+                duration_ms: integerAt(testRecord.duration_ms, "run.verifier.record.duration_ms", 0, 3_600_000),
+            },
+        },
+        landing: {
+            operation_id: stringAt(landing.operation_id, "run.landing.operation_id", { min: 1, max: 256 }),
+            receipt_root: sha256At(landing.receipt_root, "run.landing.receipt_root"),
+            proposal_id: stringAt(landing.proposal_id, "run.landing.proposal_id", { min: 1, max: 256 }),
+            route: enumAt(landing.route, "run.landing.route", ["permit", "defer", "exact_retry"]),
+            original_route: nullableRoute(landing.original_route, "run.landing.original_route"),
+            accepted_event_delta: nullableCount(landing.accepted_event_delta, "run.landing.accepted_event_delta"),
+            publication_state: stringAt(landing.publication_state, "run.landing.publication_state", { min: 1, max: 64 }),
+        },
+        final_roots: rootsAt(record.final_roots, "run.final_roots"),
+        reproduction: {
+            matched: literal(reproduction.matched, true, "run.reproduction.matched"),
+            roots: rootsAt(reproduction.roots, "run.reproduction.roots"),
+            verifier_status: enumAt(reproduction.verifier_status, "run.reproduction.verifier_status", ["passed", "failed", "error"]),
+            stdout_digest: sha256At(reproduction.stdout_digest, "run.reproduction.stdout_digest"),
+            stderr_digest: sha256At(reproduction.stderr_digest, "run.reproduction.stderr_digest"),
+        },
+        budget: {
+            research_elapsed_ms: integerAt(budget.research_elapsed_ms, "run.budget.research_elapsed_ms", 0, 3_600_000),
+            research_processes: integerAt(budget.research_processes, "run.budget.research_processes", 0, 64),
+            research_output_bytes: integerAt(budget.research_output_bytes, "run.budget.research_output_bytes", 0, 67_108_864),
+            prompt_bytes: integerAt(budget.prompt_bytes, "run.budget.prompt_bytes", 0, 8_388_608),
+            artifact_bytes: integerAt(budget.artifact_bytes, "run.budget.artifact_bytes", 0, 1_073_741_824),
+            attempts: integerAt(budget.attempts, "run.budget.attempts", 0, 8),
+            observed_tokens: integerAt(budget.observed_tokens, "run.budget.observed_tokens", 0, 1_000_000),
+        },
+    };
+}
+export function projectRun(record) {
+    if ((record.landing.route === "exact_retry") !== (record.landing.original_route !== null)) {
+        throw new Error("exact retry must name exactly one durable original route");
+    }
+    const effectiveRoute = record.landing.route === "exact_retry"
+        ? record.landing.original_route
+        : record.landing.route;
+    if (effectiveRoute === null)
+        throw new Error("landing has no effective route");
+    const expectedDelta = effectiveRoute === "permit" ? 1 : 0;
+    if (record.landing.accepted_event_delta !== null &&
+        record.landing.accepted_event_delta !== expectedDelta) {
+        throw new Error(`${record.landing.route} landing has invalid accepted-event delta ${String(record.landing.accepted_event_delta)}`);
+    }
+    const acceptedStateEffect = record.landing.route === "permit"
+        ? "policy_admitted"
+        : record.landing.route === "defer"
+            ? "unchanged_pending"
+            : "exact_retry";
+    return {
+        schema: RUN_PROJECTION_SCHEMA,
+        authority: "read_only_projection",
+        run_id: record.run_id,
+        mission_id: record.mission.id,
+        target: record.mission.target,
+        starting_roots: record.mission.starting_roots,
+        final_roots: record.final_roots,
+        candidate_digest: record.candidate.digest,
+        candidate_status: record.candidate.status,
+        artifact_digests: record.candidate.artifacts.map((artifact) => artifact.digest),
+        verifier_status: record.verifier.status,
+        receipt_root: record.landing.receipt_root,
+        proposal_id: record.landing.proposal_id,
+        route: record.landing.route,
+        original_route: record.landing.original_route,
+        accepted_state_effect: acceptedStateEffect,
+        publication_state: record.landing.publication_state,
+        clean_clone_reproduced: record.reproduction.matched,
+        deletion_test: "Vela replay and accepted state do not depend on this projection.",
+    };
+}

package/dist/src/receipt/map.d.ts

@@ -0,0 +1,25 @@
+import { type FrozenArtifactLocation } from "../artifact/freeze.js";
+import type { BudgetSnapshot } from "../budget/enforce.js";
+import { type Candidate } from "../contracts/candidate.js";
+import type { Mission } from "../contracts/mission.js";
+import type { EngineResult } from "../engines/engine.js";
+import type { VerifierOutcome } from "../verifier/run.js";
+import type { AuthoredReceiptInput } from "../vela/cli.js";
+export declare function finalizeCandidate(options: {
+    mission: Mission;
+    engine: EngineResult;
+    frozen: readonly FrozenArtifactLocation[];
+    verifier: VerifierOutcome;
+    budget: BudgetSnapshot;
+    supportingArtifacts?: ReadonlyArray<{
+        path: string;
+        kind: string;
+    }>;
+}): Candidate;
+export declare function mapCandidateToReceipt(mission: Mission, candidate: Candidate, verifier: VerifierOutcome, work?: string): AuthoredReceiptInput;
+export declare function installFrozenArtifacts(options: {
+    landingRepo: string;
+    frontier: string;
+    frozen: readonly FrozenArtifactLocation[];
+    maxBytes: number;
+}): Promise<string[]>;

package/dist/src/receipt/map.js

@@ -0,0 +1,162 @@
+import { constants } from "node:fs";
+import { chmod, copyFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { hashRegularFile, } from "../artifact/freeze.js";
+import { parseCandidate } from "../contracts/candidate.js";
+function unique(values) {
+    return [...new Set(values)];
+}
+export function finalizeCandidate(options) {
+    const draftPaths = options.engine.draft.artifacts.map((artifact) => `${artifact.path}:${artifact.kind}`).sort();
+    const supporting = new Map((options.supportingArtifacts ?? []).map((entry) => [entry.path, entry.kind]));
+    const frozenPaths = options.frozen
+        .filter((entry) => !supporting.has(entry.artifact.path))
+        .map((entry) => `${entry.artifact.path}:${entry.artifact.kind}`)
+        .sort();
+    if (JSON.stringify(draftPaths) !== JSON.stringify(frozenPaths)) {
+        throw new Error("frozen artifacts do not exactly match the engine declaration");
+    }
+    for (const [path, kind] of supporting) {
+        const entry = options.frozen.find((candidate) => candidate.artifact.path === path);
+        if (entry === undefined || entry.artifact.kind !== kind) {
+            throw new Error(`supporting artifact ${path} is absent or misclassified`);
+        }
+    }
+    const verifierFailed = options.engine.draft.status === "success" && options.verifier.status !== "passed";
+    const status = verifierFailed ? "failed" : options.engine.draft.status;
+    const exactPositiveClaim = options.mission.schema === "canopus.mission.v1" &&
+        options.mission.result_contract !== undefined &&
+        options.engine.draft.status === "success" &&
+        options.verifier.status === "passed"
+        ? options.mission.result_contract.claim_exact
+        : undefined;
+    const claim = verifierFailed
+        ? `The engine proposed a candidate, but the declared verifier did not pass: ${options.engine.draft.claim}`
+        : exactPositiveClaim ?? options.engine.draft.claim;
+    const caveats = unique([
+        ...options.engine.draft.caveats,
+        `Declared verifier outcome: ${options.verifier.status}.`,
+        "Canopus produced this record; it is not a human acceptance decision.",
+    ]);
+    const base = {
+        schema: "canopus.candidate.v0",
+        mission_id: options.mission.id,
+        status,
+        claim,
+        artifacts: options.frozen.map((entry) => entry.artifact),
+        observations: options.engine.draft.observations,
+        tests: [options.verifier.record],
+        costs: {
+            wall_time_ms: options.budget.research_elapsed_ms,
+            attempt: options.budget.attempts,
+            input_tokens: options.engine.usage.input_tokens,
+            output_tokens: options.engine.usage.output_tokens,
+        },
+        caveats,
+        engine: options.engine.engine,
+    };
+    return parseCandidate(options.mission.parent_candidate === undefined
+        ? base
+        : {
+            ...base,
+            repair: {
+                parent_candidate: options.mission.parent_candidate,
+                reason: options.mission.repair_reason ?? "Bounded repair of the named candidate.",
+            },
+        });
+}
+export function mapCandidateToReceipt(mission, candidate, verifier, work) {
+    if (candidate.mission_id !== mission.id) {
+        throw new Error("candidate belongs to a different mission");
+    }
+    if (candidate.artifacts.length === 0) {
+        throw new Error("Receipt v1 requires at least one frozen artifact");
+    }
+    if (candidate.status === "success" && verifier.status !== "passed") {
+        throw new Error("a success candidate requires a passing declared verifier");
+    }
+    if (mission.schema === "canopus.mission.v1" && mission.result_contract !== undefined) {
+        const contract = mission.result_contract;
+        if (candidate.status !== contract.candidate_status ||
+            candidate.claim !== contract.claim_exact ||
+            verifier.status !== contract.verifier_status ||
+            mission.target !== contract.target ||
+            mission.claim_type !== contract.claim_type ||
+            mission.replayability !== contract.replayability) {
+            throw new Error("candidate does not satisfy the exact positive result contract");
+        }
+        const artifactKinds = new Set(candidate.artifacts.map((artifact) => artifact.kind));
+        for (const kind of contract.required_artifact_kinds) {
+            if (!artifactKinds.has(kind)) {
+                throw new Error(`candidate is missing result-contract artifact kind ${kind}`);
+            }
+        }
+    }
+    const result = verifier.status === "passed"
+        ? "The declared verifier exited zero on the frozen artifact set."
+        : verifier.status === "failed"
+            ? `The declared verifier returned nonzero exit ${verifier.record.exit_code}.`
+            : `The declared verifier could not complete: ${verifier.error ?? "unspecified error"}.`;
+    const evidence = [
+        ...candidate.artifacts.map((artifact) => `artifact:${artifact.digest}`),
+        `verifier_executable:${verifier.record.executable_digest}`,
+        `verifier_stdout:${verifier.record.stdout_digest}`,
+        `verifier_stderr:${verifier.record.stderr_digest}`,
+    ];
+    const counterevidence = verifier.status === "passed"
+        ? []
+        : [
+            `verifier_outcome:${verifier.status}`,
+        ];
+    const prediction = "predicted_observable" in mission.scientific_chain
+        ? { predictedObservable: mission.scientific_chain.predicted_observable }
+        : { notApplicable: true };
+    return {
+        claim: candidate.claim,
+        claimType: mission.claim_type,
+        replayability: mission.replayability,
+        artifacts: candidate.artifacts.map((artifact) => ({
+            path: artifact.path,
+            kind: artifact.kind,
+        })),
+        caveats: unique(candidate.caveats),
+        ...prediction,
+        performedTest: mission.scientific_chain.performed_test,
+        result,
+        evidence,
+        counterevidence,
+        ...(mission.schema === "canopus.mission.v1" && mission.execution_binding !== undefined
+            ? { executionBinding: mission.execution_binding }
+            : {}),
+        ...(work === undefined ? {} : { work }),
+    };
+}
+export async function installFrozenArtifacts(options) {
+    const frontierRoot = path.resolve(options.landingRepo, options.frontier);
+    const installed = [];
+    for (const entry of options.frozen) {
+        const target = path.resolve(frontierRoot, entry.artifact.path);
+        const relative = path.relative(frontierRoot, target);
+        if (relative === "" ||
+            relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative)) {
+            throw new Error(`artifact path escapes the landing frontier: ${entry.artifact.path}`);
+        }
+        await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+        try {
+            await copyFile(entry.frozenPath, target, constants.COPYFILE_EXCL);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const observed = await hashRegularFile(target, options.maxBytes);
+        if (observed.digest !== entry.artifact.digest || observed.bytes !== entry.artifact.bytes) {
+            throw new Error(`installed artifact ${entry.artifact.path} does not match frozen bytes`);
+        }
+        await chmod(target, 0o444);
+        installed.push(target);
+    }
+    return installed;
+}

package/dist/src/repair/plan.d.ts

@@ -0,0 +1,2 @@
+import type { Mission } from "../contracts/mission.js";
+export declare function planRepair(mission: Mission, parentCandidate: string, reason: string, remainingAttempts: number): Mission;

package/dist/src/repair/plan.js

@@ -0,0 +1,22 @@
+import { parseMission } from "../contracts/mission.js";
+import { sha256At, stringAt } from "../contracts/validation.js";
+import { contentDigest } from "../util/canonical.js";
+export function planRepair(mission, parentCandidate, reason, remainingAttempts) {
+    const parent = sha256At(parentCandidate, "parent_candidate");
+    const repairReason = stringAt(reason, "repair_reason", { min: 1, max: 4096 });
+    if (!Number.isSafeInteger(remainingAttempts) || remainingAttempts < 1) {
+        throw new Error("repair requires at least one remaining attempt");
+    }
+    const suffix = contentDigest({ mission: mission.id, parent, repairReason }).slice(7, 19);
+    return parseMission({
+        ...mission,
+        id: `mission_repair_${suffix}`,
+        objective: `Repair candidate ${parent}: ${repairReason}`.slice(0, 8192),
+        budgets: {
+            ...mission.budgets,
+            max_attempts: Math.min(mission.budgets.max_attempts, remainingAttempts),
+        },
+        parent_candidate: parent,
+        repair_reason: repairReason,
+    });
+}

package/dist/src/roles.d.ts

@@ -0,0 +1,2 @@
+import type { MissionRole } from "./contracts/mission.js";
+export declare function roleInstruction(role: MissionRole): string;

package/dist/src/roles.js

@@ -0,0 +1,9 @@
+const ROLE_INSTRUCTIONS = {
+    producer: "Construct the smallest candidate that meets the completion condition. Preserve a null result when the evidence does not support the claim.",
+    adversary: "Try to falsify or narrow the inherited candidate. Prefer a concrete counterexample or an explicit no-counterexample result over stylistic criticism.",
+    verifier: "Inspect whether the candidate and declared checks correspond. You do not replace the separate frozen verifier and you do not issue an acceptance verdict.",
+    fidelity: "Check that the claim says no more than the frozen artifacts and verifier facts support. Record mismatches as caveats or a failed candidate.",
+};
+export function roleInstruction(role) {
+    return ROLE_INSTRUCTIONS[role];
+}

package/dist/src/run.d.ts

@@ -0,0 +1,94 @@
+import type { Mission, MissionRoots, StrictBaseline } from "./contracts/mission.js";
+import type { FrozenArtifact } from "./contracts/candidate.js";
+import type { Engine } from "./engines/engine.js";
+import { type RunProjection, type RunRecord } from "./projection/run.js";
+import { type CommandRunner } from "./util/command.js";
+import type { AuthoredReceiptInput, VelaClient, VelaLandCommandObservation } from "./vela/cli.js";
+import type { LandResult, VelaCommandResponse, VelaInspection } from "./vela/types.js";
+import { type WorkspacePaths } from "./workspace/prepare.js";
+export interface VelaPort {
+    assertRoots(repoRoot: string, frontier: string, expected: MissionRoots, strictBaseline?: StrictBaseline): Promise<VelaInspection>;
+    inspect(repoRoot: string, frontier: string, strictBaseline?: StrictBaseline): Promise<VelaInspection>;
+    next(mission: Mission, repoRoot: string): Promise<VelaCommandResponse>;
+    work(mission: Mission, repoRoot: string, target: string, expected: MissionRoots): Promise<VelaCommandResponse>;
+    landAuthoredCommand(mission: Mission, repoRoot: string, input: AuthoredReceiptInput, expected: MissionRoots): Promise<VelaLandCommandObservation>;
+    parseLandCommand(observation: VelaLandCommandObservation): Record<string, unknown>;
+    validateLandResult(mission: Mission, raw: Record<string, unknown>): LandResult;
+    verifyReceiptBinding(mission: Mission, repoRoot: string, landing: LandResult, input: AuthoredReceiptInput, artifacts: readonly FrozenArtifact[]): Promise<void>;
+}
+export interface CanopusRunOptions {
+    mission: Mission;
+    sourceRepo: string;
+    runRoot: string;
+    vela: VelaPort | VelaClient;
+    engine: Engine;
+    bundleRoot?: string;
+    dockerBinary?: string;
+    verifierRunner?: CommandRunner;
+    retainWithdrawalCapability?: (context: {
+        velaHome: string;
+        landingRepo: string;
+        mission: Mission;
+        landing: LandResult;
+        finalRoots: MissionRoots;
+    }) => Promise<void>;
+    noLand?: false;
+}
+export interface CanopusNoLandOptions extends Omit<CanopusRunOptions, "noLand"> {
+    noLand: true;
+}
+export interface CanopusRunResult {
+    record: RunRecord;
+    projection: RunProjection;
+    paths: WorkspacePaths;
+}
+export interface DiagnosticRunRecord {
+    schema: "canopus.diagnostic-run.v1";
+    run_id: string;
+    status: "completed";
+    mode: "no_land";
+    authority: "non_authoritative";
+    external_gate_credit: false;
+    mission: {
+        id: string;
+        target: string;
+        digest: string;
+        starting_roots: MissionRoots;
+    };
+    candidate: {
+        digest: string;
+        status: "success" | "null" | "failed";
+        claim: string;
+        artifacts: Array<{
+            path: string;
+            kind: string;
+            digest: string;
+            bytes: number;
+        }>;
+        caveats: string[];
+    };
+    verifier: RunRecord["verifier"];
+    landing: null;
+    reproduction: RunRecord["reproduction"];
+    budget: RunRecord["budget"];
+}
+export interface CanopusDiagnosticRunResult {
+    record: DiagnosticRunRecord;
+    projection: {
+        schema: "canopus.diagnostic-projection.v1";
+        authority: "read_only_projection";
+        run_id: string;
+        target: string;
+        candidate_digest: string;
+        verifier_status: "passed" | "failed" | "error";
+        landed: false;
+        clean_clone_reproduced: boolean;
+    };
+    paths: WorkspacePaths;
+}
+export declare function validateTargetOffer(target: string, response: VelaCommandResponse): {
+    index: number;
+    id: string;
+};
+export declare function runCanopus(options: CanopusNoLandOptions): Promise<CanopusDiagnosticRunResult>;
+export declare function runCanopus(options: CanopusRunOptions): Promise<CanopusRunResult>;