@alisio/core 0.5.2 → 0.7.0

package/dist/forge/guides/python.js

@@ -0,0 +1,170 @@
+/** Python spec §4.3, one row per backend; the guide never states more than this. */
+const GUARANTEES = {
+    managed: [
+        "Isolation: none. The script runs with your user permissions: it can read your files and use the network.",
+        "Termination: the process is killed on timeout. Memory: no hard limit.",
+    ],
+    oci: [
+        "Isolation: os-container. Network off (`--network=none`); only the job folders are mounted (the scratchpad read-only).",
+        "Termination: the container is killed on timeout. Memory: hard limit (cgroup).",
+    ],
+    wasm: [
+        "Isolation: wasm-process (Pyodide in a restricted Node process). It reads only the Pyodide distribution and the job, and writes only its work/ and out/ folders.",
+        "Network: NOT blocked by the OS on Node 22/24; do not rely on it being off. Memory: soft limit (RSS watchdog). Termination: the process is killed on timeout.",
+    ],
+};
+const SETUP_NOTE = "Setup commands are run by the user, never by you: `alisio analysis setup --wasm [--profile analysis|science]` or `alisio analysis setup --oci`.";
+const has = (env, pkg) => {
+    if (!env.available)
+        return false;
+    if (!env.packages.known)
+        return undefined;
+    return env.packages.packages.includes(pkg);
+};
+/** What the model should know about one package group right now. */
+function availability(env, pkgs) {
+    const states = pkgs.map((pkg) => has(env, pkg));
+    if (states.every((s) => s === true))
+        return "available";
+    if (states.every((s) => s === undefined))
+        return "depends on the container image (not listed here)";
+    const missing = pkgs.filter((_, i) => states[i] === false);
+    return `NOT available (${missing.join(", ")} missing)`;
+}
+function installAdvice(env, profile) {
+    if (env.backend === "wasm")
+        return `ask the user to run \`alisio analysis setup --wasm --profile ${profile}\``;
+    if (env.backend === "managed")
+        return `pass \`extras: ["${profile}"]\` (the user approves the download once)`;
+    return "use an image that includes them (`analysis.oci.image`)";
+}
+export function pythonRuntimeGuide(env) {
+    return [
+        "# python_run runtime",
+        "",
+        "Your script runs once in a job folder outside the repository, with `main.py` as the entry. The helper package `alisio_runtime` (standard library only) is importable.",
+        "",
+        "## Folders (environment variables)",
+        "- `ALISIO_OUTPUT_DIR`: everything written here is published as a downloadable artifact only if the script exits 0 (`publishOnError` keeps partial output). Publication is validated by the host: paths, sizes and types. An `outputs.json` limits publishing to the files it declares.",
+        "- `ALISIO_INPUT_DIR`: read-only copies of `inputs`. `ALISIO_WORK_DIR`: scratch, also the current directory.",
+        "- `ALISIO_SCRATCH_DIR`: the session scratchpad, READ-ONLY (write scripts there with the file tools, run them with `codePath`).",
+        "- `ALISIO_EXECUTION_ID` identifies the run. `ALISIO_FORGE_*` belong to the protocol: never print them or fake their lines.",
+        "",
+        "## alisio_runtime",
+        "- `output_dir()`, `input_dir()`, `work_dir()`, `execution_id()`; `outputs.path(name)` makes a new output path, `outputs.declare(name, title)` registers it.",
+        "- `forge.progress(message, completed=, total=)`, `forge.text(value)` (explicit output for you), `forge.result(value)` (the final JSON value), `forge.state.get/set/delete` (small JSON shared with js_run; kept only if the run succeeds).",
+        "- `datasets`, `html`, `charts`, `svg`: see `python.data` and `python.dashboards`.",
+        "",
+        "## Rules",
+        "- Print little: stdout and stderr return only their last 4 KB. Use `forge.text`/`forge.result` for what you need to read.",
+        "- No nested tool calls and no JavaScript from Python. Chain tools yourself, or compose with `js_run` first.",
+        "- Keep each script short; save long ones to the scratchpad. Rerun an earlier analysis unchanged with `rerunOf`.",
+        `- Packages depend on the backend: see \`python.environment\` (now: ${env.available ? env.backend : "no backend can run"}).`,
+    ].join("\n");
+}
+export function pythonDataGuide(env) {
+    const pandas = availability(env, ["pandas"]);
+    return [
+        "# Data in python_run",
+        "",
+        "## Which tool",
+        "- A SQL question on a loaded dataset: `data_query` (no code, read-only). Use `data_inspect` first for tables and columns.",
+        "- Joins across files, statistics, models, exports, or anything SQL cannot do: `python_run`.",
+        "",
+        "## Inputs",
+        "- `inputs: [{ datasetId }]` copies a dataset to `$ALISIO_INPUT_DIR/<name>.sqlite`; `inputs: [{ path }]` copies a workspace file.",
+        "- `from alisio_runtime import datasets`: `datasets.inputs()` lists what was placed; `datasets.open(name)` returns a read-only `sqlite3` connection (table `data`, or `s_<sheet>` for workbooks); `datasets.tables(name)` and `datasets.columns(name, table)` describe them.",
+        "- XLSX files are converted to SQLite by `alisio_runtime/xlsx_to_sqlite.py` (standard library `sqlite3`); you rarely need to call it yourself.",
+        "",
+        "## pandas",
+        `- pandas is ${pandas} on the backend that would run now.`,
+        "- Without pandas use `sqlite3`, `csv`, `statistics` and `json` from the standard library.",
+        '- `pandas.read_sql_query("SELECT * FROM data", datasets.open(name))` loads a dataset.',
+        ...(env.available && env.backend === "wasm"
+            ? ["- The wasm backend limits the total input size (`analysis.wasm.maxInputBytes`)."]
+            : []),
+    ].join("\n");
+}
+export function pythonMlGuide(env) {
+    const science = availability(env, ["scipy", "statsmodels", "scikit-learn"]);
+    const where = env.available
+        ? `Backend that would run now: ${env.backend}.`
+        : "No Python backend can run right now (see `python.environment`).";
+    return [
+        "# Statistics and machine learning",
+        "",
+        where,
+        `- scikit-learn, statsmodels and scipy are ${science}.`,
+        ...(env.available && has(env, "scikit-learn") === false
+            ? [`- To get them: ${installAdvice(env, "science")}.`]
+            : []),
+        "",
+        "## Patterns",
+        "- Split first: `train_test_split(X, y, test_size=0.2, random_state=0)`; fix `random_state` so a rerun gives the same numbers.",
+        "- Tabular baseline: `sklearn.ensemble.RandomForestClassifier` or `sklearn.linear_model.LogisticRegression`; report accuracy AND a baseline (majority class) with `forge.result({...})`.",
+        "- Inference and tests: `scipy.stats.ttest_ind`, `chi2_contingency`; regression with coefficients and p-values: `statsmodels.api.OLS(y, sm.add_constant(X)).fit().summary()`.",
+        '- Return numbers, not objects: `forge.result({"r2": float(r2), "n": int(n)})`. JSON cannot hold NaN or Infinity; convert them first.',
+        "- Keep a time budget in mind: heavy training can exceed the call's timeout. Subsample first, then scale up.",
+        "- Pandas first, then models; without the science packages use the standard library `statistics` for descriptive work.",
+    ].join("\n");
+}
+export function pythonDashboardsGuide(env) {
+    const plotly = availability(env, ["plotly"]);
+    const matplotlib = availability(env, ["matplotlib"]);
+    return [
+        "# Charts and dashboards",
+        "",
+        ...(env.smartDashboard
+            ? [
+                "- A standard dashboard from a dataset: `dashboard_generate` (no code). Use `python_run` only for visuals its catalog does not cover.",
+            ]
+            : ["- `dashboard_generate` is not enabled here: build dashboards with `alisio_runtime`."]),
+        "",
+        "## alisio_runtime (no extra packages)",
+        "- `charts`: Chart.js is bundled. `charts.pie/donut/bar/hbar/line/area/scatter(labels, values, title=, fmt='currency:USD', locale=)` return HTML; compose with `charts.card(title, chart)`, `charts.grid(*cards)`, `charts.kpis((label, value), ...)`, then `charts.write('dashboard.html', 'Title', body)`.",
+        "- `html`: `html.page/table/write` for plain reports. `svg`: static SVG, no script.",
+        "- Never hand-write SVG arcs, never load a CDN: HTML is shown offline, so inline every script and style. One chart per card; pie only for 2 to 5 parts.",
+        "",
+        "## Static images",
+        `- matplotlib is ${matplotlib}. It runs with the Agg backend: save a PNG with \`fig.savefig(output_dir() / 'chart.png', dpi=150)\`; \`plt.show()\` does nothing.`,
+        `- plotly is ${plotly}. Write a self-contained file with \`fig.write_html(path, include_plotlyjs=True)\` (several MB); prefer \`charts\` when it is enough.`,
+        "",
+        "A folder under the output directory with an `index.html` is published as one multi-file dashboard.",
+    ].join("\n");
+}
+export function pythonEnvironmentGuide(env) {
+    if (!env.available)
+        return [
+            "# Python environment",
+            "",
+            "No Python backend can run a script right now.",
+            "",
+            env.reason,
+            "",
+            SETUP_NOTE,
+            "Until one is ready, use `js_run` or the dataset tools (`data_inspect`, `data_query`).",
+        ].join("\n");
+    const packages = env.packages.known
+        ? env.packages.packages.length
+            ? env.packages.packages.join(", ")
+            : "none beyond the standard library"
+        : "those baked into the container image (not listed here)";
+    return [
+        "# Python environment",
+        "",
+        `Backend that runs your next script: ${env.backend} (${env.reason}).`,
+        "",
+        "## Guarantees of this backend",
+        ...GUARANTEES[env.backend].map((line) => `- ${line}`),
+        "",
+        "## Packages here",
+        `- Standard library and \`alisio_runtime\` always. ${env.packages.detail}`,
+        `- Installed: ${packages}.`,
+        "- Anything else fails with `PACKAGE_UNAVAILABLE`/`ModuleNotFoundError` and is never retried on another backend.",
+        ...(env.packages.known && !env.packages.packages.includes("scikit-learn")
+            ? ["", `For scikit-learn, statsmodels and scipy: ${installAdvice(env, "science")}.`]
+            : []),
+        "",
+        SETUP_NOTE,
+    ].join("\n");
+}

package/dist/forge/javascript/engine.d.ts

@@ -0,0 +1,44 @@
+import type { EngineDescriptor } from "@alisio/sdk";
+import type { EngineOutcome, ExecutionEngine, ExecutionRequest, IsolateHost, IsolateSession, KernelChannel, PreparedExecution, TerminationReason, TerminationReport, TrustedExecutionContext } from "../ports.ts";
+import type { IsolateHostFactory } from "./hosts/factory.ts";
+export interface PreparedJavaScript extends PreparedExecution {
+    readonly source: string;
+    /** The state snapshot the script starts with. */
+    readonly state: Record<string, unknown>;
+    readonly catalogSize: number;
+    readonly host: IsolateHost;
+    session?: IsolateSession;
+    /** Ends the run with a host verdict; set by `run`, used when a stop cannot be confirmed. */
+    forceEnd?: () => void;
+}
+export interface JavaScriptEngineOptions {
+    hosts: IsolateHostFactory;
+    /** The verified module; defaults to the process-wide cache. */
+    loadModule?: () => Promise<WebAssembly.Module>;
+}
+export declare class JavaScriptEngine implements ExecutionEngine {
+    #private;
+    readonly id: "javascript-quickjs";
+    constructor(options: JavaScriptEngineOptions);
+    /**
+     * Cheap self-check (runs at startup): the WASM matches its pinned hash and compiles, and the
+     * files the chosen host starts exist. The full spin-up of an isolate is `probe()`.
+     */
+    describe(): Promise<EngineDescriptor>;
+    /** The kind of host that runs the isolates (`forge status`). */
+    get hostKind(): "worker" | "process";
+    prepare(request: ExecutionRequest, ctx: TrustedExecutionContext): Promise<PreparedJavaScript>;
+    run(prepared: PreparedExecution, channel: KernelChannel): Promise<EngineOutcome>;
+    terminate(prepared: PreparedExecution, reason: TerminationReason): Promise<TerminationReport>;
+    dispose(prepared: PreparedExecution): Promise<void>;
+    /**
+     * Full self-test (`alisio forge status`): starts a real isolate, runs `return 1` and reports how
+     * long it took. Nothing here is on the hot path of a normal execution.
+     */
+    probe(): Promise<{
+        ok: boolean;
+        reason?: string;
+        bootMs?: number;
+        host: "worker" | "process";
+    }>;
+}

package/dist/forge/javascript/engine.js

@@ -0,0 +1,229 @@
+/**
+ * `JavaScriptEngine` (spec §6, D1-D5): the `ExecutionEngine` strategy that runs a script in a
+ * QuickJS-WASM VM inside an isolate host. It owns the transport and the lifecycle of the isolate;
+ * what the guest's messages MEAN (tool calls, state, output, budget) is the kernel's broker.
+ *
+ * Host-side checks, whatever the guest says: every message passes `GuestMessageValidator`
+ * (schema, sequence, correlation, size, depth, forbidden keys, capability gate); a violation or a
+ * handler error terminates the isolate and fails the execution with the matching code.
+ */
+import { access } from "node:fs/promises";
+import { isForgeError } from "../errors.js";
+import { GuestMessageValidator } from "../protocol.js";
+import { resolveIsolateCommand } from "./hosts/process-host.js";
+import { workerEntryUrl } from "./hosts/worker-host.js";
+import { PRELUDE_HASH } from "./prelude.js";
+import { FORGE_PROTOCOL_VERSION, JAVASCRIPT_ENGINE_VERSION } from "./runtime-manifest.js";
+import { loadQuickJsModule } from "./wasm.js";
+const GUEST_LIMIT_KEYS = [
+    "timeoutMs",
+    "memoryBytes",
+    "stackBytes",
+    "maxToolCalls",
+    "maxConcurrency",
+    "maxCallInputBytes",
+    "maxCallResponseBytes",
+    "maxRetainedOutputBytes",
+];
+const guestLimits = (limits) => Object.fromEntries(GUEST_LIMIT_KEYS.map((key) => [key, limits[key]]));
+export class JavaScriptEngine {
+    id = "javascript-quickjs";
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    #module() {
+        return (this.#options.loadModule ?? loadQuickJsModule)();
+    }
+    /**
+     * Cheap self-check (runs at startup): the WASM matches its pinned hash and compiles, and the
+     * files the chosen host starts exist. The full spin-up of an isolate is `probe()`.
+     */
+    async describe() {
+        const base = {
+            id: this.id,
+            language: "javascript",
+            version: JAVASCRIPT_ENGINE_VERSION,
+            isolation: "wasm-isolate",
+            ready: true,
+            capabilities: {
+                cooperativeInterrupt: true,
+                hardTermination: true,
+                hardMemoryLimit: false,
+                networkDeniedByOS: false,
+                toolCalls: true,
+            },
+        };
+        const unavailable = (reason) => ({ ...base, ready: false, reason });
+        try {
+            await this.#module();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return unavailable(`the QuickJS runtime failed verification (${message}); reinstall @alisio/core`);
+        }
+        try {
+            if (this.#options.hosts.kind === "worker")
+                await access(workerEntryUrl());
+            else {
+                const command = resolveIsolateCommand();
+                await access(command.execPath);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return unavailable(`the ${this.#options.hosts.kind} isolate host cannot start (${message})`);
+        }
+        return base;
+    }
+    /** The kind of host that runs the isolates (`forge status`). */
+    get hostKind() {
+        return this.#options.hosts.kind;
+    }
+    async prepare(request, ctx) {
+        await this.#module();
+        const payload = request.payload ?? {};
+        return {
+            executionId: ctx.executionId,
+            engine: this.id,
+            limits: ctx.limits,
+            source: request.source,
+            state: payload.state ?? {},
+            catalogSize: typeof payload.catalogSize === "number" ? payload.catalogSize : 0,
+            host: await this.#options.hosts.create(),
+        };
+    }
+    async run(prepared, channel) {
+        const job = prepared;
+        const session = job.host.start();
+        job.session = session;
+        const validator = new GuestMessageValidator({ toolCalls: true });
+        let hostSeq = 0;
+        let settled = false;
+        return new Promise((resolve) => {
+            const send = (reply) => {
+                if (settled)
+                    return;
+                // Answering a call or a lookup closes its correlation (a second answer is a bug).
+                if (reply.type === "result")
+                    validator.resolveCall(reply.payload.callId);
+                else if (reply.type === "catalog.result")
+                    validator.resolveCatalog(reply.payload.requestId);
+                session.send({ protocol: FORGE_PROTOCOL_VERSION, seq: hostSeq++, ...reply });
+            };
+            const finish = (outcome, stop) => {
+                if (settled)
+                    return;
+                settled = true;
+                validator.close();
+                // The guest ends itself after its terminal message; a failure stops it from here.
+                if (stop)
+                    void session.stop(stop);
+                resolve(outcome);
+            };
+            const fail = (code, message, stop) => finish({ kind: "failed", code, message }, stop);
+            // The kernel stopped the run (deadline or cancellation) and the isolate never confirmed it
+            // is gone: no terminal message and no exit will come, so the host ends the run itself. The
+            // kernel's own verdict decides the status; the unconfirmed report is journaled from there.
+            job.forceEnd = () => finish({
+                kind: "failed",
+                code: "ISOLATE_FAILURE",
+                message: "the isolate did not confirm that it stopped",
+            });
+            session.onStreamError((reason) => fail("PROTOCOL_VIOLATION", reason, "protocol_violation"));
+            session.exited.then((exit) => {
+                if (settled)
+                    return;
+                const detail = exit.error ?? `code ${String(exit.code)}${exit.signal ? `, signal ${exit.signal}` : ""}`;
+                finish({
+                    kind: "failed",
+                    code: "ISOLATE_FAILURE",
+                    message: `the isolate exited unexpectedly (${detail})`,
+                });
+            });
+            session.onMessage((raw) => {
+                if (settled)
+                    return;
+                const checked = validator.accept(raw);
+                if (!checked.ok)
+                    return fail("PROTOCOL_VIOLATION", checked.error.message, "protocol_violation");
+                const message = checked.message;
+                if (message.type === "complete") {
+                    const value = message.payload.value;
+                    return finish({ kind: "completed", ...(value !== undefined ? { value } : {}) });
+                }
+                if (message.type === "fatal") {
+                    return finish({
+                        kind: "failed",
+                        code: message.payload.code,
+                        message: message.payload.message,
+                    });
+                }
+                if (message.type === "ready") {
+                    if (message.payload.engine !== this.id || message.payload.preludeHash !== PRELUDE_HASH)
+                        return fail("PROTOCOL_VIOLATION", "the isolate runs an unexpected prelude", "protocol_violation");
+                    send({
+                        type: "start",
+                        payload: {
+                            source: job.source,
+                            state: job.state,
+                            limits: guestLimits(job.limits),
+                            catalogSize: job.catalogSize,
+                        },
+                    });
+                }
+                Promise.resolve()
+                    .then(() => channel.receive(message))
+                    .then((reply) => {
+                    if (reply)
+                        send(reply);
+                })
+                    .catch((error) => {
+                    if (isForgeError(error))
+                        return fail(error.code, error.message, "limit_exceeded");
+                    fail("ISOLATE_FAILURE", error instanceof Error ? error.message : String(error), "limit_exceeded");
+                });
+            });
+            channel.bind(send);
+        });
+    }
+    async terminate(prepared, reason) {
+        const job = prepared;
+        const session = job.session;
+        if (!session)
+            return { confirmed: true, method: "interrupt", elapsedMs: 0 };
+        const report = await session.stop(reason);
+        if (!report.confirmed)
+            job.forceEnd?.();
+        return report;
+    }
+    async dispose(prepared) {
+        const session = prepared.session;
+        if (!session)
+            return;
+        // A normal run ends with the guest leaving by itself; anything still alive is stopped now.
+        const gone = await Promise.race([
+            session.exited.then(() => true),
+            new Promise((resolve) => setTimeout(() => resolve(false), 250).unref?.()),
+        ]);
+        if (!gone)
+            await session.stop("limit_exceeded");
+    }
+    /**
+     * Full self-test (`alisio forge status`): starts a real isolate, runs `return 1` and reports how
+     * long it took. Nothing here is on the hot path of a normal execution.
+     */
+    async probe() {
+        const host = this.#options.hosts.kind;
+        const started = performance.now();
+        try {
+            const { probeIsolate } = await import("./probe.js");
+            const module = await this.#module();
+            await probeIsolate(await this.#options.hosts.create(), module);
+            return { ok: true, host, bootMs: Math.round(performance.now() - started) };
+        }
+        catch (error) {
+            return { ok: false, host, reason: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}

package/dist/forge/javascript/hosts/factory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Chooses the isolate host (spec §6.3, D-20). Node always gets the worker; Bun (directly or as a
+ * compiled binary) gets the child process, because `worker.terminate()` does not reliably stop a
+ * WASM loop there. `forge.javascript.host` can force either one for diagnosis. The only runtime
+ * detection in Forja lives here and reads `process.versions.bun`, not a Bun global.
+ */
+import type { IsolateHost } from "../../ports.ts";
+import { type ProcessHostOptions } from "./process-host.ts";
+import { type WorkerHostOptions } from "./worker-host.ts";
+export type HostChoice = "auto" | "worker" | "process";
+export declare function chooseHostKind(choice: HostChoice, bun?: boolean): "worker" | "process";
+export interface IsolateHostFactoryOptions {
+    choice: HostChoice;
+    /** The verified, compiled module (the worker receives it; the child compiles its own copy). */
+    module: () => Promise<WebAssembly.Module>;
+    worker?: Omit<WorkerHostOptions, "module">;
+    process?: ProcessHostOptions;
+    bun?: boolean;
+}
+export declare class IsolateHostFactory {
+    #private;
+    constructor(options: IsolateHostFactoryOptions);
+    get kind(): "worker" | "process";
+    create(): Promise<IsolateHost>;
+}

package/dist/forge/javascript/hosts/factory.js

@@ -0,0 +1,21 @@
+import { ProcessIsolateHost } from "./process-host.js";
+import { WorkerIsolateHost } from "./worker-host.js";
+export function chooseHostKind(choice, bun = !!process.versions.bun) {
+    if (choice !== "auto")
+        return choice;
+    return bun ? "process" : "worker";
+}
+export class IsolateHostFactory {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    get kind() {
+        return chooseHostKind(this.#options.choice, this.#options.bun);
+    }
+    async create() {
+        if (this.kind === "process")
+            return new ProcessIsolateHost(this.#options.process);
+        return new WorkerIsolateHost({ ...this.#options.worker, module: await this.#options.module() });
+    }
+}

package/dist/forge/javascript/hosts/framing.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Length-prefixed JSON framing of the process host (spec §6.3, D10): a big-endian u32 byte count
+ * followed by that many bytes of UTF-8 JSON. Pure. A frame over the limit or a body that is not
+ * JSON breaks the stream: the caller treats it as a protocol violation and kills the child.
+ *
+ * Erasable TypeScript only (D-33): the isolate process loads this file under type stripping.
+ */
+export declare function encodeFrame(message: unknown): Buffer;
+export declare class FrameStreamError extends Error {
+    constructor(message: string);
+}
+export declare class FrameDecoder {
+    #private;
+    constructor(maxFrameBytes: number);
+    /** Adds bytes and returns every message completed by them. Throws `FrameStreamError`. */
+    push(chunk: Uint8Array): unknown[];
+}

package/dist/forge/javascript/hosts/framing.js

@@ -0,0 +1,49 @@
+/**
+ * Length-prefixed JSON framing of the process host (spec §6.3, D10): a big-endian u32 byte count
+ * followed by that many bytes of UTF-8 JSON. Pure. A frame over the limit or a body that is not
+ * JSON breaks the stream: the caller treats it as a protocol violation and kills the child.
+ *
+ * Erasable TypeScript only (D-33): the isolate process loads this file under type stripping.
+ */
+export function encodeFrame(message) {
+    const body = Buffer.from(JSON.stringify(message), "utf8");
+    const header = Buffer.allocUnsafe(4);
+    header.writeUInt32BE(body.length, 0);
+    return Buffer.concat([header, body]);
+}
+export class FrameStreamError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FrameStreamError";
+    }
+}
+export class FrameDecoder {
+    #buffer = Buffer.alloc(0);
+    #maxFrameBytes;
+    constructor(maxFrameBytes) {
+        this.#maxFrameBytes = maxFrameBytes;
+    }
+    /** Adds bytes and returns every message completed by them. Throws `FrameStreamError`. */
+    push(chunk) {
+        this.#buffer =
+            this.#buffer.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.#buffer, chunk]);
+        const messages = [];
+        while (this.#buffer.length >= 4) {
+            const size = this.#buffer.readUInt32BE(0);
+            // The size is checked before the body is buffered: a hostile length never allocates.
+            if (size > this.#maxFrameBytes)
+                throw new FrameStreamError(`frame of ${size} bytes exceeds the ${this.#maxFrameBytes} limit`);
+            if (this.#buffer.length < 4 + size)
+                break;
+            const body = this.#buffer.subarray(4, 4 + size).toString("utf8");
+            this.#buffer = this.#buffer.subarray(4 + size);
+            try {
+                messages.push(JSON.parse(body));
+            }
+            catch {
+                throw new FrameStreamError("frame is not valid JSON");
+            }
+        }
+        return messages;
+    }
+}

package/dist/forge/javascript/hosts/isolate-main.d.ts

@@ -0,0 +1,9 @@
+export interface WorkerIsolateData {
+    forgeIsolate: 1;
+    module: WebAssembly.Module;
+    flag: SharedArrayBuffer;
+}
+/** Body of a worker thread started by `WorkerIsolateHost`. */
+export declare function runWorkerIsolate(): Promise<void>;
+/** Body of the child process started by `ProcessIsolateHost` (or by `alisio __forge-isolate`). */
+export declare function runProcessIsolate(env?: Record<string, string | undefined>): Promise<void>;

package/dist/forge/javascript/hosts/isolate-main.js

@@ -0,0 +1,63 @@
+/**
+ * What runs inside an isolate (spec §6.3, D-20, D-21): the worker thread body and the child
+ * process body. Both build a `GuestTransport` over their channel and hand it to `runGuest`.
+ *
+ * The process variant refuses to run unless `ALISIO_FORGE_ISOLATE=1` is set (the host sets it
+ * with an otherwise empty environment), so the hidden `__forge-isolate` command cannot be
+ * mistaken for something a user runs. It talks only through stdin/stdout frames and exits when
+ * the execution reaches its terminal message.
+ *
+ * Erasable TypeScript only (D-33).
+ */
+import { isMainThread, parentPort, workerData } from "node:worker_threads";
+import { runGuest } from "../vm-runner.js";
+import { loadQuickJsModule } from "../wasm.js";
+import { encodeFrame, FrameDecoder } from "./framing.js";
+/** Body of a worker thread started by `WorkerIsolateHost`. */
+export async function runWorkerIsolate() {
+    const data = workerData;
+    if (isMainThread || !parentPort || data?.forgeIsolate !== 1)
+        return;
+    const port = parentPort;
+    await runGuest({
+        module: data.module,
+        flag: new Int32Array(data.flag),
+        transport: {
+            send: (message) => port.postMessage(message),
+            onMessage: (handler) => port.on("message", handler),
+        },
+    });
+    // The terminal message is posted; leaving the thread lets the parent observe a clean `exit`.
+    process.exit(0);
+}
+/** Body of the child process started by `ProcessIsolateHost` (or by `alisio __forge-isolate`). */
+export async function runProcessIsolate(env = process.env) {
+    if (env.ALISIO_FORGE_ISOLATE !== "1") {
+        process.stderr.write("__forge-isolate is internal and is started by the Forja process host\n");
+        process.exit(2);
+    }
+    const module = await loadQuickJsModule();
+    const decoder = new FrameDecoder(8 * 1024 * 1024);
+    let handler = () => { };
+    process.stdin.on("data", (chunk) => {
+        try {
+            for (const message of decoder.push(chunk))
+                handler(message);
+        }
+        catch {
+            process.exit(3);
+        }
+    });
+    process.stdin.on("end", () => process.exit(0));
+    await runGuest({
+        module,
+        transport: {
+            send: (message) => process.stdout.write(encodeFrame(message)),
+            onMessage: (next) => {
+                handler = next;
+            },
+        },
+    });
+    // Exit once the last frame is flushed.
+    process.stdout.write("", () => process.exit(0));
+}

package/dist/forge/javascript/hosts/process-entry.d.ts

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

package/dist/forge/javascript/hosts/process-entry.js

@@ -0,0 +1,3 @@
+/** Entry file of the isolate child process when run from a file (spec D-33: erasable TypeScript only). */
+import { runProcessIsolate } from "./isolate-main.js";
+await runProcessIsolate();