@alisio/core 0.1.0-alpha.9 → 0.1.0

package/dist/analysis/janitor.js

@@ -0,0 +1,264 @@
+/**
+ * Retention of analysis data (spec §19): `AnalysisJanitor.sweep()` runs at most once every 24 hours
+ * (the mark is `<state>/analysis/.last-sweep`), launched in the background shortly after startup
+ * with an unreferenced timer, so it never delays the start nor keeps a process alive.
+ *
+ *  - `work/` of a job goes after `intermediateDays`; `logs/` and `staging/` after `jobsDays`.
+ *  - `script/`, `input/` and `job.json` stay while any artifact of that execution is `ready`
+ *    (a rerun needs them); once none is, the whole job folder goes after `jobsDays`.
+ *  - With `artifactsDays > 0`, older artifacts become `expired` (folder deleted, row kept).
+ *  - Datasets unused for `jobsDays` are deleted with their uploaded original in `blobs/`; an
+ *    upload without a dataset (a failed ingestion) goes after the same time.
+ *  - `0` disables the deletion of that class. Running executions are never touched.
+ *
+ * Deletions are best effort and independent: one that fails is counted and the sweep goes on.
+ */
+import { mkdir, readFile, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+const DAY = 86_400_000;
+export const SWEEP_INTERVAL_MS = DAY;
+/** A lock older than this belongs to a dead process. */
+const STALE_LOCK_MS = 60 * 60_000;
+/** A job still `running` after this long was left by a crashed process. */
+const STALE_RUNNING_MS = DAY;
+const empty = () => ({
+    workDeleted: 0,
+    jobsTrimmed: 0,
+    jobsDeleted: 0,
+    artifactsExpired: 0,
+    datasetsDeleted: 0,
+    uploadsDeleted: 0,
+    bytesFreed: 0,
+    errors: 0,
+});
+/** Size in bytes of a file or folder (0 when it does not exist). */
+async function sizeOf(path) {
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch {
+        return 0;
+    }
+    if (!info.isDirectory())
+        return info.size;
+    const { readdir } = await import("node:fs/promises");
+    let total = 0;
+    for (const entry of await readdir(path).catch(() => []))
+        total += await sizeOf(join(path, entry));
+    return total;
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export class AnalysisJanitor {
+    options;
+    timer;
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    get dir() {
+        return join(this.options.root, "analysis");
+    }
+    /** When the last sweep started (epoch ms), if there was one. */
+    async lastSweep() {
+        try {
+            const value = Number((await readFile(join(this.dir, ".last-sweep"), "utf8")).trim());
+            return Number.isFinite(value) ? value : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Launches the sweep in the background; never delays the caller and never keeps Node alive. */
+    start() {
+        this.stopped = false;
+        this.arm(this.options.initialDelayMs ?? 30_000);
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    arm(delay) {
+        if (this.stopped)
+            return;
+        this.timer = setTimeout(() => {
+            void this.sweep()
+                .catch(() => undefined)
+                .finally(() => this.arm(SWEEP_INTERVAL_MS));
+        }, delay);
+        this.timer.unref();
+    }
+    /** One sweep (see the module comment). `force` ignores the 24 h mark. */
+    async sweep(options = {}) {
+        const report = empty();
+        const now = this.now();
+        const last = await this.lastSweep();
+        if (!options.force && last !== undefined && now - last < SWEEP_INTERVAL_MS)
+            return { ...report, skipped: "recent" };
+        const release = await this.lock();
+        if (!release)
+            return { ...report, skipped: "locked" };
+        try {
+            // The mark is written first: a crash mid-sweep does not make every start retry at once.
+            await writeFile(join(this.dir, ".last-sweep"), `${now}\n`);
+            const policy = this.options.retention();
+            await this.expireArtifacts(policy, now, report);
+            await this.trimJobs(policy, now, report);
+            await this.dropDatasets(policy, now, report);
+        }
+        finally {
+            await release();
+        }
+        return report;
+    }
+    /** Exclusive lock between processes sharing the state folder; undefined when someone holds it. */
+    async lock() {
+        await mkdir(this.dir, { recursive: true });
+        const file = join(this.dir, ".sweep.lock");
+        for (let attempt = 0; attempt < 2; attempt++)
+            try {
+                await writeFile(file, `${process.pid}\n`, { flag: "wx" });
+                return () => rm(file, { force: true });
+            }
+            catch {
+                const info = await stat(file).catch(() => undefined);
+                // Real time on purpose: the lock belongs to a live process, not to the injected clock.
+                if (info && Date.now() - info.mtimeMs < STALE_LOCK_MS)
+                    return undefined;
+                await rm(file, { force: true });
+            }
+        return undefined;
+    }
+    async expireArtifacts(policy, now, report) {
+        if (policy.artifactsDays <= 0)
+            return;
+        for (const record of this.options.artifacts.readyBefore(now - policy.artifactsDays * DAY))
+            try {
+                const bytes = await sizeOf(this.options.artifacts.folder(record));
+                if (await this.options.artifacts.markExpired(record.id)) {
+                    report.artifactsExpired++;
+                    report.bytesFreed += bytes;
+                }
+            }
+            catch {
+                report.errors++;
+            }
+    }
+    async trimJobs(policy, now, report) {
+        if (policy.jobsDays <= 0 && policy.intermediateDays <= 0)
+            return;
+        const rows = this.options.db
+            .prepare("SELECT id, status, rel_dir, created_at, ended_at FROM analysis_executions")
+            .all();
+        const ready = this.options.db.prepare("SELECT count(*) AS n FROM artifacts WHERE execution_id=? AND status='ready'");
+        for (const row of rows) {
+            const stamp = row.ended_at ?? row.created_at;
+            if (row.status === "running" && now - row.created_at < STALE_RUNNING_MS)
+                continue;
+            const age = now - stamp;
+            const folder = join(this.options.root, row.rel_dir);
+            // Only folders under analysis/jobs are ever deleted, whatever a row says.
+            const inside = relative(join(this.options.root, "analysis", "jobs"), folder);
+            if (!inside || inside.startsWith("..") || isAbsolute(inside))
+                continue;
+            if (!(await exists(folder)))
+                continue;
+            try {
+                if (policy.intermediateDays > 0 && age > policy.intermediateDays * DAY) {
+                    const target = join(folder, "work");
+                    if (await exists(target)) {
+                        report.bytesFreed += await sizeOf(target);
+                        await rm(target, { recursive: true, force: true });
+                        report.workDeleted++;
+                    }
+                }
+                if (policy.jobsDays > 0 && age > policy.jobsDays * DAY) {
+                    for (const name of ["logs", "staging"]) {
+                        const target = join(folder, name);
+                        if (await exists(target)) {
+                            report.bytesFreed += await sizeOf(target);
+                            await rm(target, { recursive: true, force: true });
+                        }
+                    }
+                    const { n } = ready.get(row.id);
+                    if (n === 0) {
+                        report.bytesFreed += await sizeOf(folder);
+                        await rm(folder, { recursive: true, force: true });
+                        report.jobsDeleted++;
+                        await this.pruneEmptyParents(folder);
+                    }
+                    else
+                        report.jobsTrimmed++;
+                }
+            }
+            catch {
+                report.errors++;
+            }
+        }
+    }
+    /** Removes the empty session and workspace folders a deleted job leaves behind. */
+    async pruneEmptyParents(folder) {
+        const stop = join(this.options.root, "analysis", "jobs");
+        let dir = dirname(folder);
+        while (dir.startsWith(stop) && dir !== stop)
+            try {
+                await rmdir(dir);
+                dir = dirname(dir);
+            }
+            catch {
+                return; // not empty (or gone): done
+            }
+    }
+    async dropDatasets(policy, now, report) {
+        if (policy.jobsDays <= 0)
+            return;
+        const { datasets, blobs } = this.options;
+        const cutoff = now - policy.jobsDays * DAY;
+        if (datasets)
+            for (const record of datasets.all())
+                try {
+                    const info = await stat(datasets.file(record)).catch(() => undefined);
+                    // The file's modification time moves when the dataset is used (DatasetService.touch).
+                    const lastUse = info ? Math.max(record.createdAt, info.mtimeMs) : record.createdAt;
+                    if (lastUse >= cutoff)
+                        continue;
+                    const bytes = info?.size ?? 0;
+                    await datasets.remove(record);
+                    report.datasetsDeleted++;
+                    report.bytesFreed += bytes;
+                }
+                catch {
+                    report.errors++;
+                }
+        if (!blobs)
+            return;
+        // Uploaded originals: those no dataset refers to any more (and failed ingestions) go too.
+        const referenced = new Set(this.options.db
+            .prepare("SELECT blob_hash FROM datasets WHERE blob_hash IS NOT NULL")
+            .all().map((r) => r.blob_hash));
+        for (const hash of blobs.uploadsBefore(cutoff))
+            try {
+                if (referenced.has(hash))
+                    continue;
+                const freed = blobs.removeUpload(hash);
+                report.uploadsDeleted++;
+                report.bytesFreed += freed;
+            }
+            catch {
+                report.errors++;
+            }
+    }
+}

package/dist/analysis/jobs.d.ts

@@ -0,0 +1,94 @@
+import type { SqlDatabase } from "@alisio/sdk";
+export type ExecutionStatus = "running" | "completed" | "failed" | "cancelled" | "timed_out";
+export interface JobPaths {
+    id: string;
+    root: string;
+    script: string;
+    main: string;
+    input: string;
+    work: string;
+    staging: string;
+    logs: string;
+}
+export interface JobInput {
+    /** Name inside `input/`. */
+    name: string;
+    /** Hash of the content named in the provenance (for a dataset: the original file). */
+    sha256: string;
+    bytes: number;
+    /** Set for a dataset (the `.sqlite` file of §17): its id and the hash of the original file. */
+    datasetId?: string;
+    /** Hash of the copy inside `input/` (differs from `sha256` for a dataset's SQLite file). */
+    copySha256?: string;
+}
+/** What `job.json` records about the inputs, so a rerun can verify them (internal; never public). */
+export interface RecordedInputs {
+    inputs: JobInput[];
+    /** The `input/inputs.json` entries the script reads. */
+    manifest: unknown[];
+    /** Extras the run asked for (`python_run { extras }`), so a rerun asks for the same. */
+    extras?: string[];
+}
+export interface ExecutionDetails {
+    id: string;
+    sessionId: string;
+    rootSessionId: string;
+    workspace: string;
+    runtime: "managed" | "oci";
+    status: ExecutionStatus;
+    scriptSha256: string;
+    exitCode?: number;
+    relDir: string;
+    rerunOf?: string;
+    createdAt: number;
+    endedAt?: number;
+}
+/** Executions of `python_run` (`analysis_executions`) and their job folders. */
+export declare class AnalysisJobs {
+    private options;
+    constructor(options: {
+        root: string;
+        db: SqlDatabase;
+        now?: () => number;
+    });
+    private now;
+    /** Creates the job folder (script, runtime helpers, empty input/work/staging/logs) and its row. */
+    create(input: {
+        sessionId: string;
+        rootSessionId: string;
+        workspace: string;
+        runId?: string;
+        callId?: string;
+        code: string;
+        runtime: "managed" | "oci";
+        /** The execution this one repeats (a rerun); recorded in the row and in `job.json`. */
+        rerunOf?: string;
+    }): Promise<JobPaths & {
+        scriptSha256: string;
+    }>;
+    /**
+     * 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.
+     */
+    addInput(job: JobPaths, source: string, preferred?: string): Promise<JobInput>;
+    /** `input/inputs.json`: what each input is (the script reads it with `alisio_runtime.datasets.inputs()`). */
+    writeInputsManifest(job: JobPaths, entries: unknown[]): Promise<void>;
+    /** Adds the inputs to `job.json` (atomically), once they are copied into `input/`. */
+    recordInputs(job: JobPaths, recorded: RecordedInputs): Promise<void>;
+    /** The inputs a finished job recorded; `undefined` when `job.json` is missing or has none. */
+    recordedInputs(relDir: string): Promise<RecordedInputs | undefined>;
+    /** Absolute folder of an execution (`rel_dir` is always relative to the state root). */
+    folder(relDir: string): string;
+    /** The whole row of an execution. */
+    details(id: string): ExecutionDetails | undefined;
+    finish(id: string, status: ExecutionStatus, details?: {
+        exitCode?: number;
+        error?: string;
+    }): void;
+    get(id: string): {
+        status: ExecutionStatus;
+        exitCode?: number;
+        relDir: string;
+    } | undefined;
+}

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[];