@vela-science/canopus 0.6.5 → 0.8.0

package/dist/src/vela/cli.js

@@ -1,20 +1,14 @@
 import path from "node:path";
 import { GIT_OBJECT_RE, SHA256_RE, objectAt, relativePathAt, stringAt, } from "../contracts/validation.js";
-import { MAX_COMMAND_ARGV, isolatedEnvironment, runCommand, } from "../util/command.js";
-import { canonicalJcs, sha256Bytes } from "../util/canonical.js";
-import { MAX_EXECUTABLE_BYTES, readBoundedRegularFile, sha256RegularFile } from "../util/files.js";
-// Real large frontiers can spend tens of seconds in Vela's recoverable
-// transaction preparation and derived-view materialization. Keep this well
-// below mission wall-time budgets while allowing the measured 38.6-second
-// Erdős work operation to reach its atomic commit instead of being killed in
-// Prepared state.
-export const DEFAULT_VELA_COMMAND_TIMEOUT_MS = 120_000;
-export function retainedArtifactPath(repoRoot, frontier, digest) {
-    if (!/^sha256:[0-9a-f]{64}$/u.test(digest)) {
-        throw new VelaClientError("malformed_output", "artifact digest is not sha256");
-    }
-    return path.join(repoRoot, frontier, "records", "artifacts", "sha256", digest.slice("sha256:".length));
-}
+import { isolatedEnvironment, runCommand, } from "../util/command.js";
+import { sha256Bytes } from "../util/canonical.js";
+import { MAX_EXECUTABLE_BYTES, sha256RegularFile } from "../util/files.js";
+// Large frontiers can spend several minutes in Vela's recoverable transaction
+// preparation, exact replay, and derived-view materialization. This ceiling is
+// bounded independently from model, verifier, and mission budgets: it prevents
+// Canopus from killing a healthy authority transaction while still stopping a
+// stalled Vela subprocess.
+export const DEFAULT_VELA_COMMAND_TIMEOUT_MS = 600_000;
 export class VelaClientError extends Error {
     code;
     constructor(code, message) {
@@ -38,13 +32,6 @@ function parseJsonObject(stdout, command) {
         throw new VelaClientError("malformed_output", String(error));
     }
 }
-function usesCompactStatusProjection(version) {
-    const match = /^0\.(\d+)\.(\d+)$/u.exec(version);
-    if (match === null)
-        return false;
-    const minor = Number(match[1]);
-    return Number.isSafeInteger(minor) && minor >= 900 && minor <= 915;
-}
 function safeFailureMessage(value) {
     if (typeof value !== "string" || value.length === 0)
         return undefined;
@@ -99,20 +86,6 @@ function commandFailureSummary(result) {
         `stderr_sha256=${sha256Bytes(result.stderr)}`,
     ].join("; ");
 }
-function bool(value, at) {
-    if (typeof value !== "boolean") {
-        throw new VelaClientError("malformed_output", `${at} must be a boolean`);
-    }
-    return value;
-}
-function nullableCount(value, at) {
-    if (value === null)
-        return null;
-    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
-        throw new VelaClientError("malformed_output", `${at} must be a nonnegative integer or null`);
-    }
-    return value;
-}
 function normalizeSha256(value, at) {
     if (typeof value !== "string") {
         throw new VelaClientError("malformed_output", `${at} must be a SHA-256 string`);
@@ -142,8 +115,7 @@ function assertEqual(actual, expected, label) {
 function compareRoots(actual, expected) {
     assertEqual(actual.git_commit, expected.git_commit, "Git commit");
     assertEqual(actual.git_tree, expected.git_tree, "Git tree");
-    assertEqual(actual.vela_event_log, expected.vela_event_log, "Vela event log");
-    assertEqual(actual.vela_snapshot, expected.vela_snapshot, "Vela snapshot");
+    assertEqual(actual.vela_repository, expected.vela_repository, "Vela repository");
 }
 function nonnegativeInteger(value, at) {
     if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
@@ -151,174 +123,6 @@ function nonnegativeInteger(value, at) {
     }
     return value;
 }
-function strictSignalCheck(check) {
-    if (!Array.isArray(check.checks)) {
-        throw new VelaClientError("malformed_output", "vela check.checks must be an array");
-    }
-    let signalCheck;
-    for (const [index, value] of check.checks.entries()) {
-        const entry = fieldObject({ entry: value }, "entry", `vela check.checks[${index}]`);
-        const id = stringAt(entry.id, `vela check.checks[${index}].id`, { min: 1, max: 128 });
-        const status = stringAt(entry.status, `vela check.checks[${index}].status`, {
-            min: 1,
-            max: 32,
-        });
-        if (id === "signals") {
-            if (signalCheck !== undefined) {
-                throw new VelaClientError("malformed_output", "vela check contains duplicate signals checks");
-            }
-            signalCheck = entry;
-        }
-        else if (status !== "pass") {
-            throw new VelaClientError("command_failed", `vela strict check failed outside the registered signals baseline: ${id}=${status}`);
-        }
-    }
-    if (signalCheck === undefined) {
-        throw new VelaClientError("malformed_output", "vela check omitted the signals check");
-    }
-    return signalCheck;
-}
-export function strictBaselineFromCheck(check) {
-    const summary = fieldObject(check, "summary", "vela check");
-    if (summary.strict !== true) {
-        throw new VelaClientError("malformed_output", "vela check summary is not strict");
-    }
-    if (nonnegativeInteger(summary.errors, "vela check.summary.errors") !== 0 ||
-        nonnegativeInteger(summary.invalid_findings, "vela check.summary.invalid_findings") !== 0) {
-        throw new VelaClientError("command_failed", "vela strict check contains structural errors or invalid findings");
-    }
-    const signalCheck = strictSignalCheck(check);
-    if (!Array.isArray(signalCheck.blockers)) {
-        throw new VelaClientError("malformed_output", "vela check signals.blockers must be an array");
-    }
-    const blockers = signalCheck.blockers.map((value, index) => fieldObject({ blocker: value }, "blocker", `vela check signals.blockers[${index}]`));
-    const blocker_count = nonnegativeInteger(signalCheck.failed, "vela check signals.failed");
-    if (blockers.length !== blocker_count) {
-        throw new VelaClientError("malformed_output", "vela check signals blocker array and failed count disagree");
-    }
-    const counts = new Map();
-    for (const [index, blocker] of blockers.entries()) {
-        const kind = stringAt(blocker.kind, `vela check signals.blockers[${index}].kind`, {
-            min: 1,
-            max: 128,
-            pattern: /^[a-z][a-z0-9_]*$/u,
-        });
-        counts.set(kind, (counts.get(kind) ?? 0) + 1);
-    }
-    const canonicalBlockers = blockers
-        .map((blocker) => canonicalJcs(blocker))
-        .sort()
-        .map((serialized) => JSON.parse(serialized));
-    const status = blocker_count === 0 ? "pass" : "fail";
-    const signalStatus = stringAt(signalCheck.status, "vela check signals.status", {
-        min: 1,
-        max: 32,
-    });
-    if (signalStatus !== status || summary.status !== status || bool(check.ok, "vela check.ok") !== (status === "pass")) {
-        throw new VelaClientError("malformed_output", "vela strict status fields disagree");
-    }
-    return {
-        status,
-        blocker_count,
-        blockers_root: sha256Bytes(canonicalJcs(canonicalBlockers)),
-        rule_counts: [...counts.entries()]
-            .sort(([left], [right]) => left.localeCompare(right))
-            .map(([rule, count]) => ({ rule, count })),
-    };
-}
-function assertStrictBaseline(actual, expected) {
-    if (expected === undefined) {
-        if (actual.status !== "pass") {
-            throw new VelaClientError("command_failed", `vela strict check has ${actual.blocker_count} unregistered blockers`);
-        }
-        return;
-    }
-    if (canonicalJcs(actual) !== canonicalJcs(expected)) {
-        throw new VelaClientError("root_mismatch", `strict baseline mismatch: expected ${canonicalJcs(expected)}, observed ${canonicalJcs(actual)}`);
-    }
-}
-export function validateLandResult(mission, raw) {
-    if (raw.ok !== true || raw.command !== "land") {
-        throw new VelaClientError("malformed_output", "vela land did not return its success envelope");
-    }
-    const rawRoute = stringAt(raw.route, "vela land.route", { min: 1, max: 64 });
-    const route = rawRoute === "policy_admitted"
-        ? "permit"
-        : rawRoute === "deferred"
-            ? "defer"
-            : rawRoute === "exact_retry"
-                ? "exact_retry"
-                : undefined;
-    if (route === undefined) {
-        throw new VelaClientError("malformed_output", `unknown landing route ${rawRoute}`);
-    }
-    const detail = stringAt(raw.detail, "vela land.detail", { max: 8192 });
-    const rawOriginalRoute = raw.original_route;
-    const originalRoute = route === "exact_retry"
-        ? rawOriginalRoute === "policy_admitted"
-            ? "permit"
-            : rawOriginalRoute === "deferred"
-                ? "defer"
-                : undefined
-        : rawOriginalRoute === null
-            ? null
-            : undefined;
-    if (originalRoute === undefined) {
-        throw new VelaClientError("malformed_output", "landing returned an invalid structured original_route");
-    }
-    const effectiveRoute = route === "exact_retry" ? originalRoute : route;
-    if (effectiveRoute === null) {
-        throw new VelaClientError("malformed_output", "landing has no effective route");
-    }
-    if (!mission.landing.expected_routes.includes(effectiveRoute)) {
-        throw new VelaClientError("unexpected_route", `landing route ${effectiveRoute} was not registered by the mission`);
-    }
-    const before = nullableCount(raw.accepted_event_count_before, "vela land.accepted_event_count_before");
-    const after = nullableCount(raw.accepted_event_count_after, "vela land.accepted_event_count_after");
-    const delta = nullableCount(raw.accepted_event_delta, "vela land.accepted_event_delta");
-    if ((before === null) !== (after === null) || (before === null) !== (delta === null)) {
-        throw new VelaClientError("malformed_output", "landing returned a partial accepted-event count tuple");
-    }
-    if (before !== null && after !== null && delta !== null && (after < before || delta !== after - before)) {
-        throw new VelaClientError("malformed_output", "landing accepted-event delta is inconsistent");
-    }
-    if (delta !== null && delta > mission.landing.max_accepted_delta) {
-        throw new VelaClientError("unexpected_route", `accepted-event delta ${delta} exceeds registered maximum`);
-    }
-    const expectedDelta = effectiveRoute === "permit" ? 1 : 0;
-    if (delta !== null && delta !== expectedDelta) {
-        throw new VelaClientError("malformed_output", `${effectiveRoute} durable landing requires accepted-event delta ${expectedDelta}`);
-    }
-    if (route !== "exact_retry" && delta === null) {
-        throw new VelaClientError("malformed_output", "new landing omitted accepted-event counts");
-    }
-    const publication = fieldObject(raw, "publication", "vela land");
-    const publicationState = stringAt(publication.state, "vela land.publication.state", {
-        min: 1,
-        max: 64,
-    });
-    if (publicationState !== "committed_local" &&
-        publicationState !== "pushed" &&
-        publicationState !== "unchanged") {
-        throw new VelaClientError("command_failed", `vela land was durable but not Git-published: ${publicationState}`);
-    }
-    return {
-        operationId: stringAt(raw.operation_id, "vela land.operation_id", { min: 1, max: 256 }),
-        receiptRoot: normalizeSha256(raw.receipt_root, "vela land.receipt_root"),
-        recordId: stringAt(raw.record_id, "vela land.record_id", { min: 1, max: 256 }),
-        proposalId: stringAt(raw.proposal_id, "vela land.proposal_id", { min: 1, max: 256 }),
-        findingId: stringAt(raw.finding_id, "vela land.finding_id", { min: 1, max: 256 }),
-        route,
-        originalRoute,
-        rawRoute,
-        detail,
-        acceptedEventCountBefore: before,
-        acceptedEventCountAfter: after,
-        acceptedEventDelta: delta,
-        publication,
-        raw,
-    };
-}
 export class VelaClient {
     #binary;
     #expectedVersion;
@@ -335,11 +139,24 @@ export class VelaClient {
         this.#home = options.home;
         this.#maxOutputBytes = options.maxOutputBytes ?? 16 * 1024 * 1024;
         this.#timeoutMs = options.timeoutMs ?? DEFAULT_VELA_COMMAND_TIMEOUT_MS;
-        // Deliberately do not accept caller-supplied environment entries. In
-        // particular, this prevents a harness integration from forwarding human
-        // key variables into the Vela control lane. Agent actors auto-mint only an
-        // agent session key beneath this isolated HOME.
-        this.#env = isolatedEnvironment(options.home);
+        // The control lane accepts only the standard repository-authority agent
+        // socket. It never accepts caller-supplied environment entries or key
+        // bytes, and this environment is not reused by the Codex worker or
+        // verifier.
+        const baseEnvironment = isolatedEnvironment(options.home);
+        if (options.repositoryAuthorityAgentSocket === undefined) {
+            this.#env = baseEnvironment;
+        }
+        else {
+            if (!path.isAbsolute(options.repositoryAuthorityAgentSocket) ||
+                options.repositoryAuthorityAgentSocket.includes("\0")) {
+                throw new VelaClientError("malformed_output", "repository authority agent socket must be one absolute path");
+            }
+            this.#env = {
+                ...baseEnvironment,
+                SSH_AUTH_SOCK: options.repositoryAuthorityAgentSocket,
+            };
+        }
         this.#runner = options.runner ?? runCommand;
     }
     async #execute(argv, cwd) {
@@ -359,46 +176,6 @@ export class VelaClient {
         const result = await this.#execute([this.#binary, ...args], cwd);
         return parseJsonObject(result.stdout, label);
     }
-    async #strictCheck(frontier, cwd, baseline) {
-        const argv = [this.#binary, "check", frontier, "--strict", "--json"];
-        const result = await this.#runner({
-            argv,
-            cwd,
-            env: this.#env,
-            timeoutMs: this.#timeoutMs,
-            maxOutputBytes: this.#maxOutputBytes,
-        });
-        if (result.exitCode !== 0 && result.exitCode !== 1) {
-            throw new VelaClientError("command_failed", `${argv[0]} ${argv.slice(1).join(" ")} exited ${result.exitCode}: ${commandFailureSummary(result)}`);
-        }
-        const check = parseJsonObject(result.stdout, "vela check");
-        const actual = strictBaselineFromCheck(check);
-        if ((result.exitCode === 0) !== (actual.status === "pass")) {
-            throw new VelaClientError("malformed_output", "vela strict exit code and status disagree");
-        }
-        assertStrictBaseline(actual, baseline);
-        return check;
-    }
-    async observeStrictBaseline(repoRoot, frontier) {
-        const safeFrontier = frontierPath(frontier);
-        const argv = [this.#binary, "check", safeFrontier, "--strict", "--json"];
-        const result = await this.#runner({
-            argv,
-            cwd: repoRoot,
-            env: this.#env,
-            timeoutMs: this.#timeoutMs,
-            maxOutputBytes: this.#maxOutputBytes,
-        });
-        if (result.exitCode !== 0 && result.exitCode !== 1) {
-            throw new VelaClientError("command_failed", `${argv[0]} ${argv.slice(1).join(" ")} exited ${result.exitCode}: ${commandFailureSummary(result)}`);
-        }
-        const check = parseJsonObject(result.stdout, "vela check");
-        const baseline = strictBaselineFromCheck(check);
-        if ((result.exitCode === 0) !== (baseline.status === "pass")) {
-            throw new VelaClientError("malformed_output", "vela strict exit code and status disagree");
-        }
-        return baseline;
-    }
     async assertVersion(cwd) {
         const binaryDigest = await sha256RegularFile(this.#binary, MAX_EXECUTABLE_BYTES);
         if (binaryDigest !== this.#expectedSha256) {
@@ -423,62 +200,86 @@ export class VelaClient {
         }
         return observed;
     }
-    async inspect(repoRoot, frontier, strictBaseline) {
+    async inspect(repoRoot, frontier) {
         const safeFrontier = frontierPath(frontier);
         const version = await this.assertVersion(repoRoot);
-        const [gitCommit, gitTree, check] = await Promise.all([
+        const [gitCommit, gitTree, status, repository] = await Promise.all([
             this.#gitObject(repoRoot, "HEAD^{commit}"),
             this.#gitObject(repoRoot, "HEAD^{tree}"),
-            this.#strictCheck(safeFrontier, repoRoot, strictBaseline),
+            this.#json(["status", safeFrontier, "--json"], repoRoot, "vela status"),
+            this.#json(["repository", "verify", safeFrontier, "--json"], repoRoot, "vela repository verify"),
         ]);
-        // Vela 0.9 makes the compact status projection the ordinary root reader.
-        // Historical binaries retain proof verification for exact Mission v0/v1
-        // replay, but a minimal 0.9 frontier intentionally has no proof bundle.
-        const replay = typeof check.replay === "object" && check.replay !== null
-            ? fieldObject(check, "replay", "vela check")
-            : fieldObject(fieldObject(check, "state_integrity", "vela check"), "replay", "vela check.state_integrity");
-        const checkEvent = normalizeSha256(replay.event_log_hash, "vela check.replay.event_log_hash");
-        const checkCurrent = normalizeSha256(replay.current_hash, "vela check.replay.current_hash");
-        if (replay.replayed_hash !== undefined) {
-            assertEqual(normalizeSha256(replay.replayed_hash, "vela check.replay.replayed_hash"), checkCurrent, "Vela replayed snapshot");
-        }
-        if (replay.source_hash !== undefined) {
-            assertEqual(normalizeSha256(replay.source_hash, "vela check.replay.source_hash"), checkCurrent, "Vela source snapshot");
-        }
-        const proof = usesCompactStatusProjection(version)
-            ? {
-                ok: true,
-                command: "status_root_projection",
-                event_log_hash: checkEvent,
-                snapshot_hash: checkCurrent,
-            }
-            : await this.#json(["proof", "verify", safeFrontier, "--json"], repoRoot, "vela proof verify");
-        if (!bool(proof.ok, "vela root projection.ok")) {
-            throw new VelaClientError("command_failed", "vela root projection returned ok=false");
-        }
-        const proofEvent = normalizeSha256(proof.event_log_hash, "vela root projection.event_log_hash");
-        const proofSnapshot = normalizeSha256(proof.snapshot_hash, "vela root projection.snapshot_hash");
-        assertEqual(proofEvent, checkEvent, "check/proof event log");
-        assertEqual(proofSnapshot, checkCurrent, "check/proof snapshot");
-        if (proof.proof !== undefined) {
-            const proofBody = fieldObject(proof, "proof", "vela proof verify");
-            assertEqual(normalizeSha256(proofBody.event_log_hash, "vela proof verify.proof.event_log_hash"), checkEvent, "proof body event log");
-            assertEqual(normalizeSha256(proofBody.frontier_hash, "vela proof verify.proof.frontier_hash"), checkCurrent, "proof body snapshot");
+        if (status.schema !== "vela.status.v1" ||
+            status.ok !== true ||
+            status.command !== "status") {
+            throw new VelaClientError("malformed_output", "vela status contract identity is invalid");
+        }
+        if (repository.schema !== "vela.repository-verification.v1" ||
+            repository.ok !== true ||
+            repository.command !== "repository verify") {
+            throw new VelaClientError("malformed_output", "vela repository verification contract identity is invalid");
+        }
+        const statusGit = fieldObject(status, "git", "vela status");
+        const integrity = fieldObject(status, "integrity", "vela status");
+        const statusRoots = fieldObject(status, "roots", "vela status");
+        if (integrity.replay !== "verified" ||
+            integrity.strict !== "pass" ||
+            nonnegativeInteger(integrity.blocker_count, "vela status.integrity.blocker_count") !== 0) {
+            throw new VelaClientError("command_failed", "Vela repository must replay and pass strict verification before Canopus can run");
+        }
+        const blockers = fieldObject(integrity, "blockers_by_code", "vela status.integrity");
+        if (Object.keys(blockers).length !== 0) {
+            throw new VelaClientError("malformed_output", "vela status strict pass contains blocker classifications");
+        }
+        const statusCommit = stringAt(statusGit.commit, "vela status.git.commit", {
+            min: 40,
+            max: 64,
+            pattern: GIT_OBJECT_RE,
+        });
+        const statusTree = stringAt(statusGit.tree, "vela status.git.tree", {
+            min: 40,
+            max: 64,
+            pattern: GIT_OBJECT_RE,
+        });
+        assertEqual(statusCommit, gitCommit, "Git/status commit");
+        assertEqual(statusTree, gitTree, "Git/status tree");
+        assertEqual(stringAt(repository.git_commit, "vela repository verify.git_commit", {
+            min: 40,
+            max: 64,
+            pattern: GIT_OBJECT_RE,
+        }), gitCommit, "Git/repository commit");
+        assertEqual(stringAt(repository.git_tree, "vela repository verify.git_tree", {
+            min: 40,
+            max: 64,
+            pattern: GIT_OBJECT_RE,
+        }), gitTree, "Git/repository tree");
+        const repositoryRoot = normalizeSha256(repository.repository_root, "vela repository verify.repository_root");
+        assertEqual(normalizeSha256(statusRoots.repository, "vela status.roots.repository"), repositoryRoot, "status/repository root");
+        for (const [statusKey, repositoryKey, label] of [
+            ["epoch", "epoch_root", "epoch"],
+            ["authority_keyset", "authority_keyset_root", "authority keyset"],
+            ["authority_policy", "authority_policy_root", "authority policy"],
+        ]) {
+            assertEqual(normalizeSha256(statusRoots[statusKey], `vela status.roots.${statusKey}`), normalizeSha256(repository[repositoryKey], `vela repository verify.${repositoryKey}`), `status/repository ${label}`);
         }
+        const statusFrontier = fieldObject(status, "frontier", "vela status");
+        assertEqual(stringAt(statusFrontier.id, "vela status.frontier.id", { min: 1, max: 64 }), stringAt(repository.frontier_id, "vela repository verify.frontier_id", {
+            min: 1,
+            max: 64,
+        }), "status/repository frontier");
         return {
             version,
             roots: {
                 git_commit: gitCommit,
                 git_tree: gitTree,
-                vela_event_log: checkEvent,
-                vela_snapshot: checkCurrent,
+                vela_repository: repositoryRoot,
             },
-            check,
-            proof,
+            status,
+            repository,
         };
     }
-    async assertRoots(repoRoot, frontier, expected, strictBaseline) {
-        const inspection = await this.inspect(repoRoot, frontier, strictBaseline);
+    async assertRoots(repoRoot, frontier, expected) {
+        const inspection = await this.inspect(repoRoot, frontier);
         compareRoots(inspection.roots, expected);
         return inspection;
     }
@@ -486,246 +287,24 @@ export class VelaClient {
         if (mission.vela_version !== this.#expectedVersion) {
             throw new VelaClientError("version_mismatch", "mission and client Vela versions differ");
         }
-        return await this.offer(repoRoot, mission.frontier, mission.roots, mission.schema === "canopus.mission.v1" ? mission.strict_baseline : undefined);
+        return await this.offer(repoRoot, mission.frontier, mission.roots);
     }
-    async offer(repoRoot, frontier, roots, strictBaseline, limit = 128) {
+    async offer(repoRoot, frontier, roots, limit = 128) {
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 128) {
             throw new VelaClientError("malformed_output", "vela next limit must be 1..128");
         }
         const safeFrontier = frontierPath(frontier);
-        await this.assertRoots(repoRoot, safeFrontier, roots, strictBaseline);
+        await this.assertRoots(repoRoot, safeFrontier, roots);
         const value = await this.#json(["next", safeFrontier, "--limit", String(limit), "--json"], repoRoot, "vela next");
         if (value.ok === false) {
             throw new VelaClientError("command_failed", "vela next returned ok=false");
         }
-        return { ok: true, value };
-    }
-    async work(mission, repoRoot, target, expected) {
-        stringAt(target, "target", { min: 1, max: 256 });
-        await this.assertRoots(repoRoot, mission.frontier, expected, mission.schema === "canopus.mission.v1" ? mission.strict_baseline : undefined);
-        const value = await this.#json(["work", target, "--frontier", mission.frontier, "--as", mission.actor, "--json"], repoRoot, "vela work");
-        if (value.ok === false) {
-            throw new VelaClientError("command_failed", "vela work returned ok=false");
+        if (value.schema !== "vela.offer.v1" ||
+            value.command !== "next" ||
+            value.ok !== true) {
+            throw new VelaClientError("malformed_output", "vela next contract identity is invalid");
         }
+        assertEqual(normalizeSha256(value.repository_root, "vela next.repository_root"), roots.vela_repository, "mission/offer repository");
         return { ok: true, value };
     }
-    async withdraw(repoRoot, frontier, proposalId, actor, reason) {
-        if (!/^vpr_[0-9a-f]{16}$/u.test(proposalId)) {
-            throw new VelaClientError("malformed_output", "withdrawal requires a full proposal id");
-        }
-        if (!actor.startsWith("agent:") || reason.trim().length === 0) {
-            throw new VelaClientError("malformed_output", "withdrawal requires an agent actor and reason");
-        }
-        const value = await this.#json(["review", "withdraw", frontierPath(frontier), proposalId, "--as", actor, "--reason", reason, "--json"], repoRoot, "vela review withdraw");
-        if (value.ok !== true || value.command !== "review.withdraw") {
-            throw new VelaClientError("malformed_output", "vela review withdraw returned an invalid envelope");
-        }
-        if (value.proposal_id !== proposalId || value.idempotent !== false || value.key_read !== true) {
-            throw new VelaClientError("malformed_output", "vela review withdraw did not bind one new key-backed withdrawal");
-        }
-        const eventId = stringAt(value.withdrawal_event_id, "vela review withdraw.withdrawal_event_id", {
-            max: 20,
-            pattern: /^vev_[0-9a-f]{16}$/u,
-        });
-        const withdrawnAt = stringAt(value.withdrawn_at, "vela review withdraw.withdrawn_at", {
-            min: 20,
-            max: 64,
-        });
-        if (!Number.isFinite(Date.parse(withdrawnAt))) {
-            throw new VelaClientError("malformed_output", "vela review withdraw returned an invalid timestamp");
-        }
-        const stateRootBefore = normalizeSha256(value.state_root_before, "vela review withdraw.state_root_before");
-        const stateRootAfter = normalizeSha256(value.state_root_after, "vela review withdraw.state_root_after");
-        if (stateRootBefore === stateRootAfter) {
-            throw new VelaClientError("malformed_output", "new withdrawal did not change the event-log root");
-        }
-        const publication = fieldObject(value, "publication", "vela review withdraw");
-        const publicationState = stringAt(publication.state, "vela review withdraw.publication.state", {
-            min: 1,
-            max: 32,
-        });
-        if (publicationState !== "committed_local" && publicationState !== "pushed") {
-            throw new VelaClientError("command_failed", `withdrawal publication is ${publicationState}, not committed`);
-        }
-        const publicationCommit = stringAt(publication.commit, "vela review withdraw.publication.commit", { max: 64, pattern: GIT_OBJECT_RE });
-        return {
-            proposal_id: proposalId,
-            withdrawal_event_id: eventId,
-            withdrawn_at: withdrawnAt,
-            state_root_before: stateRootBefore,
-            state_root_after: stateRootAfter,
-            publication_commit: publicationCommit,
-        };
-    }
-    async landAuthoredCommand(mission, repoRoot, input, _expected) {
-        if ((input.predictedObservable === undefined) === (input.notApplicable === undefined)) {
-            throw new VelaClientError("malformed_output", "authored receipt requires exactly one prediction mode");
-        }
-        // The caller performs the strict exact-root check immediately before it
-        // installs the candidate artifacts. Those files legitimately stale the
-        // derived artifacts hash until `vela land` records them atomically, so a
-        // second strict check here would make the normal porcelain path unusable.
-        const args = [
-            "land",
-            "--frontier",
-            mission.frontier,
-            "--claim",
-            input.claim,
-            "--type",
-            input.claimType,
-            "--replayability",
-            input.replayability,
-        ];
-        for (const artifact of input.artifacts) {
-            args.push("--artifact", `${relativePathAt(artifact.path, "artifact.path")}:${artifact.kind}`);
-        }
-        for (const caveat of input.caveats)
-            args.push("--caveat", caveat);
-        if (input.predictedObservable !== undefined) {
-            args.push("--predicted-observable", input.predictedObservable);
-        }
-        else {
-            args.push("--not-applicable");
-        }
-        args.push("--performed-test", input.performedTest, "--result", input.result);
-        for (const evidence of input.evidence)
-            args.push("--evidence", evidence);
-        for (const counterevidence of input.counterevidence) {
-            args.push("--counterevidence", counterevidence);
-        }
-        if (input.executionBinding !== undefined) {
-            args.push("--packet-root", input.executionBinding.packet_root, "--profile-root", input.executionBinding.profile_root, "--verifier-capsule-root", input.executionBinding.verifier_capsule_root, "--result-contract-root", input.executionBinding.result_contract_root);
-        }
-        if (input.work !== undefined)
-            args.push("--work", input.work);
-        args.push("--as", mission.actor, "--json");
-        const argv = [this.#binary, ...args];
-        if (argv.length > MAX_COMMAND_ARGV) {
-            throw new VelaClientError("malformed_output", `authored Receipt requires ${argv.length} argv entries; maximum is ${MAX_COMMAND_ARGV}`);
-        }
-        const result = await this.#runner({
-            argv,
-            cwd: repoRoot,
-            env: this.#env,
-            timeoutMs: this.#timeoutMs,
-            maxOutputBytes: this.#maxOutputBytes,
-        });
-        return {
-            argv,
-            exit_code: result.exitCode,
-            stdout: result.stdout.toString("utf8"),
-            stderr: result.stderr.toString("utf8"),
-            stdout_digest: sha256Bytes(result.stdout),
-            stderr_digest: sha256Bytes(result.stderr),
-        };
-    }
-    parseLandCommand(observation) {
-        if (observation.exit_code !== 0) {
-            throw new VelaClientError("command_failed", `vela land exited ${observation.exit_code}: ${observation.stderr}`);
-        }
-        return parseJsonObject(Buffer.from(observation.stdout), "vela land");
-    }
-    validateLandResult(mission, raw) {
-        return validateLandResult(mission, raw);
-    }
-    async verifyReceiptBinding(mission, repoRoot, landing, input, artifacts) {
-        const hex = landing.receiptRoot.slice("sha256:".length);
-        const receiptPath = path.join(repoRoot, mission.frontier, "records", "receipts", "sha256", `${hex}.json`);
-        const bytes = await readBoundedRegularFile(receiptPath, 8 * 1024 * 1024);
-        let parsed;
-        try {
-            parsed = JSON.parse(bytes.toString("utf8"));
-        }
-        catch (error) {
-            throw new VelaClientError("malformed_output", `retained receipt is not JSON: ${String(error)}`);
-        }
-        const receipt = objectAt(parsed, "retained receipt");
-        if (sha256Bytes(canonicalJcs(receipt)) !== landing.receiptRoot) {
-            throw new VelaClientError("root_mismatch", "retained Receipt v1 root does not match vela land");
-        }
-        const recordPath = path.join(repoRoot, mission.frontier, "records", `${landing.recordId}.json`);
-        let recordValue;
-        try {
-            recordValue = JSON.parse((await readBoundedRegularFile(recordPath, 8 * 1024 * 1024)).toString("utf8"));
-        }
-        catch (error) {
-            throw new VelaClientError("malformed_output", `retained activity record is unavailable or malformed: ${String(error)}`);
-        }
-        const record = objectAt(recordValue, "retained activity record");
-        const expectedReceiptPath = `records/receipts/sha256/${hex}.json`;
-        if (record.id !== landing.recordId ||
-            record.receipt_digest !== landing.receiptRoot ||
-            record.receipt_path !== expectedReceiptPath) {
-            throw new VelaClientError("root_mismatch", "retained activity record does not bind the landed Receipt v1");
-        }
-        for (const [actual, expected, label] of [
-            [receipt.claim, input.claim, "claim"],
-            [receipt.type, input.claimType, "claim type"],
-            [receipt.replayability, input.replayability, "replayability"],
-        ]) {
-            if (actual !== expected) {
-                throw new VelaClientError("malformed_output", `retained receipt ${label} drifted`);
-            }
-        }
-        if (JSON.stringify(receipt.caveats) !== JSON.stringify(input.caveats)) {
-            throw new VelaClientError("malformed_output", "retained receipt caveats drifted");
-        }
-        const rawArtifacts = receipt.artifacts;
-        if (!Array.isArray(rawArtifacts) || rawArtifacts.length !== artifacts.length) {
-            throw new VelaClientError("malformed_output", "retained receipt artifact set drifted");
-        }
-        const recordArtifacts = record.artifacts;
-        if (!Array.isArray(recordArtifacts) || recordArtifacts.length !== artifacts.length) {
-            throw new VelaClientError("malformed_output", "activity record artifact set drifted");
-        }
-        for (const [index, expected] of artifacts.entries()) {
-            const rawArtifact = objectAt(rawArtifacts[index], `retained receipt.artifacts[${index}]`);
-            if (rawArtifact.path !== expected.path ||
-                rawArtifact.kind !== expected.kind ||
-                rawArtifact.sha256 !== expected.digest.slice("sha256:".length)) {
-                throw new VelaClientError("malformed_output", `retained receipt artifact ${index} drifted`);
-            }
-            const recordArtifact = objectAt(recordArtifacts[index], `retained activity record.artifacts[${index}]`);
-            const hexDigest = expected.digest.slice("sha256:".length);
-            if (recordArtifact.kind !== expected.kind ||
-                recordArtifact.sha256 !== hexDigest ||
-                recordArtifact.locator !== `records/artifacts/sha256/${hexDigest}` ||
-                recordArtifact.size_bytes !== expected.bytes ||
-                recordArtifact.locator_integrity !== "immutable" ||
-                recordArtifact.availability !== "available") {
-                throw new VelaClientError("malformed_output", `activity record artifact ${index} is not an immutable available blob binding`);
-            }
-            const installed = await readBoundedRegularFile(retainedArtifactPath(repoRoot, mission.frontier, expected.digest), mission.budgets.max_artifact_bytes);
-            if (installed.length !== expected.bytes || sha256Bytes(installed) !== expected.digest) {
-                throw new VelaClientError("root_mismatch", `retained artifact ${expected.path} drifted`);
-            }
-        }
-        const environment = fieldObject(receipt, "environment", "retained receipt");
-        if (input.executionBinding === undefined) {
-            if (environment["vela:execution_binding"] !== undefined) {
-                throw new VelaClientError("malformed_output", "retained receipt invented an exact execution binding");
-            }
-        }
-        else {
-            const binding = fieldObject(environment, "vela:execution_binding", "retained receipt.environment");
-            if (canonicalJcs(binding) !== canonicalJcs(input.executionBinding)) {
-                throw new VelaClientError("root_mismatch", "retained exact execution binding drifted");
-            }
-        }
-        const chain = fieldObject(environment, "vela:scientific_chain", "retained receipt.environment");
-        const expectedChain = {
-            schema: "vela.scientific-chain.producer.v1",
-            authority: "producer",
-            ...(input.predictedObservable === undefined
-                ? { not_applicable: true }
-                : { predicted_observable: input.predictedObservable, not_applicable: false }),
-            performed_test: input.performedTest,
-            result: input.result,
-            evidence: input.evidence,
-            counterevidence: input.counterevidence,
-        };
-        if (canonicalJcs(chain) !== canonicalJcs(expectedChain)) {
-            throw new VelaClientError("malformed_output", "retained scientific-chain assertion drifted");
-        }
-    }
 }