@markii/lua 0.10.0 → 0.12.0

package/dist/doc.d.ts

@@ -0,0 +1,89 @@
+import type { DocView } from '@markii/runtime';
+import { type MarshalLimits } from './marshal.js';
+/**
+ * The `doc` table (GitHub issue #33): a script's read-only view of the
+ * note it is written in.
+ *
+ * `doc.directives(filter)` lists the note's directives in document order,
+ * and `doc.value(name)` reads what a script ABOVE this one produced. Both
+ * are pure reads of content the note already holds, so unlike `net`,
+ * `cache` and `bundle` this table is NOT tier-gated and needs no grant: it
+ * is wired identically for a manual run and an auto/scheduled one. There
+ * is no write side to gate.
+ *
+ * ## Why the listing crosses as JSON text
+ *
+ * For the same reason `net.fetch_json` does (see `./json-decode`): a plain
+ * JS object handed to `global.set` arrives in Lua as a wasmoon `js_proxy`
+ * userdata, not a genuine table, so `type()`, `#`, `ipairs` and marshaling
+ * a piece of it back out all misbehave. A string is a scalar and crosses
+ * cleanly, and `__smd_json_decode` rebuilds it into an ordinary Lua table
+ * the script cannot tell from one it wrote itself.
+ *
+ * The decode is repeated on every `doc.directives()` call rather than
+ * cached in a Lua local, and that is deliberate: each call therefore hands
+ * back FRESH tables. A script that scribbles on an entry it was given
+ * cannot make the next call in the same script see its edits, and it never
+ * had a way to reach the next script at all, since each script runs in its
+ * own engine (`./sandbox`'s `runScript` builds and closes one per script).
+ * The JSON itself is built once, on the JS side, and reused.
+ *
+ * ## What a rejected read looks like
+ *
+ * Reading a name that belongs to a script further down the note is a
+ * script-authoring mistake, not a permission or resource problem. It is
+ * therefore NOT recorded on `./capabilities`' `CapabilityDenials` handle:
+ * recording it there would classify the run as `'capability-denied'` and
+ * the host would tell the user their note needs a permission it does not
+ * need. It stays a `'runtime'` failure, which `./executor` maps to
+ * `'script-error'`, so the marker reads "script error: reads "quiz", which
+ * runs later in the note".
+ *
+ * It does get its own out-of-band record ({@link DocRejections}), for the
+ * same reason the capability denials have one: the message that comes back
+ * OUT of Lua is wrapped ("Error: ..." plus a stack traceback) and may have
+ * been rewritten by the script's own `pcall`/`error` games, so the host
+ * would otherwise put a traceback in a tooltip. `./sandbox` reads the
+ * recorded sentence instead, which the script can neither see nor forge.
+ */
+export interface DocConfig {
+    /**
+     * This script's view of its note, built by `@markii/runtime`'s
+     * `runDocumentScripts` from the listing the host handed it. Absent, the
+     * `doc` table is still wired, with an empty listing and a `value` that
+     * answers nil for every name: a script must never meet a `doc` that is
+     * nil, or the first thing an author writes fails as "attempt to index a
+     * nil value" with nothing to explain it.
+     */
+    doc?: DocView;
+    /**
+     * The depth/node budget a value read through `doc.value` is checked
+     * against before it is handed to Lua, exactly as `net.fetch_json` and
+     * `cache.get` check theirs. A stored value has already passed this same
+     * budget on its way OUT of the script that produced it, so this is a
+     * second, defensive reading rather than the first one.
+     */
+    marshalLimits?: MarshalLimits;
+}
+/**
+ * Non-spoofable record of the LAST `doc` read this run refused. A plain JS
+ * closure, exactly like `./capabilities`' `CapabilityDenials`: no Lua
+ * value, no metatable, nothing a script can read or write. `./sandbox`
+ * consults it (after the capability handle, which outranks it) to report
+ * the clean sentence rather than whatever came back through Lua.
+ */
+export interface DocRejections {
+    last(): string | undefined;
+}
+/**
+ * Builds the raw host functions and the trusted Lua prelude defining the
+ * `doc` table. Shaped like `./capabilities`' `buildCapabilities` (raw flat
+ * globals captured into prelude locals, then nil'd out) so the two follow
+ * one pattern; see that function's doc comment for why the ergonomic
+ * wrappers must be Lua-native tables rather than JS objects.
+ */
+export declare function buildDoc(config: DocConfig): {
+    rawGlobals: Record<string, (...args: never[]) => Promise<unknown>>;
+    preludeLua: string;
+    rejections: DocRejections;
+};

package/dist/doc.js

@@ -0,0 +1,131 @@
+import { buildJsonDecodePrelude } from './json-decode.js';
+import { checkJsonWithinLimits, DEFAULT_MARSHAL_LIMITS, } from './marshal.js';
+/**
+ * Builds the raw host functions and the trusted Lua prelude defining the
+ * `doc` table. Shaped like `./capabilities`' `buildCapabilities` (raw flat
+ * globals captured into prelude locals, then nil'd out) so the two follow
+ * one pattern; see that function's doc comment for why the ergonomic
+ * wrappers must be Lua-native tables rather than JS objects.
+ */
+export function buildDoc(config) {
+    const view = config.doc;
+    const limits = config.marshalLimits ?? DEFAULT_MARSHAL_LIMITS;
+    let lastRejection;
+    /** Records the clean sentence, THEN throws it — same order every denial site in `./capabilities` uses. */
+    function reject(message) {
+        lastRejection = message;
+        return new Error(message);
+    }
+    let listingJson;
+    const rawGlobals = {};
+    rawGlobals.__smd_doc_listing_raw = (async () => {
+        if (listingJson === undefined) {
+            // The listing is already capped, sanitized plain data
+            // (`@markii/runtime`'s `buildDirectiveListing`), so this cannot
+            // throw on a cycle or a non-serializable member. The `?? '[]'` is
+            // the belt for a host that supplied something stranger than a
+            // listing: an empty list is always a truthful answer, an exception
+            // never is.
+            try {
+                listingJson = JSON.stringify(view?.directives.directives ?? []) ?? '[]';
+            }
+            catch {
+                listingJson = '[]';
+            }
+        }
+        return listingJson;
+    });
+    rawGlobals.__smd_doc_value_raw = (async (name) => {
+        if (!view)
+            return undefined;
+        const read = view.value(typeof name === 'string' ? name : '');
+        if (!read.ok) {
+            // `@markii/runtime` owns this sentence; this module only carries it.
+            throw reject(read.message);
+        }
+        const value = read.value;
+        if (value === undefined || value === null)
+            return undefined;
+        const budget = checkJsonWithinLimits(value, limits);
+        if (!budget.ok) {
+            throw reject(`doc.value("${name}") ${budget.message}`);
+        }
+        try {
+            const encoded = JSON.stringify(value);
+            return encoded === undefined ? undefined : encoded;
+        }
+        catch {
+            throw reject(`doc.value("${name}") could not be read as a value`);
+        }
+    });
+    const truncated = view?.directives.truncated === true;
+    // `buildJsonDecodePrelude` is emitted here rather than assumed: this
+    // module is exercised standalone in its own tests, and `./capabilities`
+    // only emits it when `net`/`cache` are wired. Emitting it twice in one
+    // run simply redefines the same idempotent trusted function, which is
+    // the same reasoning `./capabilities`' own `ensureMarshalPrelude` uses.
+    //
+    // It defines `__smd_json_decode` as a GLOBAL, though, and `doc` is wired
+    // for every run, so emitting it unconditionally would leave that private
+    // name reachable from user code in runs that never wire `net`/`cache` --
+    // exactly the residue `require-pass3.probe.test.ts` fails the suite for.
+    // So the previous value is saved before and put back after: this module
+    // pins its own copy in a local and leaves the globals table exactly as
+    // it found it. Every other consumer pins its own copy at ITS prelude
+    // time too (`./capabilities`), so restoring a nil here can never take a
+    // decoder away from anyone.
+    const preludeLua = `local __smd_doc_prev_decode = __smd_json_decode
+${buildJsonDecodePrelude(limits)}
+local __smd_doc_listing = __smd_doc_listing_raw
+local __smd_doc_value = __smd_doc_value_raw
+-- Every primitive this table needs is pinned HERE, at prelude-definition
+-- time, never resolved as a global inside the wrappers -- the same
+-- discipline \`./json-decode\` and \`./capabilities\` follow (adversarial
+-- findings A1/A2). Without it, a script could rebind \`__smd_json_decode\`
+-- or \`type\` before calling \`doc.directives\` and change what its own
+-- guards do.
+local __smd_doc_decode = __smd_json_decode
+local __smd_doc_type, __smd_doc_error = type, error
+__smd_json_decode = __smd_doc_prev_decode
+__smd_doc_listing_raw = nil
+__smd_doc_value_raw = nil
+
+doc = {}
+doc.truncated = ${truncated ? 'true' : 'false'}
+
+doc.directives = function(filter)
+  local wanted = nil
+  if filter ~= nil then
+    if __smd_doc_type(filter) ~= "table" then
+      __smd_doc_error("doc.directives(filter): filter must be a table")
+    end
+    wanted = filter.name
+    if wanted ~= nil and __smd_doc_type(wanted) ~= "string" then
+      __smd_doc_error("doc.directives(filter): filter.name must be a string")
+    end
+  end
+  local entries = __smd_doc_decode(__smd_doc_listing():await())
+  if wanted == nil then return entries end
+  local out = {}
+  local n = 0
+  for i = 1, #entries do
+    local entry = entries[i]
+    if entry.name == wanted then
+      n = n + 1
+      out[n] = entry
+    end
+  end
+  return out
+end
+
+doc.value = function(name)
+  if __smd_doc_type(name) ~= "string" then
+    __smd_doc_error("doc.value(name): name must be a string")
+  end
+  local text = __smd_doc_value(name):await()
+  if text == nil then return nil end
+  return __smd_doc_decode(text)
+end
+`;
+    return { rawGlobals, preludeLua, rejections: { last: () => lastRejection } };
+}

package/dist/executor.d.ts

@@ -16,13 +16,16 @@ import { type RunScriptOptions } from './sandbox.js';
  * cycle.
  */
 /**
- * Everything `runScript` accepts except `code`/`tier` — those two are
- * supplied per call by `runDocumentScripts` (`@markii/runtime`); everything
+ * Everything `runScript` accepts except `code`/`tier`/`doc` — those three
+ * are supplied per call by `runDocumentScripts` (`@markii/runtime`): the
+ * first two per the `ScriptExecutor` contract, and `doc` because a note
+ * view is per-SCRIPT (it says which values are already available), so it
+ * can never be captured once at construction time; 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'>;
+export type LuaExecutorConfig = Omit<RunScriptOptions, 'code' | 'tier' | 'doc'>;
 /**
  * Builds a `ScriptExecutor` (`@markii/runtime`) backed by this package's
  * `runScript`. `config` is captured once and reused for every script the

package/dist/executor.js

@@ -42,8 +42,13 @@ function toRuntimeFailureKind(failure) {
  * the stored error).
  */
 export function createLuaExecutor(config = {}) {
-    return async ({ code, tier }) => {
-        const result = await runScript({ ...config, code, tier });
+    return async ({ code, tier, doc }) => {
+        const result = await runScript({
+            ...config,
+            code,
+            tier,
+            ...(doc ? { doc } : {}),
+        });
         if (result.ok) {
             return { ok: true, value: result.value };
         }

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export type { LimitHandle, ScriptLimits } from './limits.js';
 export { DEFAULT_LIMITS, installLimits } from './limits.js';
 export type { CacheEntry, CacheProvider, CapabilityConfig, CapabilityDenial, CapabilityDenials, CapabilityTier, NetGrants, NetProvider, NetResponse, } from './capabilities.js';
 export { DEFAULT_MAX_FETCH_BYTES, bytesToLuaString, buildCapabilities, isNetProviderDenial, luaStringToBytes, netProviderDenial, } from './capabilities.js';
+export type { DocConfig } from './doc.js';
+export { buildDoc } from './doc.js';
 export type { MarshalLimits } from './marshal.js';
 export { DEFAULT_MARSHAL_LIMITS, buildMarshalPrelude, checkJsonWithinLimits, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
 export type { PackModuleResolver, RequireConfig } from './require.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export { CAPABILITY_ERROR_TAG, FETCH_DECODE_ERROR_TAG, MARSHAL_ERROR_TAG, Script
 export { ALLOWED_GLOBALS, DENIED_GLOBALS, createEmptyLuaEngine, } from './globals.js';
 export { DEFAULT_LIMITS, installLimits } from './limits.js';
 export { DEFAULT_MAX_FETCH_BYTES, bytesToLuaString, buildCapabilities, isNetProviderDenial, luaStringToBytes, netProviderDenial, } from './capabilities.js';
+export { buildDoc } from './doc.js';
 export { DEFAULT_MARSHAL_LIMITS, buildMarshalPrelude, checkJsonWithinLimits, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
 export { buildRequire } from './require.js';
 export { runScript } from './sandbox.js';

package/dist/require.d.ts

@@ -1,17 +1,19 @@
 import type { ScriptView } from '@markii/bundle';
 /**
  * Sandboxed `require` (spec §8 "Long scripts and shared code", docs/
- * scripting.md): exactly two of the spec's three sources are implemented
- * here — bundle-local modules and the SEAM for pack modules (the pack
- * loader itself, and the third source, the vault library, are later
- * phases: packs need the pack-installation machinery from packs.md, and
- * the vault library needs a host-side namespace-to-folder mapping neither
- * of which exists yet). Both implemented sources, and the not-yet-wired
- * one, share ONE property: every require target this module resolves is
- * PURE LUA SOURCE TEXT, loaded as a fresh PROTECTED CHUNK on the SAME
- * thread as the rest of the run, so it shares that run's globals,
- * capabilities, and instruction/wall-clock/memory budget — a module can
- * never grant itself more than the script that required it already had.
+ * scripting.md): there are exactly TWO sources of shared Lua, and this
+ * module implements both — bundle-local modules, and pack modules (the
+ * `PackModuleResolver` seam below, which a host wires to its own installed
+ * packs, e.g. `@markii/host`'s `createPackModuleResolver`). There is no
+ * third source: a folder of shared Lua with nothing to render is simply a
+ * pack whose manifest declares no components (`"components": {}`) and
+ * carries its own `scripts/*.lua` — it is a pack module like any other, not
+ * a separate mechanism. Both sources share ONE property: every require
+ * target this module resolves is PURE LUA SOURCE TEXT, loaded as a fresh
+ * PROTECTED CHUNK on the SAME thread as the rest of the run, so it shares
+ * that run's globals, capabilities, and instruction/wall-clock/memory
+ * budget — a module can never grant itself more than the script that
+ * required it already had.
  *
  * ## Two sources, told apart by the first path segment (docs/scripting.md)
  *
@@ -28,11 +30,13 @@ import type { ScriptView } from '@markii/bundle';
  *   no separate tier gate to apply on top of what `bundle.read` already
  *   enforces.
  * - **Pack-namespaced**: `require "ana/http"` (first segment anything
- *   else). This phase implements ONLY the seam: an optional injected
- *   `PackModuleResolver`. With no resolver configured (packs are not
- *   wired into any host yet), a pack-namespaced `require` fails cleanly
- *   as a capability denial — never a crash, never a fallthrough into
- *   filesystem or network access.
+ *   else). This package only defines the seam: an optional injected
+ *   `PackModuleResolver`. A host that has wired up pack installation
+ *   (`@markii/host`'s `discoverPacks` + `loadPackModules` +
+ *   `createPackModuleResolver`) passes a real resolver in; with none
+ *   configured, a pack-namespaced `require` fails cleanly as a capability
+ *   denial — never a crash, never a fallthrough into filesystem or network
+ *   access.
  *
  * ## Why a real `require` needs `load` back, carefully
  *

package/dist/sandbox.d.ts

@@ -1,4 +1,5 @@
 import type { ScriptView } from '@markii/bundle';
+import type { DocView } from '@markii/runtime';
 import { type CacheProvider, type CapabilityTier, type NetGrants, type NetProvider } from './capabilities.js';
 import type { ScriptFailure } from './errors.js';
 import { type ScriptLimits } from './limits.js';
@@ -13,6 +14,14 @@ export interface RunScriptOptions {
     cache?: CacheProvider;
     /** Bundle-scoped filesystem (spec §11), already capability-restricted — see `@markii/bundle`'s `createScriptView`. Also backs bundle-local `require "scripts/..."` (`./require`) — the SAME `ScriptView`, so a module require goes through the identical path-jail and read-permission check as `bundle.read`. */
     bundle?: ScriptView;
+    /**
+     * This script's read-only view of the note it runs in (GitHub issue #33,
+     * `./doc`), supplied per script by `@markii/runtime`'s
+     * `runDocumentScripts`. Omitted (a standalone `runScript` call), the
+     * `doc` table is still defined, with an empty listing and a `value` that
+     * answers nil: a script never meets a nil `doc`.
+     */
+    doc?: DocView;
     /** Optional pack-module `require` seam (`./require`'s `PackModuleResolver`) — resolves `require "packName/modulePath"`. Omitted (the default: no host wires packs yet), every pack-namespaced `require` fails as a clean capability denial, never a crash. */
     packModuleResolver?: PackModuleResolver;
     maxFetchBytes?: number;

package/dist/sandbox.js

@@ -1,5 +1,6 @@
 import { LuaReturn } from 'wasmoon';
 import { buildCapabilities, } from './capabilities.js';
+import { buildDoc } from './doc.js';
 import { MARSHAL_ERROR_TAG, ScriptLimitError } from './errors.js';
 import { createEmptyLuaEngine } from './globals.js';
 import { DEFAULT_LIMITS, installLimits } from './limits.js';
@@ -260,6 +261,19 @@ export async function runScript(options) {
             throw new Error(`sandbox assembly left a code-loading primitive reachable (${String(loadResidue)}); refusing to run`);
         }
         await engine.doString(buildMarshalPrelude(marshalLimits));
+        // ./doc: the note-scoped read-only view (GitHub issue #33). Wired
+        // AFTER the marshal prelude and, like `require`, wired unconditionally
+        // — with no `options.doc` it is an empty listing, never an absent
+        // global. It records nothing on `denials`: nothing here is a
+        // capability, so nothing here may classify a run as capability-denied.
+        const docBuild = buildDoc({
+            ...(options.doc ? { doc: options.doc } : {}),
+            marshalLimits,
+        });
+        for (const [name, fn] of Object.entries(docBuild.rawGlobals)) {
+            engine.global.set(name, fn);
+        }
+        await engine.doString(docBuild.preludeLua);
         thread = engine.global.newThread();
         threadStackIndex = engine.global.getTop();
         limitHandle = installLimits(thread, limits);
@@ -386,6 +400,21 @@ export async function runScript(options) {
                     },
                 };
             }
+            // A refused `doc` read (`./doc`, GitHub issue #33), recorded the
+            // same out-of-band way and checked AFTER the capability handle,
+            // which outranks it: a genuine denial is the more important thing to
+            // tell the user about. This is NOT a capability failure, so it stays
+            // a `'runtime'` kind (`'script-error'` once `./executor` maps it);
+            // the handle exists only so the reported MESSAGE is the clean
+            // sentence rather than the Lua-wrapped one, which arrives prefixed
+            // with "Error: " and trailing a stack traceback. It carries the same
+            // accepted edge as the denial handle above: a script that provokes a
+            // refusal, swallows it with its own `pcall`, and then fails for an
+            // unrelated reason is still reported against the refusal.
+            const rejection = docBuild.rejections.last();
+            if (rejection) {
+                return { ok: false, error: { kind: 'runtime', message: rejection } };
+            }
             return { ok: false, error: classifyRuntimeError(runResult.err) };
         }
         const finalized = finalizeMarshaledValue(runResult.value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/lua",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Sandboxed Lua 5.4 (wasmoon) execution runtime for Mark's document scripting: an empty-env global whitelist, two-tier capability-gated net/cache/bundle access, instruction-count/wall-clock/memory limits, and depth/size-capped Lua<->JS marshaling.",
   "keywords": [
     "markdown",
@@ -44,8 +44,8 @@
     "lint": "eslint ."
   },
   "dependencies": {
-    "@markii/bundle": "0.10.0",
-    "@markii/runtime": "0.10.0",
+    "@markii/bundle": "0.12.0",
+    "@markii/runtime": "0.12.0",
     "wasmoon": "^1.16.0"
   }
 }