@vela-science/canopus 0.4.0-rc.1

package/dist/src/product/runtime.js

@@ -0,0 +1,64 @@
+import { constants } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import path from "node:path";
+import { isolatedEnvironment, runCommand } from "../util/command.js";
+import { MAX_EXECUTABLE_BYTES, sha256RegularFile } from "../util/files.js";
+export function executableNames(name, platform, pathExt) {
+    if (platform !== "win32" || path.win32.extname(name) !== "")
+        return [name];
+    const extensions = pathExt
+        .split(";")
+        .map((extension) => extension.trim())
+        .filter((extension) => extension !== "")
+        .map((extension) => extension.startsWith(".") ? extension : `.${extension}`);
+    return [name, ...extensions.map((extension) => `${name}${extension.toLowerCase()}`)];
+}
+export async function findExecutable(name, searchPath = process.env.PATH ?? "", options = {}) {
+    const platform = options.platform ?? process.platform;
+    const pathExt = options.pathExt ?? process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
+    const paths = platform === "win32" ? path.win32 : path;
+    const names = executableNames(name, platform, pathExt);
+    if (name.includes("/") || name.includes("\\")) {
+        const binary = await realpath(path.resolve(name));
+        await access(binary, constants.X_OK);
+        return binary;
+    }
+    for (const directory of searchPath.split(platform === "win32" ? ";" : path.delimiter)) {
+        if (directory === "")
+            continue;
+        for (const executable of names) {
+            const candidate = paths.join(directory, executable);
+            try {
+                await access(candidate, constants.X_OK);
+                return await realpath(candidate);
+            }
+            catch {
+                // Continue through the explicit PATH and PATHEXT only.
+            }
+        }
+    }
+    throw new Error(`${name} was not found on PATH`);
+}
+export async function runtimeIdentity(options) {
+    const runner = options.runner ?? runCommand;
+    const binary = await findExecutable(options.name);
+    const result = await runner({
+        argv: [binary, ...(options.versionArgs ?? ["--version"])],
+        cwd: options.cwd,
+        env: isolatedEnvironment(options.home),
+        timeoutMs: 30_000,
+        maxOutputBytes: 64 * 1024,
+    });
+    if (result.exitCode !== 0)
+        throw new Error(`${options.name} version probe failed`);
+    const stdout = result.stdout.toString("utf8").trim();
+    const version = stdout === "" ? result.stderr.toString("utf8").trim() : stdout;
+    if (version === "" || version.length > 4096) {
+        throw new Error(`${options.name} returned an invalid version`);
+    }
+    return {
+        binary,
+        version,
+        sha256: await sha256RegularFile(binary, MAX_EXECUTABLE_BYTES),
+    };
+}

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

@@ -0,0 +1 @@
+export declare const CANOPUS_VERSION: string;

package/dist/src/product/version.js

@@ -0,0 +1,6 @@
+import { readFileSync } from "node:fs";
+const packageJson = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8"));
+if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+    throw new Error("Canopus package version is missing");
+}
+export const CANOPUS_VERSION = packageJson.version;

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

@@ -0,0 +1,8 @@
+import { type CommandRunner } from "../util/command.js";
+export declare function withdrawProduct(options: {
+    frontier: string;
+    runFile: string;
+    reason: string;
+    storeRoot?: string;
+    runner?: CommandRunner;
+}): Promise<Record<string, unknown>>;

package/dist/src/product/withdraw.js

@@ -0,0 +1,255 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdir, mkdtemp, readdir, realpath, rm } from "node:fs/promises";
+import { consumeWithdrawalCapability, installWithdrawalCapabilitySecret, loadWithdrawalCapability, } from "../capability/withdrawal.js";
+import { parseRunRecord } from "../projection/run.js";
+import { canonicalJcs, contentDigest, protocolDigest, sha256Bytes, } from "../util/canonical.js";
+import { isolatedEnvironment, runCommand } from "../util/command.js";
+import { readBoundedRegularFile } from "../util/files.js";
+import { VelaClient } from "../vela/cli.js";
+async function gitText(runner, cwd, home, argv) {
+    const result = await runner({
+        argv: ["git", ...argv],
+        cwd,
+        env: isolatedEnvironment(home),
+        timeoutMs: 120_000,
+        maxOutputBytes: 8 * 1024 * 1024,
+    });
+    if (result.exitCode !== 0 || result.stderr.length !== 0) {
+        throw new Error(`git ${argv.join(" ")} failed: stdout=${sha256Bytes(result.stdout)} stderr=${sha256Bytes(result.stderr)}`);
+    }
+    return result.stdout.toString("utf8").trim();
+}
+function safeActor(actor) {
+    return [...actor].map((character) => /[A-Za-z0-9_-]/u.test(character) ? character : "-").join("");
+}
+async function scientificProjectionRoot(frontierRoot) {
+    const project = JSON.parse((await readBoundedRegularFile(path.join(frontierRoot, "frontier.json"), 128 * 1024 * 1024))
+        .toString("utf8"));
+    const fields = [
+        "actors",
+        "anchor_links",
+        "artifacts",
+        "condition_records",
+        "evidence_atoms",
+        "findings",
+        "frontier",
+        "frontier_id",
+        "released_diff_packs",
+        "sources",
+        "statement_attestations",
+        "verifier_attachments",
+    ];
+    return contentDigest(Object.fromEntries(fields.map((field) => [field, project[field] ?? null])));
+}
+function jsonObject(value, at) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${at} must be an object`);
+    }
+    return value;
+}
+function proposalStanding(value) {
+    if (value !== "pending_review" &&
+        value !== "accepted" &&
+        value !== "applied" &&
+        value !== "rejected" &&
+        value !== "revision_requested" &&
+        value !== "needs_revision" &&
+        value !== "withdrawn") {
+        throw new Error(`proposal has unrecognized standing ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+async function frontierWithin(repo, frontier) {
+    const resolved = await realpath(path.resolve(repo, frontier));
+    if (resolved !== repo && !resolved.startsWith(`${repo}${path.sep}`)) {
+        throw new Error("capability frontier resolves outside the selected source repository");
+    }
+    return resolved;
+}
+async function terminalProposalEvent(frontierRoot, proposalId) {
+    const directory = path.join(frontierRoot, ".vela", "events");
+    const entries = await readdir(directory, { withFileTypes: true });
+    if (entries.length > 1_000_000)
+        throw new Error("frontier event directory exceeds the supported audit bound");
+    const matches = [];
+    const decisionByKind = new Map([
+        ["review.accepted", "accepted"],
+        ["review.rejected", "rejected"],
+        ["review.revision_requested", "revision_requested"],
+        ["proposal.withdrawn", "withdrawn"],
+    ]);
+    for (const entry of entries) {
+        if (!entry.isFile() || !/^vev_[0-9a-f]{16}\.json$/u.test(entry.name))
+            continue;
+        const event = jsonObject(JSON.parse((await readBoundedRegularFile(path.join(directory, entry.name), 8 * 1024 * 1024)).toString("utf8")), `event ${entry.name}`);
+        const decision = typeof event.kind === "string" ? decisionByKind.get(event.kind) : undefined;
+        if (decision === undefined)
+            continue;
+        const target = jsonObject(event.target, `event ${entry.name}.target`);
+        if (target.type !== "proposal" || target.id !== proposalId)
+            continue;
+        const eventId = entry.name.slice(0, -".json".length);
+        if (event.id !== eventId || typeof event.signature !== "string" || event.signature.length === 0) {
+            throw new Error(`terminal proposal event ${entry.name} is not a signed canonical event file`);
+        }
+        const payload = jsonObject(event.payload, `event ${entry.name}.payload`);
+        if (payload.proposal_id !== proposalId) {
+            throw new Error(`terminal proposal event ${entry.name} payload targets another proposal`);
+        }
+        if (decision === "withdrawn") {
+            if (payload.schema !== "vela.proposal-withdrawal.v1") {
+                throw new Error(`withdrawal event ${entry.name} has the wrong payload schema`);
+            }
+        }
+        else if (payload.verdict !== decision) {
+            throw new Error(`review event ${entry.name} verdict disagrees with its kind`);
+        }
+        matches.push({ event_id: eventId, decision });
+    }
+    if (matches.length > 1)
+        throw new Error("proposal has conflicting terminal events");
+    return matches[0] ?? null;
+}
+function terminalDecisionMatchesStanding(decision, standing) {
+    return decision === "accepted"
+        ? standing === "accepted" || standing === "applied"
+        : decision === "revision_requested"
+            ? standing === "revision_requested" || standing === "needs_revision"
+            : decision === standing;
+}
+export async function withdrawProduct(options) {
+    if (options.reason.trim().length === 0)
+        throw new Error("withdrawal reason must not be empty");
+    const runner = options.runner ?? runCommand;
+    const source = await realpath(options.frontier);
+    const runFile = path.resolve(options.runFile);
+    const record = parseRunRecord(JSON.parse((await readBoundedRegularFile(runFile, 8 * 1024 * 1024)).toString("utf8")));
+    const capability = await loadWithdrawalCapability(record.landing.proposal_id, options.storeRoot);
+    if (capability.manifest.state !== "available" || !capability.secret_available) {
+        throw new Error("withdrawal capability is not available");
+    }
+    if (capability.manifest.receipt_root !== record.landing.receipt_root ||
+        canonicalJcs(capability.manifest.final_roots) !== canonicalJcs(record.final_roots)) {
+        throw new Error("withdrawal capability does not match the selected run");
+    }
+    const controlRoot = await mkdtemp(path.join(os.tmpdir(), "canopus-withdraw-"));
+    const controlHome = path.join(controlRoot, "home");
+    const clone = path.join(controlRoot, "candidate");
+    const replay = path.join(controlRoot, "replay");
+    await mkdir(path.join(controlHome, ".vela", "agents", safeActor(capability.manifest.actor)), {
+        recursive: true,
+        mode: 0o700,
+    });
+    try {
+        const sourceHead = await gitText(runner, source, controlHome, ["rev-parse", "--verify", "HEAD^{commit}"]);
+        const sourceStatus = await gitText(runner, source, controlHome, ["status", "--porcelain=v1", "--untracked-files=all"]);
+        if (sourceStatus !== "")
+            throw new Error("source frontier must be clean before withdrawal");
+        const client = new VelaClient({
+            binary: capability.manifest.vela.binary,
+            expectedVersion: capability.manifest.vela.version,
+            expectedSha256: capability.manifest.vela.sha256,
+            home: controlHome,
+            runner,
+        });
+        const strictBaseline = capability.manifest.strict_baseline;
+        const sourceInspection = await client.inspect(source, capability.manifest.frontier, strictBaseline);
+        const frontierRoot = await frontierWithin(source, capability.manifest.frontier);
+        const proposalPath = path.join(frontierRoot, ".vela", "proposals", `${record.landing.proposal_id}.json`);
+        const proposal = jsonObject(JSON.parse((await readBoundedRegularFile(proposalPath, 8 * 1024 * 1024)).toString("utf8")), "proposal");
+        if (proposal.id !== record.landing.proposal_id)
+            throw new Error("proposal file id disagrees with the run");
+        const standing = proposalStanding(proposal.status);
+        const terminalEvent = await terminalProposalEvent(frontierRoot, record.landing.proposal_id);
+        const stableHead = await gitText(runner, source, controlHome, ["rev-parse", "--verify", "HEAD^{commit}"]);
+        const stableStatus = await gitText(runner, source, controlHome, ["status", "--porcelain=v1", "--untracked-files=all"]);
+        if (stableHead !== sourceHead || stableStatus !== "") {
+            throw new Error("source frontier changed during proposal verification");
+        }
+        if (standing !== "pending_review") {
+            if (terminalEvent === null || !terminalDecisionMatchesStanding(terminalEvent.decision, standing)) {
+                throw new Error("terminal proposal standing is not backed by exactly one matching signed event");
+            }
+            await consumeWithdrawalCapability(record.landing.proposal_id, terminalEvent.decision === "withdrawn" ? "withdrawn" : "human_decision_observed", options.storeRoot);
+            return {
+                ok: true,
+                command: "withdraw",
+                proposal_id: record.landing.proposal_id,
+                terminal_event_id: terminalEvent.event_id,
+                state: terminalEvent.decision === "withdrawn" ? "already_withdrawn" : "human_decision_observed",
+                frontier_mutated: false,
+                capability_consumed: true,
+            };
+        }
+        if (terminalEvent !== null)
+            throw new Error("pending proposal already has a terminal event");
+        if (protocolDigest(proposal) !== capability.manifest.proposal_root) {
+            throw new Error("pending proposal bytes drifted from the retained withdrawal capability");
+        }
+        await gitText(runner, controlRoot, controlHome, ["clone", "--quiet", "--no-local", source, clone]);
+        const before = await client.inspect(clone, capability.manifest.frontier, strictBaseline);
+        if (canonicalJcs(before.roots) !== canonicalJcs(sourceInspection.roots)) {
+            throw new Error("disposable withdrawal clone does not match the selected source head");
+        }
+        await installWithdrawalCapabilitySecret(record.landing.proposal_id, path.join(controlHome, ".vela", "agents", safeActor(capability.manifest.actor), "private.key"), options.storeRoot);
+        const scientificRootBefore = await scientificProjectionRoot(path.resolve(clone, capability.manifest.frontier));
+        const withdrawal = await client.withdraw(clone, capability.manifest.frontier, record.landing.proposal_id, capability.manifest.actor, options.reason);
+        const after = await client.inspect(clone, capability.manifest.frontier, strictBaseline);
+        const scientificRootAfter = await scientificProjectionRoot(path.resolve(clone, capability.manifest.frontier));
+        if (after.roots.git_commit === before.roots.git_commit || after.roots.vela_event_log === before.roots.vela_event_log) {
+            throw new Error("withdrawal did not append and publish one event");
+        }
+        if (withdrawal.publication_commit !== after.roots.git_commit ||
+            withdrawal.state_root_before !== before.roots.vela_event_log ||
+            withdrawal.state_root_after !== after.roots.vela_event_log) {
+            throw new Error("withdrawal response does not bind the verified Git and event-log roots");
+        }
+        if (scientificRootAfter !== scientificRootBefore) {
+            throw new Error("withdrawal changed the accepted scientific projection");
+        }
+        const withdrawnFrontier = await frontierWithin(await realpath(clone), capability.manifest.frontier);
+        const withdrawnProposal = jsonObject(JSON.parse((await readBoundedRegularFile(path.join(withdrawnFrontier, ".vela", "proposals", `${record.landing.proposal_id}.json`), 8 * 1024 * 1024)).toString("utf8")), "withdrawn proposal");
+        const withdrawnEvent = await terminalProposalEvent(withdrawnFrontier, record.landing.proposal_id);
+        if (withdrawnProposal.status !== "withdrawn" ||
+            withdrawnEvent?.decision !== "withdrawn" ||
+            withdrawnEvent.event_id !== withdrawal.withdrawal_event_id) {
+            throw new Error("withdrawal output is not backed by the exact materialized terminal event");
+        }
+        await gitText(runner, controlRoot, controlHome, ["clone", "--quiet", "--no-local", clone, replay]);
+        const reproduced = await client.inspect(replay, capability.manifest.frontier, strictBaseline);
+        if (canonicalJcs(reproduced.roots) !== canonicalJcs(after.roots)) {
+            throw new Error("clean-clone withdrawal replay drifted");
+        }
+        const unchangedHead = await gitText(runner, source, controlHome, ["rev-parse", "--verify", "HEAD^{commit}"]);
+        const unchangedStatus = await gitText(runner, source, controlHome, ["status", "--porcelain=v1", "--untracked-files=all"]);
+        if (unchangedHead !== sourceHead || unchangedStatus !== "") {
+            throw new Error("source frontier changed during withdrawal");
+        }
+        await gitText(runner, source, controlHome, ["fetch", "--quiet", "--no-tags", clone, "HEAD"]);
+        await gitText(runner, source, controlHome, ["merge", "--ff-only", "--no-edit", "FETCH_HEAD"]);
+        const installed = await client.inspect(source, capability.manifest.frontier, strictBaseline);
+        if (canonicalJcs(installed.roots) !== canonicalJcs(after.roots)) {
+            throw new Error("fast-forwarded source does not match the verified withdrawal clone");
+        }
+        const installedStatus = await gitText(runner, source, controlHome, ["status", "--porcelain=v1", "--untracked-files=all"]);
+        if (installedStatus !== "")
+            throw new Error("fast-forwarded source is not clean");
+        await consumeWithdrawalCapability(record.landing.proposal_id, "withdrawn", options.storeRoot);
+        return {
+            ok: true,
+            command: "withdraw",
+            proposal_id: record.landing.proposal_id,
+            withdrawal_event_id: withdrawal.withdrawal_event_id,
+            roots: after.roots,
+            scientific_state_root_before: scientificRootBefore,
+            scientific_state_root_after: scientificRootAfter,
+            accepted_state_changed: false,
+            clean_clone_reproduced: true,
+            capability_consumed: true,
+        };
+    }
+    finally {
+        await rm(controlRoot, { recursive: true, force: true });
+    }
+}

package/dist/src/projection/diagnostic.d.ts

@@ -0,0 +1,12 @@
+import type { DiagnosticRunRecord } from "../run.js";
+export declare function parseDiagnosticRunRecord(value: unknown): DiagnosticRunRecord;
+export declare function projectDiagnosticRun(record: DiagnosticRunRecord): {
+    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: true;
+};

package/dist/src/projection/diagnostic.js

@@ -0,0 +1,61 @@
+import { arrayAt, enumAt, exactKeys, objectAt, relativePathAt, sha256At, stringAt, } from "../contracts/validation.js";
+function literal(value, expected, at) {
+    if (value !== expected)
+        throw new Error(`${at} must be ${String(expected)}`);
+    return expected;
+}
+export function parseDiagnosticRunRecord(value) {
+    const record = objectAt(value, "diagnostic run");
+    exactKeys(record, [
+        "schema", "run_id", "status", "mode", "authority", "external_gate_credit",
+        "mission", "candidate", "verifier", "landing", "reproduction", "budget",
+    ], [], "diagnostic run");
+    const mission = objectAt(record.mission, "diagnostic run.mission");
+    exactKeys(mission, ["id", "target", "digest", "starting_roots"], [], "diagnostic run.mission");
+    const candidate = objectAt(record.candidate, "diagnostic run.candidate");
+    exactKeys(candidate, ["digest", "status", "claim", "artifacts", "caveats"], [], "diagnostic run.candidate");
+    const verifier = objectAt(record.verifier, "diagnostic run.verifier");
+    exactKeys(verifier, ["status", "sandbox", "record"], [], "diagnostic run.verifier");
+    const reproduction = objectAt(record.reproduction, "diagnostic run.reproduction");
+    exactKeys(reproduction, ["matched", "roots", "verifier_status", "stdout_digest", "stderr_digest"], [], "diagnostic run.reproduction");
+    objectAt(mission.starting_roots, "diagnostic run.mission.starting_roots");
+    objectAt(reproduction.roots, "diagnostic run.reproduction.roots");
+    objectAt(record.budget, "diagnostic run.budget");
+    literal(record.schema, "canopus.diagnostic-run.v1", "diagnostic run.schema");
+    literal(record.status, "completed", "diagnostic run.status");
+    literal(record.mode, "no_land", "diagnostic run.mode");
+    literal(record.authority, "non_authoritative", "diagnostic run.authority");
+    literal(record.external_gate_credit, false, "diagnostic run.external_gate_credit");
+    literal(record.landing, null, "diagnostic run.landing");
+    stringAt(record.run_id, "diagnostic run.run_id", { min: 5, max: 128 });
+    stringAt(mission.id, "diagnostic run.mission.id", { min: 1, max: 134 });
+    stringAt(mission.target, "diagnostic run.mission.target", { min: 1, max: 256 });
+    sha256At(mission.digest, "diagnostic run.mission.digest");
+    sha256At(candidate.digest, "diagnostic run.candidate.digest");
+    enumAt(candidate.status, "diagnostic run.candidate.status", ["success", "null", "failed"]);
+    stringAt(candidate.claim, "diagnostic run.candidate.claim", { min: 1, max: 8192 });
+    arrayAt(candidate.artifacts, "diagnostic run.candidate.artifacts", { max: 10 }, (item, at) => {
+        const artifact = objectAt(item, at);
+        exactKeys(artifact, ["path", "kind", "digest", "bytes"], [], at);
+        relativePathAt(artifact.path, `${at}.path`);
+        stringAt(artifact.kind, `${at}.kind`, { min: 1, max: 128 });
+        sha256At(artifact.digest, `${at}.digest`);
+        return true;
+    });
+    arrayAt(candidate.caveats, "diagnostic run.candidate.caveats", { max: 10 }, (item, at) => stringAt(item, at, { min: 1, max: 4096 }));
+    enumAt(verifier.status, "diagnostic run.verifier.status", ["passed", "failed", "error"]);
+    literal(reproduction.matched, true, "diagnostic run.reproduction.matched");
+    return value;
+}
+export function projectDiagnosticRun(record) {
+    return {
+        schema: "canopus.diagnostic-projection.v1",
+        authority: "read_only_projection",
+        run_id: record.run_id,
+        target: record.mission.target,
+        candidate_digest: record.candidate.digest,
+        verifier_status: record.verifier.status,
+        landed: false,
+        clean_clone_reproduced: true,
+    };
+}

package/dist/src/projection/failure.d.ts

@@ -0,0 +1,26 @@
+export declare const FAILURE_RECORD_SCHEMA: "canopus.failure.v0";
+export declare const FAILURE_PROJECTION_SCHEMA: "canopus.failure-projection.v0";
+export interface FailureRecord {
+    schema: typeof FAILURE_RECORD_SCHEMA;
+    run_id: string;
+    error: string;
+    phase: string;
+    landing_observed: boolean;
+    landing_recovery: string | null;
+    activity_tip: string;
+    authority: "non_authoritative";
+}
+export interface FailureProjection {
+    schema: typeof FAILURE_PROJECTION_SCHEMA;
+    authority: "read_only_projection";
+    run_id: string;
+    status: "failed";
+    phase: string;
+    error: string;
+    landing_status: "not_attempted" | "observed_requires_recovery";
+    landing_recovery: string | null;
+    activity_tip: string;
+    deletion_test: "Vela state does not depend on this projection; inspect retained recovery evidence for any observed landing effect.";
+}
+export declare function parseFailureRecord(value: unknown): FailureRecord;
+export declare function projectFailure(record: FailureRecord): FailureProjection;

package/dist/src/projection/failure.js

@@ -0,0 +1,63 @@
+import { exactKeys, objectAt, relativePathAt, sha256At, stringAt, } from "../contracts/validation.js";
+export const FAILURE_RECORD_SCHEMA = "canopus.failure.v0";
+export const FAILURE_PROJECTION_SCHEMA = "canopus.failure-projection.v0";
+function literal(value, expected, at) {
+    if (value !== expected)
+        throw new Error(`${at} must be ${String(expected)}`);
+    return expected;
+}
+function booleanAt(value, at) {
+    if (typeof value !== "boolean")
+        throw new Error(`${at} must be a boolean`);
+    return value;
+}
+export function parseFailureRecord(value) {
+    const record = objectAt(value, "failure");
+    exactKeys(record, [
+        "schema",
+        "run_id",
+        "error",
+        "phase",
+        "landing_observed",
+        "landing_recovery",
+        "activity_tip",
+        "authority",
+    ], [], "failure");
+    return {
+        schema: literal(record.schema, FAILURE_RECORD_SCHEMA, "failure.schema"),
+        run_id: stringAt(record.run_id, "failure.run_id", {
+            min: 5,
+            max: 128,
+            pattern: /^run_[A-Za-z0-9._-]+$/u,
+        }),
+        error: stringAt(record.error, "failure.error", { min: 1, max: 16_384 }),
+        phase: stringAt(record.phase, "failure.phase", {
+            min: 1,
+            max: 128,
+            pattern: /^[a-z][a-z0-9_]*$/u,
+        }),
+        landing_observed: booleanAt(record.landing_observed, "failure.landing_observed"),
+        landing_recovery: record.landing_recovery === null
+            ? null
+            : relativePathAt(record.landing_recovery, "failure.landing_recovery"),
+        activity_tip: sha256At(record.activity_tip, "failure.activity_tip"),
+        authority: literal(record.authority, "non_authoritative", "failure.authority"),
+    };
+}
+export function projectFailure(record) {
+    if (record.landing_observed !== (record.landing_recovery !== null)) {
+        throw new Error("failure landing observation and recovery evidence disagree");
+    }
+    return {
+        schema: FAILURE_PROJECTION_SCHEMA,
+        authority: "read_only_projection",
+        run_id: record.run_id,
+        status: "failed",
+        phase: record.phase,
+        error: record.error,
+        landing_status: record.landing_observed ? "observed_requires_recovery" : "not_attempted",
+        landing_recovery: record.landing_recovery,
+        activity_tip: record.activity_tip,
+        deletion_test: "Vela state does not depend on this projection; inspect retained recovery evidence for any observed landing effect.",
+    };
+}

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

@@ -0,0 +1,89 @@
+import type { MissionRoots } from "../contracts/mission.js";
+export declare const RUN_RECORD_SCHEMA: "canopus.run.v0";
+export declare const RUN_PROJECTION_SCHEMA: "canopus.run-projection.v0";
+export interface RunRecord {
+    schema: typeof RUN_RECORD_SCHEMA;
+    run_id: string;
+    status: "completed";
+    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: {
+        status: "passed" | "failed" | "error";
+        sandbox: "macos_sandbox" | "container_network_denied";
+        record: {
+            argv: string[];
+            executable_digest: string;
+            exit_code: number;
+            stdout_digest: string;
+            stderr_digest: string;
+            duration_ms: number;
+        };
+    };
+    landing: {
+        operation_id: string;
+        receipt_root: string;
+        proposal_id: string;
+        route: "permit" | "defer" | "exact_retry";
+        original_route: "permit" | "defer" | null;
+        accepted_event_delta: number | null;
+        publication_state: string;
+    };
+    final_roots: MissionRoots;
+    reproduction: {
+        matched: boolean;
+        roots: MissionRoots;
+        verifier_status: "passed" | "failed" | "error";
+        stdout_digest: string;
+        stderr_digest: string;
+    };
+    budget: {
+        research_elapsed_ms: number;
+        research_processes: number;
+        research_output_bytes: number;
+        prompt_bytes: number;
+        artifact_bytes: number;
+        attempts: number;
+        observed_tokens: number;
+    };
+}
+export interface RunProjection {
+    schema: typeof RUN_PROJECTION_SCHEMA;
+    authority: "read_only_projection";
+    run_id: string;
+    mission_id: string;
+    target: string;
+    starting_roots: MissionRoots;
+    final_roots: MissionRoots;
+    candidate_digest: string;
+    candidate_status: "success" | "null" | "failed";
+    artifact_digests: string[];
+    verifier_status: "passed" | "failed" | "error";
+    receipt_root: string;
+    proposal_id: string;
+    route: "permit" | "defer" | "exact_retry";
+    original_route: "permit" | "defer" | null;
+    accepted_state_effect: "policy_admitted" | "unchanged_pending" | "exact_retry";
+    publication_state: string;
+    clean_clone_reproduced: boolean;
+    deletion_test: "Vela replay and accepted state do not depend on this projection.";
+}
+export declare function parseRunRecord(value: unknown): RunRecord;
+export declare function projectRun(record: RunRecord): RunProjection;