@nimbus-sh/worker 0.1.0

package/dist/runtime/wasm-runner.d.ts

@@ -0,0 +1,117 @@
+/**
+ * wasm-runner.ts — native-WASM runner via the LOADER-modules transport.
+ *
+ * Re-introduced after the multi-runtime wave's revert. The previous
+ * version relied on direct `WebAssembly.instantiate(bytes)` at request
+ * time — workerd's CSP blocks that path inside both the supervisor
+ * and facet isolates (verified in the multi-runtime feasibility
+ * memo). The new version routes through the LOADER's modules map:
+ * bytes ride INSIDE the worker code blob, workerd compiles them
+ * during the inner worker's MODULE-LOAD phase (the one phase where
+ * wasm code generation IS allowed), and the resulting
+ * WebAssembly.Module is exposed to the user fn via the
+ * NimbusLoaderPool's `globalThis.__NIMBUS_WASM[<name>]` table.
+ *
+ * The validation that this works on the deployed Cloudflare fleet
+ * lives at /workspace/.seal-internal/2026-05-10-wasm-csp/findings.md
+ * (`add(3,4) === 7` returned in 11ms warm, 113ms cold).
+ *
+ * Shell command shape
+ * ───────────────────
+ *
+ *   wasm-runner --version
+ *   wasm-runner <file.wasm> <exportName> [int args...]
+ *
+ * Each invocation:
+ *   1. Reads bytes from VFS (or any caller-supplied source).
+ *   2. Allocates a PID via processTable (Process tab integration).
+ *   3. NimbusLoaderPool.submit() with wasmModules: { 'user.wasm': bytes }
+ *      — pool merges per-call wasm with constructor-time entries,
+ *      generates a worker.js that imports './user.wasm', and ships
+ *      the modules map to env.LOADER.get(...).
+ *   4. The submitted fn runs inside the inner facet:
+ *      - reads globalThis.__NIMBUS_WASM['user.wasm'] (the precompiled
+ *        Module the pool registered)
+ *      - WebAssembly.instantiate(module, {}) — allowed because the
+ *        Module is precompiled
+ *      - looks up the export, calls with parsed integer args, returns
+ *        the result + the export list
+ *   5. Supervisor formats and writes stdout/stderr; exit code 0/1.
+ *
+ * Limitations (documented in --help):
+ *   - Function args are integers only (parseInt). Float / string /
+ *     multi-arg-shapes need a wrapper module.
+ *   - Only WebAssembly.Memory and integer return values are surfaced.
+ *   - WASI imports are NOT provided. Modules expecting wasi_snapshot
+ *     won't instantiate (fail at the in-facet instantiate step).
+ *
+ * Anti-requirements
+ * ─────────────────
+ *   - NO setTimeout / NO retry / NO defensive-catch in the dispatch
+ *     path. The pool's resilience options handle retries.
+ *   - The try/catch around vfs.readFile is a legitimate I/O boundary;
+ *     the diagnostic propagates as exitCode 1 + stderr line.
+ *   - NO direct WebAssembly.instantiate(bytes) at request time —
+ *     that's the architectural mistake from the prior wave.
+ */
+import type { RuntimeRunOpts, RuntimeRunResult } from './runtime-registry.js';
+export declare const WASM_RUNNER_VERSION = "0.3.0";
+export declare const WASM_RUNNER_HELP: string;
+/**
+ * Minimal VFS shape we depend on. Avoids importing the full
+ * SqliteVFS type tree from the supervisor module graph — this file
+ * is part of `src/runtime/`, importing supervisor-specific types
+ * would create a cycle.
+ *
+ * Wave-2: extended for WASI file-IO. The snapshot path uses readdir +
+ * isDirectory + stat to traverse the user's session subtree; the
+ * flush path uses writeFile + mkdir + unlink + rmdir.
+ */
+interface VfsLike {
+    exists(path: string): boolean;
+    isDirectory(path: string): boolean;
+    readFile(path: string): Uint8Array;
+    writeFile(path: string, content: Uint8Array | string): void;
+    readdir(path: string): {
+        name: string;
+        type: string;
+    }[];
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+    }): void;
+    unlink(path: string): void;
+    rmdir(path: string): void;
+}
+/**
+ * Minimal processTable shape — the parts wasm-runner needs to
+ * register a PID + mark exit so `ps` and `logs <pid>` see the
+ * invocation. Mirrors the surface the .bin handler uses; kept
+ * narrow to avoid the cycle through facets/manager.ts.
+ */
+interface ProcessTableLike {
+    spawn(command: string, argv: string[], cwd: string): {
+        pid: number;
+    };
+    exit(pid: number, code: number): void;
+}
+interface ProcessLogStoreLike {
+    append(pid: number, stream: 'stdout' | 'stderr', data: string): void;
+    getExit(pid: number): unknown;
+    markExit(pid: number, code: number): void;
+}
+/**
+ * Build a `run` function suitable for RuntimeSpec.run(). Parameterised
+ * over the VFS, env (for env.LOADER), ctx (for the pool's doId-scoped
+ * cache key), and processTable + processLogs (for `ps` / `logs <pid>` /
+ * Process tab integration). Returns a fn that matches the runtime-
+ * registry's contract.
+ */
+export declare function makeWasmRunner(deps: {
+    vfs: VfsLike;
+    env: any;
+    ctx: DurableObjectState;
+    processTable: ProcessTableLike;
+    processLogs: ProcessLogStoreLike;
+}): (_facetMgr: unknown, _code: string, opts: RuntimeRunOpts) => Promise<RuntimeRunResult>;
+export {};
+//# sourceMappingURL=wasm-runner.d.ts.map

package/dist/runtime/wasm-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/wasm-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAqD9E,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C,eAAO,MAAM,gBAAgB,QA+BwC,CAAC;AAEtE;;;;;;;;;GASG;AACH,UAAU,OAAO;IACf,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IACnC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA2CD;;;;;GAKG;AACH,UAAU,gBAAgB;IACxB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,UAAU,mBAAmB;IAC3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACrE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AA2ID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,kBAAkB,CAAC;IACxB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,WAAW,EAAE,mBAAmB,CAAC;CAClC,IAEG,WAAW,OAAO,EAClB,OAAO,MAAM,EACb,MAAM,cAAc,KACnB,OAAO,CAAC,gBAAgB,CAAC,CAgd7B"}