@moldesk/core 0.0.5 → 0.0.6

package/dist/cloud/state.test.js

@@ -0,0 +1,199 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { CloudJournal, cloudResourceName } from "./state.js";
+const dirs = [];
+const RUN = "2026-10-13T11-55-45-123Z-0a1b2c3d-1111-2222-3333-444455556666";
+function tempFile() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk cloud journal "));
+    dirs.push(dir);
+    return path.join(dir, "cloud.sqlite");
+}
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+function clock(start = "2026-10-13T12:00:00.000Z") {
+    let ms = Date.parse(start);
+    return { now: () => new Date(ms).toISOString(), advance: (seconds) => void (ms += seconds * 1000) };
+}
+const job = {
+    runId: RUN,
+    accountScope: "acct1",
+    quoteDigest: "q".repeat(64),
+    cachePolicy: "ephemeral",
+    gpuId: "NVIDIA A40",
+    datacenterId: "EU-RO-1",
+    deadlineAt: "2026-10-13T13:00:00.000Z",
+    manifestDigest: "m".repeat(64),
+};
+describe("CloudJournal", () => {
+    it("keeps a stable client id across reopen and rejects a newer schema", () => {
+        const file = tempFile();
+        const first = CloudJournal.openFile(file);
+        const id = first.clientId;
+        first.close();
+        const second = CloudJournal.openFile(file);
+        expect(second.clientId).toBe(id);
+        expect(id).toMatch(/^[0-9a-f-]{36}$/);
+        second.close();
+    });
+    it("tracks a job through stages and survives reopen", () => {
+        const file = tempFile();
+        const journal = CloudJournal.openFile(file);
+        const created = journal.createJob(job);
+        expect(created).toMatchObject({ stage: "approved", status: "active", gpuId: "NVIDIA A40", volumeId: null });
+        journal.updateJob(RUN, { stage: "running", volumeId: "vol1", transferState: "none" });
+        journal.close();
+        const reopened = CloudJournal.openFile(file);
+        expect(reopened.getJob(RUN)).toMatchObject({ stage: "running", volumeId: "vol1", transferState: "none" });
+        expect(reopened.listOpenJobs().map((j) => j.runId)).toEqual([RUN]);
+        reopened.updateJob(RUN, { stage: "done", status: "cleanup_pending", error: { code: "CLOUD_CLEANUP_PENDING", message: "x" } });
+        expect(reopened.getJob(RUN).error).toEqual({ code: "CLOUD_CLEANUP_PENDING", message: "x" });
+        expect(reopened.listOpenJobs()).toHaveLength(1);
+        reopened.updateJob(RUN, { status: "succeeded", error: null });
+        expect(reopened.listOpenJobs()).toHaveLength(0);
+        expect(() => reopened.updateJob("missing", { stage: "done" })).toThrow(/No cloud job/);
+        reopened.close();
+    });
+    it("persists resource intent before the provider call and reconstructs it after a crash", () => {
+        const file = tempFile();
+        const first = CloudJournal.openFile(file);
+        first.createJob(job);
+        const intent = first.recordResourceIntent({ runId: RUN, role: "gpu", deadlineAt: job.deadlineAt });
+        expect(intent).toMatchObject({ state: "create_pending", providerId: null });
+        expect(intent.name).toBe(cloudResourceName(first.clientId, RUN, "gpu"));
+        expect(intent.name).toMatch(/^moldesk-[0-9a-f]{8}-0a1b2c3d-gpu$/);
+        first.close(); // simulated client crash before the create response
+        const second = CloudJournal.openFile(file);
+        expect(second.listResources({ states: ["create_pending"] }).map((r) => r.intentId)).toEqual([intent.intentId]);
+        const active = second.recordResourceCreated(intent.intentId, "pod1");
+        expect(active).toMatchObject({ state: "active", providerId: "pod1" });
+        expect(second.findOwnedByProviderId("pod1")?.intentId).toBe(intent.intentId);
+        second.markResourceDeletePending(intent.intentId);
+        second.markResourceDeleted(intent.intentId);
+        expect(second.findOwnedByProviderId("pod1")).toBeUndefined();
+        second.close();
+    });
+    it("rejects illegal resource transitions", () => {
+        const journal = CloudJournal.openFile(tempFile());
+        const intent = journal.recordResourceIntent({ runId: RUN, role: "volume" });
+        journal.markResourceDeleted(intent.intentId);
+        expect(() => journal.recordResourceCreated(intent.intentId, "v1")).toThrow(/Cannot move/);
+        expect(() => journal.markResourceDeletePending("nope")).toThrow(/No cloud resource/);
+        journal.close();
+    });
+    describe("reconcile", () => {
+        it("adopts an ambiguous create that did take effect, matched by exact name", () => {
+            const journal = CloudJournal.openFile(tempFile());
+            const intent = journal.recordResourceIntent({ runId: RUN, role: "gpu" });
+            const report = journal.reconcile([{ providerId: "pod9", name: intent.name, role: "gpu" }]);
+            expect(report.adopted.map((r) => r.providerId)).toEqual(["pod9"]);
+            expect(journal.getResource(intent.intentId)).toMatchObject({ state: "active", providerId: "pod9" });
+            journal.close();
+        });
+        it("abandons a create that never took effect", () => {
+            const journal = CloudJournal.openFile(tempFile());
+            const intent = journal.recordResourceIntent({ runId: RUN, role: "gpu" });
+            const report = journal.reconcile([]);
+            expect(report.abandoned.map((r) => r.intentId)).toEqual([intent.intentId]);
+            expect(journal.getResource(intent.intentId).state).toBe("deleted");
+            journal.close();
+        });
+        it("marks resources the provider no longer has as vanished", () => {
+            const journal = CloudJournal.openFile(tempFile());
+            const intent = journal.recordResourceIntent({ runId: RUN, role: "cpu" });
+            journal.recordResourceCreated(intent.intentId, "pod1");
+            expect(journal.reconcile([]).vanished.map((r) => r.intentId)).toEqual([intent.intentId]);
+            expect(journal.getResource(intent.intentId).state).toBe("deleted");
+            journal.close();
+        });
+        it("reports, but never adopts, a provider resource that only claims this client by name", () => {
+            const journal = CloudJournal.openFile(tempFile());
+            const prefix = journal.clientId.replace(/-/g, "").slice(0, 8);
+            const lookalike = { providerId: "podX", name: `moldesk-${prefix}-deadbeef-gpu`, role: "gpu" };
+            const foreign = { providerId: "podY", name: "moldesk-ffffffff-deadbeef-gpu", role: "gpu" };
+            const unrelated = { providerId: "podZ", name: "my-own-pod", role: "gpu" };
+            const report = journal.reconcile([lookalike, foreign, unrelated]);
+            expect(report.orphaned).toEqual([lookalike]);
+            expect(journal.findOwnedByProviderId("podX")).toBeUndefined();
+            journal.close();
+        });
+        it("leaves ambiguous same-name candidates pending and flags them", () => {
+            const journal = CloudJournal.openFile(tempFile());
+            const intent = journal.recordResourceIntent({ runId: RUN, role: "gpu" });
+            const report = journal.reconcile([
+                { providerId: "a", name: intent.name, role: "gpu" },
+                { providerId: "b", name: intent.name, role: "gpu" },
+            ]);
+            expect(report.adopted).toHaveLength(0);
+            expect(report.orphaned.map((r) => r.providerId).sort()).toEqual(["a", "b"]);
+            expect(journal.getResource(intent.intentId).state).toBe("create_pending");
+            journal.close();
+        });
+        it("lists owed cleanup: delete_pending and active resources past their deadline", () => {
+            const time = clock();
+            const journal = CloudJournal.openFile(tempFile(), { now: time.now });
+            const pending = journal.recordResourceIntent({ runId: RUN, role: "gpu" });
+            journal.recordResourceCreated(pending.intentId, "pod1");
+            journal.markResourceDeletePending(pending.intentId);
+            const overdue = journal.recordResourceIntent({ runId: RUN, role: "cpu", deadlineAt: "2026-10-13T12:30:00.000Z" });
+            journal.recordResourceCreated(overdue.intentId, "pod2");
+            const view = (providerId, name, role) => ({ providerId, name, role });
+            const listing = [view("pod1", pending.name, "gpu"), view("pod2", overdue.name, "cpu")];
+            expect(journal.reconcile(listing).cleanupOwed.map((r) => r.providerId)).toEqual(["pod1"]);
+            time.advance(31 * 60);
+            expect(journal.reconcile(listing).cleanupOwed.map((r) => r.providerId).sort()).toEqual(["pod1", "pod2"]);
+            journal.close();
+        });
+    });
+    describe("caches", () => {
+        const key = { accountScope: "acct1", datacenterId: "EU-RO-1", volumeId: "vol1", cacheKey: "k".repeat(64) };
+        const base = {
+            ...key,
+            model: "boltz",
+            modelVersion: "2.2.1",
+            layoutRevision: "1",
+            manifestDigest: "m".repeat(64),
+            cachePath: "/workspace/moldesk-cache/k",
+            sizeBytes: null,
+            checksumManifestDigest: null,
+        };
+        it("only reaches READY through VERIFYING with a checksum manifest", () => {
+            const journal = CloudJournal.openFile(tempFile());
+            expect(journal.upsertCache(base).state).toBe("PREPARING");
+            expect(() => journal.setCacheState(key, "READY")).toThrow(/Cannot move/);
+            journal.setCacheState(key, "VERIFYING");
+            expect(() => journal.setCacheState(key, "READY")).toThrow(/checksum manifest/);
+            const ready = journal.setCacheState(key, "READY", { sizeBytes: 123, checksumManifestDigest: "c".repeat(64) });
+            expect(ready).toMatchObject({ state: "READY", sizeBytes: 123 });
+            journal.setCacheState(key, "FAILED");
+            expect(journal.setCacheState(key, "PREPARING").state).toBe("PREPARING");
+            journal.close();
+        });
+        it("grants a lease to one owner at a time, allows renewal, and reclaims after expiry", () => {
+            const time = clock();
+            const journal = CloudJournal.openFile(tempFile(), { now: time.now });
+            journal.upsertCache(base);
+            expect(journal.acquireCacheLease(key, "a", 60)).toBe(true);
+            expect(journal.acquireCacheLease(key, "b", 60)).toBe(false);
+            expect(journal.acquireCacheLease(key, "a", 60)).toBe(true); // renewal
+            time.advance(61);
+            expect(journal.acquireCacheLease(key, "b", 60)).toBe(true);
+            journal.releaseCacheLease(key, "a"); // not the owner: no effect
+            expect(journal.getCache(key.accountScope, key.datacenterId, key.volumeId, key.cacheKey).leaseOwner).toBe("b");
+            journal.releaseCacheLease(key, "b");
+            expect(journal.acquireCacheLease(key, "a", 60)).toBe(true);
+            journal.close();
+        });
+        it("lists and deletes cache rows", () => {
+            const journal = CloudJournal.openFile(tempFile());
+            journal.upsertCache(base);
+            expect(journal.listCaches()).toHaveLength(1);
+            journal.deleteCache(key);
+            expect(journal.listCaches()).toHaveLength(0);
+            journal.close();
+        });
+    });
+});

package/dist/cloud/worker/cache.d.ts

@@ -0,0 +1,75 @@
+import { type ModelManifestV1 } from "@moldesk/registry";
+/**
+ * On-volume model cache. Layout under `<volume>/moldesk-cache`:
+ *   objects/ and home/...   raw download cache (checksummed objects)
+ *   <key>/assets/           materialized assets
+ *   <key>/ready.json        written LAST, inside a staging directory that is then renamed into place
+ * A cache is only ever reachable as `<key>` after the rename, so an interrupted preparation can
+ * never look READY, and a mutated or partial tree is detected by re-hashing against `ready.json`.
+ */
+export declare const CACHE_DIR_NAME = "moldesk-cache";
+export declare const READY_FILE = "ready.json";
+export interface CacheFileEntry {
+    path: string;
+    sizeBytes: number;
+    sha256: string;
+}
+export interface CacheReadyMetadata {
+    version: 1;
+    cacheKey: string;
+    layoutRevision: string;
+    manifestDigest: string;
+    files: CacheFileEntry[];
+    /** Digest of the canonical file list; also recorded in the client journal. */
+    checksumManifestSha256: string;
+    sizeBytes: number;
+    preparedAt: string;
+}
+/** Changes whenever anything that affects the prepared assets changes; conservative by design. */
+export declare function cloudCacheKey(manifest: ModelManifestV1): string;
+export declare const cacheRoot: (volumeMount: string) => string;
+export declare const cacheDirFor: (root: string, key: string) => string;
+/** Hashes every regular file under `dir`; symlinks, special files and unsafe names are refused. */
+export declare function hashTree(dir: string, skip?: ReadonlySet<string>): Promise<CacheFileEntry[]>;
+/**
+ * Publishes a fully prepared staging directory (`<staging>/assets/...`) as the cache for `key`:
+ * hashes the tree, writes ready.json into staging, then atomically renames staging into place.
+ */
+export declare function publishCache(params: {
+    root: string;
+    key: string;
+    stagingDir: string;
+    manifestDigest: string;
+    layoutRevision: string;
+}): Promise<CacheReadyMetadata>;
+export type CacheVerification = {
+    ok: true;
+    metadata: CacheReadyMetadata;
+    assetsDir: string;
+} | {
+    ok: false;
+    code: "CLOUD_CACHE_MISSING" | "CLOUD_CACHE_INVALID";
+    message: string;
+};
+/** Verifies the on-volume cache before use: metadata matches this job, and every file hashes as recorded. */
+export declare function verifyCache(params: {
+    root: string;
+    key: string;
+    manifestDigest: string;
+    layoutRevision: string;
+}): Promise<CacheVerification>;
+export interface VolumeLock {
+    release(): void;
+}
+/**
+ * Advisory lock for preparing one cache, as an atomic directory with owner and expiry. An expired
+ * lock is reclaimed only when the caller asserts the previous owner is gone (`reclaimStale`).
+ */
+export declare function acquireVolumeLock(params: {
+    root: string;
+    key: string;
+    owner: string;
+    ttlSeconds: number;
+    reclaimStale?: boolean;
+    now?: () => number;
+}): VolumeLock;

package/dist/cloud/worker/cache.js

@@ -0,0 +1,152 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { effectiveRuntimeSource, selectPythonRuntime } from "@moldesk/registry";
+import { isSafeRelativePath } from "@moldesk/runtime";
+import { MoldeskError } from "../../errors.js";
+import { digest } from "../../hash.js";
+/**
+ * On-volume model cache. Layout under `<volume>/moldesk-cache`:
+ *   objects/ and home/...   raw download cache (checksummed objects)
+ *   <key>/assets/           materialized assets
+ *   <key>/ready.json        written LAST, inside a staging directory that is then renamed into place
+ * A cache is only ever reachable as `<key>` after the rename, so an interrupted preparation can
+ * never look READY, and a mutated or partial tree is detected by re-hashing against `ready.json`.
+ */
+export const CACHE_DIR_NAME = "moldesk-cache";
+export const READY_FILE = "ready.json";
+const REMOTE_PLATFORM = "linux-x64";
+/** Changes whenever anything that affects the prepared assets changes; conservative by design. */
+export function cloudCacheKey(manifest) {
+    const runtime = selectPythonRuntime(manifest.runtimes, REMOTE_PLATFORM);
+    const source = effectiveRuntimeSource(manifest, runtime);
+    return digest({
+        model: manifest.name,
+        modelVersion: manifest.modelVersion,
+        sourceRevision: source?.revision ?? null,
+        assets: (manifest.assets ?? []).map((asset) => ({ id: asset.id, sha256: asset.sha256.toLowerCase(), target: asset.target, archive: asset.archive ?? "none" })),
+        layout: manifest.cloud?.assetLayoutRevision ?? null,
+    });
+}
+export const cacheRoot = (volumeMount) => path.posix.join(volumeMount, CACHE_DIR_NAME);
+export const cacheDirFor = (root, key) => path.join(root, key);
+function cacheError(code, message, remediation) {
+    return new MoldeskError({ code, message, remediation });
+}
+/** Hashes every regular file under `dir`; symlinks, special files and unsafe names are refused. */
+export async function hashTree(dir, skip = new Set()) {
+    const files = [];
+    const walk = async (current, prefix) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const full = path.join(current, entry.name);
+            if (skip.has(relative))
+                continue;
+            const stat = fs.lstatSync(full);
+            if (stat.isSymbolicLink())
+                throw cacheError("CLOUD_CACHE_UNSAFE", `Cache contains a symlink: ${relative}.`, "The cache is rejected and will be rebuilt.");
+            if (!isSafeRelativePath(relative))
+                throw cacheError("CLOUD_CACHE_UNSAFE", `Cache contains an unsafe path: ${relative}.`, "The cache is rejected and will be rebuilt.");
+            if (stat.isDirectory())
+                await walk(full, relative);
+            else if (stat.isFile()) {
+                const hash = createHash("sha256");
+                for await (const chunk of fs.createReadStream(full))
+                    hash.update(chunk);
+                files.push({ path: relative, sizeBytes: stat.size, sha256: hash.digest("hex") });
+            }
+            else
+                throw cacheError("CLOUD_CACHE_UNSAFE", `Cache contains a non-regular file: ${relative}.`, "The cache is rejected and will be rebuilt.");
+        }
+    };
+    await walk(dir, "");
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+const checksumDigest = (files) => digest(files.map((file) => [file.path, file.sizeBytes, file.sha256]));
+/**
+ * Publishes a fully prepared staging directory (`<staging>/assets/...`) as the cache for `key`:
+ * hashes the tree, writes ready.json into staging, then atomically renames staging into place.
+ */
+export async function publishCache(params) {
+    const files = await hashTree(params.stagingDir, new Set([READY_FILE]));
+    const metadata = {
+        version: 1,
+        cacheKey: params.key,
+        layoutRevision: params.layoutRevision,
+        manifestDigest: params.manifestDigest,
+        files,
+        checksumManifestSha256: checksumDigest(files),
+        sizeBytes: files.reduce((total, file) => total + file.sizeBytes, 0),
+        preparedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(path.join(params.stagingDir, READY_FILE), `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+    const final = cacheDirFor(params.root, params.key);
+    if (fs.existsSync(final))
+        fs.renameSync(final, `${final}.replaced-${randomUUID()}`);
+    fs.renameSync(params.stagingDir, final);
+    return metadata;
+}
+/** Verifies the on-volume cache before use: metadata matches this job, and every file hashes as recorded. */
+export async function verifyCache(params) {
+    const dir = cacheDirFor(params.root, params.key);
+    const readyPath = path.join(dir, READY_FILE);
+    if (!fs.existsSync(readyPath))
+        return { ok: false, code: "CLOUD_CACHE_MISSING", message: "No prepared cache exists on the volume." };
+    let metadata;
+    try {
+        metadata = JSON.parse(fs.readFileSync(readyPath, "utf8"));
+    }
+    catch {
+        return { ok: false, code: "CLOUD_CACHE_INVALID", message: "The cache metadata is unreadable." };
+    }
+    if (metadata.version !== 1 || metadata.cacheKey !== params.key || metadata.layoutRevision !== params.layoutRevision || metadata.manifestDigest !== params.manifestDigest) {
+        return { ok: false, code: "CLOUD_CACHE_INVALID", message: "The cache was prepared for a different model, source or layout." };
+    }
+    if (checksumDigest(metadata.files) !== metadata.checksumManifestSha256) {
+        return { ok: false, code: "CLOUD_CACHE_INVALID", message: "The cache checksum manifest was altered." };
+    }
+    let actual;
+    try {
+        actual = await hashTree(dir, new Set([READY_FILE]));
+    }
+    catch (error) {
+        return { ok: false, code: "CLOUD_CACHE_INVALID", message: error instanceof Error ? error.message : String(error) };
+    }
+    if (checksumDigest(actual) !== metadata.checksumManifestSha256) {
+        return { ok: false, code: "CLOUD_CACHE_INVALID", message: "The cache contents no longer match their recorded checksums." };
+    }
+    return { ok: true, metadata, assetsDir: path.join(dir, "assets") };
+}
+/**
+ * Advisory lock for preparing one cache, as an atomic directory with owner and expiry. An expired
+ * lock is reclaimed only when the caller asserts the previous owner is gone (`reclaimStale`).
+ */
+export function acquireVolumeLock(params) {
+    const now = params.now ?? Date.now;
+    const lock = path.join(params.root, `${params.key}.lock`);
+    fs.mkdirSync(params.root, { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            fs.mkdirSync(lock);
+            fs.writeFileSync(path.join(lock, "owner.json"), JSON.stringify({ owner: params.owner, expiresAt: now() + params.ttlSeconds * 1000 }));
+            return { release: () => fs.rmSync(lock, { recursive: true, force: true }) };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let expired = false;
+            try {
+                expired = JSON.parse(fs.readFileSync(path.join(lock, "owner.json"), "utf8")).expiresAt <= now();
+            }
+            catch {
+                expired = true;
+            }
+            if (expired && params.reclaimStale && attempt === 0) {
+                fs.rmSync(lock, { recursive: true, force: true });
+                continue;
+            }
+            throw cacheError("CLOUD_CACHE_LOCKED", "Another machine is preparing this cache.", "Wait for it to finish; a stale lock is reclaimed only after the previous owner is confirmed gone.");
+        }
+    }
+    throw cacheError("CLOUD_CACHE_LOCKED", "Could not take the cache lock.", "Retry.");
+}

package/dist/cloud/worker/cache.test.d.ts

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

package/dist/cloud/worker/cache.test.js

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { parseManifest } from "@moldesk/registry";
+import { acquireVolumeLock, cacheDirFor, cloudCacheKey, hashTree, publishCache, verifyCache } from "./cache.js";
+const dirs = [];
+const tmp = () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk cache "));
+    dirs.push(dir);
+    return dir;
+};
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+function manifest(patch = {}, layout = "1") {
+    return parseManifest({
+        schemaVersion: 1,
+        name: "m",
+        displayName: "M",
+        modelVersion: "1.0.0",
+        adapterVersion: "0.1.0",
+        description: "t",
+        category: "other",
+        status: "planned",
+        source: { repository: "https://example.com/r", revision: "b".repeat(40) },
+        runtimes: [{ kind: "python", python: "3.11", installer: "uv", platforms: ["linux-x64"], requirements: [{ name: "torch" }] }],
+        hardware: { platforms: ["linux-x64"] },
+        assets: [{ id: "w", url: "https://example.com/w.bin", sha256: "c".repeat(64), target: "w.bin" }],
+        input: { formats: [".txt"], required: true },
+        outputs: [{ id: "o", glob: "*.out", required: true }],
+        cloud: { schemaVersion: 1, platform: "linux-x64", images: { gpu: `r.example/g@sha256:${"a".repeat(64)}`, cpu: `r.example/c@sha256:${"a".repeat(64)}` }, minVramGb: 24, minRamGb: 32, ephemeralDiskGb: 40, volumeGb: 40, assetLayoutRevision: layout, cpuAssetPreparation: true },
+        ...patch,
+    }, "x/manifest.yaml");
+}
+function stage(root, key) {
+    const staging = path.join(root, `${key}.staging-1`);
+    fs.mkdirSync(path.join(staging, "assets", "sub"), { recursive: true });
+    fs.writeFileSync(path.join(staging, "assets", "w.bin"), "weights");
+    fs.writeFileSync(path.join(staging, "assets", "sub", "x.dat"), "data");
+    return staging;
+}
+describe("cloudCacheKey", () => {
+    it("is stable, and changes with assets, source revision, version and layout", () => {
+        const base = cloudCacheKey(manifest());
+        expect(cloudCacheKey(manifest())).toBe(base);
+        expect(cloudCacheKey(manifest({}, "2"))).not.toBe(base);
+        expect(cloudCacheKey(manifest({ assets: [{ id: "w", url: "https://example.com/w.bin", sha256: "d".repeat(64), target: "w.bin" }] }))).not.toBe(base);
+        expect(cloudCacheKey(manifest({ source: { repository: "https://example.com/r", revision: "e".repeat(40) } }))).not.toBe(base);
+        expect(cloudCacheKey(manifest({ modelVersion: "1.0.1" }))).not.toBe(base);
+    });
+});
+describe("publishCache / verifyCache", () => {
+    const params = (root, key = "k1") => ({ root, key, manifestDigest: "md", layoutRevision: "1" });
+    it("publishes atomically and verifies a warm cache", async () => {
+        const root = tmp();
+        const meta = await publishCache({ ...params(root), stagingDir: stage(root, "k1") });
+        expect(meta.files.map((f) => f.path)).toEqual(["assets/sub/x.dat", "assets/w.bin"]);
+        expect(fs.existsSync(path.join(root, "k1.staging-1"))).toBe(false);
+        const result = await verifyCache(params(root));
+        expect(result).toMatchObject({ ok: true, assetsDir: path.join(root, "k1", "assets") });
+    });
+    it("reports missing, wrong-key, mutated, added and symlinked caches as unusable", async () => {
+        const root = tmp();
+        expect(await verifyCache(params(root))).toMatchObject({ ok: false, code: "CLOUD_CACHE_MISSING" });
+        await publishCache({ ...params(root), stagingDir: stage(root, "k1") });
+        expect(await verifyCache({ ...params(root), manifestDigest: "other" })).toMatchObject({ ok: false, code: "CLOUD_CACHE_INVALID" });
+        expect(await verifyCache({ ...params(root), layoutRevision: "2" })).toMatchObject({ ok: false, code: "CLOUD_CACHE_INVALID" });
+        fs.writeFileSync(path.join(root, "k1", "assets", "w.bin"), "tampered");
+        expect(await verifyCache(params(root))).toMatchObject({ ok: false, code: "CLOUD_CACHE_INVALID", message: expect.stringMatching(/no longer match/) });
+        const added = tmp();
+        await publishCache({ ...params(added), stagingDir: stage(added, "k1") });
+        fs.writeFileSync(path.join(added, "k1", "assets", "extra.bin"), "x");
+        expect(await verifyCache(params(added))).toMatchObject({ ok: false, code: "CLOUD_CACHE_INVALID" });
+        const linked = tmp();
+        await publishCache({ ...params(linked), stagingDir: stage(linked, "k1") });
+        fs.symlinkSync("/etc/passwd", path.join(linked, "k1", "assets", "link"));
+        expect(await verifyCache(params(linked))).toMatchObject({ ok: false, message: expect.stringMatching(/symlink/) });
+    });
+    it("detects a tampered checksum manifest", async () => {
+        const root = tmp();
+        await publishCache({ ...params(root), stagingDir: stage(root, "k1") });
+        const readyPath = path.join(root, "k1", "ready.json");
+        const meta = JSON.parse(fs.readFileSync(readyPath, "utf8"));
+        meta.files[0].sha256 = "0".repeat(64);
+        fs.writeFileSync(readyPath, JSON.stringify(meta));
+        expect(await verifyCache(params(root))).toMatchObject({ ok: false, message: expect.stringMatching(/altered/) });
+    });
+    it("an interrupted preparation (no publish) is never reachable as READY", async () => {
+        const root = tmp();
+        stage(root, "k1"); // staging exists, publish never ran
+        expect(await verifyCache(params(root))).toMatchObject({ ok: false, code: "CLOUD_CACHE_MISSING" });
+        expect(fs.existsSync(cacheDirFor(root, "k1"))).toBe(false);
+    });
+    it("hashTree refuses unsafe entries", async () => {
+        const dir = tmp();
+        fs.writeFileSync(path.join(dir, "ok"), "x");
+        fs.symlinkSync("ok", path.join(dir, "ln"));
+        await expect(hashTree(dir)).rejects.toMatchObject({ code: "CLOUD_CACHE_UNSAFE" });
+    });
+});
+describe("acquireVolumeLock", () => {
+    it("excludes a second holder, releases cleanly, and reclaims stale locks only when asserted", () => {
+        const root = tmp();
+        let now = 1_000;
+        const take = (extra = {}) => acquireVolumeLock({ root, key: "k", owner: "a", ttlSeconds: 10, now: () => now, ...extra });
+        const first = take();
+        expect(() => take()).toThrow(expect.objectContaining({ code: "CLOUD_CACHE_LOCKED" }));
+        first.release();
+        const second = take();
+        now += 60_000;
+        expect(() => take()).toThrow(expect.objectContaining({ code: "CLOUD_CACHE_LOCKED" })); // stale but not asserted gone
+        const reclaimed = take({ reclaimStale: true });
+        reclaimed.release();
+        second.release();
+    });
+    it("does not reclaim a live lock even when asked", () => {
+        const root = tmp();
+        acquireVolumeLock({ root, key: "k", owner: "a", ttlSeconds: 600, now: () => 1_000 });
+        expect(() => acquireVolumeLock({ root, key: "k", owner: "b", ttlSeconds: 600, reclaimStale: true, now: () => 2_000 })).toThrow(expect.objectContaining({ code: "CLOUD_CACHE_LOCKED" }));
+    });
+});

package/dist/cloud/worker/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cloud/worker/main.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { createManifestPipeline } from "./pipeline.js";
+import { createWorkerServer } from "./server.js";
+import { startDeadlineWatchdog } from "./watchdog.js";
+/**
+ * Worker entry point, run inside the Pod. Configuration comes from the environment the client set
+ * at Pod creation; the token is never printed.
+ */
+async function main() {
+    const token = process.env.MOLDESK_WORKER_TOKEN;
+    if (!token || token.length < 24) {
+        console.error("MOLDESK_WORKER_TOKEN is missing or too short.");
+        process.exit(2);
+    }
+    const rootDir = process.env.MOLDESK_WORKER_ROOT ?? "/job";
+    const port = Number(process.env.MOLDESK_WORKER_PORT ?? "8000");
+    const secrets = [process.env.RUNPOD_API_KEY].filter((value) => Boolean(value));
+    const worker = createWorkerServer({ token, rootDir, pipeline: createManifestPipeline(), secrets });
+    await worker.listen(port);
+    console.error(`moldesk worker listening on ${port}`);
+    const deadlineAt = process.env.MOLDESK_WORKER_DEADLINE_AT;
+    const podId = process.env.RUNPOD_POD_ID;
+    const podKey = process.env.RUNPOD_API_KEY;
+    if (deadlineAt && podId && podKey) {
+        startDeadlineWatchdog({ deadlineAt, podId, apiKey: podKey, log: (message) => console.error(`watchdog: ${message}`) });
+    }
+    else {
+        console.error("watchdog: not armed (missing deadline, pod id or pod-scoped key)");
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/cloud/worker/pipeline.d.ts

@@ -0,0 +1,26 @@
+import { type ModelAdapterDefinition } from "@moldesk/adapters";
+import { type ModelManifestV1 } from "@moldesk/registry";
+import { cacheAsset, getSystemReport, materializeAsset, preparePythonEnvironment, type RuntimeProvider } from "@moldesk/runtime";
+import type { WorkerPipeline } from "./server.js";
+export interface PipelineSteps {
+    cacheAsset: typeof cacheAsset;
+    materializeAsset: typeof materializeAsset;
+    preparePythonEnvironment: typeof preparePythonEnvironment;
+    getSystemReport: typeof getSystemReport;
+    runtime: RuntimeProvider;
+}
+export interface ManifestPipelineOptions {
+    /** Looks up the bundled manifest and adapter; the worker only ever runs what it ships with. */
+    resolveModel?: (name: string) => {
+        manifest: ModelManifestV1;
+        adapter: ModelAdapterDefinition;
+    } | undefined;
+    steps?: Partial<PipelineSteps>;
+}
+/**
+ * The real worker pipeline: prepare assets, install the Linux runtime, verify (CUDA included), build
+ * the adapter's own command with POSIX paths, and execute. It reuses the same installer, adapter and
+ * execution code as local runs and never accepts a command or manifest from the client; the client's
+ * job only selects a bundled model and must match that manifest's digest exactly.
+ */
+export declare function createManifestPipeline(options?: ManifestPipelineOptions): WorkerPipeline;