@vela-science/canopus 0.4.0-rc.1

package/dist/src/util/canonical.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+function normalize(value, at) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError(`${at} contains a non-finite number`);
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => normalize(item, `${at}[${index}]`));
+    }
+    if (typeof value === "object") {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`${at} must contain plain JSON objects`);
+        }
+        const input = value;
+        const output = {};
+        for (const key of Object.keys(input).sort()) {
+            const item = input[key];
+            if (item === undefined) {
+                throw new TypeError(`${at}.${key} is undefined`);
+            }
+            output[key] = normalize(item, `${at}.${key}`);
+        }
+        return output;
+    }
+    throw new TypeError(`${at} contains a non-JSON value`);
+}
+export function canonicalJson(value) {
+    return `${JSON.stringify(normalize(value, "$"))}\n`;
+}
+// RFC 8785 uses ECMAScript JSON serialization over recursively sorted object
+// keys and does not append a record newline. Vela Receipt v1 uses these bytes.
+export function canonicalJcs(value) {
+    return JSON.stringify(normalize(value, "$"));
+}
+export function sha256Bytes(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+export function contentDigest(value) {
+    return sha256Bytes(canonicalJson(value));
+}
+// Vela protocol objects use compact canonical JSON bytes, without the record
+// newline used by Canopus-owned manifests and activity records.
+export function protocolDigest(value) {
+    return sha256Bytes(canonicalJcs(value));
+}

package/dist/src/util/command.d.ts

@@ -0,0 +1,26 @@
+export type CommandFailureKind = "invalid_argv" | "spawn" | "timeout" | "output_limit" | "aborted";
+export declare class CommandFailure extends Error {
+    readonly kind: CommandFailureKind;
+    constructor(kind: CommandFailureKind, message: string);
+}
+export interface CommandResult {
+    argv: string[];
+    exitCode: number;
+    signal: NodeJS.Signals | null;
+    stdout: Buffer;
+    stderr: Buffer;
+    durationMs: number;
+}
+export interface CommandOptions {
+    argv: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    stdin?: Uint8Array | string;
+    signal?: AbortSignal;
+}
+export type CommandRunner = (options: CommandOptions) => Promise<CommandResult>;
+export declare const MAX_COMMAND_ARGV = 128;
+export declare function isolatedEnvironment(home: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+export declare function runCommand(options: CommandOptions): Promise<CommandResult>;

package/dist/src/util/command.js

@@ -0,0 +1,161 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+export class CommandFailure extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "CommandFailure";
+        this.kind = kind;
+    }
+}
+export const MAX_COMMAND_ARGV = 128;
+function validateArgv(argv) {
+    if (argv.length === 0 || argv.length > MAX_COMMAND_ARGV) {
+        throw new CommandFailure("invalid_argv", `argv must contain 1..${MAX_COMMAND_ARGV} entries`);
+    }
+    for (const [index, item] of argv.entries()) {
+        if (item.length === 0 || item.length > 16_384 || item.includes("\0")) {
+            throw new CommandFailure("invalid_argv", `argv[${index}] is invalid`);
+        }
+    }
+}
+function terminateTree(pid, signal) {
+    if (pid === undefined) {
+        return;
+    }
+    try {
+        if (process.platform === "win32") {
+            process.kill(pid, signal);
+        }
+        else {
+            process.kill(-pid, signal);
+        }
+    }
+    catch {
+        // The process may already have exited.
+    }
+}
+export function isolatedEnvironment(home, platform = process.platform) {
+    const path = process.env.PATH;
+    const common = {
+        ...(path === undefined ? {} : { PATH: path }),
+        HOME: home,
+        XDG_CONFIG_HOME: `${home}/.config`,
+        XDG_CACHE_HOME: `${home}/.cache`,
+        XDG_DATA_HOME: `${home}/.local/share`,
+        GIT_CONFIG_NOSYSTEM: "1",
+        GIT_TERMINAL_PROMPT: "0",
+        VELA_NO_KEY_ACCESS: "1",
+        NO_PROXY: "*",
+        no_proxy: "*",
+    };
+    if (platform === "win32") {
+        return {
+            ...common,
+            USERPROFILE: home,
+            APPDATA: `${home}\\AppData\\Roaming`,
+            LOCALAPPDATA: `${home}\\AppData\\Local`,
+            GIT_CONFIG_GLOBAL: "NUL",
+        };
+    }
+    return {
+        ...common,
+        LANG: "C.UTF-8",
+        LC_ALL: "C.UTF-8",
+        // rustls-native-certs checks this before macOS keychains. Pinning the
+        // system PEM bundle keeps TLS functional without exposing user keychains.
+        SSL_CERT_FILE: "/etc/ssl/cert.pem",
+        GIT_CONFIG_GLOBAL: "/dev/null",
+    };
+}
+export async function runCommand(options) {
+    validateArgv(options.argv);
+    if (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1) {
+        throw new CommandFailure("invalid_argv", "timeoutMs must be a positive integer");
+    }
+    if (!Number.isInteger(options.maxOutputBytes) || options.maxOutputBytes < 1) {
+        throw new CommandFailure("invalid_argv", "maxOutputBytes must be a positive integer");
+    }
+    if (options.signal?.aborted === true) {
+        throw new CommandFailure("aborted", "command was aborted before spawn");
+    }
+    const executable = options.argv[0];
+    if (executable === undefined) {
+        throw new CommandFailure("invalid_argv", "argv must name an executable");
+    }
+    const started = performance.now();
+    return await new Promise((resolve, reject) => {
+        const child = spawn(executable, options.argv.slice(1), {
+            cwd: options.cwd,
+            env: options.env,
+            detached: process.platform !== "win32",
+            shell: false,
+            stdio: "pipe",
+            windowsHide: true,
+        });
+        const stdout = [];
+        const stderr = [];
+        let bytes = 0;
+        let failure;
+        let killTimer;
+        const terminate = (nextFailure) => {
+            if (failure !== undefined) {
+                return;
+            }
+            failure = nextFailure;
+            terminateTree(child.pid, "SIGTERM");
+            killTimer = setTimeout(() => terminateTree(child.pid, "SIGKILL"), 250);
+            killTimer.unref();
+        };
+        const collect = (target, chunk) => {
+            bytes += chunk.length;
+            if (bytes > options.maxOutputBytes) {
+                terminate(new CommandFailure("output_limit", `command output exceeded ${options.maxOutputBytes} bytes`));
+                return;
+            }
+            target.push(chunk);
+        };
+        child.stdout.on("data", (chunk) => collect(stdout, chunk));
+        child.stderr.on("data", (chunk) => collect(stderr, chunk));
+        const timeout = setTimeout(() => terminate(new CommandFailure("timeout", `command exceeded ${options.timeoutMs} milliseconds`)), options.timeoutMs);
+        timeout.unref();
+        const abort = () => terminate(new CommandFailure("aborted", "command was aborted"));
+        options.signal?.addEventListener("abort", abort, { once: true });
+        child.once("error", (error) => {
+            clearTimeout(timeout);
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            options.signal?.removeEventListener("abort", abort);
+            reject(new CommandFailure("spawn", `could not spawn ${executable}: ${error.message}`));
+        });
+        child.once("close", (code, signal) => {
+            clearTimeout(timeout);
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            options.signal?.removeEventListener("abort", abort);
+            // A verifier may fork, close inherited stdio, and let its parent exit.
+            // The wrapper's successful exit is therefore not sufficient: terminate
+            // the entire detached process group before returning in every outcome.
+            terminateTree(child.pid, "SIGTERM");
+            terminateTree(child.pid, "SIGKILL");
+            if (failure !== undefined) {
+                reject(failure);
+                return;
+            }
+            resolve({
+                argv: [...options.argv],
+                exitCode: code ?? -1,
+                signal,
+                stdout: Buffer.concat(stdout),
+                stderr: Buffer.concat(stderr),
+                durationMs: Math.round(performance.now() - started),
+            });
+        });
+        if (options.stdin === undefined) {
+            child.stdin.end();
+        }
+        else {
+            child.stdin.end(options.stdin);
+        }
+    });
+}

package/dist/src/util/files.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_EXECUTABLE_BYTES: number;
+export declare function readBoundedRegularFile(file: string, maxBytes: number): Promise<Buffer>;
+export declare function sha256RegularFile(file: string, maxBytes: number): Promise<string>;

package/dist/src/util/files.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+export const MAX_EXECUTABLE_BYTES = 1024 * 1024 * 1024;
+function assertStableRegularFile(file, before, after) {
+    if (before.dev !== after.dev ||
+        before.ino !== after.ino ||
+        before.size !== after.size ||
+        before.mtimeMs !== after.mtimeMs) {
+        throw new Error(`${file} changed while it was being read`);
+    }
+}
+export async function readBoundedRegularFile(file, maxBytes) {
+    const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+    const handle = await open(file, constants.O_RDONLY | noFollow);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.nlink !== 1) {
+            throw new Error(`${file} is not one singly linked regular file`);
+        }
+        if (before.size > maxBytes)
+            throw new Error(`${file} exceeds ${maxBytes} bytes`);
+        const value = Buffer.alloc(before.size);
+        let offset = 0;
+        while (offset < value.length) {
+            const { bytesRead } = await handle.read(value, offset, value.length - offset, offset);
+            if (bytesRead === 0)
+                throw new Error(`${file} ended before its declared size`);
+            offset += bytesRead;
+        }
+        assertStableRegularFile(file, before, await handle.stat());
+        return value;
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function sha256RegularFile(file, maxBytes) {
+    const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+    const handle = await open(file, constants.O_RDONLY | noFollow);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.nlink !== 1) {
+            throw new Error(`${file} is not one singly linked regular file`);
+        }
+        if (before.size > maxBytes)
+            throw new Error(`${file} exceeds ${maxBytes} bytes`);
+        const hash = createHash("sha256");
+        const buffer = Buffer.allocUnsafe(1024 * 1024);
+        let offset = 0;
+        while (offset < before.size) {
+            const length = Math.min(buffer.length, before.size - offset);
+            const { bytesRead } = await handle.read(buffer, 0, length, offset);
+            if (bytesRead === 0)
+                throw new Error(`${file} ended before its declared size`);
+            hash.update(buffer.subarray(0, bytesRead));
+            offset += bytesRead;
+        }
+        assertStableRegularFile(file, before, await handle.stat());
+        return `sha256:${hash.digest("hex")}`;
+    }
+    finally {
+        await handle.close();
+    }
+}

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

@@ -0,0 +1,71 @@
+import type { FrozenArtifact } from "../contracts/candidate.js";
+import type { ExecutionBindingV1, Mission, MissionRoots, StrictBaseline } from "../contracts/mission.js";
+import { type CommandRunner } from "../util/command.js";
+import type { LandResult, VelaCommandResponse, VelaInspection } from "./types.js";
+export type { CommandRunner } from "../util/command.js";
+export declare function retainedArtifactPath(repoRoot: string, frontier: string, digest: string): string;
+export declare class VelaClientError extends Error {
+    readonly code: "command_failed" | "malformed_output" | "version_mismatch" | "root_mismatch" | "unexpected_route";
+    constructor(code: VelaClientError["code"], message: string);
+}
+export interface VelaClientOptions {
+    binary: string;
+    expectedVersion: string;
+    expectedSha256: string;
+    home: string;
+    maxOutputBytes?: number;
+    timeoutMs?: number;
+    runner?: CommandRunner;
+}
+export interface AuthoredReceiptInput {
+    claim: string;
+    claimType: Mission["claim_type"];
+    replayability: Mission["replayability"];
+    artifacts: Array<{
+        path: string;
+        kind: string;
+    }>;
+    caveats: string[];
+    predictedObservable?: string;
+    notApplicable?: true;
+    performedTest: string;
+    result: string;
+    evidence: string[];
+    counterevidence: string[];
+    executionBinding?: ExecutionBindingV1;
+    work?: string;
+}
+export interface VelaLandCommandObservation {
+    argv: string[];
+    exit_code: number;
+    stdout: string;
+    stderr: string;
+    stdout_digest: string;
+    stderr_digest: string;
+}
+export interface VelaWithdrawalResult {
+    proposal_id: string;
+    withdrawal_event_id: string;
+    withdrawn_at: string;
+    state_root_before: string;
+    state_root_after: string;
+    publication_commit: string;
+}
+export declare function strictBaselineFromCheck(check: Record<string, unknown>): StrictBaseline;
+export declare function validateLandResult(mission: Mission, raw: Record<string, unknown>): LandResult;
+export declare class VelaClient {
+    #private;
+    constructor(options: VelaClientOptions);
+    observeStrictBaseline(repoRoot: string, frontier: string): Promise<StrictBaseline>;
+    assertVersion(cwd: string): Promise<string>;
+    inspect(repoRoot: string, frontier: string, strictBaseline?: StrictBaseline): Promise<VelaInspection>;
+    assertRoots(repoRoot: string, frontier: string, expected: MissionRoots, strictBaseline?: StrictBaseline): Promise<VelaInspection>;
+    next(mission: Mission, repoRoot: string): Promise<VelaCommandResponse>;
+    offer(repoRoot: string, frontier: string, roots: MissionRoots, strictBaseline?: StrictBaseline, limit?: number): Promise<VelaCommandResponse>;
+    work(mission: Mission, repoRoot: string, target: string, expected: MissionRoots): Promise<VelaCommandResponse>;
+    withdraw(repoRoot: string, frontier: string, proposalId: string, actor: string, reason: string): Promise<VelaWithdrawalResult>;
+    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>;
+}