@alisio/core 0.5.2 → 0.6.0

package/dist/analysis/janitor.d.ts

@@ -58,3 +58,51 @@ export declare class AnalysisJanitor {
     private pruneEmptyParents;
     private dropDatasets;
 }
+export interface ScratchSweepReport {
+    /** Why nothing ran: swept less than 24 h ago, or another process is sweeping. */
+    skipped?: "recent" | "locked";
+    sessionsDeleted: number;
+    bytesFreed: number;
+    errors: number;
+}
+/**
+ * Retention of the volatile Forja session directories (spec §9.4): every `<root>/<workspace>/
+ * <rootSessionId>` folder goes when its root session no longer exists or its last activity
+ * (newest file in it) is older than `retentionDays`; `0` disables the deletion.
+ *
+ * Before deleting, the folder must be a real directory (never a symlink) under a real directory
+ * under a verified root, its `.alisio-session` marker must name the same session as the folder,
+ * and its real path must stay inside the real root. `rm` never follows a symlink it meets inside.
+ * Same schedule as the analysis janitor: at most once every 24 h (mark under `<state>/forge/`),
+ * with a lock between processes; deletions are best effort and independent.
+ */
+export declare class ScratchJanitor {
+    private options;
+    private timer?;
+    private stopped;
+    constructor(options: {
+        /** State root; holds the sweep mark and lock under `forge/`. */
+        stateRoot: string;
+        /** The scratch roots to sweep: `<tmp>/alisio-<uid>` and `<state>/scratch`. */
+        roots: () => string[];
+        /** Whether the root session still exists in the store. */
+        sessionExists: (rootSessionId: string) => boolean;
+        /** Read at every sweep, so a changed setting applies without a restart. */
+        retentionDays: () => number;
+        now?: () => number;
+        initialDelayMs?: number;
+    });
+    private now;
+    private get dir();
+    lastSweep(): Promise<number | undefined>;
+    /** Launches the sweep in the background; never delays the caller and never keeps Node alive. */
+    start(): void;
+    stop(): void;
+    private arm;
+    sweep(options?: {
+        force?: boolean;
+    }): Promise<ScratchSweepReport>;
+    private sweepRoot;
+    /** Whether `folder` is a verified session folder that is due; adds its size to the report. */
+    private expired;
+}

package/dist/analysis/janitor.js

@@ -13,8 +13,9 @@
  *
  * 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";
+import { lstat, mkdir, readdir, readFile, realpath, rm, rmdir, stat, writeFile, } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { readSessionMarker } from "../forge/session-dir.js";
 const DAY = 86_400_000;
 export const SWEEP_INTERVAL_MS = DAY;
 /** A lock older than this belongs to a dead process. */
@@ -57,6 +58,27 @@ async function exists(path) {
         return false;
     }
 }
+/**
+ * Exclusive lock file `<dir>/<name>` between processes sharing the state folder; undefined when a
+ * live holder has it. A lock older than `STALE_LOCK_MS` belongs to a dead process and is replaced.
+ */
+async function acquireLock(dir, name) {
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, name);
+    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;
+}
 export class AnalysisJanitor {
     options;
     timer;
@@ -125,22 +147,8 @@ export class AnalysisJanitor {
         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;
+    lock() {
+        return acquireLock(this.dir, ".sweep.lock");
     }
     async expireArtifacts(policy, now, report) {
         if (policy.artifactsDays <= 0)
@@ -262,3 +270,147 @@ export class AnalysisJanitor {
             }
     }
 }
+/** Newest modification time and total size under `dir`, without following symlinks. */
+async function treeFacts(dir) {
+    const info = await lstat(dir);
+    let newest = info.mtimeMs;
+    let bytes = 0;
+    if (!info.isDirectory())
+        return { newest, bytes: info.size };
+    for (const entry of await readdir(dir)) {
+        const facts = await treeFacts(join(dir, entry)).catch(() => undefined);
+        if (!facts)
+            continue;
+        newest = Math.max(newest, facts.newest);
+        bytes += facts.bytes;
+    }
+    return { newest, bytes };
+}
+/** A directory that is really one (not a symlink to one). */
+async function realDirectory(path) {
+    const info = await lstat(path).catch(() => undefined);
+    return !!info && info.isDirectory() && !info.isSymbolicLink();
+}
+/**
+ * Retention of the volatile Forja session directories (spec §9.4): every `<root>/<workspace>/
+ * <rootSessionId>` folder goes when its root session no longer exists or its last activity
+ * (newest file in it) is older than `retentionDays`; `0` disables the deletion.
+ *
+ * Before deleting, the folder must be a real directory (never a symlink) under a real directory
+ * under a verified root, its `.alisio-session` marker must name the same session as the folder,
+ * and its real path must stay inside the real root. `rm` never follows a symlink it meets inside.
+ * Same schedule as the analysis janitor: at most once every 24 h (mark under `<state>/forge/`),
+ * with a lock between processes; deletions are best effort and independent.
+ */
+export class ScratchJanitor {
+    options;
+    timer;
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    get dir() {
+        return join(this.options.stateRoot, "forge");
+    }
+    async lastSweep() {
+        try {
+            const value = Number((await readFile(join(this.dir, ".last-scratch-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();
+    }
+    async sweep(options = {}) {
+        const report = { sessionsDeleted: 0, bytesFreed: 0, errors: 0 };
+        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 acquireLock(this.dir, ".scratch-sweep.lock");
+        if (!release)
+            return { ...report, skipped: "locked" };
+        try {
+            await writeFile(join(this.dir, ".last-scratch-sweep"), `${now}\n`);
+            const days = this.options.retentionDays();
+            if (days <= 0)
+                return report;
+            for (const root of this.options.roots())
+                await this.sweepRoot(root, days, now, report);
+        }
+        finally {
+            await release();
+        }
+        return report;
+    }
+    async sweepRoot(root, days, now, report) {
+        if (!(await realDirectory(root)))
+            return;
+        let realRoot;
+        try {
+            realRoot = await realpath(root);
+        }
+        catch {
+            return;
+        }
+        for (const workspace of await readdir(root).catch(() => [])) {
+            const workspaceDir = join(root, workspace);
+            if (!(await realDirectory(workspaceDir)))
+                continue;
+            for (const id of await readdir(workspaceDir).catch(() => [])) {
+                const folder = join(workspaceDir, id);
+                try {
+                    if (await this.expired(folder, id, realRoot, days, now, report)) {
+                        await rm(folder, { recursive: true, force: true });
+                        report.sessionsDeleted++;
+                    }
+                }
+                catch {
+                    report.errors++;
+                }
+            }
+            // Drop the workspace folder when its last session went (rmdir only removes an empty one).
+            await rmdir(workspaceDir).catch(() => undefined);
+        }
+    }
+    /** Whether `folder` is a verified session folder that is due; adds its size to the report. */
+    async expired(folder, id, realRoot, days, now, report) {
+        if (!(await realDirectory(folder)))
+            return false;
+        const marker = await readSessionMarker(folder);
+        if (!marker || marker.sessionId !== basename(folder) || marker.sessionId !== id)
+            return false;
+        const real = await realpath(folder);
+        if (!real.startsWith(realRoot + sep))
+            return false;
+        const facts = await treeFacts(folder);
+        const due = !this.options.sessionExists(id) || now - facts.newest > days * DAY;
+        if (due)
+            report.bytesFreed += facts.bytes;
+        return due;
+    }
+}

package/dist/analysis/jobs.d.ts

@@ -1,4 +1,6 @@
 import type { SqlDatabase } from "@alisio/sdk";
+/** Where an execution ran (`analysis_executions.runtime`). */
+export type AnalysisBackendId = "managed" | "oci" | "wasm";
 export type ExecutionStatus = "running" | "completed" | "failed" | "cancelled" | "timed_out";
 export interface JobPaths {
     id: string;
@@ -34,7 +36,7 @@ export interface ExecutionDetails {
     sessionId: string;
     rootSessionId: string;
     workspace: string;
-    runtime: "managed" | "oci";
+    runtime: AnalysisBackendId;
     status: ExecutionStatus;
     scriptSha256: string;
     exitCode?: number;
@@ -52,6 +54,8 @@ export declare class AnalysisJobs {
         now?: () => number;
     });
     private now;
+    /** The store's database (Forja's journal and state live in it too). */
+    get database(): SqlDatabase;
     /** Creates the job folder (script, runtime helpers, empty input/work/staging/logs) and its row. */
     create(input: {
         sessionId: string;
@@ -60,7 +64,7 @@ export declare class AnalysisJobs {
         runId?: string;
         callId?: string;
         code: string;
-        runtime: "managed" | "oci";
+        runtime: AnalysisBackendId;
         /** The execution this one repeats (a rerun); recorded in the row and in `job.json`. */
         rerunOf?: string;
     }): Promise<JobPaths & {
@@ -74,6 +78,11 @@ export declare class AnalysisJobs {
     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>;
+    /**
+     * `work/.forge/state.json`: the Forja state snapshot a script reads with `forge.state.get`. A
+     * copy, written fresh for every run; changes travel back as protocol messages, never through it.
+     */
+    writeForgeState(job: JobPaths, values: Record<string, 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. */

package/dist/analysis/jobs.js

@@ -21,6 +21,10 @@ export class AnalysisJobs {
     now() {
         return (this.options.now ?? Date.now)();
     }
+    /** The store's database (Forja's journal and state live in it too). */
+    get database() {
+        return this.options.db;
+    }
     /** Creates the job folder (script, runtime helpers, empty input/work/staging/logs) and its row. */
     async create(input) {
         const id = newId("exec", this.now());
@@ -84,6 +88,15 @@ export class AnalysisJobs {
     async writeInputsManifest(job, entries) {
         await writeFile(join(job.input, "inputs.json"), `${JSON.stringify(entries, null, 2)}\n`);
     }
+    /**
+     * `work/.forge/state.json`: the Forja state snapshot a script reads with `forge.state.get`. A
+     * copy, written fresh for every run; changes travel back as protocol messages, never through it.
+     */
+    async writeForgeState(job, values) {
+        const dir = join(job.work, ".forge");
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, "state.json"), JSON.stringify(values));
+    }
     /** Adds the inputs to `job.json` (atomically), once they are copied into `input/`. */
     async recordInputs(job, recorded) {
         const file = join(job.root, "job.json");

package/dist/analysis/oci.d.ts

@@ -13,6 +13,8 @@ export interface OciMounts {
     input: string;
     work: string;
     staging: string;
+    /** The Forja scratchpad, mounted read-only at `/job/scratch` (Forja spec §9.4). Optional. */
+    scratch?: string;
 }
 /** Paths inside the container (spec §8.3). */
 export declare const CONTAINER: {
@@ -20,6 +22,7 @@ export declare const CONTAINER: {
     readonly input: "/job/input";
     readonly work: "/job/work";
     readonly out: "/job/out";
+    readonly scratch: "/job/scratch";
 };
 export declare const PIDS_LIMIT = 256;
 export declare const TMPFS_SIZE = "256m";
@@ -94,7 +97,11 @@ export declare class OciRuntime {
      */
     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>;
+    unavailable(signal?: AbortSignal, 
+    /** `auto` chooses the runtime itself, so the messages must not talk about `analysis.runtime: "oci"`. */
+    options?: {
+        auto?: boolean;
+    }): 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.
@@ -105,12 +112,14 @@ export declare class OciRuntime {
         signal: AbortSignal;
         timeoutMs: number;
         maxBytes: number;
-        onData?: (chunk: string) => void;
+        onData?: (chunk: string, stream: "stdout" | "stderr") => void;
         logFiles: {
             stdout: string;
             stderr: string;
         };
         maxLogBytes: number;
+        /** Extra variables for the script (Forja: the frame nonce). */
+        env?: Record<string, string>;
     }): Promise<ProcessResult & {
         containerName: string;
     }>;

package/dist/analysis/oci.js

@@ -19,6 +19,7 @@ export const CONTAINER = {
     input: "/job/input",
     work: "/job/work",
     out: "/job/out",
+    scratch: "/job/scratch",
 };
 export const PIDS_LIMIT = 256;
 export const TMPFS_SIZE = "256m";
@@ -69,7 +70,10 @@ export function ociRunArgs(input) {
         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}`);
+    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"));
+    if (input.mounts.scratch)
+        args.push("-v", mount(input.mounts.scratch, CONTAINER.scratch, "ro"));
+    args.push("--tmpfs", `/tmp:size=${TMPFS_SIZE}`);
     const env = {
         ALISIO_INPUT_DIR: CONTAINER.input,
         ALISIO_OUTPUT_DIR: CONTAINER.out,
@@ -83,6 +87,7 @@ export function ociRunArgs(input) {
         PYTHONUNBUFFERED: "1",
         PYTHONNOUSERSITE: "1",
         PYTHONIOENCODING: "utf-8",
+        ...(input.mounts.scratch ? { ALISIO_SCRATCH_DIR: CONTAINER.scratch } : {}),
         ...input.env,
     };
     for (const [key, value] of Object.entries(env))
@@ -191,16 +196,26 @@ export class OciRuntime {
         }
     }
     /** The reason a run cannot start (`undefined` = ready), checked before any job is created. */
-    async unavailable(signal) {
+    async unavailable(signal, 
+    /** `auto` chooses the runtime itself, so the messages must not talk about `analysis.runtime: "oci"`. */
+    options = {}) {
         const { image } = this.settings;
+        if (!image && options.auto)
+            return "no container image is set (analysis.oci.image); `alisio analysis setup --oci --image <name>` prints the value";
         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.`;
+        if (!status.ok) {
+            const alternative = status.alternative
+                ? `; ${status.alternative} is installed (set analysis.oci.engine to "${status.alternative}")`
+                : "";
+            return options.auto
+                ? `${status.reason}${alternative}`
+                : `${status.reason}${alternative}. The container runtime is optional: remove analysis.runtime "oci" to use managed Python.`;
+        }
         return undefined;
     }
     /**
@@ -221,6 +236,7 @@ export class OciRuntime {
             executionId: input.executionId,
             mounts: input.mounts,
             host: { ...host, rootless: status.ok ? status.rootless : false },
+            ...(input.env ? { env: input.env } : {}),
         });
         const name = containerName(input.executionId);
         const stop = AbortSignal.any([input.signal, AbortSignal.timeout(input.timeoutMs)]);