@moldesk/adapters 0.0.0-stage → 0.0.3

package/dist/boltz/index.js

@@ -0,0 +1,285 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MoldeskError } from "@moldesk/registry";
+import { runCommand } from "@moldesk/runtime";
+import { parse as parseYaml, YAMLParseError } from "yaml";
+import { collectGlobOutputs } from "../outputs.js";
+/**
+ * Boltz's CLI writes `<out_dir>/boltz_results_<input_stem>/predictions/<record_id>/…`
+ * (verified against both pinned source revisions' `src/boltz/main.py` and
+ * `src/boltz/data/write/writer.py`). The matcher in `outputs.ts` is segment-wise
+ * (`*` per path component, no `**`), so these globs are written as four precise
+ * single-segment wildcards rather than a recursive pattern.
+ */
+const OUTPUTS = [
+    { id: "structures", glob: "boltz_results_*/predictions/*/*.cif", required: true },
+    { id: "confidence", glob: "boltz_results_*/predictions/*/confidence_*.json", required: true },
+    // Only produced when an affinity checkpoint/config is used; not every job requests it.
+    { id: "affinity", glob: "boltz_results_*/predictions/*/affinity_*.json", required: false },
+];
+/**
+ * Params verified directly against the pinned CLI's `@click.option` declarations:
+ * - jwohlwend/boltz @ cb04aeccdd480fd4db707f0bbafde538397fa2ac, src/boltz/main.py
+ * - Novel-Therapeutics/boltz-community @ 401f18150cc7184b7e1bb37239a25035ef6b3a57, src/boltz/main.py
+ *
+ * `--accelerator` choices differ between the two pinned CLIs: official boltz only
+ * accepts `gpu|cpu|tpu`; boltz-community additionally accepts `mps`. Both pinned
+ * revisions define the remaining flags below identically. No static `default` is
+ * declared for `accelerator` — see `resolveParamDefaults`.
+ */
+const PARAMS = [
+    { name: "accelerator", type: "string", enum: ["gpu", "mps", "cpu"], description: "Accelerator to use for prediction (platform-dependent default; see resolveParamDefaults)" },
+    { name: "devices", type: "number", default: 1, min: 1, description: "Number of devices to use for prediction" },
+    { name: "recycling_steps", type: "number", min: 0, description: "Number of recycling steps" },
+    { name: "sampling_steps", type: "number", min: 1, description: "Number of diffusion sampling steps" },
+    { name: "diffusion_samples", type: "number", min: 1, description: "Number of diffusion samples" },
+    { name: "max_parallel_samples", type: "number", min: 1, description: "Maximum samples to predict in parallel" },
+    { name: "use_msa_server", type: "boolean", description: "Use the MMSeqs2 server for MSA generation" },
+    { name: "no_kernels", type: "boolean", description: "Disable custom kernels" },
+    { name: "seed", type: "number", description: "Random seed (omit for no seeding)" },
+];
+/** Resolves the venv's `boltz` console-script entry point, installed by `uv pip install`
+ * from the `[project.scripts]` `boltz = "boltz.main:cli"` entry both pinned distributions declare. */
+function boltzExecutable(runtimeExecutable) {
+    return path.join(path.dirname(runtimeExecutable), "boltz");
+}
+function darwinAcceleratorError(requested) {
+    return new MoldeskError({
+        code: "INVALID_RUN_PARAMS",
+        message: `--param accelerator=${requested} is not valid for this installation: the darwin-arm64 install uses boltz-community without CUDA support.`,
+        remediation: `Use --param accelerator=mps (or omit --param accelerator to use the platform default) on darwin-arm64, or "cpu".`,
+    });
+}
+function mpsOffDarwinError() {
+    return new MoldeskError({
+        code: "INVALID_RUN_PARAMS",
+        message: "--param accelerator=mps requires the darwin-arm64 (boltz-community) installation; the official boltz CLI's --accelerator does not accept \"mps\".",
+        remediation: "Use --param accelerator=gpu (or omit --param accelerator to use the platform default) or \"cpu\" on this installation.",
+    });
+}
+/** Minimal structural check: parses the document as real YAML (not a regex — a
+ * regex like `/^sequences\s*:/m` matches on malformed documents such as
+ * `sequences: [` that would fail deep inside a long Boltz run) and requires a
+ * non-empty top-level `sequences` array. Not a full Boltz job-schema validator —
+ * just enough to reject an obviously-invalid job before a long prediction run. */
+function checkYamlJobStructure(inputPath, text) {
+    if (text.trim().length === 0) {
+        throw new MoldeskError({
+            code: "INVALID_RUN_INPUT",
+            message: `Boltz job file is empty: ${inputPath}.`,
+            remediation: "Provide a non-empty .yaml job file with a top-level `sequences` key.",
+        });
+    }
+    let doc;
+    try {
+        doc = parseYaml(text);
+    }
+    catch (error) {
+        const reason = error instanceof YAMLParseError ? error.message : String(error);
+        throw new MoldeskError({
+            code: "INVALID_RUN_INPUT",
+            message: `Boltz job file is not valid YAML: ${inputPath}. ${reason}`,
+            remediation: "Fix the YAML syntax error and retry.",
+        });
+    }
+    const sequences = doc !== null && typeof doc === "object" && !Array.isArray(doc)
+        ? doc.sequences
+        : undefined;
+    if (!Array.isArray(sequences) || sequences.length === 0) {
+        throw new MoldeskError({
+            code: "INVALID_RUN_INPUT",
+            message: `Boltz job file is missing a non-empty top-level "sequences" array: ${inputPath}.`,
+            remediation: "Add a top-level `sequences` key (a non-empty list) per the Boltz job schema (see examples/boltz/).",
+        });
+    }
+}
+export const boltzAdapter = {
+    modelName: "boltz",
+    params: PARAMS,
+    async validateInput(inputPath) {
+        if (!fs.existsSync(inputPath)) {
+            throw new MoldeskError({
+                code: "INVALID_RUN_INPUT",
+                message: `Input file not found: ${inputPath}.`,
+                remediation: "Provide a path to an existing .yaml, .yml, or .fasta job file.",
+            });
+        }
+        const ext = path.extname(inputPath).toLowerCase();
+        if (![".yaml", ".yml", ".fasta"].includes(ext)) {
+            throw new MoldeskError({
+                code: "INVALID_RUN_INPUT",
+                message: `Boltz requires a .yaml, .yml, or .fasta input file, got "${ext || "(no extension)"}".`,
+                remediation: "Provide a .yaml/.yml job file or a .fasta sequence file.",
+            });
+        }
+        if (ext === ".fasta") {
+            const text = fs.readFileSync(inputPath, "utf8");
+            if (text.trim().length === 0) {
+                throw new MoldeskError({
+                    code: "INVALID_RUN_INPUT",
+                    message: `Boltz .fasta input is empty: ${inputPath}.`,
+                    remediation: "Provide a non-empty FASTA file.",
+                });
+            }
+            return;
+        }
+        checkYamlJobStructure(inputPath, fs.readFileSync(inputPath, "utf8"));
+    },
+    /**
+     * `accelerator`'s correct default depends on which platform-specific runtime entry
+     * was actually installed (`installed.runtime.python.platform`), not `process.platform`
+     * — the installed record is the source of truth. `run.ts` calls this before
+     * `validateParams` and merges the result in as an additional default.
+     */
+    resolveParamDefaults(context) {
+        const platform = context.installed.runtime.python?.platform;
+        if (platform === "darwin-arm64")
+            return { accelerator: "mps" };
+        return { accelerator: "gpu" };
+    },
+    async installPlan(_context) {
+        return {
+            steps: [
+                { id: "source", description: "Fetch the pinned Boltz source revision for this platform" },
+                { id: "python", description: "Create an isolated managed Python environment" },
+                { id: "dependencies", description: "Install pinned Python dependencies (official boltz on Linux/CUDA, boltz-community on Darwin/MPS)" },
+                { id: "postInstall", description: "Run platform-specific post-install fixups (e.g. boltz-fix-macos-libomp on Darwin)" },
+                { id: "verify", description: "Verify the CLI, checkpoints, and accelerator (CUDA/MPS) availability" },
+            ],
+        };
+    },
+    async command(context) {
+        const params = context.params;
+        const accelerator = params.accelerator;
+        if (accelerator === "mps" && context.platform !== "darwin-arm64") {
+            throw mpsOffDarwinError();
+        }
+        if (accelerator === "gpu" && context.platform === "darwin-arm64") {
+            throw darwinAcceleratorError("gpu");
+        }
+        const args = [
+            "predict",
+            context.inputPath,
+            "--out_dir", context.outputDir,
+            "--cache", path.join(context.assetsDir, "boltz-cache"),
+        ];
+        if (accelerator !== undefined)
+            args.push("--accelerator", accelerator);
+        if (params.devices !== undefined)
+            args.push("--devices", String(params.devices));
+        if (params.recycling_steps !== undefined)
+            args.push("--recycling_steps", String(params.recycling_steps));
+        if (params.sampling_steps !== undefined)
+            args.push("--sampling_steps", String(params.sampling_steps));
+        if (params.diffusion_samples !== undefined)
+            args.push("--diffusion_samples", String(params.diffusion_samples));
+        if (params.max_parallel_samples !== undefined)
+            args.push("--max_parallel_samples", String(params.max_parallel_samples));
+        if (params.use_msa_server === true)
+            args.push("--use_msa_server");
+        if (params.no_kernels === true)
+            args.push("--no_kernels");
+        if (params.seed !== undefined)
+            args.push("--seed", String(params.seed));
+        return { executable: boltzExecutable(context.runtimeExecutable), args };
+    },
+    async collectOutputs(context) {
+        return collectGlobOutputs(context.outputDir, OUTPUTS);
+    },
+    async verifyInstallation(context) {
+        const venvBin = path.join(context.modelDir, ".venv", "bin");
+        const python = path.join(venvBin, "python");
+        const boltzCli = path.join(venvBin, "boltz");
+        const cacheDir = path.join(context.assetsDir, "boltz-cache");
+        // Checkpoint/CCD assets are populated and checksum-verified at install time
+        // (see manifest `assets:`), never lazily on first run — check their presence
+        // here so a run never silently re-triggers an unverified download.
+        const requiredFiles = [
+            python,
+            boltzCli,
+            path.join(cacheDir, "mols"),
+            path.join(cacheDir, "boltz2_conf.ckpt"),
+            path.join(cacheDir, "boltz2_aff.ckpt"),
+        ];
+        const missing = requiredFiles.filter((file) => !fs.existsSync(file));
+        if (missing.length > 0)
+            return { passed: false, output: `Missing ${missing.join(", ")}` };
+        const runner = context.runner ?? runCommand;
+        const platform = context.platform ?? detectInstalledPlatform(context.modelDir);
+        const probe = platform === "darwin-arm64" ? MPS_PROBE : CUDA_PROBE;
+        const result = await runner(python, ["-c", probe], { timeoutMs: 60_000 });
+        if (result.code !== 0)
+            return { passed: false, output: result.stderr.trim() };
+        // The pinned CLI's --accelerator choices are baked in at build time (verified
+        // against source above), but assert it here too so a future dependency
+        // upgrade that silently drops "mps" from the installed CLI is caught by
+        // install verification rather than surfacing only during a run.
+        if (platform === "darwin-arm64") {
+            const help = await runner(boltzCli, ["predict", "--help"], { timeoutMs: 30_000 });
+            if (help.code !== 0 || !help.stdout.includes("mps")) {
+                return { passed: false, output: `Installed boltz CLI does not advertise an "mps" --accelerator choice: ${(help.stdout || help.stderr).trim()}` };
+            }
+        }
+        return { passed: true, output: result.stdout.trim() };
+    },
+};
+/** Fallback for when `context.platform` isn't populated (e.g. a caller invoking
+ * `verifyInstallation` directly outside the core installer): best-effort read of
+ * the installed runtime's recorded platform from `installation.json`, used only
+ * to pick which verification probe to run (CUDA vs MPS). Never guesses from
+ * `process.platform` — falls back to CUDA probing when the record can't be read, matching
+ * the Linux/CUDA path's expectations. */
+function detectInstalledPlatform(modelDir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(modelDir, "installation.json"), "utf8"));
+        return raw.runtime?.python?.platform;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Pinned distribution versions (see `models/boltz/manifest.yaml`). Kept as
+ * constants here, not read from the manifest at verify time, because
+ * `InstallContext` doesn't carry parsed manifest data — bump alongside the
+ * manifest's runtime entries' `requirements[].version`. Both distributions are
+ * installed from git (source+revision), so the manifest's `version` field
+ * isn't itself enforced by the installer (a hash check only applies to
+ * PyPI-artifact-pinned requirements, which git-sourced ones can't be) —
+ * asserting the exact installed distribution version here is what actually
+ * verifies "package version and source revision correspond" (rule 1) for
+ * these two requirements. */
+const PINNED_BOLTZ_COMMUNITY_VERSION = "2.10.12";
+const PINNED_OFFICIAL_BOLTZ_VERSION = "2.2.1";
+const CUDA_PROBE = `
+import torch, boltz
+from importlib.metadata import version
+assert torch.cuda.is_available(), "torch.cuda.is_available() is False"
+assert torch.cuda.device_count() >= 1, "no CUDA devices visible"
+assert torch.version.cuda is not None, "torch was not built with CUDA support (torch.version.cuda is None)"
+dist_version = version("boltz")
+assert dist_version == "${PINNED_OFFICIAL_BOLTZ_VERSION}", f"expected pinned boltz==${PINNED_OFFICIAL_BOLTZ_VERSION}, got {dist_version}"
+print(f"cuda ok: torch={torch.__version__} cuda_build={torch.version.cuda} devices={torch.cuda.device_count()} boltz={dist_version}")
+`.trim();
+const MPS_PROBE = `
+import platform, torch, boltz
+from importlib.metadata import version, PackageNotFoundError
+assert platform.system() == "Darwin", f"expected Darwin, got {platform.system()}"
+assert platform.machine() == "arm64", f"expected arm64, got {platform.machine()}"
+assert torch.backends.mps.is_built(), "torch was not built with MPS support"
+assert torch.backends.mps.is_available(), "MPS backend is not available on this host"
+x = torch.ones(4, device="mps") * 2
+result = x.cpu().tolist()
+assert result == [2.0, 2.0, 2.0, 2.0], f"unexpected MPS tensor op result: {result}"
+try:
+    dist_version = version("boltz-community")
+except PackageNotFoundError:
+    dist_version = None
+assert dist_version is not None, "expected the boltz-community distribution to be installed, not official boltz"
+assert dist_version == "${PINNED_BOLTZ_COMMUNITY_VERSION}", f"expected pinned boltz-community==${PINNED_BOLTZ_COMMUNITY_VERSION}, got {dist_version}"
+try:
+    official_version = version("boltz")
+except PackageNotFoundError:
+    official_version = None
+assert official_version is None, f"official boltz distribution is also installed (version {official_version}) alongside boltz-community — both expose the same boltz import/CLI and must never coexist"
+print(f"mps ok: torch={torch.__version__} boltz-community={dist_version}")
+`.trim();

package/dist/boltz/index.test.d.ts

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

package/dist/boltz/index.test.js

@@ -0,0 +1,368 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { boltzAdapter } from "./index.js";
+const dirs = [];
+function tempDir() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk-boltz-test-"));
+    dirs.push(dir);
+    return dir;
+}
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+describe("boltzAdapter.validateInput", () => {
+    it("accepts a .yaml job file with a top-level sequences key", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.yaml");
+        fs.writeFileSync(input, "sequences:\n  - protein:\n      id: A\n      sequence: MKV\n");
+        await expect(boltzAdapter.validateInput(input)).resolves.toBeUndefined();
+    });
+    it("accepts a .yml job file", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.yml");
+        fs.writeFileSync(input, "sequences:\n  - protein:\n      id: A\n      sequence: MKV\n");
+        await expect(boltzAdapter.validateInput(input)).resolves.toBeUndefined();
+    });
+    it("accepts a non-empty .fasta file without a sequences-key check", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.fasta");
+        fs.writeFileSync(input, ">A\nMKV\n");
+        await expect(boltzAdapter.validateInput(input)).resolves.toBeUndefined();
+    });
+    it("rejects a missing file", async () => {
+        await expect(boltzAdapter.validateInput(path.join(tempDir(), "missing.yaml"))).rejects.toMatchObject({
+            code: "INVALID_RUN_INPUT",
+        });
+    });
+    it("rejects an unsupported extension", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.pdb");
+        fs.writeFileSync(input, "ATOM\n");
+        await expect(boltzAdapter.validateInput(input)).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+    });
+    it("rejects an empty .yaml file", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.yaml");
+        fs.writeFileSync(input, "");
+        await expect(boltzAdapter.validateInput(input)).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+    });
+    it("rejects a .yaml file missing a top-level sequences key", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.yaml");
+        fs.writeFileSync(input, "version: 1\nname: not-a-job\n");
+        await expect(boltzAdapter.validateInput(input)).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+    });
+    it("rejects an empty .fasta file", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.fasta");
+        fs.writeFileSync(input, "   \n");
+        await expect(boltzAdapter.validateInput(input)).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+    });
+    it("rejects syntactically malformed YAML that a regex-based check would miss", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.yaml");
+        // An unclosed flow sequence — `/^sequences\s*:/m` would match this and let
+        // it through; a real YAML parser must reject it.
+        fs.writeFileSync(input, "sequences: [\n");
+        await expect(boltzAdapter.validateInput(input)).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+    });
+    it("rejects a .yaml file where sequences is not an array", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.yaml");
+        fs.writeFileSync(input, "sequences: not-a-list\n");
+        await expect(boltzAdapter.validateInput(input)).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+    });
+    it("rejects a .yaml file where sequences is an empty array", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "job.yaml");
+        fs.writeFileSync(input, "sequences: []\n");
+        await expect(boltzAdapter.validateInput(input)).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+    });
+});
+describe("boltzAdapter.resolveParamDefaults", () => {
+    it("resolves accelerator:mps for a darwin-arm64 install", () => {
+        const defaults = boltzAdapter.resolveParamDefaults({
+            manifestName: "boltz",
+            installed: { runtime: { kind: "python", python: { platform: "darwin-arm64", platformSelected: true } } },
+        });
+        expect(defaults).toEqual({ accelerator: "mps" });
+    });
+    it("resolves accelerator:gpu for a linux-x64 install", () => {
+        const defaults = boltzAdapter.resolveParamDefaults({
+            manifestName: "boltz",
+            installed: { runtime: { kind: "python", python: { platform: "linux-x64", platformSelected: true } } },
+        });
+        expect(defaults).toEqual({ accelerator: "gpu" });
+    });
+});
+describe("boltzAdapter.command", () => {
+    it("builds the expected boltz predict invocation", async () => {
+        const spec = await boltzAdapter.command({
+            manifestName: "boltz",
+            inputPath: "/run/input/job.yaml",
+            outputDir: "/run/output",
+            modelDir: "/models/boltz",
+            assetsDir: "/models/boltz/assets",
+            params: {
+                accelerator: "gpu",
+                devices: 1,
+                recycling_steps: 3,
+                sampling_steps: 200,
+                diffusion_samples: 1,
+                max_parallel_samples: 5,
+                use_msa_server: true,
+                no_kernels: false,
+                seed: 42,
+            },
+            runtimeExecutable: "/models/boltz/.venv/bin/python",
+            platform: "linux-x64",
+        });
+        expect(spec.executable).toBe(path.join("/models/boltz/.venv/bin", "boltz"));
+        expect(spec.args[0]).toBe("predict");
+        expect(spec.args[1]).toBe("/run/input/job.yaml");
+        expect(spec.args).toContain("--out_dir");
+        expect(spec.args).toContain("/run/output");
+        expect(spec.args).toContain("--cache");
+        expect(spec.args).toContain(path.join("/models/boltz/assets", "boltz-cache"));
+        expect(spec.args).toContain("--accelerator");
+        expect(spec.args).toContain("gpu");
+        expect(spec.args).toContain("--devices");
+        expect(spec.args).toContain("--recycling_steps");
+        expect(spec.args).toContain("--sampling_steps");
+        expect(spec.args).toContain("--diffusion_samples");
+        expect(spec.args).toContain("--max_parallel_samples");
+        expect(spec.args).toContain("--use_msa_server");
+        expect(spec.args).not.toContain("--no_kernels");
+        expect(spec.args).toContain("--seed");
+        expect(spec.args).toContain("42");
+    });
+    it("omits boolean flags when false", async () => {
+        const spec = await boltzAdapter.command({
+            manifestName: "boltz",
+            inputPath: "/run/input/job.yaml",
+            outputDir: "/run/output",
+            modelDir: "/models/boltz",
+            assetsDir: "/models/boltz/assets",
+            params: { accelerator: "mps", use_msa_server: false, no_kernels: false },
+            runtimeExecutable: "/models/boltz/.venv/bin/python",
+            platform: "darwin-arm64",
+        });
+        expect(spec.args).not.toContain("--use_msa_server");
+        expect(spec.args).not.toContain("--no_kernels");
+    });
+    it("rejects accelerator=mps on a non-darwin-arm64 installation", async () => {
+        await expect(boltzAdapter.command({
+            manifestName: "boltz",
+            inputPath: "/run/input/job.yaml",
+            outputDir: "/run/output",
+            modelDir: "/models/boltz",
+            assetsDir: "/models/boltz/assets",
+            params: { accelerator: "mps" },
+            runtimeExecutable: "/models/boltz/.venv/bin/python",
+            platform: "linux-x64",
+        })).rejects.toMatchObject({ code: "INVALID_RUN_PARAMS" });
+    });
+    it("rejects accelerator=gpu on a darwin-arm64 installation", async () => {
+        await expect(boltzAdapter.command({
+            manifestName: "boltz",
+            inputPath: "/run/input/job.yaml",
+            outputDir: "/run/output",
+            modelDir: "/models/boltz",
+            assetsDir: "/models/boltz/assets",
+            params: { accelerator: "gpu" },
+            runtimeExecutable: "/models/boltz/.venv/bin/python",
+            platform: "darwin-arm64",
+        })).rejects.toMatchObject({ code: "INVALID_RUN_PARAMS" });
+    });
+});
+describe("boltzAdapter.collectOutputs", () => {
+    function writePrediction(outputDir, options = {}) {
+        const predDir = path.join(outputDir, "boltz_results_job", "predictions", "record1");
+        fs.mkdirSync(predDir, { recursive: true });
+        fs.writeFileSync(path.join(predDir, "record1_model_0.cif"), "data_record1\n");
+        fs.writeFileSync(path.join(predDir, "confidence_record1_model_0.json"), "{}");
+        if (options.withAffinity) {
+            fs.writeFileSync(path.join(predDir, "affinity_record1.json"), "{}");
+        }
+    }
+    it("collects structures, confidence, and (when present) affinity outputs", async () => {
+        const dir = tempDir();
+        const outputDir = path.join(dir, "output");
+        writePrediction(outputDir, { withAffinity: true });
+        const outputs = await boltzAdapter.collectOutputs({
+            manifestName: "boltz",
+            inputPath: path.join(dir, "input", "job.yaml"),
+            outputDir,
+            modelDir: dir,
+            assetsDir: path.join(dir, "assets"),
+            params: {},
+            runtimeExecutable: "python",
+        });
+        expect(outputs.map((o) => o.id).sort()).toEqual(["affinity", "confidence", "structures"]);
+    });
+    it("succeeds without affinity output since it is not required", async () => {
+        const dir = tempDir();
+        const outputDir = path.join(dir, "output");
+        writePrediction(outputDir);
+        const outputs = await boltzAdapter.collectOutputs({
+            manifestName: "boltz",
+            inputPath: path.join(dir, "input", "job.yaml"),
+            outputDir,
+            modelDir: dir,
+            assetsDir: path.join(dir, "assets"),
+            params: {},
+            runtimeExecutable: "python",
+        });
+        expect(outputs.map((o) => o.id).sort()).toEqual(["confidence", "structures"]);
+    });
+    it("throws MISSING_REQUIRED_OUTPUT when no .cif files were produced", async () => {
+        const dir = tempDir();
+        const outputDir = path.join(dir, "output");
+        fs.mkdirSync(outputDir, { recursive: true });
+        await expect(boltzAdapter.collectOutputs({
+            manifestName: "boltz",
+            inputPath: path.join(dir, "input", "job.yaml"),
+            outputDir,
+            modelDir: dir,
+            assetsDir: path.join(dir, "assets"),
+            params: {},
+            runtimeExecutable: "python",
+        })).rejects.toMatchObject({ code: "MISSING_REQUIRED_OUTPUT" });
+    });
+});
+describe("boltzAdapter.verifyInstallation", () => {
+    /** Creates the venv scripts + the three install-time-populated cache assets
+     * (mols/, boltz2_conf.ckpt, boltz2_aff.ckpt) verifyInstallation now requires
+     * to exist before running any probe. */
+    function createInstalledFixture(dir, assetsDir) {
+        fs.mkdirSync(path.join(dir, ".venv", "bin"), { recursive: true });
+        fs.writeFileSync(path.join(dir, ".venv", "bin", "python"), "#!/bin/sh\n");
+        fs.writeFileSync(path.join(dir, ".venv", "bin", "boltz"), "#!/bin/sh\n");
+        const cacheDir = path.join(assetsDir, "boltz-cache");
+        fs.mkdirSync(path.join(cacheDir, "mols"), { recursive: true });
+        fs.writeFileSync(path.join(cacheDir, "boltz2_conf.ckpt"), "");
+        fs.writeFileSync(path.join(cacheDir, "boltz2_aff.ckpt"), "");
+    }
+    it("fails when the venv's boltz console script is missing", async () => {
+        const dir = tempDir();
+        fs.mkdirSync(path.join(dir, ".venv", "bin"), { recursive: true });
+        fs.writeFileSync(path.join(dir, ".venv", "bin", "python"), "#!/bin/sh\n");
+        const result = await boltzAdapter.verifyInstallation({ manifestName: "boltz", modelDir: dir, assetsDir: path.join(dir, "assets") });
+        expect(result.passed).toBe(false);
+        expect(result.output).toContain("boltz");
+    });
+    it("fails when the install-time-populated checkpoint/CCD cache is missing, even with a working venv", async () => {
+        const dir = tempDir();
+        fs.mkdirSync(path.join(dir, ".venv", "bin"), { recursive: true });
+        fs.writeFileSync(path.join(dir, ".venv", "bin", "python"), "#!/bin/sh\n");
+        fs.writeFileSync(path.join(dir, ".venv", "bin", "boltz"), "#!/bin/sh\n");
+        // No boltz-cache/ populated — checkpoints/CCD must be verified present
+        // before a run is ever allowed, never lazily downloaded at run time.
+        const result = await boltzAdapter.verifyInstallation({
+            manifestName: "boltz",
+            modelDir: dir,
+            assetsDir: path.join(dir, "assets"),
+            runner: async () => ({ code: 0, stdout: "should not run", stderr: "" }),
+        });
+        expect(result.passed).toBe(false);
+        expect(result.output).toContain("boltz-cache");
+    });
+    it("runs the CUDA probe via the injected runner when no installation.json platform is recorded", async () => {
+        const dir = tempDir();
+        const assetsDir = path.join(dir, "assets");
+        createInstalledFixture(dir, assetsDir);
+        let capturedScript = "";
+        const result = await boltzAdapter.verifyInstallation({
+            manifestName: "boltz",
+            modelDir: dir,
+            assetsDir,
+            runner: async (_cmd, args) => {
+                capturedScript = args[1] ?? "";
+                return { code: 0, stdout: "cuda ok", stderr: "" };
+            },
+        });
+        expect(result.passed).toBe(true);
+        expect(capturedScript).toContain("torch.cuda.is_available()");
+        expect(capturedScript).toContain("torch.version.cuda is not None");
+        expect(capturedScript).toContain('== "2.2.1"');
+    });
+    it("runs the MPS probe when installation.json records a darwin-arm64 platform", async () => {
+        const dir = tempDir();
+        const assetsDir = path.join(dir, "assets");
+        createInstalledFixture(dir, assetsDir);
+        fs.writeFileSync(path.join(dir, "installation.json"), JSON.stringify({ runtime: { python: { platform: "darwin-arm64" } } }));
+        let capturedScript = "";
+        const result = await boltzAdapter.verifyInstallation({
+            manifestName: "boltz",
+            modelDir: dir,
+            assetsDir,
+            runner: async (cmd, args) => {
+                if (cmd.endsWith("boltz"))
+                    return { code: 0, stdout: "--accelerator [gpu|cpu|tpu|mps]", stderr: "" };
+                capturedScript = args[1] ?? "";
+                return { code: 0, stdout: "mps ok", stderr: "" };
+            },
+        });
+        expect(result.passed).toBe(true);
+        expect(capturedScript).toContain("torch.backends.mps.is_available()");
+        expect(capturedScript).toContain('== "2.10.12"');
+        expect(capturedScript).toContain('official_version is None');
+    });
+    it("runs the MPS probe from context.platform even with no installation.json (pre-promotion staging verify)", async () => {
+        const dir = tempDir();
+        const assetsDir = path.join(dir, "assets");
+        createInstalledFixture(dir, assetsDir);
+        // No installation.json written yet — this is the staging-directory verify call
+        // the core installer makes BEFORE promotion, so installation.json cannot exist.
+        // The adapter must trust context.platform here, not fall back to CUDA.
+        let capturedScript = "";
+        const result = await boltzAdapter.verifyInstallation({
+            manifestName: "boltz",
+            modelDir: dir,
+            assetsDir,
+            platform: "darwin-arm64",
+            runner: async (cmd, args) => {
+                if (cmd.endsWith("boltz"))
+                    return { code: 0, stdout: "--accelerator [gpu|cpu|tpu|mps]", stderr: "" };
+                capturedScript = args[1] ?? "";
+                return { code: 0, stdout: "mps ok", stderr: "" };
+            },
+        });
+        expect(result.passed).toBe(true);
+        expect(capturedScript).toContain("torch.backends.mps.is_available()");
+    });
+    it("fails when the installed CLI doesn't advertise an mps accelerator choice", async () => {
+        const dir = tempDir();
+        const assetsDir = path.join(dir, "assets");
+        createInstalledFixture(dir, assetsDir);
+        const result = await boltzAdapter.verifyInstallation({
+            manifestName: "boltz",
+            modelDir: dir,
+            assetsDir,
+            platform: "darwin-arm64",
+            runner: async (cmd) => {
+                if (cmd.endsWith("boltz"))
+                    return { code: 0, stdout: "--accelerator [gpu|cpu|tpu]", stderr: "" };
+                return { code: 0, stdout: "mps ok", stderr: "" };
+            },
+        });
+        expect(result.passed).toBe(false);
+        expect(result.output).toContain("mps");
+    });
+    it("reports failure output when the probe fails", async () => {
+        const dir = tempDir();
+        const assetsDir = path.join(dir, "assets");
+        createInstalledFixture(dir, assetsDir);
+        const result = await boltzAdapter.verifyInstallation({
+            manifestName: "boltz",
+            modelDir: dir,
+            assetsDir,
+            runner: async () => ({ code: 1, stdout: "", stderr: "MPS backend is not available on this host" }),
+        });
+        expect(result.passed).toBe(false);
+        expect(result.output).toContain("MPS backend is not available");
+    });
+});

package/dist/catalog.d.ts

@@ -0,0 +1,6 @@
+import type { ModelAdapterDefinition } from "./index.js";
+import type { ModelManifestV1 } from "@moldesk/registry";
+export declare const adapterCatalog: Record<string, ModelAdapterDefinition>;
+export declare function getAdapter(modelName: string): ModelAdapterDefinition | undefined;
+export declare function hasAdapter(modelName: string): boolean;
+export declare function validateAdapterCatalog(manifests: ReadonlyArray<Pick<ModelManifestV1, "name" | "status">>, catalog?: Record<string, ModelAdapterDefinition>): string[];