@wenathlan/saddle 2.0.154 → 2.0.155

package/dist/edgeplane.d.ts

@@ -1,121 +0,0 @@
-/** one edge execution request: the modality lane to ride, the program
- * payload (or the base64 wasm bytes, or the vfs payload), the optional
- * inputs and the optional deadline budget in milliseconds. */
-export type EdgeRequest = {
-    /** the modality id of the lane to ride (the registry id). */
-    modality: string;
-    /** the program payload the lane interprets (code, bytes or script). */
-    code: string;
-    /** the caller inputs the lane surfaces to the program when given. */
-    inputs?: unknown;
-    /** the run deadline in milliseconds (clamped between 250 and 60000). */
-    deadlinems?: number;
-};
-/** one lane of the edge plane as the report answers it: the modality it
- * wires, whether the lane executes (live) or probes (host), the runtime
- * surface it rides, and the honest probed presence of that runtime. */
-export type EdgeLaneReport = {
-    /** the modality id the lane wires. */
-    modality: string;
-    /** live lanes execute, host lanes probe the runtime (the next rung). */
-    kind: "live" | "host";
-    /** the runtime surface the lane rides ("node:vm", "bun", "docker"...). */
-    runtime: string;
-    /** whether this report row reflects a probe performed now (always true —
-     * every lane probes its runtime surface when the table is read). */
-    probed: boolean;
-    /** whether the probed runtime surface is present on this engine host. */
-    present: boolean;
-};
-/** one edge run result: the run identity, the lane it rode, the honest
- * status, the captured streams, the committed artifact manifest and the
- * coded error when the run failed. */
-export type EdgeRunResult = {
-    /** the run id the engine minted. */
-    runid: string;
-    /** the modality id that was requested. */
-    modality: string;
-    /** the runtime surface the run rode (empty when no lane rode it). */
-    lane: string;
-    /** the honest status of the run. */
-    status: "succeeded" | "failed";
-    /** the captured stdout when the run produced any. */
-    stdout?: string;
-    /** the captured stderr when the run produced any. */
-    stderr?: string;
-    /** the artifact the run committed (mime, byte count, storage ref). */
-    artifact?: {
-        mime: string;
-        bytes: number;
-        storageref?: string;
-    };
-    /** the coded error when the run failed. */
-    error?: {
-        code: string;
-        message: string;
-    };
-};
-/** the storage surface the edge plane commits artifacts through: the
- * duck-typed shape of the virtual.ts storageadapter products
- * (localstorage, memorystorage, the pools), so any adapter the engine
- * already carries slots in without importing the root domain graph. */
-export interface EdgeStorageAdapter {
-    /** writes one artifact and answers its manifest. */
-    put(input: {
-        key: string;
-        data: Uint8Array | ArrayBuffer | string;
-        contenttype?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<unknown>;
-    /** reads one artifact back as bytes. */
-    get(key: string): Promise<Uint8Array | ArrayBuffer>;
-    /** answers the manifest of one artifact when present. */
-    head(key: string): Promise<unknown>;
-    /** removes one artifact. */
-    delete(key: string): Promise<unknown>;
-    /** lists the manifests under one prefix. */
-    list(prefix?: string): Promise<readonly unknown[]>;
-}
-/** edgelanes — the lane table with every runtime probed now: the report
- * never lies, a lane whose runtime is absent says absent (an ops
- * surface, not a hot path — the probes walk PATH and the module
- * resolver synchronously). */
-export declare function edgelanes(): EdgeLaneReport[];
-/** edgelandesreport — the same probed lane table keyed by modality id
- * for the api surface (GET /api/v1/edge/lanes answers {lanes: this}). */
-export declare function edgelandesreport(): Record<string, EdgeLaneReport>;
-/** assertvisitorfree — the law guard of the edge plane: throws
- * {code: "VISITOR_CONTEXT_REFUSED"} when the scope carries
- * browser-shaped globals, because the engine executes server-side only
- * and never as the visitor browser. Every runonedge entry calls it on
- * globalThis before a single instruction rides a lane.
- *
- * the node server process exemption: when the scope is the globalThis
- * of a live node process, the webstorage globals the runtime defines
- * itself (the experimental webstorage surface of node 26) never mark
- * the scope — the server defining its own storage is the server, while
- * any storage riding a scope the runtime did not define (a browser
- * realm, an arbitrary object) stays refused.
- *
- * @param scope the scope to inspect (duck-typed, works in node).
- * @throws the coded refusal when the scope is browser-shaped.
- */
-export declare function assertvisitorfree(scope: unknown): void;
-/** runonedge — the dispatch law of the edge plane: the visitor guard
- * refuses any browser scope, the registry resolves the modality, the
- * lane executor rides the runtime server-side, the output is captured,
- * and the artifact (the lane artifact, or the stdout when the lane
- * produced none) is committed through the caller's storage adapter when
- * given. A planned or unknown modality answers MODALITY_NOT_LIVE; a
- * lane whose host runtime is absent answers HOST_RUNTIME_ABSENT naming
- * the runtime; a storage commit failure fails the run honestly
- * (STORAGE_FAILURE — an unpersisted artifact is a failed commit, the
- * engine law).
- *
- * @param request the edge run request (modality, code, inputs, deadline).
- * @param options the caller surfaces (the storage adapter for artifacts).
- * @returns the honest EdgeRunResult of the dispatch.
- */
-export declare function runonedge(request: EdgeRequest, options?: {
-    storage?: EdgeStorageAdapter;
-}): Promise<EdgeRunResult>;

package/dist/edgeplane.js

@@ -1,341 +0,0 @@
-// # edgeplane.ts — the edge execution law of the saddle engine: every
-// pass of the system rides one modality lane of the engine, server-side,
-// and the visitor browser never executes anything (the owner's law: the
-// interface never uses the visitor browser, gpu or cpu; the sandbox and
-// the saddle modalities act for the system over the internet). The plane
-// owns the lane table — the ten live lanes the engine drives today and
-// the six host lanes it probes — the visitor guard that refuses any
-// browser-shaped scope before a single instruction rides, and the
-// dispatcher that resolves the modality through the registry, rides the
-// lane executor, captures the output and commits the artifact through
-// the caller's storage adapter. The lane table is the wiring truth of
-// this plane: the sv1 catalog declared most of these lanes planned
-// before the edge wave wired them, and the report states what the engine
-// drives today, honestly probed per runtime. The imports stay node-safe
-// on purpose: the webserver's plain node host strips types and resolves
-// only .ts specifiers, so the plane imports the pure registry and
-// foundation modules directly and leaves the root domain graph
-// (virtual.ts and its .js specifiers) to the lazy lane loads.
-import { edgelaneexecutorsall, edgelanespecsall } from "./edgelandes.ninety.ts";
-import { probedocker, probehostbinary, probemodule, probenodevm, probevirtualmodule, probewasm } from "./edgelandes.ts";
-import { idfactory } from "./foundation.ts";
-import { getmodality } from "./modalityregistry.ts";
-/** the lane table of the edge plane: the ten live lanes (the execution
- * lanes the engine drives today) and the six host lanes (the runtimes
- * the engine probes, the execution wiring the next rung) of the base
- * contract, then the sixty-three lanes of the ninety modalities wave
- * merged in through edgelandes.ninety.ts (the twenty-five host binary
- * lanes, the nineteen in-process lanes, the seven virtual hardware
- * lanes and the six heavyweight probes). The ids are pinned — parallel
- * waves and the api routes read them exactly. */
-const EDGELANES = Object.freeze([
-    ...edgelanespecsall,
-    // the live lanes: the engine executes through these today
-    { modality: "container-docker", kind: "live", runtime: "docker", present: probedocker },
-    { modality: "fs-vfs", kind: "live", runtime: "virtual-vfs", present: probevirtualmodule },
-    { modality: "runner-node", kind: "live", runtime: "node:vm", present: probenodevm },
-    { modality: "runner-bun", kind: "live", runtime: "bun", present: () => probehostbinary("bun") },
-    { modality: "runner-wasm", kind: "live", runtime: "webassembly", present: probewasm },
-    { modality: "runner-babel", kind: "live", runtime: "@babel/core", present: () => probemodule("@babel/core") },
-    { modality: "runner-webpack", kind: "live", runtime: "webpack", present: () => probemodule("webpack") },
-    { modality: "runner-universal", kind: "live", runtime: "bash", present: () => probehostbinary("bash") },
-    { modality: "language-python", kind: "live", runtime: "python3", present: () => probehostbinary("python3") },
-    { modality: "language-java", kind: "live", runtime: "java", present: () => probehostbinary("java") },
-    // the host lanes: the engine probes the runtime, execution is the next rung
-    { modality: "container-runsc", kind: "host", runtime: "runsc", present: () => probehostbinary("runsc") },
-    {
-        modality: "emulator-qemu",
-        kind: "host",
-        runtime: "qemu-system-x86_64",
-        present: () => probehostbinary("qemu-system-x86_64"),
-    },
-    {
-        modality: "microvm-firecracker",
-        kind: "host",
-        runtime: "firecracker",
-        present: () => probehostbinary("firecracker"),
-    },
-    { modality: "runtime-jvm", kind: "host", runtime: "java", present: () => probehostbinary("java") },
-    { modality: "language-go", kind: "host", runtime: "go", present: () => probehostbinary("go") },
-    { modality: "language-ruby", kind: "host", runtime: "ruby", present: () => probehostbinary("ruby") },
-]);
-/** edgelanes — the lane table with every runtime probed now: the report
- * never lies, a lane whose runtime is absent says absent (an ops
- * surface, not a hot path — the probes walk PATH and the module
- * resolver synchronously). */
-export function edgelanes() {
-    return EDGELANES.map((lane) => ({
-        modality: lane.modality,
-        kind: lane.kind,
-        runtime: lane.runtime,
-        probed: true,
-        present: lane.present(),
-    }));
-}
-/** edgelandesreport — the same probed lane table keyed by modality id
- * for the api surface (GET /api/v1/edge/lanes answers {lanes: this}). */
-export function edgelandesreport() {
-    const report = {};
-    for (const lane of edgelanes())
-        report[lane.modality] = lane;
-    return report;
-}
-/* ════════════════════════════════════════════════════════════════════ */
-/* Section 3: the visitor law guard — the engine refuses browser scopes. */
-/* ════════════════════════════════════════════════════════════════════ */
-/** the browser shells and storage surfaces that mark a visitor scope
- * (window, document, localStorage, sessionStorage, indexedDB): a scope
- * carrying any of them is a browser, and the engine refuses to execute
- * as one. navigator alone is not a marker — node itself ships a
- * vestigial navigator since v21 — the shells and the storages are the
- * law. the node runtime may also define the experimental webstorage
- * globals (node 26 ships localStorage and sessionStorage without
- * --localstorage-file): the storages the server process defines on its
- * own globalThis never mark the visitor machine — the engine executes
- * server-side, and the node process carrying its own storage surface is
- * the server, never the visitor browser. */
-const VISITORMARKERS = Object.freeze([
-    "window",
-    "document",
-    "localStorage",
-    "sessionStorage",
-    "indexedDB",
-]);
-/** the storage markers the law refuses on any scope: the two webstorage
- * seats (localStorage and sessionStorage) are the ones a node runtime
- * defines on its own globalThis, so the exemption below is scoped to
- * exactly them. */
-const STORAGEMARKERS = Object.freeze([
-    "localStorage",
-    "sessionStorage",
-]);
-/** whether the inspected scope is the globalThis of a live node server
- * process: the runtime identity the exemption rides on (the versions
- * table only exists inside node, and the scope identity is the global
- * object itself, so a browser carrying a node-shaped shim never
- * qualifies). */
-function isnodeprocess(scope) {
-    if (scope !== globalThis)
-        return false;
-    if (typeof process !== "object" || process === null)
-        return false;
-    const versions = process.versions;
-    return typeof versions?.node === "string";
-}
-/** assertvisitorfree — the law guard of the edge plane: throws
- * {code: "VISITOR_CONTEXT_REFUSED"} when the scope carries
- * browser-shaped globals, because the engine executes server-side only
- * and never as the visitor browser. Every runonedge entry calls it on
- * globalThis before a single instruction rides a lane.
- *
- * the node server process exemption: when the scope is the globalThis
- * of a live node process, the webstorage globals the runtime defines
- * itself (the experimental webstorage surface of node 26) never mark
- * the scope — the server defining its own storage is the server, while
- * any storage riding a scope the runtime did not define (a browser
- * realm, an arbitrary object) stays refused.
- *
- * @param scope the scope to inspect (duck-typed, works in node).
- * @throws the coded refusal when the scope is browser-shaped.
- */
-export function assertvisitorfree(scope) {
-    if (scope === null || typeof scope !== "object")
-        return;
-    const record = scope;
-    const serverprocess = isnodeprocess(scope);
-    for (const marker of VISITORMARKERS) {
-        if (record[marker] === undefined)
-            continue;
-        if (serverprocess && STORAGEMARKERS.includes(marker))
-            continue;
-        const error = new Error(`the visitor context is refused: the scope carries the browser global ${marker} and the edge plane executes server-side only`);
-        error.name = "edgeplaneerror";
-        error.code = "VISITOR_CONTEXT_REFUSED";
-        throw error;
-    }
-}
-/* ════════════════════════════════════════════════════════════════════ */
-/* Section 4: the dispatch — runonedge rides one lane, honestly. */
-/* ════════════════════════════════════════════════════════════════════ */
-/** the default deadline of one edge run. */
-const DEFAULTDEADLINEMS = 10000;
-/** the deadline floor and ceiling: no run rides under 250 ms or over 60 s. */
-const MINDEADLINEMS = 250;
-const MAXDEADLINEMS = 60000;
-/** the artifact extension of one mime type (the storage key suffix). */
-function extensionfor(mime) {
-    const base = mime.split(";")[0]?.trim() ?? "";
-    const extensions = {
-        "text/plain": ".txt",
-        "application/json": ".json",
-        "application/javascript": ".js",
-        "application/wasm": ".wasm",
-        "application/octet-stream": ".bin",
-    };
-    return extensions[base] ?? ".bin";
-}
-/** clamps the caller deadline into the honest budget window. */
-function clampdeadline(deadlinems) {
-    const requested = typeof deadlinems === "number" && Number.isFinite(deadlinems) ? deadlinems : DEFAULTDEADLINEMS;
-    return Math.min(Math.max(Math.round(requested), MINDEADLINEMS), MAXDEADLINEMS);
-}
-/** the safe message of an unknown thrown value (no stack rides a result). */
-function errormessage(error) {
-    return error instanceof Error ? error.message : String(error ?? "unknown edge failure");
-}
-/** the lane error code of an unknown thrown value: coded lane errors keep
- * their code, timeouts answer RUN_DEADLINE_EXCEEDED, the rest is honest
- * EDGE_LANE_FAILURE. */
-function lanecode(error) {
-    const code = error?.code;
-    if (typeof code === "string" && code.length > 0)
-        return code;
-    if (/timed out|timeout/i.test(errormessage(error)))
-        return "RUN_DEADLINE_EXCEEDED";
-    return "EDGE_LANE_FAILED";
-}
-/** the id factory of the edge plane (one run id per dispatch). */
-const ids = idfactory();
-/** runonedge — the dispatch law of the edge plane: the visitor guard
- * refuses any browser scope, the registry resolves the modality, the
- * lane executor rides the runtime server-side, the output is captured,
- * and the artifact (the lane artifact, or the stdout when the lane
- * produced none) is committed through the caller's storage adapter when
- * given. A planned or unknown modality answers MODALITY_NOT_LIVE; a
- * lane whose host runtime is absent answers HOST_RUNTIME_ABSENT naming
- * the runtime; a storage commit failure fails the run honestly
- * (STORAGE_FAILURE — an unpersisted artifact is a failed commit, the
- * engine law).
- *
- * @param request the edge run request (modality, code, inputs, deadline).
- * @param options the caller surfaces (the storage adapter for artifacts).
- * @returns the honest EdgeRunResult of the dispatch.
- */
-export async function runonedge(request, options = {}) {
-    const runid = ids.next("edgerun");
-    const modality = typeof request?.modality === "string" ? request.modality : "";
-    let lanename = "";
-    try {
-        assertvisitorfree(globalThis);
-        if (modality.length === 0 || typeof request?.code !== "string") {
-            return {
-                runid,
-                modality,
-                lane: lanename,
-                status: "failed",
-                error: { code: "INVALID_EDGE_REQUEST", message: "an edge run requires a modality id and a code payload" },
-            };
-        }
-        const lane = EDGELANES.find((entry) => entry.modality === modality);
-        if (lane === undefined) {
-            const record = getmodality(modality);
-            if (record === undefined) {
-                return {
-                    runid,
-                    modality,
-                    lane: lanename,
-                    status: "failed",
-                    error: { code: "MODALITY_NOT_LIVE", message: `the modality id ${modality} is unknown to the registry` },
-                };
-            }
-            // a record the registry already drives live through another engine
-            // surface (the envelope sandbox lane) is never lied about here: the
-            // modality is live, this plane simply wires no lane for it yet.
-            if (record.state === "planned") {
-                return {
-                    runid,
-                    modality,
-                    lane: lanename,
-                    status: "failed",
-                    error: {
-                        code: "MODALITY_NOT_LIVE",
-                        message: `the modality ${modality} is planned: no engine surface drives it yet`,
-                    },
-                };
-            }
-            return {
-                runid,
-                modality,
-                lane: lanename,
-                status: "failed",
-                error: {
-                    code: "LANE_NOT_WIRED_IN_PLANE",
-                    message: `the modality ${modality} is ${record.state} in the registry, but this edge plane wires no lane for it yet — the other engine surfaces drive it`,
-                },
-            };
-        }
-        lanename = lane.runtime;
-        const executor = edgelaneexecutorsall[lane.modality];
-        if (executor === undefined) {
-            return {
-                runid,
-                modality,
-                lane: lanename,
-                status: "failed",
-                error: { code: "EDGE_PLANE_MISWIRED", message: `no executor is wired for the lane ${lanename}` },
-            };
-        }
-        const deadline = clampdeadline(request.deadlinems);
-        const output = await executor(request.code, request.inputs, deadline);
-        const payload = output.artifact ??
-            (output.stdout.length > 0
-                ? { mime: "text/plain;charset=utf-8", bytes: new TextEncoder().encode(output.stdout) }
-                : undefined);
-        let artifact;
-        if (payload !== undefined) {
-            artifact = { mime: payload.mime, bytes: payload.bytes.byteLength };
-            if (options.storage !== undefined) {
-                try {
-                    const key = `edge/runs/${runid}/output${extensionfor(payload.mime)}`;
-                    const manifest = (await options.storage.put({
-                        key,
-                        data: payload.bytes,
-                        contenttype: payload.mime,
-                        metadata: { runid, modality },
-                    }));
-                    artifact.storageref = typeof manifest?.key === "string" ? manifest.key : key;
-                }
-                catch (error) {
-                    return {
-                        runid,
-                        modality,
-                        lane: lanename,
-                        status: "failed",
-                        stderr: output.stderr,
-                        error: {
-                            code: "STORAGE_FAILURE",
-                            message: `the artifact of the edge run ${runid} failed to persist: ${errormessage(error)}`,
-                        },
-                    };
-                }
-            }
-        }
-        return {
-            runid,
-            modality,
-            lane: lanename,
-            status: "succeeded",
-            stdout: output.stdout,
-            stderr: output.stderr,
-            artifact,
-        };
-    }
-    catch (error) {
-        return {
-            runid,
-            modality,
-            lane: lanename,
-            status: "failed",
-            stderr: error.stderr,
-            error: { code: lanecode(error), message: errormessage(error) },
-        };
-    }
-}
-/* the wiring self-check: the plane refuses to load over a lane it
- * cannot wire (a table entry without an executor is a miswired plane,
- * and miswiring must fail loud at boot, never silently at run time). */
-for (const lane of EDGELANES) {
-    if (edgelaneexecutorsall[lane.modality] === undefined) {
-        throw new Error(`the edge plane is miswired: no executor for the lane ${lane.modality}`);
-    }
-}

package/dist/examplelocaljob.d.ts

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

package/dist/examplelocaljob.js

@@ -1,14 +0,0 @@
-/**
- * the local example shows that the library can run without a remote service.
- */
-import { mkdtemp } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { eventbus, engine, inprocess, scheduler } from "../index.js";
-import { localmemory } from "../virtual.js";
-import { localstorage } from "../virtual.js";
-const root = await mkdtemp(join(tmpdir(), "saddleexample"));
-const events = eventbus();
-const run = engine({ storage: localstorage(root), memory: localmemory(), scheduler: scheduler([inprocess()]), events });
-const result = await run.run({ name: "localexample", input: { source: "example" }, outputkey: "results/example.json" }, ({ job }) => ({ jobid: job.id, ok: true }));
-console.log({ jobid: result.job.id, artifact: result.artifact.key, eventcount: events.all().length });