@moldesk/core 0.0.1 → 0.0.3

package/dist/run.d.ts

@@ -0,0 +1,89 @@
+import { type RuntimeKind } from "@moldesk/registry";
+import { type MoldeskPaths, type RuntimeProvider, type SystemReport } from "@moldesk/runtime";
+/**
+ * `runModel` only rejects for usage errors discovered before a run directory
+ * is allocated (unknown model, not installed, invalid input/params — spec
+ * §4.2 steps 1-3). From the moment a run directory exists (step 4 onward),
+ * every outcome — success, nonzero exit, missing output, cancellation, or an
+ * unexpected internal failure — resolves as a typed `RunModelResult` with a
+ * finalized `run.json`, never a rejection. The CLI distinguishes the two by
+ * catch (usage error, mapped via `MoldeskError.code`) vs. `result.status`.
+ */
+export interface RunModelOptions {
+    paths?: MoldeskPaths;
+    runtime?: RuntimeKind;
+    /** Raw `--param key=value` strings, validated against the adapter's declared params. */
+    params?: Record<string, string>;
+    /** Copy declared outputs here after a successful run. Refuses to overwrite existing files. */
+    outputDir?: string;
+    /** CLI-constructed abort signal (SIGINT/SIGTERM) for graceful cancellation. */
+    signal?: AbortSignal;
+    onLog?: (stream: "stdout" | "stderr", chunk: string) => void;
+    /** Injected for testability; defaults to a real `PythonRuntimeProvider`. */
+    runtimeProvider?: RuntimeProvider;
+}
+export interface RunRecord {
+    schemaVersion: 1;
+    id: string;
+    status: "preparing" | "running" | "succeeded" | "failed" | "cancelled";
+    model: string;
+    modelVersion: string;
+    adapterVersion: string;
+    moldeskVersion: string;
+    runtime: RuntimeKind;
+    installationFingerprint: string;
+    manifestSha256: string;
+    hardware: SystemReport;
+    /** `role` is `"job"` for the primary submitted input and the companion's
+     * declared `id` for anything staged via `resolveCompanionInputs`/
+     * `stageCompanionInputs`. Optional/additive so existing single-input records
+     * (every entry implicitly the primary input) remain valid. */
+    input: Array<{
+        originalPath: string;
+        storedPath: string;
+        sha256: string;
+        role?: string;
+    }>;
+    parameters: {
+        supplied: Record<string, unknown>;
+        effective: Record<string, unknown>;
+    };
+    command: {
+        executable: string;
+        args: string[];
+        cwd: string;
+        env?: Record<string, string>;
+    };
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    process?: {
+        pid?: number;
+        exitCode?: number;
+        signal?: string;
+    };
+    outputs: Array<{
+        id: string;
+        path: string;
+        sha256: string;
+        sizeBytes: number;
+    }>;
+    logs: {
+        stdout: string;
+        stderr: string;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface RunModelResult {
+    status: "succeeded" | "failed" | "cancelled";
+    record: RunRecord;
+    /** Set only if `--output` copy failed after an otherwise-succeeded run; see the module doc. */
+    exportError?: {
+        code: string;
+        message: string;
+    };
+}
+export declare function runModel(modelName: string, inputPath: string, options?: RunModelOptions): Promise<RunModelResult>;

package/dist/run.dynamic-defaults.test.d.ts

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

package/dist/run.dynamic-defaults.test.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getMoldeskPaths } from "@moldesk/runtime";
+import { listAvailableModels } from "@moldesk/registry";
+import { createInstallationPlan, installModel } from "./installation.js";
+/**
+ * Proves `ModelAdapterDefinition.resolveParamDefaults` (the hook `run.ts` calls
+ * before `validateParams`, per the Boltz milestone's "resolved accelerator must
+ * already be in run.json's parameters.effective" requirement): its output lands
+ * in `run.json`'s `parameters.effective`, and an explicit `--param` still wins
+ * over it. Mocks `@moldesk/adapters`'s `getAdapter` to return the real
+ * ProteinMPNN adapter augmented with a fake `resolveParamDefaults`, so the rest
+ * of `runModel`'s install/execute plumbing is exercised unchanged.
+ */
+vi.mock("@moldesk/adapters", async (importOriginal) => {
+    const actual = await importOriginal();
+    const fakeAdapter = {
+        ...actual.adapterCatalog["proteinmpnn"],
+        resolveParamDefaults: () => ({ num_seq_per_target: 5 }),
+    };
+    return {
+        ...actual,
+        getAdapter: (name) => (name === "proteinmpnn" ? fakeAdapter : actual.getAdapter(name)),
+    };
+});
+const { runModel } = await import("./run.js");
+const homes = [];
+function tempPaths() {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk core run dyn "));
+    homes.push(home);
+    return getMoldeskPaths({ MOLDESK_HOME: home });
+}
+afterEach(() => {
+    for (const home of homes.splice(0))
+        fs.rmSync(home, { recursive: true, force: true });
+});
+function successfulInstallRunner(revision) {
+    return async (command, args) => {
+        if (command === "git" && args[0] === "init") {
+            const source = args[1];
+            fs.mkdirSync(path.join(source, "vanilla_model_weights"), { recursive: true });
+            fs.mkdirSync(path.join(path.dirname(source), "assets", "vanilla_model_weights"), { recursive: true });
+            fs.writeFileSync(path.join(source, "protein_mpnn_run.py"), "# pinned source\n");
+            fs.writeFileSync(path.join(source, "vanilla_model_weights", "v_48_020.pt"), "weights");
+            fs.writeFileSync(path.join(path.dirname(source), "assets", "vanilla_model_weights", "v_48_020.pt"), "weights");
+        }
+        if (command === "git" && args.includes("rev-parse"))
+            return { code: 0, stdout: `${revision}\n`, stderr: "" };
+        if (command === "uv" && args[0] === "venv")
+            fs.mkdirSync(path.join(args.at(-1), "bin"), { recursive: true });
+        if (command === "uv" && args.includes("freeze"))
+            return { code: 0, stdout: "numpy==1.26.4\ntorch==2.2.1\n", stderr: "" };
+        if (args[0] === "--version")
+            return { code: 0, stdout: "Python 3.11.9\n", stderr: "" };
+        return { code: 0, stdout: "", stderr: "" };
+    };
+}
+async function installFixture(paths) {
+    const manifest = { ...listAvailableModels().find((item) => item.name === "proteinmpnn"), assets: [] };
+    const runtime = manifest.runtimes.find((item) => item.kind === "python");
+    const planned = await createInstallationPlan(manifest, runtime, paths);
+    await installModel(planned, { paths, runner: successfulInstallRunner(manifest.source.revision), uvExecutable: "uv" });
+}
+function fakeProvider(behavior) {
+    return {
+        kind: "python",
+        async inspect() {
+            return { kind: "python", available: true };
+        },
+        async prepare(request) {
+            return { kind: "python", executable: request.targetDir, fingerprint: request.runtimeFingerprint };
+        },
+        async execute(request) {
+            request.onSpawn?.(4242);
+            return behavior(request);
+        },
+        async remove() { },
+    };
+}
+function writeSequenceOutput(request) {
+    const seqsDir = path.join(request.cwd, "output", "seqs");
+    fs.mkdirSync(seqsDir, { recursive: true });
+    fs.writeFileSync(path.join(seqsDir, "input.fa"), ">input\nMKV\n");
+}
+function writeInputFixture(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+    const inputPath = path.join(dir, "input.pdb");
+    fs.writeFileSync(inputPath, "ATOM      1  N   MET A   1\n");
+    return inputPath;
+}
+describe("runModel dynamic param defaults (resolveParamDefaults)", () => {
+    it("merges resolveParamDefaults's output into run.json's parameters.effective when the caller supplied nothing for that key", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        const result = await runModel("proteinmpnn", inputPath, {
+            paths,
+            runtimeProvider: fakeProvider((request) => {
+                writeSequenceOutput(request);
+                return { exitCode: 0, stdoutPath: path.join(request.cwd, "stdout.log"), stderrPath: path.join(request.cwd, "stderr.log") };
+            }),
+        });
+        expect(result.status).toBe("succeeded");
+        expect(result.record.parameters.effective.num_seq_per_target).toBe(5);
+        expect(result.record.parameters.supplied.num_seq_per_target).toBeUndefined();
+    });
+    it("lets an explicit --param override resolveParamDefaults's value", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        const result = await runModel("proteinmpnn", inputPath, {
+            paths,
+            params: { num_seq_per_target: "9" },
+            runtimeProvider: fakeProvider((request) => {
+                writeSequenceOutput(request);
+                return { exitCode: 0, stdoutPath: path.join(request.cwd, "stdout.log"), stderrPath: path.join(request.cwd, "stderr.log") };
+            }),
+        });
+        expect(result.status).toBe("succeeded");
+        expect(result.record.parameters.effective.num_seq_per_target).toBe(9);
+    });
+});

package/dist/run.js

@@ -0,0 +1,222 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { getAdapter, validateParams } from "@moldesk/adapters";
+import { listAvailableModels } from "@moldesk/registry";
+import { getMoldeskPaths, getSystemReport, redactEnv, runDir, stageCompanionInputs, PythonRuntimeProvider, } from "@moldesk/runtime";
+import { MoldeskError } from "./errors.js";
+import { digest, sha256File } from "./hash.js";
+import { listInstalledModels } from "./install-state.js";
+import { VERSION } from "./version.js";
+function runFailure(code, message, remediation, details) {
+    return new MoldeskError({ code, message, remediation, details });
+}
+function toErrorInfo(error, fallbackCode) {
+    if (error instanceof MoldeskError)
+        return { code: error.code, message: error.message };
+    return { code: fallbackCode, message: error instanceof Error ? error.message : String(error) };
+}
+function writeRunRecord(runDirPath, record) {
+    const file = path.join(runDirPath, "run.json");
+    const temporary = `${file}.tmp-${process.pid}-${randomUUID()}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+}
+export async function runModel(modelName, inputPath, options = {}) {
+    const paths = options.paths ?? getMoldeskPaths();
+    // --- Step 1: load and validate manifest. No run directory yet: a failure here rejects. ---
+    const manifest = listAvailableModels().find((entry) => entry.name === modelName);
+    if (!manifest) {
+        throw runFailure("UNKNOWN_MODEL", `Unknown model "${modelName}".`, "Run `moldesk list` to see available models.");
+    }
+    // --- Step 2: resolve a ready installation. ---
+    const allInstalled = listInstalledModels(paths).filter((record) => record.model === modelName);
+    const candidates = options.runtime ? allInstalled.filter((record) => record.runtime.kind === options.runtime) : allInstalled;
+    if (candidates.length === 0) {
+        throw runFailure("MODEL_NOT_INSTALLED", options.runtime
+            ? `${modelName} is not installed for the "${options.runtime}" runtime.`
+            : `${modelName} is not installed.`, `Run \`moldesk install ${modelName}\`.`);
+    }
+    if (!options.runtime && candidates.length > 1) {
+        throw runFailure("RUN_RUNTIME_SELECTION_REQUIRED", `${modelName} has ${candidates.length} installed runtime variants.`, "Pass --runtime python|docker to select one.");
+    }
+    const installed = candidates[0];
+    if (installed.runtime.kind !== "python" || !installed.runtime.python) {
+        throw runFailure("RUNTIME_EXECUTION_UNSUPPORTED", `Running ${modelName} via the "${installed.runtime.kind}" runtime is not yet supported.`, "Install and run a Python-runtime variant of this model instead.");
+    }
+    // --- Step 3: validate input and params. Still no run directory: failures here reject. ---
+    const adapter = getAdapter(modelName);
+    if (!adapter) {
+        throw runFailure("ADAPTER_NOT_FOUND", `No adapter is registered for ${modelName}.`, "Repair the registry installation.");
+    }
+    const resolvedInputPath = path.resolve(inputPath);
+    await adapter.validateInput(resolvedInputPath);
+    // Platform-dependent defaults (e.g. Boltz's `accelerator`) come from the adapter,
+    // not a static `ParamDescriptor.default`, since the right value depends on which
+    // platform-specific runtime entry was actually installed. Pre-seed `supplied` with
+    // them (as strings, since `validateParams` coerces from `--param` strings) for any
+    // key the caller didn't explicitly pass — an explicit `--param` always wins.
+    const dynamicDefaults = adapter.resolveParamDefaults?.({ manifestName: manifest.name, installed }) ?? {};
+    const suppliedParams = { ...(options.params ?? {}) };
+    for (const [key, value] of Object.entries(dynamicDefaults)) {
+        if (suppliedParams[key] === undefined)
+            suppliedParams[key] = String(value);
+    }
+    const { effective: effectiveParams, errors: paramErrors } = validateParams(adapter.params ?? [], suppliedParams);
+    if (paramErrors.length > 0) {
+        throw runFailure("INVALID_RUN_PARAMS", paramErrors.join("; "), "Fix the listed --param values and retry.", { errors: paramErrors });
+    }
+    // --- Step 4: allocate run ID and directory. From here on, every outcome resolves. ---
+    const runId = `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomUUID()}`;
+    const runDirPath = runDir(runId, { MOLDESK_HOME: paths.home });
+    const inputDir = path.join(runDirPath, "input");
+    const outputDir = path.join(runDirPath, "output");
+    fs.mkdirSync(inputDir, { recursive: true });
+    fs.mkdirSync(outputDir, { recursive: true });
+    // --- Step 5: copy/snapshot the original input. ---
+    const storedInputPath = path.join(inputDir, path.basename(resolvedInputPath));
+    fs.copyFileSync(resolvedInputPath, storedInputPath);
+    const inputSha256 = await sha256File(storedInputPath);
+    const inputRecords = [
+        { originalPath: resolvedInputPath, storedPath: storedInputPath, sha256: inputSha256, role: "job" },
+    ];
+    // Models whose job file references separate companion files (e.g. DiffDock-L's
+    // protein PDB + ligand file) declare them via `resolveCompanionInputs`, given the
+    // *original* (pre-copy) resolved job path so relative references resolve against
+    // where the job file actually lives. Absent means unchanged single-file behavior.
+    const companionRefs = await adapter.resolveCompanionInputs?.(resolvedInputPath) ?? [];
+    const stagedCompanions = companionRefs.length > 0
+        ? stageCompanionInputs({ jobFilePath: resolvedInputPath, refs: companionRefs, inputDir })
+        : [];
+    for (const staged of stagedCompanions) {
+        inputRecords.push({
+            originalPath: staged.originalPath,
+            storedPath: staged.storedPath,
+            sha256: await sha256File(staged.storedPath),
+            role: staged.id,
+        });
+    }
+    const companionInputs = stagedCompanions.map((staged) => ({ id: staged.id, path: staged.storedPath }));
+    const hardware = await getSystemReport();
+    const startedAt = new Date().toISOString();
+    const record = {
+        schemaVersion: 1,
+        id: runId,
+        status: "preparing",
+        model: manifest.name,
+        modelVersion: manifest.modelVersion,
+        adapterVersion: manifest.adapterVersion,
+        moldeskVersion: VERSION,
+        runtime: installed.runtime.kind,
+        installationFingerprint: installed.runtime.fingerprint,
+        manifestSha256: digest(manifest),
+        hardware,
+        input: inputRecords,
+        parameters: { supplied: options.params ?? {}, effective: effectiveParams },
+        command: { executable: "", args: [], cwd: runDirPath },
+        startedAt,
+        outputs: [],
+        logs: { stdout: path.join(runDirPath, "stdout.log"), stderr: path.join(runDirPath, "stderr.log") },
+    };
+    // --- Step 6: write the initial record. From this point, every path below finalizes run.json. ---
+    writeRunRecord(runDirPath, record);
+    try {
+        // --- Step 7: build the structured command. ---
+        const commandSpec = await adapter.command({
+            manifestName: manifest.name,
+            inputPath: storedInputPath,
+            outputDir,
+            modelDir: installed.installDir,
+            assetsDir: path.join(installed.installDir, "assets"),
+            params: effectiveParams,
+            runtimeExecutable: installed.runtime.python.executable,
+            platform: installed.runtime.python.platform,
+            ...(companionInputs.length > 0 ? { companionInputs } : {}),
+        });
+        record.command = {
+            executable: commandSpec.executable,
+            args: commandSpec.args,
+            cwd: runDirPath,
+            ...(commandSpec.env ? { env: redactEnv(commandSpec.env) } : {}),
+        };
+        // --- Step 8: execute. Rewritten to "running" with a real pid the instant the process spawns. ---
+        const provider = options.runtimeProvider ?? new PythonRuntimeProvider();
+        const execution = await provider.execute({
+            executable: commandSpec.executable,
+            args: commandSpec.args,
+            cwd: runDirPath,
+            env: commandSpec.env,
+            signal: options.signal,
+            onSpawn: (pid) => {
+                record.status = "running";
+                record.process = { pid };
+                writeRunRecord(runDirPath, record);
+            },
+            // --- Step 9: live log tee for the CLI; the provider itself persists stdout.log/stderr.log. ---
+            onStdout: (chunk) => options.onLog?.("stdout", chunk),
+            onStderr: (chunk) => options.onLog?.("stderr", chunk),
+        });
+        record.logs = { stdout: execution.stdoutPath, stderr: execution.stderrPath };
+        // `execution.pid` is optional per `ExecutionResult`; fall back to the pid already
+        // captured via `onSpawn` rather than letting a provider that omits it erase the record.
+        record.process = { pid: execution.pid ?? record.process?.pid, exitCode: execution.exitCode, signal: execution.signal };
+        // --- Step 11: exit-code precedence — cancelled, then nonzero exit, then "exit 0 isn't sufficient". ---
+        if (execution.cancelled) {
+            record.status = "cancelled";
+            record.error = { code: "RUN_CANCELLED", message: "Run was cancelled." };
+        }
+        else if (execution.exitCode !== 0) {
+            record.status = "failed";
+            record.error = {
+                code: "RUN_EXECUTION_FAILED",
+                message: `${modelName} exited with code ${execution.exitCode}.`,
+            };
+        }
+        else {
+            const collected = await adapter.collectOutputs({
+                manifestName: manifest.name,
+                inputPath: storedInputPath,
+                outputDir,
+                modelDir: installed.installDir,
+                assetsDir: path.join(installed.installDir, "assets"),
+                params: effectiveParams,
+                runtimeExecutable: installed.runtime.python.executable,
+                platform: installed.runtime.python.platform,
+                ...(companionInputs.length > 0 ? { companionInputs } : {}),
+            });
+            // --- Step 12: checksum + size each output. ---
+            record.outputs = await Promise.all(collected.map(async (output) => ({
+                id: output.id,
+                path: output.path,
+                sha256: await sha256File(output.path),
+                sizeBytes: fs.statSync(output.path).size,
+            })));
+            record.status = "succeeded";
+        }
+    }
+    catch (error) {
+        record.status = options.signal?.aborted ? "cancelled" : "failed";
+        record.error = toErrorInfo(error, "RUN_EXECUTION_FAILED");
+    }
+    // --- Step 13: write the final record atomically. ---
+    const finishedAt = new Date().toISOString();
+    record.finishedAt = finishedAt;
+    record.durationMs = Date.parse(finishedAt) - Date.parse(startedAt);
+    writeRunRecord(runDirPath, record);
+    const result = { status: record.status, record };
+    // --- --output: a distinct, post-finalization copy step; never changes the run's own status. ---
+    if (result.status === "succeeded" && options.outputDir) {
+        try {
+            fs.mkdirSync(options.outputDir, { recursive: true });
+            for (const output of record.outputs) {
+                const target = path.join(options.outputDir, path.basename(output.path));
+                fs.copyFileSync(output.path, target, fs.constants.COPYFILE_EXCL);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            result.exportError = { code: "OUTPUT_COLLISION", message };
+        }
+    }
+    return result;
+}

package/dist/run.test.d.ts

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

package/dist/run.test.js

@@ -0,0 +1,210 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { getMoldeskPaths } from "@moldesk/runtime";
+import { listAvailableModels } from "@moldesk/registry";
+import { createInstallationPlan, installModel } from "./installation.js";
+import { runModel } from "./run.js";
+const homes = [];
+function tempPaths() {
+    // Intentionally includes a space to exercise the "paths containing spaces" requirement.
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk core run "));
+    homes.push(home);
+    return getMoldeskPaths({ MOLDESK_HOME: home });
+}
+afterEach(() => {
+    for (const home of homes.splice(0))
+        fs.rmSync(home, { recursive: true, force: true });
+});
+function successfulInstallRunner(revision) {
+    return async (command, args) => {
+        if (command === "git" && args[0] === "init") {
+            const source = args[1];
+            fs.mkdirSync(path.join(source, "vanilla_model_weights"), { recursive: true });
+            fs.mkdirSync(path.join(path.dirname(source), "assets", "vanilla_model_weights"), { recursive: true });
+            fs.writeFileSync(path.join(source, "protein_mpnn_run.py"), "# pinned source\n");
+            fs.writeFileSync(path.join(source, "vanilla_model_weights", "v_48_020.pt"), "weights");
+            fs.writeFileSync(path.join(path.dirname(source), "assets", "vanilla_model_weights", "v_48_020.pt"), "weights");
+        }
+        if (command === "git" && args.includes("rev-parse"))
+            return { code: 0, stdout: `${revision}\n`, stderr: "" };
+        if (command === "uv" && args[0] === "venv")
+            fs.mkdirSync(path.join(args.at(-1), "bin"), { recursive: true });
+        if (command === "uv" && args.includes("freeze"))
+            return { code: 0, stdout: "numpy==1.26.4\ntorch==2.2.1\n", stderr: "" };
+        if (args[0] === "--version")
+            return { code: 0, stdout: "Python 3.11.9\n", stderr: "" };
+        return { code: 0, stdout: "", stderr: "" };
+    };
+}
+/** Installs a real ProteinMPNN fixture (fake install commands, no network) so `runModel` has a genuine `InstalledModel` to resolve. */
+async function installFixture(paths) {
+    const manifest = { ...listAvailableModels().find((item) => item.name === "proteinmpnn"), assets: [] };
+    const runtime = manifest.runtimes.find((item) => item.kind === "python");
+    const planned = await createInstallationPlan(manifest, runtime, paths);
+    await installModel(planned, { paths, runner: successfulInstallRunner(manifest.source.revision), uvExecutable: "uv" });
+    return planned.targetDir;
+}
+/** A fake RuntimeProvider whose `execute()` is fully scripted by the test. */
+function fakeProvider(behavior) {
+    return {
+        kind: "python",
+        async inspect() {
+            return { kind: "python", available: true };
+        },
+        async prepare(request) {
+            return { kind: "python", executable: request.targetDir, fingerprint: request.runtimeFingerprint };
+        },
+        async execute(request) {
+            request.onSpawn?.(4242);
+            return behavior(request);
+        },
+        async remove() { },
+    };
+}
+function writeSequenceOutput(request) {
+    const seqsDir = path.join(request.cwd, "output", "seqs");
+    fs.mkdirSync(seqsDir, { recursive: true });
+    fs.writeFileSync(path.join(seqsDir, "input.fa"), ">input\nMKV\n");
+}
+function writeInputFixture(dir, name = "input.pdb") {
+    fs.mkdirSync(dir, { recursive: true });
+    const inputPath = path.join(dir, name);
+    fs.writeFileSync(inputPath, "ATOM      1  N   MET A   1\n");
+    return inputPath;
+}
+describe("runModel", () => {
+    it("succeeds end-to-end, checksumming outputs and finalizing run.json", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        const result = await runModel("proteinmpnn", inputPath, {
+            paths,
+            runtimeProvider: fakeProvider((request) => {
+                writeSequenceOutput(request);
+                return { exitCode: 0, stdoutPath: path.join(request.cwd, "stdout.log"), stderrPath: path.join(request.cwd, "stderr.log") };
+            }),
+        });
+        expect(result.status).toBe("succeeded");
+        expect(result.record.outputs).toHaveLength(1);
+        expect(result.record.outputs[0].sha256).toMatch(/^[0-9a-f]{64}$/);
+        expect(result.record.process?.pid).toBe(4242);
+        const onDisk = JSON.parse(fs.readFileSync(path.join(result.record.command.cwd, "run.json"), "utf8"));
+        expect(onDisk.status).toBe("succeeded");
+    }, 15000);
+    it("fails on nonzero exit without attempting output collection", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        let collectAttempted = false;
+        const result = await runModel("proteinmpnn", inputPath, {
+            paths,
+            runtimeProvider: fakeProvider((request) => {
+                // Deliberately do NOT write an output file; if collectOutputs ran, it would throw
+                // MISSING_REQUIRED_OUTPUT instead of leaving RUN_EXECUTION_FAILED as the error.
+                collectAttempted = fs.existsSync(path.join(request.cwd, "output", "seqs"));
+                return { exitCode: 1, stdoutPath: path.join(request.cwd, "stdout.log"), stderrPath: path.join(request.cwd, "stderr.log") };
+            }),
+        });
+        expect(collectAttempted).toBe(false);
+        expect(result.status).toBe("failed");
+        expect(result.record.error?.code).toBe("RUN_EXECUTION_FAILED");
+        expect(result.record.outputs).toHaveLength(0);
+    });
+    it("fails on missing required output despite exit code 0", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        const result = await runModel("proteinmpnn", inputPath, {
+            paths,
+            runtimeProvider: fakeProvider((request) => ({
+                exitCode: 0,
+                stdoutPath: path.join(request.cwd, "stdout.log"),
+                stderrPath: path.join(request.cwd, "stderr.log"),
+            })),
+        });
+        expect(result.status).toBe("failed");
+        expect(result.record.error?.code).toBe("MISSING_REQUIRED_OUTPUT");
+    });
+    it("rejects for an invalid (non-.pdb) input before allocating a run directory", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home, "input.txt");
+        await expect(runModel("proteinmpnn", inputPath, { paths })).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+        expect(fs.existsSync(paths.runs)).toBe(false);
+    });
+    it("rejects for invalid params before allocating a run directory", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        await expect(runModel("proteinmpnn", inputPath, { paths, params: { num_seq_per_target: "not-a-number" } })).rejects.toMatchObject({ code: "INVALID_RUN_PARAMS" });
+        expect(fs.existsSync(paths.runs)).toBe(false);
+    });
+    it("marks a run cancelled regardless of the reported exit code", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        const result = await runModel("proteinmpnn", inputPath, {
+            paths,
+            runtimeProvider: fakeProvider((request) => ({
+                exitCode: 0,
+                stdoutPath: path.join(request.cwd, "stdout.log"),
+                stderrPath: path.join(request.cwd, "stderr.log"),
+                cancelled: true,
+            })),
+        });
+        expect(result.status).toBe("cancelled");
+        expect(result.record.error?.code).toBe("RUN_CANCELLED");
+    });
+    it("finalizes run.json even when execution throws unexpectedly after allocation", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        const result = await runModel("proteinmpnn", inputPath, {
+            paths,
+            runtimeProvider: fakeProvider(() => {
+                throw new Error("simulated runtime crash");
+            }),
+        });
+        expect(result.status).toBe("failed");
+        expect(result.record.error?.message).toContain("simulated runtime crash");
+        expect(result.record.finishedAt).toBeDefined();
+    });
+    it("writes status:running with the real pid before execute() resolves", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        let observedMidRun;
+        await runModel("proteinmpnn", inputPath, {
+            paths,
+            runtimeProvider: fakeProvider((request) => {
+                writeSequenceOutput(request);
+                const runJsonPath = path.join(request.cwd, "run.json");
+                observedMidRun = JSON.parse(fs.readFileSync(runJsonPath, "utf8"));
+                return { exitCode: 0, stdoutPath: path.join(request.cwd, "stdout.log"), stderrPath: path.join(request.cwd, "stderr.log") };
+            }),
+        });
+        expect(observedMidRun?.status).toBe("running");
+        expect(observedMidRun?.process?.pid).toBe(4242);
+    });
+    it("copies outputs to --output and reports a collision without changing the run's own status", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        const inputPath = writeInputFixture(paths.home);
+        const exportDir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk core run export "));
+        homes.push(exportDir);
+        fs.writeFileSync(path.join(exportDir, "input.fa"), "pre-existing");
+        const result = await runModel("proteinmpnn", inputPath, {
+            paths,
+            outputDir: exportDir,
+            runtimeProvider: fakeProvider((request) => {
+                writeSequenceOutput(request);
+                return { exitCode: 0, stdoutPath: path.join(request.cwd, "stdout.log"), stderrPath: path.join(request.cwd, "stderr.log") };
+            }),
+        });
+        expect(result.status).toBe("succeeded");
+        expect(result.exportError?.code).toBe("OUTPUT_COLLISION");
+        expect(fs.readFileSync(path.join(exportDir, "input.fa"), "utf8")).toBe("pre-existing");
+    });
+});

package/dist/version.d.ts

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

package/dist/version.js

@@ -0,0 +1,9 @@
+import fs from "node:fs";
+// Read from this package's own package.json (one level above both src/ and dist/)
+// so the reported version can never drift from the published one. A hard-coded
+// constant was missed by the 0.0.2 bump and made `moldesk --version` print 0.0.1.
+function readVersion() {
+    const manifest = new URL("../package.json", import.meta.url);
+    return JSON.parse(fs.readFileSync(manifest, "utf8")).version;
+}
+export const VERSION = readVersion();

package/dist/version.test.d.ts

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