@moldesk/core 0.0.1 → 0.0.3

package/dist/installation.d.ts

@@ -0,0 +1,74 @@
+import { type InstallPlan } from "@moldesk/adapters";
+import { type InstallCommandRunner, type InstallProgress, type AssetFetch, type MoldeskPaths } from "@moldesk/runtime";
+import { type ModelManifestV1, type PlatformId, type RuntimeSpec, type SourceSpec } from "@moldesk/registry";
+import { type InstalledModel } from "./install-state.js";
+export interface InstallationPlanResult {
+    readonly manifest: ModelManifestV1;
+    /** The runtime entry actually selected for install: for a platform-aware python
+     * manifest (more than one python `runtimes[]` entry, or one declaring
+     * `platforms`), this is re-derived from `manifest.runtimes` for the current host
+     * platform, which may differ from the `runtime` argument passed in beyond its
+     * `kind`. Legacy single-entry, no-`platforms` manifests keep the argument as-is. */
+    readonly runtime: RuntimeSpec;
+    /** The runtime's effective source: its own per-entry `source` override when
+     * present, otherwise `manifest.source`. Always defined when planning succeeds. */
+    readonly effectiveSource: SourceSpec;
+    /** The host platform `runtime` was resolved for, when determinable. `undefined`
+     * for a docker runtime or a host outside the supported `PlatformId` set. */
+    readonly resolvedPlatform?: PlatformId;
+    readonly runtimeFingerprint: string;
+    readonly targetDir: string;
+    readonly plan: InstallPlan;
+    readonly alreadyInstalled: boolean;
+    readonly estimatedDownloadBytes: number;
+    readonly estimatedDiskBytes: number;
+    /** True when some contributor to the download estimate (an asset or the runtime
+     * itself) declares no size, e.g. a Python dependency resolution whose transfer
+     * size can't be known ahead of running `uv pip install`. An unknown size must be
+     * treated as cost-worthy, not as zero. */
+    readonly downloadSizeUnknown: boolean;
+    /** Same as {@link downloadSizeUnknown}, for additional disk usage. */
+    readonly diskSizeUnknown: boolean;
+}
+export interface InstallModelOptions {
+    paths?: MoldeskPaths;
+    reinstall?: boolean;
+    runner?: InstallCommandRunner;
+    fetch?: AssetFetch;
+    uvExecutable?: string;
+    onProgress?: (progress: InstallProgress) => void;
+}
+export interface InstallModelResult {
+    status: "installed" | "already-installed" | "reinstalled";
+    installation: InstalledModel;
+}
+export interface UninstallModelOptions {
+    paths?: MoldeskPaths;
+    runtime?: RuntimeSpec["kind"];
+    all?: boolean;
+}
+export declare function runtimeFingerprint(runtime: RuntimeSpec): string;
+/** v0.1 defaults per the implementation spec: prompt at >= 1 GiB download or >= 5 GiB
+ * additional disk. Kept as constants so the policy can change without touching adapters. */
+export declare const INSTALL_CONFIRMATION_DOWNLOAD_BYTES: number;
+export declare const INSTALL_CONFIRMATION_DISK_BYTES: number;
+export interface InstallCostEstimate {
+    downloadBytes: number;
+    downloadSizeUnknown: boolean;
+    diskBytes: number;
+    diskSizeUnknown: boolean;
+}
+/**
+ * Centralized, cost-aware install confirmation policy. An unknown size (as opposed
+ * to a size known to be zero) always requires confirmation, since it cannot be shown
+ * to be small. A destructive replacement (--reinstall of an existing installation)
+ * always requires confirmation regardless of size.
+ */
+export declare function requiresInstallConfirmation(cost: InstallCostEstimate, options?: {
+    destructive?: boolean;
+}): boolean;
+export declare function createInstallationPlan(manifest: ModelManifestV1, runtime: RuntimeSpec, paths?: MoldeskPaths, options?: {
+    platform?: PlatformId;
+}): Promise<InstallationPlanResult>;
+export declare function installModel(planned: InstallationPlanResult, options?: InstallModelOptions): Promise<InstallModelResult>;
+export declare function uninstallModel(modelName: string, options?: UninstallModelOptions): Promise<InstalledModel[]>;

package/dist/installation.js

@@ -0,0 +1,310 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { getAdapter } from "@moldesk/adapters";
+import { cacheAsset, getMoldeskPaths, materializeAsset, managedUvDownloadBytes, modelInstallDir, prepareDockerImage, preparePythonEnvironment, temporaryInstallDir, } from "@moldesk/runtime";
+import { detectHostPlatformId, effectiveRuntimeSource, selectPythonRuntime, } from "@moldesk/registry";
+import { MoldeskError } from "./errors.js";
+import { digest } from "./hash.js";
+import { listInstalledModels, rebuildInstallState, writeInstallState, readInstallState, } from "./install-state.js";
+export function runtimeFingerprint(runtime) {
+    return `${runtime.kind}-${digest({ runtime, platform: process.platform, architecture: process.arch })}`;
+}
+function environmentFingerprint(data) {
+    return digest(data);
+}
+/** v0.1 defaults per the implementation spec: prompt at >= 1 GiB download or >= 5 GiB
+ * additional disk. Kept as constants so the policy can change without touching adapters. */
+export const INSTALL_CONFIRMATION_DOWNLOAD_BYTES = 1 * 1024 ** 3;
+export const INSTALL_CONFIRMATION_DISK_BYTES = 5 * 1024 ** 3;
+/**
+ * Centralized, cost-aware install confirmation policy. An unknown size (as opposed
+ * to a size known to be zero) always requires confirmation, since it cannot be shown
+ * to be small. A destructive replacement (--reinstall of an existing installation)
+ * always requires confirmation regardless of size.
+ */
+export function requiresInstallConfirmation(cost, options = {}) {
+    if (options.destructive)
+        return true;
+    if (cost.downloadSizeUnknown || cost.diskSizeUnknown)
+        return true;
+    return cost.downloadBytes >= INSTALL_CONFIRMATION_DOWNLOAD_BYTES || cost.diskBytes >= INSTALL_CONFIRMATION_DISK_BYTES;
+}
+function installFailure(code, message, remediation, details) {
+    return new MoldeskError({ code, message, remediation, details });
+}
+/**
+ * Resolves the python runtime entry to actually install for `platform`.
+ *
+ * A legacy manifest whose `runtimes[]` has a single python entry with no
+ * `platforms` field (e.g. ProteinMPNN, LigandMPNN) trusts `requested` as-is,
+ * exactly as before per-platform runtime entries existed — this keeps every
+ * pre-existing manifest and caller (including tests that construct a synthetic
+ * runtime variant not literally present in `manifest.runtimes`, to exercise
+ * fingerprint coexistence) behaving identically.
+ *
+ * Any manifest that is platform-aware — more than one python `runtimes[]` entry,
+ * or a single entry that declares `platforms` — has its installed entry re-derived
+ * from `manifest.runtimes` for the current host platform via `selectPythonRuntime`,
+ * ignoring the literal identity of `requested` beyond its `kind`, and failing
+ * closed (before any staging directory is created) on zero or multiple matches.
+ */
+function resolvePythonRuntimeForInstall(manifest, requested, platform) {
+    const pythonEntries = manifest.runtimes.filter((r) => r.kind === "python");
+    const platformAware = pythonEntries.length > 1 || pythonEntries.some((r) => r.platforms !== undefined);
+    if (!platformAware)
+        return requested;
+    return selectPythonRuntime(manifest.runtimes, platform);
+}
+async function withModelLock(paths, key, operation) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(key)) {
+        throw installFailure("UNSAFE_MODEL_ID", `Unsafe installation lock key: ${JSON.stringify(key)}.`, "Use a lowercase model id from `moldesk list`.");
+    }
+    fs.mkdirSync(paths.locks, { recursive: true });
+    const lock = path.join(paths.locks, `${key}.lock`);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            fs.mkdirSync(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let stale = false;
+            try {
+                const owner = JSON.parse(fs.readFileSync(path.join(lock, "owner.json"), "utf8"));
+                if (typeof owner.startedAt === "string" && Date.now() - Date.parse(owner.startedAt) > 24 * 60 * 60_000)
+                    stale = true;
+                if (typeof owner.pid === "number") {
+                    try {
+                        process.kill(owner.pid, 0);
+                    }
+                    catch (error) {
+                        stale ||= error.code === "ESRCH";
+                    }
+                }
+            }
+            catch {
+                stale = true;
+            }
+            if (stale && attempt === 0) {
+                fs.rmSync(lock, { recursive: true, force: true });
+                continue;
+            }
+            throw installFailure("INSTALL_LOCKED", `Another operation is already changing ${key}.`, "Wait for it to finish, then retry.", { lock });
+        }
+    }
+    fs.writeFileSync(path.join(lock, "owner.json"), JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+    try {
+        return await operation();
+    }
+    finally {
+        fs.rmSync(lock, { recursive: true, force: true });
+    }
+}
+export async function createInstallationPlan(manifest, runtime, paths = getMoldeskPaths(), options = {}) {
+    const adapter = getAdapter(manifest.name);
+    if (!adapter) {
+        throw installFailure("ADAPTER_NOT_FOUND", `No installation adapter is registered for ${manifest.name}.`, "Choose an installable model from `moldesk list`.");
+    }
+    // Resolve the platform-specific runtime entry (and its effective source) before
+    // doing anything else, including before computing the fingerprint/targetDir that
+    // depend on it — fails closed via selectPythonRuntime's MoldeskError for a
+    // platform-aware manifest with zero or multiple matches.
+    const resolvedPlatform = options.platform ?? detectHostPlatformId();
+    const resolvedRuntime = runtime.kind === "python"
+        ? resolvePythonRuntimeForInstall(manifest, runtime, resolvedPlatform)
+        : runtime;
+    const effectiveSource = resolvedRuntime.kind === "python"
+        ? effectiveRuntimeSource(manifest, resolvedRuntime)
+        : manifest.source;
+    if (!effectiveSource) {
+        throw installFailure("SOURCE_PROVENANCE_MISSING", `${manifest.name} has no pinned source provenance.`, "The registry entry must include a repository and immutable revision.");
+    }
+    const fingerprint = runtimeFingerprint(resolvedRuntime);
+    const targetDir = modelInstallDir(manifest.name, manifest.modelVersion, fingerprint, { MOLDESK_HOME: paths.home });
+    const adapterPlan = await adapter.installPlan({ manifestName: manifest.name, modelDir: targetDir, assetsDir: path.join(targetDir, "assets") });
+    const plan = Object.freeze({ steps: Object.freeze([...adapterPlan.steps]) });
+    const assets = manifest.assets ?? [];
+    const assetDownloadBytes = assets.reduce((sum, asset) => sum + (asset.sizeBytes ?? 0), 0);
+    const assetSizeUnknown = assets.some((asset) => asset.sizeBytes === undefined);
+    // A Python runtime's estimatedDownloadBytes/estimatedDiskBytes describe dependency
+    // resolution cost that can't be known ahead of running `uv pip install`; treat an
+    // undeclared estimate as unknown rather than silently rounding it to zero.
+    const runtimeDownloadUnknown = resolvedRuntime.estimatedDownloadBytes === undefined;
+    const runtimeDiskUnknown = resolvedRuntime.estimatedDiskBytes === undefined;
+    return Object.freeze({
+        manifest,
+        runtime: resolvedRuntime,
+        effectiveSource,
+        resolvedPlatform: resolvedRuntime.kind === "python" ? resolvedPlatform : undefined,
+        runtimeFingerprint: fingerprint,
+        targetDir,
+        plan,
+        alreadyInstalled: listInstalledModels(paths).some((record) => record.installDir === targetDir),
+        estimatedDownloadBytes: assetDownloadBytes + (resolvedRuntime.estimatedDownloadBytes ?? 0) +
+            (resolvedRuntime.kind === "python" ? managedUvDownloadBytes(paths) : 0),
+        estimatedDiskBytes: resolvedRuntime.estimatedDiskBytes ?? 0,
+        downloadSizeUnknown: assetSizeUnknown || runtimeDownloadUnknown,
+        diskSizeUnknown: runtimeDiskUnknown,
+    });
+}
+export async function installModel(planned, options = {}) {
+    const paths = options.paths ?? getMoldeskPaths();
+    const { manifest, runtime, effectiveSource, resolvedPlatform, runtimeFingerprint: fingerprint, targetDir } = planned;
+    const key = `${manifest.name}-${manifest.modelVersion}-${fingerprint}`;
+    return withModelLock(paths, key, async () => {
+        const adapter = getAdapter(manifest.name);
+        if (!adapter || !effectiveSource)
+            throw installFailure("ADAPTER_NOT_FOUND", `Cannot install ${manifest.name}.`, "Repair the registry installation.");
+        const existing = listInstalledModels(paths).find((record) => record.installDir === targetDir);
+        if (existing && !options.reinstall) {
+            const verification = await adapter.verifyInstallation({ manifestName: manifest.name, modelDir: targetDir, assetsDir: path.join(targetDir, "assets"), runner: options.runner, ...(resolvedPlatform !== undefined ? { platform: resolvedPlatform } : {}) });
+            if (verification.passed)
+                return { status: "already-installed", installation: existing };
+            throw installFailure("INSTALLATION_DAMAGED", `${manifest.name} is installed but verification failed: ${verification.output ?? "unknown reason"}.`, `Run \`moldesk install ${manifest.name} --reinstall --yes\`.`);
+        }
+        fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+        const staging = temporaryInstallDir(targetDir);
+        const backup = `${targetDir}.backup-${randomUUID()}`;
+        let promoted = false;
+        let backedUp = false;
+        try {
+            let dependencyLock = [];
+            let runtimeVersion = "";
+            let postInstall = [];
+            if (runtime.kind === "python") {
+                const prepared = await preparePythonEnvironment({
+                    targetDir: staging,
+                    repository: effectiveSource.repository,
+                    revision: effectiveSource.revision,
+                    runtime,
+                    runner: options.runner,
+                    fetch: options.fetch,
+                    paths,
+                    uvExecutable: options.uvExecutable,
+                    onProgress: options.onProgress,
+                });
+                dependencyLock = prepared.lock;
+                runtimeVersion = prepared.pythonVersion;
+                postInstall = prepared.postInstall;
+            }
+            else {
+                const prepared = await prepareDockerImage(runtime, options.runner);
+                dependencyLock = [prepared.image];
+                runtimeVersion = prepared.digest;
+            }
+            fs.mkdirSync(path.join(staging, "assets"), { recursive: true });
+            for (const asset of manifest.assets ?? []) {
+                const object = await cacheAsset(asset, paths, { fetch: options.fetch, onProgress: options.onProgress });
+                await materializeAsset(asset, object, path.join(staging, "assets"));
+            }
+            options.onProgress?.({ step: "verify", message: "Verifying installation" });
+            const verification = await adapter.verifyInstallation({ manifestName: manifest.name, modelDir: staging, assetsDir: path.join(staging, "assets"), runner: options.runner, ...(resolvedPlatform !== undefined ? { platform: resolvedPlatform } : {}) });
+            if (!verification.passed) {
+                throw installFailure("INSTALL_VERIFICATION_FAILED", `Verification failed for ${manifest.name}: ${verification.output ?? "unknown reason"}.`, "Review logs and retry with --reinstall.");
+            }
+            const now = new Date().toISOString();
+            const record = {
+                schemaVersion: 1,
+                installationId: randomUUID(),
+                model: manifest.name,
+                displayName: manifest.displayName,
+                modelVersion: manifest.modelVersion,
+                adapterVersion: manifest.adapterVersion,
+                runtime: {
+                    kind: runtime.kind,
+                    fingerprint,
+                    ...(runtime.kind === "python" ? {
+                        python: {
+                            version: runtimeVersion,
+                            executable: path.join(targetDir, ".venv", "bin", "python"),
+                            lockSha256: digest(dependencyLock),
+                            ...(resolvedPlatform !== undefined ? { platform: resolvedPlatform } : {}),
+                            platformSelected: runtime.platforms !== undefined,
+                            postInstall,
+                        },
+                    } : { docker: { image: runtime.image, digest: runtime.digest } }),
+                },
+                environmentFingerprint: environmentFingerprint({
+                    runtime,
+                    runtimeVersion,
+                    dependencyLock,
+                    sourceRevision: effectiveSource.revision,
+                    platform: process.platform,
+                    architecture: process.arch,
+                    release: os.release(),
+                }),
+                installDir: targetDir,
+                source: effectiveSource,
+                assets: (manifest.assets ?? []).map((asset) => ({
+                    id: asset.id,
+                    path: path.join(targetDir, "assets", asset.target),
+                    sha256: asset.sha256.toLowerCase(),
+                    sizeBytes: asset.sizeBytes ?? 0,
+                })),
+                manifestSha256: digest(manifest),
+                verification: { passed: true, ...(verification.output ? { output: verification.output } : {}) },
+                dependencyLock,
+                installedAt: existing?.installedAt ?? now,
+                verifiedAt: now,
+                status: "ready",
+            };
+            fs.writeFileSync(path.join(staging, "installation.json"), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+            if (fs.existsSync(targetDir)) {
+                fs.renameSync(targetDir, backup);
+                backedUp = true;
+            }
+            fs.renameSync(staging, targetDir);
+            promoted = true;
+            rebuildInstallState(paths);
+            if (backedUp)
+                fs.rmSync(backup, { recursive: true, force: true });
+            return { status: existing ? "reinstalled" : "installed", installation: record };
+        }
+        catch (error) {
+            if (promoted)
+                fs.rmSync(targetDir, { recursive: true, force: true });
+            if (backedUp && fs.existsSync(backup))
+                fs.renameSync(backup, targetDir);
+            fs.rmSync(staging, { recursive: true, force: true });
+            throw error;
+        }
+    });
+}
+export async function uninstallModel(modelName, options = {}) {
+    const paths = options.paths ?? getMoldeskPaths();
+    return withModelLock(paths, modelName, async () => {
+        const allRecords = readInstallState(paths).installations.filter((record) => record.model === modelName);
+        const records = options.runtime ? allRecords.filter((record) => record.runtime.kind === options.runtime) : allRecords;
+        if (records.length === 0)
+            return [];
+        if (!options.runtime && !options.all && records.length > 1) {
+            throw installFailure("RUNTIME_SELECTION_REQUIRED", `${modelName} has ${records.length} installed runtime variants.`, `Pass --runtime python|docker to remove one variant, or --all to remove all variants.`);
+        }
+        const moved = [];
+        const priorState = readInstallState(paths);
+        try {
+            for (const record of records) {
+                const expected = modelInstallDir(record.model, record.modelVersion, record.runtime.fingerprint, { MOLDESK_HOME: paths.home });
+                if (fs.existsSync(expected)) {
+                    const trash = `${expected}.removing-${randomUUID()}`;
+                    fs.renameSync(expected, trash);
+                    moved.push({ from: expected, to: trash });
+                }
+            }
+            rebuildInstallState(paths);
+            for (const item of moved)
+                fs.rmSync(item.to, { recursive: true, force: true });
+            return records;
+        }
+        catch (error) {
+            for (const item of moved.reverse())
+                if (fs.existsSync(item.to))
+                    fs.renameSync(item.to, item.from);
+            writeInstallState(priorState, paths);
+            throw error;
+        }
+    });
+}

package/dist/installation.test.d.ts

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

package/dist/installation.test.js

@@ -0,0 +1,268 @@
+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 { listInstalledModels } from "./install-state.js";
+import { createInstallationPlan, installModel, requiresInstallConfirmation, uninstallModel, INSTALL_CONFIRMATION_DISK_BYTES, INSTALL_CONFIRMATION_DOWNLOAD_BYTES, } from "./installation.js";
+const homes = [];
+function tempPaths() {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk-core-install-"));
+    homes.push(home);
+    return getMoldeskPaths({ MOLDESK_HOME: home });
+}
+afterEach(() => {
+    for (const home of homes.splice(0))
+        fs.rmSync(home, { recursive: true, force: true });
+});
+function successfulRunner(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: "" };
+    };
+}
+describe("model installation lifecycle", () => {
+    it("installs atomically, persists state, is idempotent, reinstalls, and uninstalls", async () => {
+        const paths = tempPaths();
+        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);
+        const runner = successfulRunner(manifest.source.revision);
+        const installed = await installModel(planned, { paths, runner, uvExecutable: "uv" });
+        expect(installed.status).toBe("installed");
+        expect(fs.existsSync(path.join(planned.targetDir, "installation.json"))).toBe(true);
+        expect(listInstalledModels(paths)).toHaveLength(1);
+        fs.writeFileSync(path.join(paths.state, "installed-models.json"), "not json");
+        expect(listInstalledModels(paths)).toHaveLength(1);
+        await expect(installModel(planned, { paths, runner, uvExecutable: "uv" })).resolves.toMatchObject({ status: "already-installed" });
+        const sentinel = path.join(planned.targetDir, "keep-on-failed-reinstall");
+        fs.writeFileSync(sentinel, "keep");
+        const failingRunner = async (command, args, options) => {
+            if (command === "uv" && args[0] === "pip" && args[1] === "install")
+                return { code: 2, stdout: "", stderr: "resolver failed" };
+            return runner(command, args, options);
+        };
+        await expect(installModel(planned, { paths, runner: failingRunner, uvExecutable: "uv", reinstall: true })).rejects.toMatchObject({ code: "INSTALL_COMMAND_FAILED" });
+        expect(fs.readFileSync(sentinel, "utf8")).toBe("keep");
+        fs.rmSync(path.join(planned.targetDir, "assets", "vanilla_model_weights", "v_48_020.pt"));
+        await expect(installModel(planned, { paths, runner, uvExecutable: "uv" })).rejects.toMatchObject({ code: "INSTALLATION_DAMAGED" });
+        await expect(installModel(planned, { paths, runner, uvExecutable: "uv", reinstall: true })).resolves.toMatchObject({ status: "reinstalled" });
+        const removed = await uninstallModel("proteinmpnn", { paths });
+        expect(removed).toHaveLength(1);
+        expect(fs.existsSync(planned.targetDir)).toBe(false);
+        expect(listInstalledModels(paths)).toEqual([]);
+    });
+    it("lets two runtime fingerprints of the same model version coexist and be selected independently", async () => {
+        const paths = tempPaths();
+        const base = listAvailableModels().find((item) => item.name === "proteinmpnn");
+        const manifest = { ...base, assets: [] };
+        const pythonRuntime = manifest.runtimes.find((item) => item.kind === "python");
+        const otherRuntime = { ...pythonRuntime, python: "3.12" };
+        const runner = successfulRunner(manifest.source.revision);
+        const plannedA = await createInstallationPlan(manifest, pythonRuntime, paths);
+        const plannedB = await createInstallationPlan(manifest, otherRuntime, paths);
+        expect(plannedA.runtimeFingerprint).not.toBe(plannedB.runtimeFingerprint);
+        expect(plannedA.targetDir).not.toBe(plannedB.targetDir);
+        const installedA = await installModel(plannedA, { paths, runner, uvExecutable: "uv" });
+        const installedB = await installModel(plannedB, { paths, runner, uvExecutable: "uv" });
+        expect(installedA.status).toBe("installed");
+        expect(installedB.status).toBe("installed");
+        expect(fs.existsSync(plannedA.targetDir)).toBe(true);
+        expect(fs.existsSync(plannedB.targetDir)).toBe(true);
+        const installed = listInstalledModels(paths);
+        expect(installed).toHaveLength(2);
+        expect(new Set(installed.map((record) => record.runtime.fingerprint)).size).toBe(2);
+        // Neither variant may be removed by an unqualified uninstall while more than one exists.
+        await expect(uninstallModel("proteinmpnn", { paths })).rejects.toMatchObject({ code: "RUNTIME_SELECTION_REQUIRED" });
+        const removedAll = await uninstallModel("proteinmpnn", { paths, all: true });
+        expect(removedAll).toHaveLength(2);
+        expect(fs.existsSync(plannedA.targetDir)).toBe(false);
+        expect(fs.existsSync(plannedB.targetDir)).toBe(false);
+        expect(listInstalledModels(paths)).toEqual([]);
+    });
+    it("rolls back a failed fresh installation", async () => {
+        const paths = tempPaths();
+        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);
+        const base = successfulRunner(manifest.source.revision);
+        const runner = async (command, args, options) => {
+            if (command === "uv" && args[0] === "pip" && args[1] === "install")
+                return { code: 2, stdout: "", stderr: "resolver failed" };
+            return base(command, args, options);
+        };
+        await expect(installModel(planned, { paths, runner, uvExecutable: "uv" })).rejects.toMatchObject({ code: "INSTALL_COMMAND_FAILED" });
+        expect(fs.existsSync(planned.targetDir)).toBe(false);
+        expect(listInstalledModels(paths)).toEqual([]);
+        expect(fs.existsSync(path.dirname(planned.targetDir)) ? fs.readdirSync(path.dirname(planned.targetDir)).some((name) => name.includes(".partial-")) : false).toBe(false);
+    });
+});
+/** A synthetic two-platform manifest built on the registered "proteinmpnn" adapter
+ * (so `installPlan`/`verifyInstallation` resolve) but with two platform-scoped
+ * python runtime entries and distinct per-entry `source` overrides, exactly the
+ * shape a future dual-runtime manifest (e.g. Boltz) will use. */
+function dualPlatformManifest() {
+    const base = listAvailableModels().find((item) => item.name === "proteinmpnn");
+    const darwinSource = { repository: "https://github.com/example/darwin-fork", revision: "a".repeat(40) };
+    const linuxSource = { repository: "https://github.com/example/linux-official", revision: "b".repeat(40) };
+    const runtimes = [
+        {
+            kind: "python",
+            python: "3.11",
+            installer: "uv",
+            platforms: ["darwin-arm64"],
+            source: darwinSource,
+            postInstall: ["boltz-fix-macos-libomp"],
+            requirements: [{ name: "torch", version: "2.6.0" }],
+        },
+        {
+            kind: "python",
+            python: "3.11",
+            installer: "uv",
+            platforms: ["linux-x64"],
+            source: linuxSource,
+            requirements: [{ name: "torch", version: "2.2.1" }],
+        },
+    ];
+    return { ...base, source: undefined, assets: [], runtimes };
+}
+function dualPlatformRunner() {
+    // Tracks the revision most recently fetched, so `rev-parse HEAD` can echo it back
+    // correctly regardless of which of the two entries' distinct revisions is being
+    // installed in a given call.
+    let lastFetchedRevision = "";
+    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("fetch")) {
+            lastFetchedRevision = args.at(-1);
+        }
+        if (command === "git" && args.includes("rev-parse"))
+            return { code: 0, stdout: `${lastFetchedRevision}\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: "torch==2.2.1\n", stderr: "" };
+        if (args[0] === "--version")
+            return { code: 0, stdout: "Python 3.11.9\n", stderr: "" };
+        if (command.endsWith("boltz-fix-macos-libomp"))
+            return { code: 0, stdout: "fixed libomp\n", stderr: "" };
+        return { code: 0, stdout: "", stderr: "" };
+    };
+}
+describe("platform-aware runtime selection", () => {
+    it("resolves the darwin-arm64 entry's source/fingerprint/postInstall, and the linux-x64 entry's separately, for the same manifest", async () => {
+        const paths = tempPaths();
+        const manifest = dualPlatformManifest();
+        const darwinPlanned = await createInstallationPlan(manifest, manifest.runtimes[0], paths, { platform: "darwin-arm64" });
+        expect(darwinPlanned.effectiveSource).toEqual({ repository: "https://github.com/example/darwin-fork", revision: "a".repeat(40) });
+        expect(darwinPlanned.resolvedPlatform).toBe("darwin-arm64");
+        expect(darwinPlanned.runtime.platforms).toEqual(["darwin-arm64"]);
+        const linuxPlanned = await createInstallationPlan(manifest, manifest.runtimes[1], paths, { platform: "linux-x64" });
+        expect(linuxPlanned.effectiveSource).toEqual({ repository: "https://github.com/example/linux-official", revision: "b".repeat(40) });
+        expect(linuxPlanned.resolvedPlatform).toBe("linux-x64");
+        expect(darwinPlanned.targetDir).not.toBe(linuxPlanned.targetDir);
+        expect(darwinPlanned.runtimeFingerprint).not.toBe(linuxPlanned.runtimeFingerprint);
+    });
+    it("resolves the correct entry regardless of which same-kind candidate the caller passed in (core re-derives from the manifest, not caller identity)", async () => {
+        const paths = tempPaths();
+        const manifest = dualPlatformManifest();
+        // Pass the LINUX entry as `runtime` while requesting the DARWIN platform — core
+        // must still resolve the darwin entry, proving selection is platform-driven.
+        const planned = await createInstallationPlan(manifest, manifest.runtimes[1], paths, { platform: "darwin-arm64" });
+        expect(planned.effectiveSource.repository).toBe("https://github.com/example/darwin-fork");
+    });
+    it("fails closed with RUNTIME_PLATFORM_UNSUPPORTED before creating any staging directory on an unsupported OS/arch", async () => {
+        const paths = tempPaths();
+        const manifest = dualPlatformManifest();
+        manifest.runtimes = [manifest.runtimes[1]]; // only the linux-x64 entry remains
+        await expect(createInstallationPlan(manifest, manifest.runtimes[0], paths, { platform: "darwin-arm64" }))
+            .rejects.toMatchObject({ code: "RUNTIME_PLATFORM_UNSUPPORTED" });
+        expect(fs.existsSync(paths.models) ? fs.readdirSync(paths.models) : []).toEqual([]);
+    });
+    it("fails closed with RUNTIME_SELECTION_AMBIGUOUS when two entries both match the same platform", async () => {
+        const paths = tempPaths();
+        const manifest = dualPlatformManifest();
+        manifest.runtimes = [
+            manifest.runtimes[0],
+            { ...manifest.runtimes[0], python: "3.12" },
+        ];
+        await expect(createInstallationPlan(manifest, manifest.runtimes[0], paths, { platform: "darwin-arm64" }))
+            .rejects.toMatchObject({ code: "RUNTIME_SELECTION_AMBIGUOUS" });
+    });
+    it("runs postInstall only for the platform entry that declares it, and records platform/postInstall/source provenance", async () => {
+        const paths = tempPaths();
+        const manifest = dualPlatformManifest();
+        const runner = dualPlatformRunner();
+        const darwinPlanned = await createInstallationPlan(manifest, manifest.runtimes[0], paths, { platform: "darwin-arm64" });
+        const darwinInstalled = await installModel(darwinPlanned, { paths, runner, uvExecutable: "uv" });
+        expect(darwinInstalled.installation.runtime.python?.platform).toBe("darwin-arm64");
+        expect(darwinInstalled.installation.runtime.python?.platformSelected).toBe(true);
+        expect(darwinInstalled.installation.runtime.python?.postInstall).toEqual([
+            { hook: "boltz-fix-macos-libomp", stdout: "fixed libomp\n", stderr: "" },
+        ]);
+        expect(darwinInstalled.installation.source).toEqual({ repository: "https://github.com/example/darwin-fork", revision: "a".repeat(40) });
+        const linuxPlanned = await createInstallationPlan(manifest, manifest.runtimes[1], paths, { platform: "linux-x64" });
+        const linuxInstalled = await installModel(linuxPlanned, { paths, runner, uvExecutable: "uv" });
+        expect(linuxInstalled.installation.runtime.python?.platform).toBe("linux-x64");
+        expect(linuxInstalled.installation.runtime.python?.postInstall).toEqual([]);
+        expect(linuxInstalled.installation.source).toEqual({ repository: "https://github.com/example/linux-official", revision: "b".repeat(40) });
+    });
+    it("keeps legacy single-entry, no-platforms manifests fully unaffected: the passed-in runtime is trusted as-is, no selection is performed", async () => {
+        const paths = tempPaths();
+        const manifest = { ...listAvailableModels().find((item) => item.name === "proteinmpnn"), assets: [] };
+        // A synthetic runtime variant not literally present in manifest.runtimes (mirrors
+        // the pre-existing "two fingerprints coexist" test) — since this manifest has
+        // exactly one python entry with no `platforms` field, it must be trusted as-is,
+        // not re-derived from manifest.runtimes.
+        const runtime = { ...manifest.runtimes.find((item) => item.kind === "python"), python: "3.12" };
+        const planned = await createInstallationPlan(manifest, runtime, paths, { platform: "linux-x64" });
+        expect(planned.runtime).toBe(runtime);
+        expect(planned.effectiveSource).toEqual(manifest.source);
+        expect(planned.resolvedPlatform).toBe("linux-x64");
+    });
+});
+describe("requiresInstallConfirmation", () => {
+    const knownSmall = { downloadBytes: 180_000_000, downloadSizeUnknown: false, diskBytes: 1_100_000_000, diskSizeUnknown: false };
+    it("does not require confirmation for a known small install", () => {
+        expect(requiresInstallConfirmation(knownSmall)).toBe(false);
+    });
+    it("requires confirmation at/above the download threshold", () => {
+        expect(requiresInstallConfirmation({ ...knownSmall, downloadBytes: INSTALL_CONFIRMATION_DOWNLOAD_BYTES })).toBe(true);
+        expect(requiresInstallConfirmation({ ...knownSmall, downloadBytes: INSTALL_CONFIRMATION_DOWNLOAD_BYTES - 1 })).toBe(false);
+    });
+    it("requires confirmation at/above the disk threshold", () => {
+        expect(requiresInstallConfirmation({ ...knownSmall, diskBytes: INSTALL_CONFIRMATION_DISK_BYTES })).toBe(true);
+        expect(requiresInstallConfirmation({ ...knownSmall, diskBytes: INSTALL_CONFIRMATION_DISK_BYTES - 1 })).toBe(false);
+    });
+    it("treats an unknown size as confirmation-worthy even when the known bytes are small", () => {
+        expect(requiresInstallConfirmation({ ...knownSmall, downloadSizeUnknown: true })).toBe(true);
+        expect(requiresInstallConfirmation({ ...knownSmall, diskSizeUnknown: true })).toBe(true);
+    });
+    it("always requires confirmation for a destructive replacement, regardless of size", () => {
+        expect(requiresInstallConfirmation(knownSmall, { destructive: true })).toBe(true);
+        expect(requiresInstallConfirmation({ downloadBytes: 0, downloadSizeUnknown: false, diskBytes: 0, diskSizeUnknown: false }, { destructive: true })).toBe(true);
+    });
+});