@alisio/core 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/analysis/jobs.js

@@ -0,0 +1,165 @@
+/**
+ * Internal job folders of `python_run`, outside the repository and outside the artifact store:
+ * `<root>/analysis/jobs/<workspaceKey>/<root session>/<executionId>/` with `job.json`,
+ * `script/main.py` (+ the `alisio_runtime` package), `input/`, `work/`, `staging/` and `logs/`.
+ * Nothing here is published automatically: only `staging/` is read by the artifact publisher.
+ */
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { copyFile, lstat, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, sep } from "node:path";
+import { newId } from "../runtime/ids.js";
+import { workspaceKey } from "../runtime/paths.js";
+import { ALISIO_RUNTIME_FILES } from "./python/sources.js";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** Executions of `python_run` (`analysis_executions`) and their job folders. */
+export class AnalysisJobs {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    /** Creates the job folder (script, runtime helpers, empty input/work/staging/logs) and its row. */
+    async create(input) {
+        const id = newId("exec", this.now());
+        const root = join(this.options.root, "analysis", "jobs", workspaceKey(input.workspace), input.rootSessionId, id);
+        const paths = {
+            id,
+            root,
+            script: join(root, "script"),
+            main: join(root, "script", "main.py"),
+            input: join(root, "input"),
+            work: join(root, "work"),
+            staging: join(root, "staging"),
+            logs: join(root, "logs"),
+        };
+        for (const dir of [paths.script, paths.input, paths.work, paths.staging, paths.logs])
+            await mkdir(dir, { recursive: true });
+        await writeFile(paths.main, input.code, { flag: "wx" });
+        const runtimeDir = join(paths.script, "alisio_runtime");
+        await mkdir(runtimeDir);
+        for (const [name, text] of Object.entries(ALISIO_RUNTIME_FILES))
+            await writeFile(join(runtimeDir, name), text, { flag: "wx" });
+        const scriptSha256 = sha256(input.code);
+        const createdAt = this.now();
+        await writeFile(join(root, "job.json"), `${JSON.stringify({
+            schemaVersion: 1,
+            id,
+            sessionId: input.sessionId,
+            rootSessionId: input.rootSessionId,
+            runId: input.runId,
+            callId: input.callId,
+            runtime: input.runtime,
+            scriptSha256,
+            ...(input.rerunOf ? { rerunOf: input.rerunOf } : {}),
+            createdAt,
+        }, null, 2)}\n`);
+        this.options.db
+            .prepare(`INSERT INTO analysis_executions(id,session,root_session,workspace,run_id,call_id,runtime,
+           status,script_sha256,rel_dir,rerun_of,created_at) VALUES(?,?,?,?,?,?,?,'running',?,?,?,?)`)
+            .run(id, input.sessionId, input.rootSessionId, input.workspace, input.runId ?? null, input.callId ?? null, input.runtime, scriptSha256, relative(this.options.root, root), input.rerunOf ?? null, createdAt);
+        return { ...paths, scriptSha256 };
+    }
+    /**
+     * Copies an input file (already resolved by the path policy) into `input/`, as `name` (default:
+     * its own name). Copy-on-write clones are used where the file system has them; the copy is
+     * never a link, so a script cannot alter the original.
+     */
+    async addInput(job, source, preferred) {
+        const info = await lstat(source);
+        if (!info.isFile())
+            throw new Error(`Input ${source} is not a regular file`);
+        const wanted = preferred ?? basename(source);
+        let name = wanted;
+        for (let n = 2; await exists(join(job.input, name)); n++)
+            name = wanted.replace(/(\.[^.]*)?$/, (ext) => `-${n}${ext}`);
+        const target = join(job.input, name);
+        await copyFile(source, target, constants.COPYFILE_EXCL | constants.COPYFILE_FICLONE);
+        const bytes = await readFile(target);
+        return { name, sha256: sha256(bytes), bytes: bytes.byteLength };
+    }
+    /** `input/inputs.json`: what each input is (the script reads it with `alisio_runtime.datasets.inputs()`). */
+    async writeInputsManifest(job, entries) {
+        await writeFile(join(job.input, "inputs.json"), `${JSON.stringify(entries, null, 2)}\n`);
+    }
+    /** Adds the inputs to `job.json` (atomically), once they are copied into `input/`. */
+    async recordInputs(job, recorded) {
+        const file = join(job.root, "job.json");
+        const current = JSON.parse(await readFile(file, "utf8"));
+        const temporary = `${file}.${process.pid}.tmp`;
+        await writeFile(temporary, `${JSON.stringify({ ...current, ...recorded }, null, 2)}\n`);
+        await rename(temporary, file);
+    }
+    /** The inputs a finished job recorded; `undefined` when `job.json` is missing or has none. */
+    async recordedInputs(relDir) {
+        try {
+            const value = JSON.parse(await readFile(join(this.options.root, relDir, "job.json"), "utf8"));
+            return Array.isArray(value.inputs)
+                ? {
+                    inputs: value.inputs,
+                    manifest: Array.isArray(value.manifest) ? value.manifest : [],
+                    ...(Array.isArray(value.extras) ? { extras: value.extras } : {}),
+                }
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Absolute folder of an execution (`rel_dir` is always relative to the state root). */
+    folder(relDir) {
+        const folder = join(this.options.root, relDir);
+        const inside = relative(this.options.root, folder);
+        if (!inside || inside.startsWith("..") || isAbsolute(inside) || inside.split(sep)[0] === "..")
+            throw new Error("The execution folder is outside the state folder");
+        return folder;
+    }
+    /** The whole row of an execution. */
+    details(id) {
+        const row = this.options.db.prepare("SELECT * FROM analysis_executions WHERE id=?").get(id);
+        if (!row)
+            return undefined;
+        return {
+            id: String(row.id),
+            sessionId: String(row.session),
+            rootSessionId: String(row.root_session),
+            workspace: String(row.workspace),
+            runtime: String(row.runtime),
+            status: String(row.status),
+            scriptSha256: String(row.script_sha256),
+            ...(row.exit_code != null ? { exitCode: Number(row.exit_code) } : {}),
+            relDir: String(row.rel_dir),
+            ...(row.rerun_of != null ? { rerunOf: String(row.rerun_of) } : {}),
+            createdAt: Number(row.created_at),
+            ...(row.ended_at != null ? { endedAt: Number(row.ended_at) } : {}),
+        };
+    }
+    finish(id, status, details = {}) {
+        this.options.db
+            .prepare("UPDATE analysis_executions SET status=?, exit_code=?, error=?, ended_at=? WHERE id=?")
+            .run(status, details.exitCode ?? null, details.error ?? null, this.now(), id);
+    }
+    get(id) {
+        const row = this.options.db
+            .prepare("SELECT status, exit_code, rel_dir FROM analysis_executions WHERE id=?")
+            .get(id);
+        return row
+            ? {
+                status: row.status,
+                ...(row.exit_code != null ? { exitCode: row.exit_code } : {}),
+                relDir: row.rel_dir,
+            }
+            : undefined;
+    }
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/analysis/oci.d.ts

@@ -0,0 +1,129 @@
+import { type ProcessResult } from "../runtime/process.ts";
+export type OciEngine = "docker" | "podman";
+export interface OciSettings {
+    engine: OciEngine;
+    /** `name@sha256:<digest>`; required to run. */
+    image?: string;
+    memoryMb: number;
+    cpus: number;
+}
+/** The job folders mounted into the container (host paths). */
+export interface OciMounts {
+    script: string;
+    input: string;
+    work: string;
+    staging: string;
+}
+/** Paths inside the container (spec §8.3). */
+export declare const CONTAINER: {
+    readonly script: "/job/script";
+    readonly input: "/job/input";
+    readonly work: "/job/work";
+    readonly out: "/job/out";
+};
+export declare const PIDS_LIMIT = 256;
+export declare const TMPFS_SIZE = "256m";
+/** `alisio-exec_01J…`: the container of one execution. */
+export declare function containerName(executionId: string): string;
+export interface OciHost {
+    platform: NodeJS.Platform;
+    uid?: number;
+    gid?: number;
+    /** The engine runs without root privileges (rootless Docker or Podman). */
+    rootless?: boolean;
+    /** SELinux is enforcing: bind mounts need a relabel option on the host. */
+    selinux?: boolean;
+}
+/** A host path that can be passed to `-v`; throws when the engine would misparse it. */
+export declare function mountSource(path: string, platform: NodeJS.Platform): string;
+/**
+ * `<engine> run` arguments for one execution (spec §8.3). The container name is
+ * `alisio-<executionId>` so a cancellation can `kill` it by name.
+ */
+export declare function ociRunArgs(input: {
+    settings: OciSettings & {
+        image: string;
+    };
+    executionId: string;
+    mounts: OciMounts;
+    host: OciHost;
+    /** Extra environment variables for the script (the ALISIO_* ones are always set). */
+    env?: Record<string, string>;
+}): string[];
+/** Collaborators of the runtime, replaceable in tests (a fake container CLI). */
+export interface OciDeps {
+    /** Resolves the engine executable; `undefined` when it is not installed. */
+    locate(engine: OciEngine): Promise<string | undefined>;
+    /** Arguments placed before the engine's own (test launchers only). */
+    prefixArgs?: string[];
+    host(): Promise<OciHost>;
+    /** Runs one engine command to completion. */
+    exec(command: string, args: string[], options: {
+        signal: AbortSignal;
+        timeoutMs: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+}
+export declare function defaultOciDeps(): OciDeps;
+export type OciStatus = {
+    ok: true;
+    engine: OciEngine;
+    path: string;
+    version: string;
+    rootless: boolean;
+} | {
+    ok: false;
+    engine: OciEngine;
+    reason: string;
+    /** The other engine is installed: switching `analysis.oci.engine` is a way out. */
+    alternative?: OciEngine;
+};
+/** Container runtime of `python_run`; all engine calls go through `OciDeps`. */
+export declare class OciRuntime {
+    readonly settings: OciSettings;
+    readonly deps: OciDeps;
+    constructor(settings: OciSettings, deps?: Partial<OciDeps>);
+    private command;
+    private call;
+    /**
+     * Is the engine installed and its daemon reachable? Optional by design: a missing engine is a
+     * status, not an error of Alisio. Also reports rootless mode, which changes the `--user` flags.
+     */
+    status(signal?: AbortSignal): Promise<OciStatus>;
+    /** The reason a run cannot start (`undefined` = ready), checked before any job is created. */
+    unavailable(signal?: AbortSignal): Promise<string | undefined>;
+    /**
+     * Runs the job's script in a container. Cancelling or timing out `kills` the container by name
+     * (killing the client process does not always stop it) and no `alisio-*` container is left.
+     */
+    run(input: {
+        executionId: string;
+        mounts: OciMounts;
+        signal: AbortSignal;
+        timeoutMs: number;
+        maxBytes: number;
+        onData?: (chunk: string) => void;
+        logFiles: {
+            stdout: string;
+            stderr: string;
+        };
+        maxLogBytes: number;
+    }): Promise<ProcessResult & {
+        containerName: string;
+    }>;
+    /** `<engine> kill <name>`; a container that is already gone is not an error. */
+    kill(name: string): Promise<void>;
+    /** Names of the `alisio-*` containers that still exist (running or not). */
+    leftovers(): Promise<string[]>;
+    /** Pulls the image (once, from `alisio analysis setup --oci`); a digest reference verifies itself. */
+    pull(image: string, signal: AbortSignal): Promise<{
+        digest?: string;
+    }>;
+    /** True when the image is already in the local store (so a run never needs the network). */
+    hasImage(image: string, signal?: AbortSignal): Promise<boolean>;
+}
+/** `["repo@sha256:…"]` → `["repo@sha256:…"]` (JSON from `--format {{json .RepoDigests}}`). */
+export declare function parseDigests(output: string): string[];

package/dist/analysis/oci.js

@@ -0,0 +1,330 @@
+/**
+ * Optional container runtime for `python_run` (`analysis.runtime: "oci"`): Docker or Podman with a
+ * digest-pinned image. Nothing is built or pulled during a run (`alisio analysis setup --oci` pulls
+ * once); the run only starts `<engine> run --rm …`. The isolation is partial and documented: the
+ * container sees only the job folders, has no network, a read-only root, no capabilities and
+ * memory/CPU/process limits, but a container is not a boundary against a hostile kernel exploit.
+ *
+ * Every argument goes in an array (no shell), so paths with spaces and non-ASCII names are fine.
+ * Host paths that the engine would parse as mount syntax (a `:` outside a Windows drive prefix) are
+ * refused with a clear message instead of being passed through.
+ */
+import { readFile } from "node:fs/promises";
+import { OCI_IMAGE_PATTERN } from "../config.js";
+import { which } from "../runtime/fs.js";
+import { runProcess } from "../runtime/process.js";
+/** Paths inside the container (spec §8.3). */
+export const CONTAINER = {
+    script: "/job/script",
+    input: "/job/input",
+    work: "/job/work",
+    out: "/job/out",
+};
+export const PIDS_LIMIT = 256;
+export const TMPFS_SIZE = "256m";
+/** `alisio-exec_01J…`: the container of one execution. */
+export function containerName(executionId) {
+    const safe = executionId.replace(/[^a-zA-Z0-9_.-]/g, "-");
+    return `alisio-${safe}`;
+}
+/** Windows drive prefix (`C:\` or `C:/`), which a `-v` source may legitimately contain. */
+const DRIVE = /^[A-Za-z]:[\\/]/;
+/** A host path that can be passed to `-v`; throws when the engine would misparse it. */
+export function mountSource(path, platform) {
+    const rest = platform === "win32" && DRIVE.test(path) ? path.slice(2) : path;
+    if (rest.includes(":") || /[\r\n\0]/.test(path))
+        throw new Error(`The job folder ${path} contains a character the container runtime cannot mount (":"). ` +
+            "Move the Alisio state folder (ALISIO_STATE_HOME or --db) to a path without it, or use the managed runtime.");
+    return path;
+}
+/**
+ * `<engine> run` arguments for one execution (spec §8.3). The container name is
+ * `alisio-<executionId>` so a cancellation can `kill` it by name.
+ */
+export function ociRunArgs(input) {
+    const { settings, host } = input;
+    const mount = (source, target, mode) => `${mountSource(source, host.platform)}:${target}:${mode}${host.selinux ? ",z" : ""}`;
+    const args = [
+        "run",
+        "--rm",
+        "--name",
+        containerName(input.executionId),
+        "--label",
+        "alisio=analysis",
+        "--network=none",
+        "--read-only",
+        "--cap-drop=ALL",
+        "--security-opt=no-new-privileges",
+        `--pids-limit=${PIDS_LIMIT}`,
+        `--memory=${settings.memoryMb}m`,
+        `--memory-swap=${settings.memoryMb}m`,
+        `--cpus=${settings.cpus}`,
+    ];
+    // Files the script writes must belong to the user on Linux. Docker Desktop (macOS, Windows)
+    // maps ownership itself, so `--user` is omitted there; a rootless engine already maps the user
+    // to root inside the container (Podman needs keep-id to keep the owner on the mounts).
+    if (host.platform === "linux" && host.uid !== undefined && host.gid !== undefined) {
+        if (settings.engine === "podman" && host.rootless && host.uid !== 0)
+            args.push("--userns=keep-id", "--user", `${host.uid}:${host.gid}`);
+        else if (!host.rootless && host.uid !== 0)
+            args.push("--user", `${host.uid}:${host.gid}`);
+    }
+    args.push("-v", mount(input.mounts.script, CONTAINER.script, "ro"), "-v", mount(input.mounts.input, CONTAINER.input, "ro"), "-v", mount(input.mounts.work, CONTAINER.work, "rw"), "-v", mount(input.mounts.staging, CONTAINER.out, "rw"), "--tmpfs", `/tmp:size=${TMPFS_SIZE}`);
+    const env = {
+        ALISIO_INPUT_DIR: CONTAINER.input,
+        ALISIO_OUTPUT_DIR: CONTAINER.out,
+        ALISIO_WORK_DIR: CONTAINER.work,
+        ALISIO_EXECUTION_ID: input.executionId,
+        HOME: CONTAINER.work,
+        TMPDIR: "/tmp",
+        MPLCONFIGDIR: `${CONTAINER.work}/.matplotlib`,
+        MPLBACKEND: "Agg",
+        PYTHONDONTWRITEBYTECODE: "1",
+        PYTHONUNBUFFERED: "1",
+        PYTHONNOUSERSITE: "1",
+        PYTHONIOENCODING: "utf-8",
+        ...input.env,
+    };
+    for (const [key, value] of Object.entries(env))
+        args.push("-e", `${key}=${value}`);
+    args.push("-w", CONTAINER.work, settings.image, "python", "-E", "-s", "-B", "-u", "-X", "utf8", `${CONTAINER.script}/main.py`);
+    return args;
+}
+async function selinuxEnforcing() {
+    try {
+        return (await readFile("/sys/fs/selinux/enforce", "utf8")).trim() === "1";
+    }
+    catch {
+        return false;
+    }
+}
+export function defaultOciDeps() {
+    return {
+        locate: (engine) => which(engine),
+        async host() {
+            return {
+                platform: process.platform,
+                ...(typeof process.getuid === "function" ? { uid: process.getuid() } : {}),
+                ...(typeof process.getgid === "function" ? { gid: process.getgid() } : {}),
+                ...(process.platform === "linux" ? { selinux: await selinuxEnforcing() } : {}),
+            };
+        },
+        async exec(command, args, options) {
+            const result = await runProcess(command, args, {
+                cwd: process.cwd(),
+                signal: options.signal,
+                timeoutMs: options.timeoutMs,
+                maxBytes: 256 * 1024,
+                onOverflow: "truncate",
+            });
+            return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };
+        },
+    };
+}
+const other = (engine) => (engine === "docker" ? "podman" : "docker");
+/** Container runtime of `python_run`; all engine calls go through `OciDeps`. */
+export class OciRuntime {
+    settings;
+    deps;
+    constructor(settings, deps = {}) {
+        this.settings = settings;
+        this.deps = { ...defaultOciDeps(), ...deps };
+    }
+    async command() {
+        return this.deps.locate(this.settings.engine);
+    }
+    async call(args, options = {}) {
+        const command = await this.command();
+        if (!command)
+            throw new Error(`${this.settings.engine} is not installed`);
+        return this.deps.exec(command, [...(this.deps.prefixArgs ?? []), ...args], {
+            signal: options.signal ?? AbortSignal.timeout(options.timeoutMs ?? 30_000),
+            timeoutMs: options.timeoutMs ?? 30_000,
+        });
+    }
+    /**
+     * Is the engine installed and its daemon reachable? Optional by design: a missing engine is a
+     * status, not an error of Alisio. Also reports rootless mode, which changes the `--user` flags.
+     */
+    async status(signal) {
+        const engine = this.settings.engine;
+        const path = await this.command();
+        if (!path) {
+            const alternative = (await this.deps.locate(other(engine))) ? other(engine) : undefined;
+            return {
+                ok: false,
+                engine,
+                reason: `${engine} was not found on PATH`,
+                ...(alternative ? { alternative } : {}),
+            };
+        }
+        try {
+            const version = await this.call(["version", "--format", engine === "docker" ? "{{.Server.Version}}" : "{{.Version}}"], signal ? { signal } : {});
+            if (version.exitCode !== 0)
+                return {
+                    ok: false,
+                    engine,
+                    reason: `${engine} is installed but not usable: ${(version.stderr || version.stdout).trim().split(/\r?\n/)[0] ?? "no answer"}`,
+                };
+            let rootless = false;
+            try {
+                const info = await this.call([
+                    "info",
+                    "--format",
+                    engine === "docker" ? "{{json .SecurityOptions}}" : "{{.Host.Security.Rootless}}",
+                ], signal ? { signal } : {});
+                rootless =
+                    info.exitCode === 0 &&
+                        (engine === "docker" ? /name=rootless/.test(info.stdout) : info.stdout.trim() === "true");
+            }
+            catch {
+                /* Rootless detection is best effort; the default flags are the rootful ones. */
+            }
+            return { ok: true, engine, path, version: version.stdout.trim(), rootless };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                engine,
+                reason: `${engine} did not answer: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    /** The reason a run cannot start (`undefined` = ready), checked before any job is created. */
+    async unavailable(signal) {
+        const { image } = this.settings;
+        if (!image)
+            return ('analysis.runtime is "oci" but analysis.oci.image is not set. Put a digest-pinned image ' +
+                "(name@sha256:…) in your user configuration; `alisio analysis setup --oci --image <name>` prints the value.");
+        if (!OCI_IMAGE_PATTERN.test(image))
+            return "analysis.oci.image must be pinned by digest";
+        const status = await this.status(signal);
+        if (!status.ok)
+            return `${status.reason}${status.alternative ? `; ${status.alternative} is installed (set analysis.oci.engine to "${status.alternative}")` : ""}. The container runtime is optional: remove analysis.runtime "oci" to use managed Python.`;
+        return undefined;
+    }
+    /**
+     * Runs the job's script in a container. Cancelling or timing out `kills` the container by name
+     * (killing the client process does not always stop it) and no `alisio-*` container is left.
+     */
+    async run(input) {
+        const image = this.settings.image;
+        if (!image)
+            throw new Error("analysis.oci.image is not set");
+        const command = await this.command();
+        if (!command)
+            throw new Error(`${this.settings.engine} is not installed`);
+        const status = await this.status(input.signal);
+        const host = await this.deps.host();
+        const args = ociRunArgs({
+            settings: { ...this.settings, image },
+            executionId: input.executionId,
+            mounts: input.mounts,
+            host: { ...host, rootless: status.ok ? status.rootless : false },
+        });
+        const name = containerName(input.executionId);
+        const stop = AbortSignal.any([input.signal, AbortSignal.timeout(input.timeoutMs)]);
+        const onAbort = () => void this.kill(name);
+        stop.addEventListener("abort", onAbort, { once: true });
+        try {
+            const result = await runProcess(command, [...(this.deps.prefixArgs ?? []), ...args], {
+                cwd: input.mounts.work,
+                signal: input.signal,
+                timeoutMs: input.timeoutMs,
+                maxBytes: input.maxBytes,
+                onOverflow: "truncate",
+                logFiles: input.logFiles,
+                maxLogBytes: input.maxLogBytes,
+                // The engine client only needs to find its own daemon: no variables of the script.
+                env: engineEnv(),
+                ...(input.onData ? { onData: input.onData } : {}),
+            });
+            return { ...result, containerName: name };
+        }
+        finally {
+            stop.removeEventListener("abort", onAbort);
+            // After an abort the client may have exited before the daemon stopped the container.
+            if (stop.aborted)
+                await this.kill(name);
+        }
+    }
+    /** `<engine> kill <name>`; a container that is already gone is not an error. */
+    async kill(name) {
+        try {
+            await this.call(["kill", name], { timeoutMs: 15_000 });
+        }
+        catch {
+            /* Already gone, or the engine stopped answering: nothing else to do. */
+        }
+    }
+    /** Names of the `alisio-*` containers that still exist (running or not). */
+    async leftovers() {
+        const result = await this.call([
+            "ps",
+            "-a",
+            "--filter",
+            "label=alisio=analysis",
+            "--format",
+            "{{.Names}}",
+        ]);
+        return result.stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    /** Pulls the image (once, from `alisio analysis setup --oci`); a digest reference verifies itself. */
+    async pull(image, signal) {
+        const pulled = await this.call(["pull", image], { signal, timeoutMs: 30 * 60_000 });
+        if (pulled.exitCode !== 0)
+            throw new Error(`${this.settings.engine} pull ${image} failed: ${(pulled.stderr || pulled.stdout).trim().slice(-2000)}`);
+        const inspected = await this.call(["image", "inspect", "--format", "{{json .RepoDigests}}", image], { signal });
+        const digests = parseDigests(inspected.stdout);
+        return { ...(digests[0] ? { digest: digests[0] } : {}) };
+    }
+    /** True when the image is already in the local store (so a run never needs the network). */
+    async hasImage(image, signal) {
+        try {
+            const result = await this.call(["image", "inspect", "--format", "{{.Id}}", image], signal ? { signal } : {});
+            return result.exitCode === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** `["repo@sha256:…"]` → `["repo@sha256:…"]` (JSON from `--format {{json .RepoDigests}}`). */
+export function parseDigests(output) {
+    try {
+        const value = JSON.parse(output.trim());
+        return Array.isArray(value)
+            ? value.filter((v) => typeof v === "string" && OCI_IMAGE_PATTERN.test(v))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The environment of the engine client: where to find the daemon, nothing else. */
+function engineEnv() {
+    const keep = [
+        "PATH",
+        "HOME",
+        "USERPROFILE",
+        "TMPDIR",
+        "TEMP",
+        "SystemRoot",
+        "COMSPEC",
+        "LANG",
+        "DOCKER_HOST",
+        "DOCKER_CONTEXT",
+        "DOCKER_CONFIG",
+        "XDG_RUNTIME_DIR",
+        "CONTAINER_HOST",
+        "APPDATA",
+        "LOCALAPPDATA",
+        "ProgramData",
+        "ProgramFiles",
+        "DBUS_SESSION_BUS_ADDRESS",
+    ];
+    return Object.fromEntries(keep.flatMap((key) => (process.env[key] ? [[key, process.env[key]]] : [])));
+}

package/dist/analysis/python/sources.d.ts

@@ -0,0 +1,2 @@
+/** The pure-Python `alisio_runtime` package copied next to every python_run script. */
+export declare const ALISIO_RUNTIME_FILES: Record<string, string>;