@markii/lua 0.1.0

package/dist/marshal.d.ts

@@ -0,0 +1,126 @@
+import type { ScriptMarshalReason } from './errors.js';
+/** Marshal limits: caps on the shape of a script's return value. */
+export interface MarshalLimits {
+    /** Max table nesting depth. Default 32. */
+    maxDepth: number;
+    /** Max total scalar+table nodes visited. Default 20,000. */
+    maxNodes: number;
+}
+export declare const DEFAULT_MARSHAL_LIMITS: MarshalLimits;
+/**
+ * Why marshaling is done IN LUA, before the value ever reaches wasmoon's
+ * own JS conversion:
+ *
+ * wasmoon's table type extension (`getValue` for `LuaType.Table`) eagerly
+ * and unconditionally deep-converts an ENTIRE Lua table into a JS
+ * object/array the moment `thread.run()` resolves — there is no hook to
+ * intercept or cap that conversion from the JS side, and no way to abort
+ * it partway through. Verified empirically: a returned Lua table with
+ * 1,000,000 sequential integer keys took ~12 seconds to convert on
+ * ordinary hardware, fully materializing a million-element JS array before
+ * our own code ever got a chance to look at it or reject it. A node-count
+ * cap applied AFTER that conversion would correctly reject the value, but
+ * only after already paying the full CPU/memory cost of building it — that
+ * fails the "reject quickly, not hang" requirement.
+ *
+ * So instead: the returned value is walked and re-shaped by a small
+ * trusted LUA function (defined by `MARSHAL_PRELUDE` below, injected once
+ * per engine — see `sandbox.ts`) that runs INSIDE the sandboxed VM, under
+ * the exact same instruction-count hook (`./limits`) as the rest of the
+ * script. It counts nodes and depth as it goes and raises a Lua error the
+ * INSTANT either cap is exceeded — for a 1,000,000-entry table with the
+ * default 20,000-node cap, that's ~20,000 `pairs` steps, not 1,000,000,
+ * and it never reaches wasmoon's JS conversion step at all. Only the
+ * already-capped, already-shaped result gets handed to wasmoon's
+ * `getValue`, so that conversion is now cheap by construction.
+ *
+ * This also gives us cycle detection for free: Lua tables can be used as
+ * table KEYS (by identity), so a `seen[t] = true` map, cleared on the way
+ * back out of each table (so the same table appearing twice in DIFFERENT
+ * branches — not a cycle — is still allowed), detects a true cycle
+ * (`t.self = t`) in native Lua before wasmoon's converter would otherwise
+ * have to (wasmoon's converter also handles cycles correctly by reusing a
+ * seen JS object per Lua table pointer — verified empirically it does NOT
+ * hang or stack-overflow on `t.self = t` — but a cycle is still not
+ * JSON-serializable, so we reject it explicitly rather than silently
+ * handing the host a self-referential object).
+ *
+ * Array vs. object: a table is treated as an array iff its keys are
+ * exactly `1..n` for some `n` (checked by counting entries during the
+ * `pairs` walk and comparing against `#value`) — same "sequential integer
+ * keys" rule wasmoon's own converter uses for the DISPLAY shape, applied
+ * here so the pre-shaped table wasmoon receives is unambiguous. Any other
+ * key type is rejected (`'key-type'`) — JSON object keys are strings only,
+ * and allowing e.g. a table keyed by `true`/`false` would silently produce
+ * something JSON can't represent. Two edge cases fall out of this and are
+ * both intentionally rejected as `'key-type'` rather than guessed at: a
+ * table mixing integer and string keys (e.g. `{1, 2, x = "y"}` — not
+ * cleanly a JSON array OR object), and a sparse array with holes (e.g.
+ * `{[1]=1, [3]=3}`, where Lua's `#` length operator is itself undefined at
+ * the border) — both have no faithful JSON shape, so we refuse to guess
+ * rather than silently drop or reorder data. An empty table `{}` has no
+ * keys to disambiguate and is treated as an empty array (`[]`), matching
+ * the "array unless proven otherwise" default the walk falls back to.
+ *
+ * Numbers: Lua 5.4's `number` type covers both what would be a JSON number
+ * AND non-finite IEEE-754 doubles (`0/0`, `1/0`, `-1/0`), which Lua
+ * computes and returns natively with no distinct type tag. The Lua-side
+ * walk lets any number through unchanged (rejecting here would need a
+ * `nan`/`huge` check reimplemented in Lua, which is redundant since we
+ * already do it in JS); `finalizeMarshaledValue` below does the actual
+ * NaN/Infinity check, in JS, on the final (already depth/node-capped)
+ * value.
+ *
+ * Functions, userdata, and threads are rejected outright (`'type'`) — none
+ * of the exposed stdlib or capability surface should ever hand a script a
+ * live function/userdata/thread to return in the first place, but this is
+ * the backstop in case one leaks through.
+ */
+export declare function buildMarshalPrelude(limits: MarshalLimits): string;
+/**
+ * Wraps the user's script source so its return value is piped through
+ * `__smd_marshal_root` before ever leaving the Lua VM. `__smd_marshal_root`
+ * must already be defined as a global in this engine (via
+ * `buildMarshalPrelude`, run once per engine in `sandbox.ts`) — it isn't
+ * redefined per-call, only referenced.
+ *
+ * The user code runs inside its own function scope (`__smd_user_chunk`) so
+ * a bare top-level `return` in the script behaves exactly as it would if
+ * run standalone. `__smd_marshal_root` is a genuine global (see the "NOT
+ * local" note on its definition above — it has to be, to survive being
+ * defined in a separate chunk from the one that calls it), so it is also
+ * directly visible to the untrusted script itself, not just to this
+ * wrapper — this is an accepted, deliberate trade-off: a script COULD call
+ * `__smd_marshal_root(x)` itself out of curiosity, but that function is
+ * pure (no side effects, no capability access, no ambient authority) and
+ * its worst case is raising one of the tagged errors above, so exposing it
+ * this way is harmless. Avoiding it entirely would require a much heavier
+ * mechanism (a custom `_ENV` per chunk) that this phase doesn't need.
+ */
+export declare function wrapUserCode(code: string): string;
+/**
+ * Final JS-side pass over the value wasmoon already converted from the
+ * Lua-side-capped table: strips the `__smd_is_array` marker (converting
+ * the marked object into a real JS array, since wasmoon's own array/object
+ * detection — "keys are exactly 1..n" — doesn't apply once we've added a
+ * non-numeric marker key to what should read as an array) and rejects
+ * non-finite numbers (`NaN`, `Infinity`, `-Infinity`).
+ *
+ * Judgment call on NaN/Infinity: REJECTED, not silently coerced to
+ * `null`. JSON has no representation for them, and a script that computed
+ * one is far more likely to have hit `0/0` or a runaway `1/(x-x)` by
+ * mistake than to have intended it as a value a consuming component should
+ * render — silently turning that into `null` would hide the bug. A caller
+ * that wants "stale/empty" semantics for that case already gets it for
+ * free: a `'marshal'` failure is a normal missing-value case per spec §8
+ * ("If the value is missing or the script hasn't run, the component
+ * renders its empty/stale state").
+ */
+export declare function finalizeMarshaledValue(value: unknown): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: ScriptMarshalReason;
+    message: string;
+};

package/dist/marshal.js

@@ -0,0 +1,260 @@
+import { MARSHAL_ERROR_TAG } from './errors.js';
+export const DEFAULT_MARSHAL_LIMITS = {
+    maxDepth: 32,
+    maxNodes: 20_000,
+};
+/**
+ * Why marshaling is done IN LUA, before the value ever reaches wasmoon's
+ * own JS conversion:
+ *
+ * wasmoon's table type extension (`getValue` for `LuaType.Table`) eagerly
+ * and unconditionally deep-converts an ENTIRE Lua table into a JS
+ * object/array the moment `thread.run()` resolves — there is no hook to
+ * intercept or cap that conversion from the JS side, and no way to abort
+ * it partway through. Verified empirically: a returned Lua table with
+ * 1,000,000 sequential integer keys took ~12 seconds to convert on
+ * ordinary hardware, fully materializing a million-element JS array before
+ * our own code ever got a chance to look at it or reject it. A node-count
+ * cap applied AFTER that conversion would correctly reject the value, but
+ * only after already paying the full CPU/memory cost of building it — that
+ * fails the "reject quickly, not hang" requirement.
+ *
+ * So instead: the returned value is walked and re-shaped by a small
+ * trusted LUA function (defined by `MARSHAL_PRELUDE` below, injected once
+ * per engine — see `sandbox.ts`) that runs INSIDE the sandboxed VM, under
+ * the exact same instruction-count hook (`./limits`) as the rest of the
+ * script. It counts nodes and depth as it goes and raises a Lua error the
+ * INSTANT either cap is exceeded — for a 1,000,000-entry table with the
+ * default 20,000-node cap, that's ~20,000 `pairs` steps, not 1,000,000,
+ * and it never reaches wasmoon's JS conversion step at all. Only the
+ * already-capped, already-shaped result gets handed to wasmoon's
+ * `getValue`, so that conversion is now cheap by construction.
+ *
+ * This also gives us cycle detection for free: Lua tables can be used as
+ * table KEYS (by identity), so a `seen[t] = true` map, cleared on the way
+ * back out of each table (so the same table appearing twice in DIFFERENT
+ * branches — not a cycle — is still allowed), detects a true cycle
+ * (`t.self = t`) in native Lua before wasmoon's converter would otherwise
+ * have to (wasmoon's converter also handles cycles correctly by reusing a
+ * seen JS object per Lua table pointer — verified empirically it does NOT
+ * hang or stack-overflow on `t.self = t` — but a cycle is still not
+ * JSON-serializable, so we reject it explicitly rather than silently
+ * handing the host a self-referential object).
+ *
+ * Array vs. object: a table is treated as an array iff its keys are
+ * exactly `1..n` for some `n` (checked by counting entries during the
+ * `pairs` walk and comparing against `#value`) — same "sequential integer
+ * keys" rule wasmoon's own converter uses for the DISPLAY shape, applied
+ * here so the pre-shaped table wasmoon receives is unambiguous. Any other
+ * key type is rejected (`'key-type'`) — JSON object keys are strings only,
+ * and allowing e.g. a table keyed by `true`/`false` would silently produce
+ * something JSON can't represent. Two edge cases fall out of this and are
+ * both intentionally rejected as `'key-type'` rather than guessed at: a
+ * table mixing integer and string keys (e.g. `{1, 2, x = "y"}` — not
+ * cleanly a JSON array OR object), and a sparse array with holes (e.g.
+ * `{[1]=1, [3]=3}`, where Lua's `#` length operator is itself undefined at
+ * the border) — both have no faithful JSON shape, so we refuse to guess
+ * rather than silently drop or reorder data. An empty table `{}` has no
+ * keys to disambiguate and is treated as an empty array (`[]`), matching
+ * the "array unless proven otherwise" default the walk falls back to.
+ *
+ * Numbers: Lua 5.4's `number` type covers both what would be a JSON number
+ * AND non-finite IEEE-754 doubles (`0/0`, `1/0`, `-1/0`), which Lua
+ * computes and returns natively with no distinct type tag. The Lua-side
+ * walk lets any number through unchanged (rejecting here would need a
+ * `nan`/`huge` check reimplemented in Lua, which is redundant since we
+ * already do it in JS); `finalizeMarshaledValue` below does the actual
+ * NaN/Infinity check, in JS, on the final (already depth/node-capped)
+ * value.
+ *
+ * Functions, userdata, and threads are rejected outright (`'type'`) — none
+ * of the exposed stdlib or capability surface should ever hand a script a
+ * live function/userdata/thread to return in the first place, but this is
+ * the backstop in case one leaks through.
+ */
+export function buildMarshalPrelude(limits) {
+    return `
+local function __smd_marshal(value, seen, depth, budget)
+  local t = type(value)
+  if t == "nil" or t == "boolean" or t == "string" or t == "number" then
+    budget.n = budget.n + 1
+    if budget.n > budget.maxNodes then error("${MARSHAL_ERROR_TAG}:nodes") end
+    return value
+  elseif t == "table" then
+    if depth >= budget.maxDepth then error("${MARSHAL_ERROR_TAG}:depth") end
+    if seen[value] then error("${MARSHAL_ERROR_TAG}:cycle") end
+    seen[value] = true
+    budget.n = budget.n + 1
+    if budget.n > budget.maxNodes then error("${MARSHAL_ERROR_TAG}:nodes") end
+    local count = 0
+    local isArray = true
+    for k, _ in pairs(value) do
+      count = count + 1
+      if type(k) ~= "number" or k < 1 or math.floor(k) ~= k then
+        isArray = false
+      end
+    end
+    local out = {}
+    if isArray and count == #value then
+      for i = 1, count do
+        out[i] = __smd_marshal(value[i], seen, depth + 1, budget)
+      end
+    else
+      isArray = false
+      for k, v in pairs(value) do
+        if type(k) ~= "string" then
+          error("${MARSHAL_ERROR_TAG}:key-type")
+        end
+        out[k] = __smd_marshal(v, seen, depth + 1, budget)
+      end
+    end
+    seen[value] = nil
+    if isArray then
+      out.__smd_is_array = true
+    end
+    return out
+  else
+    error("${MARSHAL_ERROR_TAG}:type:" .. t)
+  end
+end
+
+-- Deliberately NOT "local": this prelude and the wrapped user code (see
+-- \`wrapUserCode\` below) are compiled as SEPARATE chunks via separate
+-- \`loadString\` calls, and a Lua \`local\` never survives past the chunk
+-- that declared it. \`__smd_marshal_root\` must be a global so the
+-- wrapper chunk can call it. \`__smd_marshal\` itself stays local -- it is
+-- only ever called from within THIS chunk (from \`__smd_marshal_root\`,
+-- which closes over it as an upvalue regardless of who calls
+-- \`__smd_marshal_root\` later), so it never needs to be reachable by name
+-- from anywhere else.
+function __smd_marshal_root(value)
+  local budget = { n = 0, maxNodes = ${limits.maxNodes}, maxDepth = ${limits.maxDepth} }
+  return __smd_marshal(value, {}, 0, budget)
+end
+`;
+}
+/**
+ * Wraps the user's script source so its return value is piped through
+ * `__smd_marshal_root` before ever leaving the Lua VM. `__smd_marshal_root`
+ * must already be defined as a global in this engine (via
+ * `buildMarshalPrelude`, run once per engine in `sandbox.ts`) — it isn't
+ * redefined per-call, only referenced.
+ *
+ * The user code runs inside its own function scope (`__smd_user_chunk`) so
+ * a bare top-level `return` in the script behaves exactly as it would if
+ * run standalone. `__smd_marshal_root` is a genuine global (see the "NOT
+ * local" note on its definition above — it has to be, to survive being
+ * defined in a separate chunk from the one that calls it), so it is also
+ * directly visible to the untrusted script itself, not just to this
+ * wrapper — this is an accepted, deliberate trade-off: a script COULD call
+ * `__smd_marshal_root(x)` itself out of curiosity, but that function is
+ * pure (no side effects, no capability access, no ambient authority) and
+ * its worst case is raising one of the tagged errors above, so exposing it
+ * this way is harmless. Avoiding it entirely would require a much heavier
+ * mechanism (a custom `_ENV` per chunk) that this phase doesn't need.
+ */
+export function wrapUserCode(code) {
+    return `local function __smd_user_chunk()\n${code}\nend\nreturn __smd_marshal_root(__smd_user_chunk())`;
+}
+/** True array marker set by the Lua-side marshal walk (see `buildMarshalPrelude`). */
+const ARRAY_MARKER = '__smd_is_array';
+/**
+ * Final JS-side pass over the value wasmoon already converted from the
+ * Lua-side-capped table: strips the `__smd_is_array` marker (converting
+ * the marked object into a real JS array, since wasmoon's own array/object
+ * detection — "keys are exactly 1..n" — doesn't apply once we've added a
+ * non-numeric marker key to what should read as an array) and rejects
+ * non-finite numbers (`NaN`, `Infinity`, `-Infinity`).
+ *
+ * Judgment call on NaN/Infinity: REJECTED, not silently coerced to
+ * `null`. JSON has no representation for them, and a script that computed
+ * one is far more likely to have hit `0/0` or a runaway `1/(x-x)` by
+ * mistake than to have intended it as a value a consuming component should
+ * render — silently turning that into `null` would hide the bug. A caller
+ * that wants "stale/empty" semantics for that case already gets it for
+ * free: a `'marshal'` failure is a normal missing-value case per spec §8
+ * ("If the value is missing or the script hasn't run, the component
+ * renders its empty/stale state").
+ */
+export function finalizeMarshaledValue(value) {
+    const seen = new Set();
+    function walk(v) {
+        if (v === null || v === undefined)
+            return { ok: true, value: null };
+        const t = typeof v;
+        if (t === 'string' || t === 'boolean')
+            return { ok: true, value: v };
+        if (t === 'number') {
+            if (!Number.isFinite(v)) {
+                return {
+                    ok: false,
+                    reason: 'non-finite-number',
+                    message: `script returned a non-finite number (${String(v)})`,
+                };
+            }
+            return { ok: true, value: v };
+        }
+        if (Array.isArray(v)) {
+            if (seen.has(v)) {
+                return {
+                    ok: false,
+                    reason: 'cycle',
+                    message: 'script return value contains a cycle',
+                };
+            }
+            seen.add(v);
+            const out = [];
+            for (const item of v) {
+                const r = walk(item);
+                if (!r.ok)
+                    return r;
+                out.push(r.value);
+            }
+            seen.delete(v);
+            return { ok: true, value: out };
+        }
+        if (t === 'object') {
+            const obj = v;
+            if (seen.has(obj)) {
+                return {
+                    ok: false,
+                    reason: 'cycle',
+                    message: 'script return value contains a cycle',
+                };
+            }
+            seen.add(obj);
+            const isArray = obj[ARRAY_MARKER] === true;
+            if (isArray) {
+                const keys = Object.keys(obj)
+                    .filter((k) => k !== ARRAY_MARKER)
+                    .sort((a, b) => Number(a) - Number(b));
+                const out = [];
+                for (const k of keys) {
+                    const r = walk(obj[k]);
+                    if (!r.ok)
+                        return r;
+                    out.push(r.value);
+                }
+                seen.delete(obj);
+                return { ok: true, value: out };
+            }
+            const out = {};
+            for (const [k, val] of Object.entries(obj)) {
+                const r = walk(val);
+                if (!r.ok)
+                    return r;
+                out[k] = r.value;
+            }
+            seen.delete(obj);
+            return { ok: true, value: out };
+        }
+        // functions/other host objects should never reach here — the Lua-side
+        // walk already rejects them before they're returned at all.
+        return {
+            ok: false,
+            reason: 'type',
+            message: `script return value contained an unsupported JS type: ${t}`,
+        };
+    }
+    return walk(value);
+}

package/dist/require.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Sandboxed `require` (spec §8 "Script placement, long scripts, and
+ * modules"): the eventual design is exactly two sources — bundle-local
+ * modules (`require "scripts/util"`, same path-jail as `bundle.read`) and
+ * pack-namespaced pure-Lua modules (`require "ana/http"`) — pure Lua
+ * source only, no C, no bytecode, no network, module cache per run.
+ *
+ * DESIGN NOTE / explicit deferral: this phase (the sandbox primitive
+ * itself) does not wire that up yet. `bundle.read` (via the injected
+ * `ScriptView`, see `./capabilities`) already gives a script everything it
+ * needs to fetch a bundle-local module's SOURCE TEXT; what a real
+ * `require` adds on top is caching per module name and running the loaded
+ * source as a new protected chunk with the same globals/capabilities —
+ * both of those depend on the pack/namespace resolution rules (§8) that
+ * belong to a later phase (packs, §5/§12), not to this security primitive.
+ * Rather than build a real (but pack-less, cache-less) `require` now and
+ * having to change its resolution semantics later, `require` is left
+ * UNDEFINED — not stubbed as an always-erroring global — in this phase.
+ *
+ * Concretely: `sandbox.ts` never calls anything from this module, and the
+ * curated environment (`./globals`) never sets a `require` global at all.
+ * `NOT_YET_SUPPORTED_MESSAGE` and `buildRequireStub` are kept here,
+ * disconnected from the sandbox wiring, as the landing point for that
+ * later phase — a future change only needs to call `buildRequireStub()`
+ * (or replace it with the real resolver) from `sandbox.ts`'s prelude
+ * assembly, next to `buildCapabilities`.
+ *
+ * Either way — absent entirely (current state) or stubbed to always error
+ * (the stub below, for a host that wants a friendlier error message than
+ * a bare "attempt to call a nil value") — the guarantee the adversarial
+ * suite checks holds: no raw Lua `require` is ever reachable, and no
+ * script can load arbitrary source or bytecode through it.
+ */
+export declare const NOT_YET_SUPPORTED_MESSAGE = "modules not yet supported (require \"%s\")";
+/**
+ * Not wired into `sandbox.ts` in this phase (see module doc comment
+ * above) — provided so a host that wants an explicit, friendlier error
+ * message instead of Lua's default "attempt to call a nil value (global
+ * 'require')" can opt in without this package needing to change shape
+ * later. Deliberately does not touch the filesystem, network, or `load` —
+ * it only ever raises.
+ */
+export declare function buildRequireStub(): string;

package/dist/require.js

@@ -0,0 +1,49 @@
+/**
+ * Sandboxed `require` (spec §8 "Script placement, long scripts, and
+ * modules"): the eventual design is exactly two sources — bundle-local
+ * modules (`require "scripts/util"`, same path-jail as `bundle.read`) and
+ * pack-namespaced pure-Lua modules (`require "ana/http"`) — pure Lua
+ * source only, no C, no bytecode, no network, module cache per run.
+ *
+ * DESIGN NOTE / explicit deferral: this phase (the sandbox primitive
+ * itself) does not wire that up yet. `bundle.read` (via the injected
+ * `ScriptView`, see `./capabilities`) already gives a script everything it
+ * needs to fetch a bundle-local module's SOURCE TEXT; what a real
+ * `require` adds on top is caching per module name and running the loaded
+ * source as a new protected chunk with the same globals/capabilities —
+ * both of those depend on the pack/namespace resolution rules (§8) that
+ * belong to a later phase (packs, §5/§12), not to this security primitive.
+ * Rather than build a real (but pack-less, cache-less) `require` now and
+ * having to change its resolution semantics later, `require` is left
+ * UNDEFINED — not stubbed as an always-erroring global — in this phase.
+ *
+ * Concretely: `sandbox.ts` never calls anything from this module, and the
+ * curated environment (`./globals`) never sets a `require` global at all.
+ * `NOT_YET_SUPPORTED_MESSAGE` and `buildRequireStub` are kept here,
+ * disconnected from the sandbox wiring, as the landing point for that
+ * later phase — a future change only needs to call `buildRequireStub()`
+ * (or replace it with the real resolver) from `sandbox.ts`'s prelude
+ * assembly, next to `buildCapabilities`.
+ *
+ * Either way — absent entirely (current state) or stubbed to always error
+ * (the stub below, for a host that wants a friendlier error message than
+ * a bare "attempt to call a nil value") — the guarantee the adversarial
+ * suite checks holds: no raw Lua `require` is ever reachable, and no
+ * script can load arbitrary source or bytecode through it.
+ */
+export const NOT_YET_SUPPORTED_MESSAGE = 'modules not yet supported (require "%s")';
+/**
+ * Not wired into `sandbox.ts` in this phase (see module doc comment
+ * above) — provided so a host that wants an explicit, friendlier error
+ * message instead of Lua's default "attempt to call a nil value (global
+ * 'require')" can opt in without this package needing to change shape
+ * later. Deliberately does not touch the filesystem, network, or `load` —
+ * it only ever raises.
+ */
+export function buildRequireStub() {
+    return `
+require = function(name)
+  error(string.format(${JSON.stringify(NOT_YET_SUPPORTED_MESSAGE)}, tostring(name)))
+end
+`;
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,71 @@
+import type { ScriptView } from '@markii/bundle';
+import { type CacheProvider, type CapabilityTier, type NetGrants, type NetProvider } from './capabilities.js';
+import type { ScriptFailure } from './errors.js';
+import { type ScriptLimits } from './limits.js';
+import { type MarshalLimits } from './marshal.js';
+export interface RunScriptOptions {
+    code: string;
+    /** Spec §8's trigger tier: 'manual' unlocks effectful ops, 'auto' is read-only regardless of what's granted. */
+    tier: CapabilityTier;
+    net?: NetProvider;
+    netGrants?: NetGrants;
+    cache?: CacheProvider;
+    /** Bundle-scoped filesystem (spec §11), already capability-restricted — see `@markii/bundle`'s `createScriptView`. */
+    bundle?: ScriptView;
+    maxFetchBytes?: number;
+    limits?: Partial<ScriptLimits>;
+    marshalLimits?: Partial<MarshalLimits>;
+    /**
+     * Forwarded to `./globals`' `createEmptyLuaEngine` as its
+     * `wasmUri` option (wasmoon's `customWasmUri`). Left `undefined` (the
+     * default), engine creation is byte-for-byte the same as before this
+     * option existed: local `node_modules` resolution in Node, the unpkg CDN
+     * default in an unconfigured browser bundle. A host that bundles its own
+     * copy of wasmoon's `glue.wasm` (e.g. the playground, to avoid a runtime
+     * dependency on the unpkg CDN) passes that local URL here instead — see
+     * `createEmptyLuaEngine`'s doc comment for the full rationale.
+     */
+    wasmUri?: string;
+}
+export type RunScriptResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: ScriptFailure;
+};
+/**
+ * Runs one Lua script in a fresh, fully isolated sandbox and always tears
+ * the engine down before returning — a run never leaves state (globals,
+ * memory, hooks) for a later run to inherit. Never throws: every way
+ * hostile code can fail comes back as `{ ok: false, error }`, never a raw
+ * exception (see `./errors`).
+ *
+ * Orchestration, in order:
+ * 1. `./globals` — fresh engine, curated empty environment (no `os`/`io`/
+ *    `require`/etc; see that module for exactly what's kept and why).
+ * 2. Memory cap (`engine.global.setMemoryMax`, backed by the
+ *    `traceAllocations: true` custom allocator `./globals` requests).
+ * 3. `./capabilities` — build the `net`/`cache`/`bundle` Lua tables from
+ *    whatever providers/grants/tier this call was given.
+ * 4. `./marshal` — inject the trusted node/depth-capped marshal walk that
+ *    the wrapped user code's return value is piped through.
+ * 5. A dedicated child thread (NOT `engine.doString`, which creates its
+ *    own internal thread we'd have no handle to — see `./limits`'s "hooks
+ *    are per-thread" note) gets the instruction/wall-clock hook installed,
+ *    then runs the wrapped user code.
+ * 6. The out-of-band breach flag from step 5's hook is checked
+ *    UNCONDITIONALLY and, if set, wins over whatever the run otherwise
+ *    reported — see `./limits`'s doc comment for why this is the actual
+ *    enforcement point for "not swallowed by the script's own `pcall`".
+ * 7. Otherwise, a thrown error is classified by three non-spoofable
+ *    out-of-band signals, in order, before ever falling back to
+ *    `classifyRuntimeError`'s message-based path: the wall-clock guard's
+ *    own `ScriptLimitError` sentinel (`instanceof`, Defect 3), then the
+ *    raw `LuaReturn.ErrorMem` status code (Defect 2). A successful return
+ *    goes through `finalizeMarshaledValue` for the final NaN/Infinity
+ *    check and marker cleanup.
+ * 8. `finally`: hook removed, thread popped, engine closed — every path,
+ *    including every early return above.
+ */
+export declare function runScript(options: RunScriptOptions): Promise<RunScriptResult>;