@markii/lua 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sadigaxund
+
+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,5 @@
+# @markii/lua
+
+A sandboxed Lua 5.4 (via `wasmoon`) execution runtime for [Mark](https://github.com/sadigaxund/markii)'s document scripting: an empty-environment global whitelist, capability-gated net/cache/bundle access, instruction-count and wall-clock/memory limits, and depth/size-capped Lua↔JS value marshaling. No React, no markdown parsing.
+
+See the [repository](https://github.com/sadigaxund/markii) for the format spec and the reference library as a whole.

package/dist/capabilities.d.ts

@@ -0,0 +1,124 @@
+import type { ScriptView } from '@markii/bundle';
+/** A GET/POST/PATCH result handed back to Lua as `{status=..., body=...}`. */
+export interface NetResponse {
+    status: number;
+    body: string;
+}
+/**
+ * Host-provided network primitive. The runtime never imports a global
+ * `fetch` or reaches the network on its own — this is injected by the
+ * host, which is where SSRF/allowlist policy actually lives (spec §10).
+ * `net.fetch_json`/`net.post`/`net.patch` below are a thin, capability- and
+ * size-checked Lua-facing wrapper around whatever `provider` does.
+ */
+export interface NetProvider {
+    get(url: string): Promise<NetResponse>;
+    post?(url: string, body: string): Promise<NetResponse>;
+    patch?(url: string, body: string): Promise<NetResponse>;
+}
+/** One cached entry: the stored value plus when it was stored, for TTL comparison. */
+export interface CacheEntry {
+    value: unknown;
+    storedAtMs: number;
+}
+/**
+ * Host-provided cache primitive backing `cache.get(key, ttl, fn)`. Real
+ * persistence (bundle `cache/`, IndexedDB, whatever the host uses) is the
+ * host's concern; this package only defines the read-if-fresh-else-run-fn
+ * contract.
+ */
+export interface CacheProvider {
+    get(key: string): Promise<CacheEntry | undefined>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+}
+/** Spec §8's two-tier gate. `'manual'` = explicit run/run-all click, all grants apply. `'auto'` = on-open or scheduled, read-only regardless of what was granted. */
+export type CapabilityTier = 'manual' | 'auto';
+/**
+ * Hostnames this run may reach, ALREADY intersected by the caller (manifest
+ * ∩ user grant — same pattern as `@markii/bundle`'s `createScriptView`, DEFECT
+ * 10). This module does not re-derive grants from a manifest; it trusts
+ * `get`/`post` as the final, effective allowlist for this one run.
+ */
+export interface NetGrants {
+    get: readonly string[];
+    post: readonly string[];
+}
+export interface CapabilityConfig {
+    tier: CapabilityTier;
+    net?: NetProvider;
+    netGrants?: NetGrants;
+    cache?: CacheProvider;
+    /** Bundle-scoped filesystem view (spec §11) — already capability-restricted by `@markii/bundle`'s `createScriptView`; this module delegates to it, never re-implements the path-jail or write policy. */
+    bundle?: ScriptView;
+    maxFetchBytes?: number;
+}
+export declare const DEFAULT_MAX_FETCH_BYTES = 2000000;
+/**
+ * `Uint8Array` <-> Lua string, byte-for-byte via one JS UTF-16 code unit
+ * per byte (Latin-1-style). Lua strings are themselves 8-bit-clean byte
+ * arrays, but wasmoon's own JS<->Lua marshaling for strings does NOT
+ * preserve embedded NUL (0x00) bytes end-to-end — verified empirically
+ * (wasmoon 1.16.0): a JS string or Lua `string.char(...)` value containing
+ * a `\0` is truncated at the first NUL by the time it crosses the
+ * boundary, in BOTH directions (`global.set`, and a Lua value passed as an
+ * argument to a host function). This is a real, currently-unclosed gap for
+ * binary asset data containing NUL bytes (some binary formats do; JSON
+ * cache payloads and Lua source — the two documented `bundle.*` use cases
+ * per spec §9/§11 — do not). Documented here rather than silently
+ * "handled": `bundle.read`/`bundle.write` should be treated as reliable
+ * for text/JSON payloads and NOT YET reliable for arbitrary binary
+ * containing NUL bytes. See the adversarial test asserting this exact
+ * (current, imperfect) behavior so a future wasmoon upgrade that fixes it
+ * is a visible, reviewed diff rather than a silent behavior change.
+ */
+export declare function bytesToLuaString(bytes: Uint8Array): string;
+export declare function luaStringToBytes(s: string): Uint8Array;
+/**
+ * Builds the raw, host-facing async functions to inject as flat globals,
+ * and the trusted Lua prelude that wraps them into the ergonomic `net` /
+ * `cache` / `bundle` tables the DESIGN.md host API documents (`net.fetch_json(url)`,
+ * `cache.get(key, ttl, fn)`, `bundle.read/write/exists(path)`).
+ *
+ * ## Why "raw flat globals + a Lua prelude" instead of `global.set('net', {...})`
+ *
+ * The natural-looking approach — `engine.global.set('net', { fetch_json:
+ * async (url) => ... })` — silently breaks async/await for any capability
+ * whose Lua-facing wrapper needs to be REPLACED with a Lua closure later
+ * (which `cache.get` and every `:await()`-wrapping function here need to
+ * be, since raw host functions return promises that must be explicitly
+ * awaited — see below). With wasmoon's default `enableProxy: true`, a
+ * plain JS object passed to `global.set` becomes a live PROXY table: Lua
+ * writes to it round-trip back through JS, and reading a Lua-defined
+ * function back OUT of that proxy re-wraps it as a synchronous JS-callable
+ * bridge (`lua_pcallk`), which cannot yield. Concretely: assigning
+ * `cache.get = function(...) ... end` onto a proxied table and then
+ * calling `cache.get(...)` from a script ends up invoking that Lua
+ * function through the SYNCHRONOUS bridge, and if it (or anything it
+ * calls) tries to `:await()` a promise, Lua raises "attempt to yield
+ * across a C-call boundary" — verified empirically. Using genuine,
+ * Lua-native tables (built with `{}` inside the prelude, never JS-backed)
+ * avoids this entirely: every read/write of `net`/`cache`/`bundle` after
+ * setup is a normal Lua table operation, no JS round trip involved.
+ *
+ * ## Why raw calls need `:await()` at all
+ *
+ * A JS async function called from Lua does NOT automatically suspend the
+ * calling coroutine — wasmoon marshals its Promise into Lua as a
+ * `js_promise` userdata with `:await()`/`:next()`/`:catch()` methods; the
+ * CALLER must explicitly invoke `:await()` to get the resolved value
+ * (verified empirically: without it, a script sees the raw promise
+ * userdata, not the awaited result). Since `DESIGN.md`'s example script
+ * (`local repo = net.fetch_json(url)`) is written as if this were
+ * synchronous, the awaiting is done for the author, once, HERE — inside
+ * the prelude's Lua wrapper — never exposed to the untrusted script.
+ *
+ * Each raw handle is captured into a `local` inside the prelude and the
+ * matching global is set to `nil` immediately after, so it is not
+ * reachable as a global by the untrusted script that runs afterward (only
+ * the ergonomic wrapper closures, which close over the local, remain
+ * callable).
+ */
+export declare function buildCapabilities(config: CapabilityConfig): {
+    rawGlobals: Record<string, (...args: never[]) => Promise<unknown>>;
+    preludeLua: string;
+};

package/dist/capabilities.js

@@ -0,0 +1,281 @@
+import { CAPABILITY_ERROR_TAG } from './errors.js';
+export const DEFAULT_MAX_FETCH_BYTES = 2_000_000;
+function capabilityError(message) {
+    return new Error(`${CAPABILITY_ERROR_TAG}: ${message}`);
+}
+function describeThrown(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Bare hostname from a URL string, or `undefined` if the URL doesn't parse. */
+function hostnameOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `Uint8Array` <-> Lua string, byte-for-byte via one JS UTF-16 code unit
+ * per byte (Latin-1-style). Lua strings are themselves 8-bit-clean byte
+ * arrays, but wasmoon's own JS<->Lua marshaling for strings does NOT
+ * preserve embedded NUL (0x00) bytes end-to-end — verified empirically
+ * (wasmoon 1.16.0): a JS string or Lua `string.char(...)` value containing
+ * a `\0` is truncated at the first NUL by the time it crosses the
+ * boundary, in BOTH directions (`global.set`, and a Lua value passed as an
+ * argument to a host function). This is a real, currently-unclosed gap for
+ * binary asset data containing NUL bytes (some binary formats do; JSON
+ * cache payloads and Lua source — the two documented `bundle.*` use cases
+ * per spec §9/§11 — do not). Documented here rather than silently
+ * "handled": `bundle.read`/`bundle.write` should be treated as reliable
+ * for text/JSON payloads and NOT YET reliable for arbitrary binary
+ * containing NUL bytes. See the adversarial test asserting this exact
+ * (current, imperfect) behavior so a future wasmoon upgrade that fixes it
+ * is a visible, reviewed diff rather than a silent behavior change.
+ */
+export function bytesToLuaString(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        out += String.fromCharCode(bytes[i] ?? 0);
+    }
+    return out;
+}
+export function luaStringToBytes(s) {
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++) {
+        out[i] = s.charCodeAt(i) & 0xff;
+    }
+    return out;
+}
+/**
+ * Builds the raw, host-facing async functions to inject as flat globals,
+ * and the trusted Lua prelude that wraps them into the ergonomic `net` /
+ * `cache` / `bundle` tables the DESIGN.md host API documents (`net.fetch_json(url)`,
+ * `cache.get(key, ttl, fn)`, `bundle.read/write/exists(path)`).
+ *
+ * ## Why "raw flat globals + a Lua prelude" instead of `global.set('net', {...})`
+ *
+ * The natural-looking approach — `engine.global.set('net', { fetch_json:
+ * async (url) => ... })` — silently breaks async/await for any capability
+ * whose Lua-facing wrapper needs to be REPLACED with a Lua closure later
+ * (which `cache.get` and every `:await()`-wrapping function here need to
+ * be, since raw host functions return promises that must be explicitly
+ * awaited — see below). With wasmoon's default `enableProxy: true`, a
+ * plain JS object passed to `global.set` becomes a live PROXY table: Lua
+ * writes to it round-trip back through JS, and reading a Lua-defined
+ * function back OUT of that proxy re-wraps it as a synchronous JS-callable
+ * bridge (`lua_pcallk`), which cannot yield. Concretely: assigning
+ * `cache.get = function(...) ... end` onto a proxied table and then
+ * calling `cache.get(...)` from a script ends up invoking that Lua
+ * function through the SYNCHRONOUS bridge, and if it (or anything it
+ * calls) tries to `:await()` a promise, Lua raises "attempt to yield
+ * across a C-call boundary" — verified empirically. Using genuine,
+ * Lua-native tables (built with `{}` inside the prelude, never JS-backed)
+ * avoids this entirely: every read/write of `net`/`cache`/`bundle` after
+ * setup is a normal Lua table operation, no JS round trip involved.
+ *
+ * ## Why raw calls need `:await()` at all
+ *
+ * A JS async function called from Lua does NOT automatically suspend the
+ * calling coroutine — wasmoon marshals its Promise into Lua as a
+ * `js_promise` userdata with `:await()`/`:next()`/`:catch()` methods; the
+ * CALLER must explicitly invoke `:await()` to get the resolved value
+ * (verified empirically: without it, a script sees the raw promise
+ * userdata, not the awaited result). Since `DESIGN.md`'s example script
+ * (`local repo = net.fetch_json(url)`) is written as if this were
+ * synchronous, the awaiting is done for the author, once, HERE — inside
+ * the prelude's Lua wrapper — never exposed to the untrusted script.
+ *
+ * Each raw handle is captured into a `local` inside the prelude and the
+ * matching global is set to `nil` immediately after, so it is not
+ * reachable as a global by the untrusted script that runs afterward (only
+ * the ergonomic wrapper closures, which close over the local, remain
+ * callable).
+ */
+export function buildCapabilities(config) {
+    const maxFetchBytes = config.maxFetchBytes ?? DEFAULT_MAX_FETCH_BYTES;
+    const rawGlobals = {};
+    const preludeParts = [];
+    // --- net --------------------------------------------------------------
+    // `fetch_json` and `post`/`patch` are gated INDEPENDENTLY of each other
+    // (a manifest can grant POST to a host without granting it GET, or vice
+    // versa), so the `net` table and each method are wired up separately
+    // rather than behind one combined condition — an earlier version of
+    // this function nested POST/PATCH wiring inside "if GET is granted",
+    // which silently produced no `net.post` at all for a POST-only grant.
+    const netGrants = config.netGrants ?? { get: [], post: [] };
+    const netTableNeeded = config.net !== undefined &&
+        (netGrants.get.length > 0 ||
+            (config.tier === 'manual' && netGrants.post.length > 0));
+    if (netTableNeeded) {
+        preludeParts.push('net = net or {}\n');
+    }
+    if (config.net && netGrants.get.length > 0) {
+        rawGlobals.__smd_net_get_raw = (async (url) => {
+            const host = hostnameOf(url);
+            if (!host || !netGrants.get.includes(host)) {
+                throw capabilityError(`net access to host "${host ?? url}" not granted for GET`);
+            }
+            const res = await config.net.get(url);
+            if (res.body.length > maxFetchBytes) {
+                throw capabilityError(`fetch response for "${url}" exceeds the ${maxFetchBytes}-byte cap`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(res.body);
+            }
+            catch {
+                throw capabilityError(`fetch response for "${url}" was not valid JSON`);
+            }
+            return parsed;
+        });
+        preludeParts.push(`
+local __smd_net_get = __smd_net_get_raw
+__smd_net_get_raw = nil
+net.fetch_json = function(url) return __smd_net_get(url):await() end
+`);
+    }
+    // POST/PATCH are effectful — only wired at all under the 'manual' tier,
+    // and only for hosts the effective grant set allows for POST. Under
+    // 'auto' these are simply never defined: calling `net.post` fails as
+    // "attempt to call a nil value", a clean typed failure (spec §8: "An
+    // effectful call under an auto trigger fails cleanly").
+    if (config.tier === 'manual' &&
+        config.net?.post &&
+        netGrants.post.length > 0) {
+        rawGlobals.__smd_net_post_raw = (async (url, body) => {
+            const host = hostnameOf(url);
+            if (!host || !netGrants.post.includes(host)) {
+                throw capabilityError(`net access to host "${host ?? url}" not granted for POST`);
+            }
+            return config.net.post(url, body);
+        });
+        preludeParts.push(`
+local __smd_net_post = __smd_net_post_raw
+__smd_net_post_raw = nil
+net.post = function(url, body) return __smd_net_post(url, body):await() end
+`);
+    }
+    if (config.tier === 'manual' &&
+        config.net?.patch &&
+        netGrants.post.length > 0) {
+        rawGlobals.__smd_net_patch_raw = (async (url, body) => {
+            const host = hostnameOf(url);
+            if (!host || !netGrants.post.includes(host)) {
+                throw capabilityError(`net access to host "${host ?? url}" not granted for PATCH`);
+            }
+            return config.net.patch(url, body);
+        });
+        preludeParts.push(`
+local __smd_net_patch = __smd_net_patch_raw
+__smd_net_patch_raw = nil
+net.patch = function(url, body) return __smd_net_patch(url, body):await() end
+`);
+    }
+    // --- cache --------------------------------------------------------------
+    // cache.get is implemented ENTIRELY IN LUA (see the prelude below),
+    // calling the script-provided `fn` as a normal Lua-to-Lua call. This is
+    // deliberate, not just tidy: `fn` may itself call `net.fetch_json`
+    // (which needs to `:await()`), and a Lua function invoked FROM JS
+    // (rather than from Lua) goes through the same non-yieldable
+    // `lua_pcallk` bridge described above — so `cache.get`'s JS side only
+    // ever exposes plain read/write primitives (`__smd_cache_get_raw`,
+    // `__smd_cache_set_raw`); the read-if-fresh-else-run-fn CONTROL FLOW is
+    // Lua calling Lua, never JS calling Lua.
+    if (config.cache) {
+        rawGlobals.__smd_cache_get_raw = (async (key) => config.cache.get(key));
+        rawGlobals.__smd_cache_set_raw = (async (key, value, storedAtMs) => {
+            await config.cache.set(key, { value, storedAtMs });
+            return true;
+        });
+        // `now` (for TTL freshness) is computed in JS, once per cache.get
+        // call, and handed to Lua as a plain number argument — there is no
+        // `os.time()` in this sandbox (§10: no `os` library at all), so the
+        // clock is a host-provided value, not a Lua-reachable ambient
+        // capability.
+        rawGlobals.__smd_now_ms_raw = (async () => Date.now());
+        preludeParts.push(`
+local __smd_cache_get = __smd_cache_get_raw
+local __smd_cache_set = __smd_cache_set_raw
+local __smd_now_ms = __smd_now_ms_raw
+__smd_cache_get_raw = nil
+__smd_cache_set_raw = nil
+__smd_now_ms_raw = nil
+cache = cache or {}
+cache.get = function(key, ttl, fn)
+  local existing = __smd_cache_get(key):await()
+  if existing ~= nil then
+    local now = __smd_now_ms():await()
+    if (now - existing.storedAtMs) < (ttl * 1000) then
+      return existing.value
+    end
+  end
+  local value = fn()
+  __smd_cache_set(key, value, __smd_now_ms():await()):await()
+  return value
+end
+`);
+    }
+    // --- bundle -------------------------------------------------------------
+    // Delegates entirely to the injected `ScriptView` (`@markii/bundle`), which
+    // already enforces the path-jail and the read/write:cache/ split (spec
+    // §11). This module adds nothing on top except the tier gate for
+    // `bundle.write` (absent entirely under 'auto' — read-only tier) and the
+    // byte<->Lua-string conversion.
+    if (config.bundle) {
+        const view = config.bundle;
+        // `ScriptView` (@markii/bundle) throws its own `ScriptCapabilityError` /
+        // `BundlePathError` for a denied or path-jail-violating call — those
+        // are re-tagged here with `CAPABILITY_ERROR_TAG` so `sandbox.ts`'s
+        // message-based classification (see `./errors`'s doc comment on why
+        // that's necessary) reports them as `kind: 'capability'` uniformly,
+        // the same as a net host-allowlist denial, rather than falling
+        // through to the generic `'runtime'` bucket.
+        rawGlobals.__smd_bundle_read_raw = (async (path) => {
+            let data;
+            try {
+                data = await view.read(path);
+            }
+            catch (err) {
+                throw capabilityError(describeThrown(err));
+            }
+            return data === undefined ? null : bytesToLuaString(data);
+        });
+        rawGlobals.__smd_bundle_exists_raw = (async (path) => {
+            try {
+                return await view.exists(path);
+            }
+            catch (err) {
+                throw capabilityError(describeThrown(err));
+            }
+        });
+        preludeParts.push(`
+local __smd_bundle_read = __smd_bundle_read_raw
+local __smd_bundle_exists = __smd_bundle_exists_raw
+__smd_bundle_read_raw = nil
+__smd_bundle_exists_raw = nil
+bundle = bundle or {}
+bundle.read = function(path) return __smd_bundle_read(path):await() end
+bundle.exists = function(path) return __smd_bundle_exists(path):await() end
+`);
+        if (config.tier === 'manual') {
+            rawGlobals.__smd_bundle_write_raw = (async (path, data) => {
+                try {
+                    await view.write(path, luaStringToBytes(data));
+                }
+                catch (err) {
+                    throw capabilityError(describeThrown(err));
+                }
+                return true;
+            });
+            preludeParts.push(`
+local __smd_bundle_write = __smd_bundle_write_raw
+__smd_bundle_write_raw = nil
+bundle.write = function(path, data) return __smd_bundle_write(path, data):await() end
+`);
+        }
+        // Under 'auto', `bundle.write` is simply never defined — spec §8's
+        // read-only tier table: "bundle/cache reads, cache writes only".
+    }
+    return { rawGlobals, preludeLua: preludeParts.join('\n') };
+}

package/dist/errors.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Typed failure taxonomy for `runScript` (see `./sandbox`). Running hostile
+ * Lua must never throw a raw/opaque exception out of this package — every
+ * failure mode a script can trigger (resource limits, capability denial,
+ * an unmarshalable return value, or an ordinary Lua runtime error) is
+ * classified into one of these kinds before it reaches the caller.
+ *
+ * IMPORTANT CONSTRAINT this module works around: wasmoon does not preserve
+ * JS `Error` subclass identity across a round trip through the Lua VM. A
+ * custom `Error` thrown from a host-provided async capability function (see
+ * `./capabilities`) comes back out of `thread.run()` as a plain `Error`
+ * whose `.message` is the *stringified* original error — `instanceof`
+ * checks on the far side are useless (verified empirically against
+ * wasmoon 1.16.0: `new MyError('x')` thrown inside an injected async
+ * function round-trips as `Error: MyError: x`, not `MyError`). So
+ * classification of capability/marshal failures raised *from inside Lua
+ * execution* is done by tagging the error message with one of the
+ * `*_ERROR_TAG` prefixes below and pattern-matching on it in `sandbox.ts`
+ * after the run fails. Resource-limit breaches are NOT classified this way
+ * — they're tracked out-of-band via a plain JS closure flag set inside the
+ * instruction hook (see `./limits`), which Lua code can never see or touch,
+ * so that classification is exact regardless of what any error message says.
+ */
+/** Prefix tag for a capability (permission) denial raised into Lua from a host-provided function. */
+export declare const CAPABILITY_ERROR_TAG = "MARK_CAPABILITY";
+/** Prefix tag for a marshal-time rejection raised from the in-Lua marshal walk (see `./marshal`). */
+export declare const MARSHAL_ERROR_TAG = "MARK_MARSHAL";
+/** The limits a run can breach; see `./limits`. */
+export type ScriptLimitKind = 'instructions' | 'timeout' | 'memory';
+/** Why a return value was rejected by the marshaller; see `./marshal`. */
+export type ScriptMarshalReason = 'depth' | 'nodes' | 'cycle' | 'type' | 'key-type' | 'non-finite-number';
+/**
+ * The full discriminated failure shape `runScript` returns. `kind`:
+ * - `'limit'` — a resource limit was breached (instruction count, wall
+ *   clock, or memory). `limit` says which.
+ * - `'capability'` — the script attempted something its granted
+ *   capabilities don't allow (ungranted host, effectful op under an
+ *   auto-run tier, disallowed bundle path/write).
+ * - `'marshal'` — the script's return value could not be safely converted
+ *   to a JSON-serializable JS value (function/userdata/thread, a cycle,
+ *   too deep, too many nodes, a non-string table key, or a non-finite
+ *   number). `reason` says which.
+ * - `'runtime'` — an ordinary Lua error (syntax error, `error()` call,
+ *   type error, stack overflow, etc.) not covered by the above.
+ */
+export interface ScriptFailure {
+    kind: 'limit' | 'capability' | 'marshal' | 'runtime';
+    message: string;
+    limit?: ScriptLimitKind;
+    reason?: ScriptMarshalReason;
+}
+/**
+ * Thrown by the instruction-count/wall-clock hook installed in `./limits`
+ * when this package needs to surface a limit breach as a JS-level
+ * exception (e.g. from the outer `Promise.race` wall-clock guard in
+ * `sandbox.ts`, for the async-hang case a Lua-level hook can't observe).
+ * `runScript` always catches this itself — it is not part of the public
+ * throwing surface, only an internal signal.
+ */
+export declare class ScriptLimitError extends Error {
+    readonly limitKind: ScriptLimitKind;
+    constructor(limitKind: ScriptLimitKind, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,43 @@
+/**
+ * Typed failure taxonomy for `runScript` (see `./sandbox`). Running hostile
+ * Lua must never throw a raw/opaque exception out of this package — every
+ * failure mode a script can trigger (resource limits, capability denial,
+ * an unmarshalable return value, or an ordinary Lua runtime error) is
+ * classified into one of these kinds before it reaches the caller.
+ *
+ * IMPORTANT CONSTRAINT this module works around: wasmoon does not preserve
+ * JS `Error` subclass identity across a round trip through the Lua VM. A
+ * custom `Error` thrown from a host-provided async capability function (see
+ * `./capabilities`) comes back out of `thread.run()` as a plain `Error`
+ * whose `.message` is the *stringified* original error — `instanceof`
+ * checks on the far side are useless (verified empirically against
+ * wasmoon 1.16.0: `new MyError('x')` thrown inside an injected async
+ * function round-trips as `Error: MyError: x`, not `MyError`). So
+ * classification of capability/marshal failures raised *from inside Lua
+ * execution* is done by tagging the error message with one of the
+ * `*_ERROR_TAG` prefixes below and pattern-matching on it in `sandbox.ts`
+ * after the run fails. Resource-limit breaches are NOT classified this way
+ * — they're tracked out-of-band via a plain JS closure flag set inside the
+ * instruction hook (see `./limits`), which Lua code can never see or touch,
+ * so that classification is exact regardless of what any error message says.
+ */
+/** Prefix tag for a capability (permission) denial raised into Lua from a host-provided function. */
+export const CAPABILITY_ERROR_TAG = 'MARK_CAPABILITY';
+/** Prefix tag for a marshal-time rejection raised from the in-Lua marshal walk (see `./marshal`). */
+export const MARSHAL_ERROR_TAG = 'MARK_MARSHAL';
+/**
+ * Thrown by the instruction-count/wall-clock hook installed in `./limits`
+ * when this package needs to surface a limit breach as a JS-level
+ * exception (e.g. from the outer `Promise.race` wall-clock guard in
+ * `sandbox.ts`, for the async-hang case a Lua-level hook can't observe).
+ * `runScript` always catches this itself — it is not part of the public
+ * throwing surface, only an internal signal.
+ */
+export class ScriptLimitError extends Error {
+    limitKind;
+    constructor(limitKind, message) {
+        super(message);
+        this.name = 'ScriptLimitError';
+        this.limitKind = limitKind;
+    }
+}

package/dist/executor.d.ts

@@ -0,0 +1,39 @@
+import type { ScriptExecutor } from '@markii/runtime';
+import { type RunScriptOptions } from './sandbox.js';
+/**
+ * Slice 2 of the scripting-usability layer (DESIGN.md §8): the reusable
+ * adapter from this package's `runScript` to `@markii/runtime`'s
+ * language-agnostic `ScriptExecutor` shape, so `runDocumentScripts` can run
+ * a document's script blocks through the real Lua sandbox without
+ * `@markii/runtime` ever depending on `@markii/lua`, wasmoon, or any
+ * particular language runtime.
+ *
+ * Dependency direction: `@markii/lua -> @markii/runtime` (this file), TYPE
+ * ONLY (`ScriptExecutor`/`ExecuteResult` are `import type`, so nothing from
+ * `@markii/runtime` is bundled or evaluated at runtime by this package).
+ * `@markii/runtime` never imports `@markii/lua` — see `run.ts` there,
+ * which only knows about the `ScriptExecutor` function shape. There is no
+ * cycle.
+ */
+/**
+ * Everything `runScript` accepts except `code`/`tier` — those two are
+ * supplied per call by `runDocumentScripts` (`@markii/runtime`); everything
+ * else (net/netGrants/cache/bundle/maxFetchBytes/limits/marshalLimits) is
+ * this note's fixed capability/resource configuration, closed over once at
+ * executor-construction time.
+ */
+export type LuaExecutorConfig = Omit<RunScriptOptions, 'code' | 'tier'>;
+/**
+ * Builds a `ScriptExecutor` (`@markii/runtime`) backed by this package's
+ * `runScript`. `config` is captured once and reused for every script the
+ * returned executor runs; the returned function's only per-call inputs are
+ * `code` and `tier`, matching `ScriptExecutor`'s provider-agnostic
+ * signature. `runScript` never throws (see `./sandbox`'s doc comment), so
+ * this adapter doesn't need its own try/catch — it only reshapes the
+ * result: `ok: true` passes `value` through untouched; `ok: false` maps
+ * `runScript`'s `ScriptFailure` (`{ kind, message, ... }`) down to the
+ * narrower `{ kind: string; message: string }` `ExecuteFailure` shape
+ * `@markii/runtime` expects, dropping the Lua-specific `limit`/`reason`
+ * fields (still visible in `message` for anyone reading the stored error).
+ */
+export declare function createLuaExecutor(config?: LuaExecutorConfig): ScriptExecutor;

package/dist/executor.js

@@ -0,0 +1,26 @@
+import { runScript } from './sandbox.js';
+/**
+ * Builds a `ScriptExecutor` (`@markii/runtime`) backed by this package's
+ * `runScript`. `config` is captured once and reused for every script the
+ * returned executor runs; the returned function's only per-call inputs are
+ * `code` and `tier`, matching `ScriptExecutor`'s provider-agnostic
+ * signature. `runScript` never throws (see `./sandbox`'s doc comment), so
+ * this adapter doesn't need its own try/catch — it only reshapes the
+ * result: `ok: true` passes `value` through untouched; `ok: false` maps
+ * `runScript`'s `ScriptFailure` (`{ kind, message, ... }`) down to the
+ * narrower `{ kind: string; message: string }` `ExecuteFailure` shape
+ * `@markii/runtime` expects, dropping the Lua-specific `limit`/`reason`
+ * fields (still visible in `message` for anyone reading the stored error).
+ */
+export function createLuaExecutor(config = {}) {
+    return async ({ code, tier }) => {
+        const result = await runScript({ ...config, code, tier });
+        if (result.ok) {
+            return { ok: true, value: result.value };
+        }
+        return {
+            ok: false,
+            error: { kind: result.error.kind, message: result.error.message },
+        };
+    };
+}

package/dist/globals.d.ts

@@ -0,0 +1,32 @@
+import { type LuaEngine } from 'wasmoon';
+/** The Base-library names this sandbox intentionally keeps reachable. */
+export declare const ALLOWED_GLOBALS: readonly string[];
+/** Names this sandbox verifies are absent after scrubbing (see the adversarial test suite). */
+export declare const DENIED_GLOBALS: readonly string[];
+export interface CreateEmptyLuaEngineOptions {
+    /**
+     * Forwarded verbatim as wasmoon's `LuaFactory` first constructor argument
+     * (`customWasmUri` — confirmed against `node_modules/wasmoon/dist/
+     * factory.d.ts`). Left `undefined` (the default), `LuaFactory` keeps its
+     * own built-in resolution: the local `node_modules/wasmoon/dist/glue.wasm`
+     * file in Node (used by this package's own Vitest suite), or — in a
+     * browser bundle with no bundler-provided URL — a fetch to
+     * `https://unpkg.com/wasmoon@<version>/dist/glue.wasm` at runtime
+     * (confirmed in `node_modules/wasmoon/dist/index.js`). That CDN fetch is
+     * exactly what makes an unconfigured browser host non-offline-capable: no
+     * network to unpkg means no script can ever run. A host that wants to
+     * avoid it (e.g. the playground, via a Vite `?url` asset import so the
+     * wasm ships in its own bundle) passes its own local URL here instead.
+     * Passing `undefined` is IDENTICAL to omitting this options object
+     * entirely — this parameter only ever narrows behavior, never changes it
+     * by default.
+     */
+    wasmUri?: string;
+}
+/**
+ * Creates a fresh wasmoon engine with the curated, empty environment
+ * described above. `traceAllocations: true` is required for the memory cap
+ * (`./limits` / `./sandbox` call `engine.global.setMemoryMax`) — without it
+ * wasmoon uses the plain, uncapped allocator.
+ */
+export declare function createEmptyLuaEngine(options?: CreateEmptyLuaEngineOptions): Promise<LuaEngine>;