@plurnk/plurnk-execs-wasm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PossumTech Laboratories
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @plurnk/plurnk-execs-wasm
+
+WebAssembly runtime executor for [plurnk-service](https://github.com/plurnk/plurnk-service)'s `exec` scheme. Runs model-authored WebAssembly **in-process, sandboxed** — the safe arbitrary-execution tier that `node -e` can't be.
+
+A `@plurnk/plurnk-execs-*` sibling built on the [plurnk-execs](https://github.com/plurnk/plurnk-execs) framework.
+
+## Runtime tags
+
+| Tag | Glyph | Input |
+|---|---|---|
+| `wat` | 🧩 | WebAssembly **Text** (S-expression module) — the model-facing form |
+| `wasm` | 🧩 | base64-encoded **binary** module (pre-compiled) |
+
+`wat` is the primary: a model emits text, not bytes. WAT is assembled to wasm via [wabt](https://github.com/AssemblyScript/wabt.js); `wasm` decodes base64. (`.wast` — the spec test-suite superset with `assert_*` commands — is deliberately *not* supported; this executes a module, not a test script.)
+
+## Execution model
+
+Both forms instantiate in a sandbox whose only import is `env.log` (capture). The executor then calls the module's entry point — `main`, else `_start`, else the sole exported function — and writes:
+
+```json
+{ "returned": <value|null>, "log": [ … ], "exports": [ "main", … ] }
+```
+
+to the `results` channel (`application/json`). A module that imports `(import "env" "log" (func $log (param i32)))` can emit intermediate values.
+
+- **`effect: pure`** — a module can't touch the host (only the imports it's handed), so it **auto-runs inline**, never proposal-gated.
+- **`probe`** — always available (`WebAssembly` builtin + bundled `wabt`).
+- **Errors** emit a `TelemetryEvent` (`source: "exec:wat"`/`"exec:wasm"`): `wat_parse_error`, `wasm_invalid`, `wasm_trap`, `wabt_init_failed`.
+
+## Tests
+
+`test:lint`, `test:unit`.

package/dist/Wasm.d.ts

@@ -0,0 +1,9 @@
+import { BaseExecutor } from "@plurnk/plurnk-execs";
+import type { ChannelDecl, Effect, ExecArgs, ExecResult, RuntimeAvailability } from "@plurnk/plurnk-execs";
+export default class Wasm extends BaseExecutor {
+    get channels(): Readonly<Record<string, ChannelDecl>>;
+    effect(_target: string | null): Effect;
+    probe(): Promise<RuntimeAvailability>;
+    run({ runtime, command, write, setState, emit }: ExecArgs): Promise<ExecResult>;
+}
+//# sourceMappingURL=Wasm.d.ts.map

package/dist/Wasm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Wasm.d.ts","sourceRoot":"","sources":["../src/Wasm.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AA+B3G,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,YAAY;IAC1C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAEpD;IAEQ,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAIhC,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI9C,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;CAmDxF"}

package/dist/Wasm.js

@@ -0,0 +1,88 @@
+import wabtInit from "wabt";
+import { BaseExecutor } from "@plurnk/plurnk-execs";
+let wabtPromise;
+const getWabt = () => (wabtPromise ??= wabtInit());
+// WASM i64 results come back as bigint; stringify so the JSON serializes.
+const jsonReplacer = (_key, value) => (typeof value === "bigint" ? value.toString() : value);
+// Entry-point export names tried in order; falls back to the sole exported
+// function if a module exports exactly one.
+const ENTRY_POINTS = ["main", "_start"];
+// In-process WebAssembly executor (a logical runtime). `wat` assembles the
+// model's WebAssembly Text via wabt; `wasm` decodes a base64 binary module.
+// Both instantiate in a sandbox — the only host interaction is an `env.log`
+// import that captures values — call the entry point, and return its result as
+// application/json. effect `pure`: a module cannot touch the host, only call
+// the imports we hand it, so it auto-runs inline. The safe arbitrary-execution
+// tier `node -e` can't be.
+export default class Wasm extends BaseExecutor {
+    get channels() {
+        return { results: { mimetype: "application/json" } };
+    }
+    effect(_target) {
+        return "pure";
+    }
+    async probe() {
+        return { available: true, detail: "WebAssembly + wabt" };
+    }
+    async run({ runtime, command, write, setState, emit }) {
+        const fail = (kind, message) => {
+            emit({ source: `exec:${runtime}`, kind, message });
+            setState("results", "errored");
+            return { status: 500 };
+        };
+        // 1. Obtain the module bytes.
+        let bytes;
+        if (runtime === "wat") {
+            let wabt;
+            try {
+                wabt = await getWabt();
+            }
+            catch (err) {
+                return fail("wabt_init_failed", err.message);
+            }
+            let mod;
+            try {
+                mod = wabt.parseWat("module.wat", command);
+                bytes = mod.toBinary({}).buffer;
+            }
+            catch (err) {
+                return fail("wat_parse_error", err.message);
+            }
+            finally {
+                mod?.destroy();
+            }
+        }
+        else if (runtime === "wasm") {
+            bytes = Uint8Array.from(Buffer.from(command.trim(), "base64"));
+        }
+        else {
+            throw new Error(`plurnk-execs-wasm received unclaimed runtime tag '${runtime}'`);
+        }
+        // 2. Instantiate in the sandbox (only the log-capture import).
+        const log = [];
+        let instance;
+        try {
+            ({ instance } = await WebAssembly.instantiate(bytes, { env: { log: (v) => log.push(v) } }));
+        }
+        catch (err) {
+            return fail("wasm_invalid", err.message);
+        }
+        // 3. Call the entry point if present; capture its return.
+        const exports = instance.exports;
+        const funcs = Object.keys(exports).filter((n) => typeof exports[n] === "function");
+        const entry = ENTRY_POINTS.find((n) => funcs.includes(n)) ?? (funcs.length === 1 ? funcs[0] : undefined);
+        let returned = null;
+        if (entry !== undefined) {
+            try {
+                returned = exports[entry]();
+            }
+            catch (err) {
+                return fail("wasm_trap", `${entry}: ${err.message}`);
+            }
+        }
+        write("results", JSON.stringify({ returned, log, exports: funcs }, jsonReplacer));
+        setState("results", "closed");
+        return { status: 200 };
+    }
+}
+//# sourceMappingURL=Wasm.js.map

package/dist/Wasm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Wasm.js","sourceRoot":"","sources":["../src/Wasm.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAcpD,IAAI,WAAsC,CAAC;AAC3C,MAAM,OAAO,GAAG,GAAkB,EAAE,CAAC,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC,CAAC;AAElE,0EAA0E;AAC1E,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,KAAc,EAAW,EAAE,CAC3D,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAE3D,2EAA2E;AAC3E,4CAA4C;AAC5C,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAExC,2EAA2E;AAC3E,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,2BAA2B;AAC3B,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,YAAY;IAC1C,IAAI,QAAQ;QACR,OAAO,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,kBAAkB,EAAE,EAAE,CAAC;IACzD,CAAC;IAEQ,MAAM,CAAC,OAAsB;QAClC,OAAO,MAAM,CAAC;IAClB,CAAC;IAEQ,KAAK,CAAC,KAAK;QAChB,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAY;QAC3D,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,OAAe,EAAc,EAAE;YACvD,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YACnD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YAC/B,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC3B,CAAC,CAAC;QAEF,8BAA8B;QAC9B,IAAI,KAAiB,CAAC;QACtB,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;YACpB,IAAI,IAAU,CAAC;YACf,IAAI,CAAC;gBAAC,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;YAAC,CAAC;YAC/B,OAAO,GAAG,EAAE,CAAC;gBAAC,OAAO,IAAI,CAAC,kBAAkB,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YAAC,CAAC;YACxE,IAAI,GAA6C,CAAC;YAClD,IAAI,CAAC;gBACD,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;gBAC3C,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC;YACpC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,OAAO,IAAI,CAAC,iBAAiB,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YAC3D,CAAC;oBAAS,CAAC;gBACP,GAAG,EAAE,OAAO,EAAE,CAAC;YACnB,CAAC;QACL,CAAC;aAAM,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YAC5B,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;QACnE,CAAC;aAAM,CAAC;YACJ,MAAM,IAAI,KAAK,CAAC,qDAAqD,OAAO,GAAG,CAAC,CAAC;QACrF,CAAC;QAED,+DAA+D;QAC/D,MAAM,GAAG,GAAc,EAAE,CAAC;QAC1B,IAAI,QAA8C,CAAC;QACnD,IAAI,CAAC;YACD,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,CAAC,CAAU,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACzG,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,IAAI,CAAC,cAAc,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;QACxD,CAAC;QAED,0DAA0D;QAC1D,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC;QACnF,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACzG,IAAI,QAAQ,GAAY,IAAI,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACtB,IAAI,CAAC;gBAAC,QAAQ,GAAI,OAAO,CAAC,KAAK,CAAmB,EAAE,CAAC;YAAC,CAAC;YACvD,OAAO,GAAG,EAAE,CAAC;gBAAC,OAAO,IAAI,CAAC,WAAW,EAAE,GAAG,KAAK,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YAAC,CAAC;QACpF,CAAC;QAED,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;QAClF,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IAC3B,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Wasm } from "./Wasm.ts";
+export { default } from "./Wasm.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default as Wasm } from "./Wasm.js";
+export { default } from "./Wasm.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+    "name": "@plurnk/plurnk-execs-wasm",
+    "version": "0.1.0",
+    "description": "WebAssembly runtime executor for plurnk-service's exec scheme — in-process sandboxed execution of WAT (text) and wasm (binary) modules.",
+    "keywords": ["plurnk", "exec", "runtime", "executor", "webassembly", "wasm", "wat", "sandbox"],
+    "homepage": "https://github.com/plurnk/plurnk-execs-wasm#readme",
+    "bugs": {
+        "url": "https://github.com/plurnk/plurnk-execs-wasm/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-execs-wasm.git"
+    },
+    "engines": {
+        "node": ">=25"
+    },
+    "license": "MIT",
+    "author": "@wikitopian",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "plurnk": {
+        "kind": "exec",
+        "runtimes": [
+            { "name": "wat", "glyph": "🧩" },
+            { "name": "wasm", "glyph": "🧩" }
+        ]
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "README.md"
+    ],
+    "scripts": {
+        "test:lint": "tsc --noEmit",
+        "test:unit": "node --test \"src/**/*.test.ts\"",
+        "test": "npm run test:lint && npm run test:unit",
+        "build:dist": "tsc -p tsconfig.build.json",
+        "build": "npm run build:dist",
+        "prepare": "npm run build"
+    },
+    "dependencies": {
+        "@plurnk/plurnk-execs": "0.4.1",
+        "wabt": "^1.0.39"
+    },
+    "devDependencies": {
+        "@types/node": "^25.8.0",
+        "typescript": "^6.0.3"
+    }
+}