@markii/host 0.0.0-stage → 0.17.0-next.2

package/dist/run/run-host.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The host-side runner for slice 1 of the extension's v2 Run arc (GitHub
+ * issue #1's locked design comment). Plain Node — no `vscode` import — so
+ * it is unit-testable with Vitest and reusable unchanged once slice 2
+ * wires a command/button to it.
+ *
+ * `spawnRun` is the whole contract: give it a note's text, its net
+ * allowlist, a persisted cache snapshot, and a deadline; get back a
+ * `RunResult` that never rejects. The EXTERNAL watchdog
+ * (`setTimeout` -> `worker.terminate()`) is what makes this safe to call
+ * against untrusted script content — `./worker-entry.ts`'s own in-VM
+ * limits are a second, INNER layer (docs/security.md), but this file's job
+ * is the outer one: a kill switch that works even if everything inside the
+ * worker is compromised or wedged, because `terminate()` acts on the
+ * thread from outside it.
+ */
+import type { CacheEntry } from '@markii/lua';
+import type { RunTrigger, StoredValue } from '@markii/runtime';
+import type { RunJob, RunResult } from './worker-entry.js';
+import type { IsolateSpawner } from './isolate.js';
+export type { IsolateSpawner, RunIsolate, SpawnIsolateOptions, } from './isolate.js';
+export type { RunJob, RunResult, RunFailure } from './worker-entry.js';
+export type { RunProgress } from './run-progress.js';
+/** What a caller of the shared run path supplies; the host adds the isolate (`SpawnRunOptions.spawnIsolate`, `.workerPath`). */
+export type SpawnRunRequest = Omit<SpawnRunOptions, 'workerPath' | 'spawnIsolate'>;
+export interface SpawnRunOptions {
+    text: string;
+    /**
+     * How this run was triggered (GitHub issue #11), forwarded verbatim to the
+     * worker's `RunJob.trigger` and, from there, to `runDocumentScripts` — the
+     * value that `@markii/runtime`'s `tierForTrigger` maps to the execution
+     * tier THE SANDBOX ENFORCES. `'manual'` unlocks every granted capability;
+     * `'auto'`/`'scheduled'` are read-only regardless of what was granted.
+     * Omitted defaults to `'manual'` in the worker, preserving the pre-#11
+     * behavior for any caller that has not been updated.
+     */
+    trigger?: RunTrigger;
+    netAllowlist: string[];
+    /**
+     * The DNS-rebinding / private-range policy (GitHub issue #10), forwarded
+     * verbatim to the worker's `RunJob.netPolicy` — see `./net-pinning.ts`'s
+     * `PinPolicy` and `./worker-entry.ts`'s `createNetProvider`. Omitted
+     * defaults to the fail-closed posture in the worker
+     * (`allowRestrictedAddresses: false`), same pattern `trigger` and
+     * `packModules` already follow.
+     */
+    netPolicy?: RunJob['netPolicy'];
+    cacheSnapshot: Record<string, CacheEntry>;
+    /** Wall-clock budget for the whole run, enforced by this file's own external watchdog — never delegated to the worker. */
+    timeoutMs: number;
+    /** Forwarded verbatim to the worker's `RunJob.limits` (the sandbox's own, INNER resource caps) — see `./worker-entry.ts`. */
+    limits?: RunJob['limits'];
+    /** Forwarded verbatim to the worker's `RunJob.bundle` (the bundle-fs capability snapshot) — see `./worker-entry.ts`. Absent for a bare `.mk.md` run. */
+    bundle?: RunJob['bundle'];
+    /** Forwarded verbatim to the worker's `RunJob.packModules` (pre-read pack Lua modules) — see `./worker-entry.ts`. Absent when no packs are configured. */
+    packModules?: RunJob['packModules'];
+    /**
+     * The KIND of isolate this run spawns. Required: this module has no
+     * default so it stays free of `node:*`. A Node host passes
+     * `workerThreadIsolate` from `@markii/host/node` (the only kind that
+     * accepts a V8 heap cap); a host whose runtime cannot create worker
+     * threads, such as an Electron renderer, supplies a Web Worker one. See
+     * `./isolate.ts` for the constraints an implementation must meet, and
+     * for what a Web Worker cannot bound that a worker thread can.
+     *
+     * The watchdog, the exactly-once settlement, and the never-rejects
+     * contract are NOT part of what this overrides: they stay in `spawnRun`
+     * for every host, so a new isolate kind cannot accidentally ship without
+     * a kill switch.
+     */
+    spawnIsolate: IsolateSpawner;
+    /**
+     * Called once per script as its value arrives from the isolate, in
+     * document order, while the run is still going (GitHub issue #35). This
+     * is what lets a preview un-stale one component at a time instead of
+     * waiting for the whole batch: scripts run sequentially in one isolate,
+     * so the first value is often known seconds before the last.
+     *
+     * Every message is validated (`isRunProgress`) and ordered before it
+     * reaches this callback, and anything it throws is swallowed — reporting
+     * progress must never be able to fail a run or break the never-rejects
+     * contract below. It is never called after the run has settled.
+     */
+    onValue?: (name: string, value: StoredValue, index: number) => void;
+    /**
+     * The entry the isolate loads. This package cannot know how a given host
+     * bundles or lays out its own `dist/` (see e.g.
+     * `apps/vscode/src/worker-path.ts`), so the host always passes it. The
+     * Node-only dev/Vitest fallback lives in `@markii/host/node`
+     * (`defaultWorkerPath`).
+     */
+    workerPath: string;
+}
+/**
+ * Spawns one ephemeral worker, runs `options.text`'s scripts in it under
+ * the manual tier, and resolves with the outcome. NEVER REJECTS — every
+ * way this can go wrong (a message never arrives, the worker throws, the
+ * worker exits on its own, the external watchdog fires) resolves with an
+ * ordinary `RunResult` carrying a synthetic failure instead. Settlement is
+ * exactly-once: whichever of `message` / `error` / `exit` / the watchdog
+ * fires FIRST wins; every later event on the same worker is a no-op (the
+ * `settled` guard below), so there is no risk of a double-`resolve` race
+ * even though several of these could in principle fire in close
+ * succession (e.g. `terminate()` after settling on `message` still
+ * produces its own `exit` event).
+ */
+export declare function spawnRun(options: SpawnRunOptions): Promise<RunResult>;

package/dist/run/run-host.js

@@ -0,0 +1,241 @@
+// From `./run-progress.ts`, NOT from `./run-job.ts`: that module imports
+// `@markii/lua`, and a value import of it here would drag a WebAssembly Lua
+// engine into every host bundle that runs a job (the Obsidian plugin's
+// renderer bundle above all, which never executes Lua itself).
+import { isRunProgress } from './run-progress.js';
+/**
+ * `resourceLimits.maxOldGenerationSizeMb` for the spawned worker (A-1): a
+ * script's own Lua memory is already capped in-VM (`@markii/lua`'s
+ * `limits.maxMemoryBytes`), but nothing previously bounded the JS/V8 heap
+ * OF THE WORKER ITSELF — a large marshaled return value, an oversize
+ * fetched/cached JSON payload, or any other JS-side allocation this file's
+ * own code performs could still OOM that heap. Without an explicit
+ * `resourceLimits`, a V8 OOM inside a `worker_threads` worker is fatal to
+ * the WHOLE PROCESS (the extension host), not just that thread — exactly
+ * the failure mode the external, always-available `terminate()` watchdog
+ * above is meant to make impossible for a wedged/hostile script. 128MB is
+ * comfortably above what one script's marshaled result or one cached
+ * fetch response (`@markii/lua`'s `DEFAULT_MAX_FETCH_BYTES`, 2MB) should
+ * ever need, while still being small enough that a runaway allocation hits
+ * this cap, and the resulting worker `'error'` event, long before it could
+ * threaten the host process's own heap.
+ */
+const WORKER_MAX_OLD_GENERATION_SIZE_MB = 128;
+/**
+ * How many per-script progress values one run may report (GitHub issue
+ * #35). A real note has a handful of script blocks; this cap exists only
+ * so a compromised or malfunctioning isolate cannot grow the host's memory
+ * by inventing names, since the accumulated map is what a killed run's
+ * synthetic result carries. Messages past the cap are dropped, and the run
+ * itself is unaffected — its own `RunResult.values` is the authority
+ * whenever the worker gets to send one.
+ */
+const MAX_PROGRESS_VALUES = 1000;
+function describeThrown(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Spawns one ephemeral worker, runs `options.text`'s scripts in it under
+ * the manual tier, and resolves with the outcome. NEVER REJECTS — every
+ * way this can go wrong (a message never arrives, the worker throws, the
+ * worker exits on its own, the external watchdog fires) resolves with an
+ * ordinary `RunResult` carrying a synthetic failure instead. Settlement is
+ * exactly-once: whichever of `message` / `error` / `exit` / the watchdog
+ * fires FIRST wins; every later event on the same worker is a no-op (the
+ * `settled` guard below), so there is no risk of a double-`resolve` race
+ * even though several of these could in principle fire in close
+ * succession (e.g. `terminate()` after settling on `message` still
+ * produces its own `exit` event).
+ */
+export async function spawnRun(options) {
+    const workerPath = options.workerPath;
+    const job = {
+        text: options.text,
+        netAllowlist: options.netAllowlist,
+        cacheSnapshot: options.cacheSnapshot,
+        ...(options.trigger !== undefined ? { trigger: options.trigger } : {}),
+        ...(options.netPolicy !== undefined
+            ? { netPolicy: options.netPolicy }
+            : {}),
+        ...(options.limits !== undefined ? { limits: options.limits } : {}),
+        ...(options.bundle !== undefined ? { bundle: options.bundle } : {}),
+        ...(options.packModules !== undefined
+            ? { packModules: options.packModules }
+            : {}),
+    };
+    return new Promise((resolve) => {
+        let settled = false;
+        let watchdogFired = false;
+        // GitHub issue #35: every value the isolate has reported so far, in
+        // arrival order. A Map (not a plain object) because a script may
+        // legitimately be named `__proto__` (docs/spec.md's name grammar) and
+        // a plain assignment of that key sets a prototype instead of storing a
+        // value; `valuesSoFar` converts through `Object.fromEntries`, which
+        // defines it as an own property.
+        const progressValues = new Map();
+        // The last ordinal accepted, so a duplicate or out-of-order message
+        // from a misbehaving isolate is dropped rather than overwriting a
+        // value that already arrived. -1 means "nothing accepted yet".
+        let lastProgressIndex = -1;
+        /**
+         * The values this run has seen so far — what a run that never gets to
+         * send its own `RunResult` (the watchdog fired, the isolate died) is
+         * settled with, so the scripts that DID finish keep the values they
+         * produced instead of the whole run coming back empty. A worker that
+         * does send a result supersedes this entirely: its own `values` is
+         * complete and authoritative.
+         */
+        function valuesSoFar() {
+            return Object.fromEntries(progressValues);
+        }
+        const worker = options.spawnIsolate({
+            entryPath: workerPath,
+            maxOldGenerationSizeMb: WORKER_MAX_OLD_GENERATION_SIZE_MB,
+        });
+        function watchdogFailure() {
+            return {
+                values: valuesSoFar(),
+                failures: [
+                    {
+                        name: '<document>',
+                        message: `run exceeded its ${options.timeoutMs}ms watchdog and was terminated`,
+                        kind: 'limit',
+                    },
+                ],
+                cacheSnapshot: options.cacheSnapshot,
+            };
+        }
+        const watchdog = setTimeout(() => {
+            watchdogFired = true;
+            // Fire-and-forget: `terminate()`'s own returned promise resolves
+            // once the thread is actually gone, but we don't need to wait on
+            // it here -- the worker's `exit` event (handled below) is what
+            // settles this run's promise, and it fires as part of the same
+            // termination sequence.
+            worker.kill();
+            // ...except where there IS no exit event to wait for. A Web Worker's
+            // `terminate()` is immediate and silent, so a host using one would
+            // otherwise hang here forever, having killed the isolate and then
+            // waited for a notification that never comes. Settling directly is
+            // correct for both kinds: a worker thread's `exit` still arrives and
+            // is a no-op against `settled`, and this run's outcome does not
+            // depend on how promptly the runtime reports the death of something
+            // already terminated.
+            settle(watchdogFailure());
+        }, options.timeoutMs);
+        // Never let this timer keep the host process/extension-host alive on
+        // its own.
+        watchdog.unref?.();
+        function settle(result) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(watchdog);
+            resolve(result);
+            // Ephemeral-per-run: tear the worker down once we have ANY outcome,
+            // including a normal successful `message`. `terminate()` on a
+            // worker that has already exited (or is already exiting) is a safe
+            // no-op, per Node's `worker_threads` documentation.
+            worker.kill();
+        }
+        worker.onMessage((message) => {
+            // GitHub issue #35: progress first, result last. A message that
+            // passes the progress guard is never treated as a result, and one
+            // that does not is the run's single result message — the same
+            // message this handler has always received.
+            if (isRunProgress(message)) {
+                if (settled)
+                    return;
+                if (message.index <= lastProgressIndex)
+                    return;
+                lastProgressIndex = message.index;
+                // The cap bounds how many DISTINCT names are held; re-reporting a
+                // name already in the map is a legitimate run (two script blocks
+                // may share a name, and the last one wins in the store too), so it
+                // is never refused.
+                if (!progressValues.has(message.name) &&
+                    progressValues.size >= MAX_PROGRESS_VALUES) {
+                    return;
+                }
+                progressValues.set(message.name, message.value);
+                try {
+                    options.onValue?.(message.name, message.value, message.index);
+                }
+                catch {
+                    // Reporting a value must never be able to fail the run — see
+                    // `SpawnRunOptions.onValue`.
+                }
+                return;
+            }
+            settle(message);
+        });
+        worker.onError((err) => {
+            settle({
+                values: valuesSoFar(),
+                failures: [
+                    {
+                        name: '<worker>',
+                        message: describeThrown(err),
+                        kind: 'script-error',
+                    },
+                ],
+                cacheSnapshot: options.cacheSnapshot,
+            });
+        });
+        worker.onExit((code) => {
+            // A `message` already having settled this run is the ordinary
+            // happy path -- `settle`'s own `terminate()` call produces exactly
+            // this `exit` event, and `settle`'s guard makes it a no-op here.
+            if (settled)
+                return;
+            if (watchdogFired) {
+                settle(watchdogFailure());
+                return;
+            }
+            // The worker exited on its own, without the watchdog and without
+            // ever posting a result -- e.g. a hostile/rigged script that calls
+            // `process.exit()` directly (Node terminates only the calling
+            // worker thread for that, not the host process, but this run still
+            // never got a proper `RunResult` out of it). Resolve, never
+            // reject -- see this function's doc comment.
+            settle({
+                values: valuesSoFar(),
+                failures: [
+                    {
+                        name: '<worker>',
+                        message: `worker exited unexpectedly (code ${String(code)}) before returning a result`,
+                        kind: 'script-error',
+                    },
+                ],
+                cacheSnapshot: options.cacheSnapshot,
+            });
+        });
+        // N-2 fix (docs/archive/PENTEST-REPORT-2026-08-23.md): `postMessage` structured-clones
+        // `job` synchronously, so an uncloneable payload (e.g. a value containing
+        // a function, or an object with a throwing `toString`) throws a
+        // `DataCloneError` right here, before any of the worker's own event
+        // handlers above have a chance to settle this promise. Left unguarded,
+        // that throw would propagate out of the executor and REJECT `spawnRun`'s
+        // promise, breaking its documented never-rejects contract. Route it
+        // through the same synthetic-failure `settle` path as every other
+        // failure mode instead, and let `settle`'s own `terminate()` clean up the
+        // worker that was already spawned (a safe no-op if the thread never
+        // finished starting).
+        try {
+            worker.send(job);
+        }
+        catch (err) {
+            settle({
+                values: {},
+                failures: [
+                    {
+                        name: '<document>',
+                        message: `run could not be started: ${describeThrown(err)}`,
+                        kind: 'script-error',
+                    },
+                ],
+                cacheSnapshot: options.cacheSnapshot,
+            });
+        }
+    });
+}

package/dist/run/run-job.d.ts

@@ -0,0 +1,130 @@
+import { type FailureKind, type RunTrigger, type StoredValue } from '@markii/runtime';
+import { type CacheEntry, type NetProvider } from '@markii/lua';
+import type { BundleFsGrant, BundleManifest } from '@markii/bundle';
+import type { PackModulesMap } from './lua-resolver.js';
+import type { PinPolicy } from './net-pinning.js';
+import type { RunProgress } from './run-progress.js';
+export type { RunProgress } from './run-progress.js';
+export { isRunProgress } from './run-progress.js';
+/**
+ * What a runtime must supply for `runJob` to work there.
+ *
+ * `createNet` receives the SAME arguments the Node provider always took,
+ * so a browser implementation cannot quietly widen the allowlist or the
+ * fetch cap: both are handed to it, and `@markii/lua` enforces its own
+ * copy of the cap independently regardless.
+ */
+export interface RunJobDeps {
+    createNet: (netAllowlist: string[], maxFetchBytes: number, netPolicy: PinPolicy) => NetProvider;
+    /** Where wasmoon should load `glue.wasm` from; `undefined` lets it use its own default resolution. */
+    wasmUri: string | undefined;
+    /**
+     * Posts one per-script progress message back to the host (GitHub issue
+     * #35). Supplied by each worker entry so BOTH isolates emit the identical
+     * message: the shape, the ordinal, and the moment it is sent are decided
+     * here, and the entry only knows how to put a message on its own channel
+     * (`parentPort.postMessage` for the Node worker thread,
+     * `self.postMessage` for the Web Worker).
+     *
+     * Optional so an entry that has not been updated simply reports nothing
+     * during a run and its final result is unchanged.
+     */
+    postProgress?: (message: RunProgress) => void;
+}
+/** The one job message this worker ever receives, posted once by `run-host.ts`. */
+export interface RunJob {
+    text: string;
+    /**
+     * How this run was triggered (GitHub issue #11). Passed straight to
+     * `runDocumentScripts`, whose `tierForTrigger` (`@markii/runtime`) is THE
+     * SECURITY GATE: `'manual'` runs at the full capability tier, while
+     * `'auto'` and `'scheduled'` are forced to the read-only tier (GET,
+     * cache and bundle reads, cache writes — never POST/PATCH/bundle-write)
+     * regardless of what the net/bundle grants allow. Absent (an older host,
+     * or `run-host.ts` omitting it) defaults to `'manual'`, preserving the
+     * pre-#11 behavior; this default is safe because only the trusted host
+     * ever sets this field — note content can never influence it.
+     */
+    trigger?: RunTrigger;
+    /** Hostnames (exact match, case-insensitive) this run's `net.*` calls may reach. */
+    netAllowlist: string[];
+    /** The persisted `cache.get` state to seed this run with (see `./script-requirements.ts`'s sibling host-side persistence). */
+    cacheSnapshot: Record<string, CacheEntry>;
+    /**
+     * Optional resource-limit overrides, forwarded verbatim to
+     * `createLuaExecutor`'s `limits`/`maxFetchBytes`. Left `undefined`, the
+     * sandbox's own defaults (`@markii/lua`'s `DEFAULT_LIMITS`/
+     * `DEFAULT_MAX_FETCH_BYTES`) apply.
+     */
+    limits?: {
+        maxFetchBytes?: number;
+        wallClockMs?: number;
+        maxInstructions?: number;
+        maxMemoryBytes?: number;
+    };
+    /**
+     * Slice 2 of the `.mkz` Run-path arc (GitHub issue #9): the bundle
+     * filesystem capability for a bundle-backed run, entirely as an
+     * in-memory snapshot — see `./bundle-run.ts`'s doc comment for what this
+     * host-built snapshot contains and why. Absent for a bare `.mk.md` run,
+     * exactly as before this field existed.
+     */
+    bundle?: {
+        /** Bundle-relative path -> bytes, built host-side by `./bundle-run.ts`'s `buildBundleSnapshot`. */
+        snapshot: Record<string, Uint8Array>;
+        /** The bundle's manifest — `@markii/bundle`'s `createScriptView` reads its `permissions.bundle` declaration to intersect against `grantedBundlePermissions`. */
+        manifest: BundleManifest;
+        /** The user-granted bundle-fs permissions for this run (already the OUTCOME of the host's own grant flow, not the manifest's raw declaration) — `createScriptView` intersects this with what the manifest declares. */
+        grantedBundlePermissions: BundleFsGrant[];
+    };
+    /**
+     * Slice 5 of the pack-loading arc (GitHub issue #3): shared Lua modules
+     * from every configured, installed pack's `scripts/` directory, pre-read
+     * on the extension host (`../packs/pack-scripts.ts`) since this worker has
+     * no filesystem access of its own. Builds this run's `PackModuleResolver`
+     * (`../packs/lua-resolver.ts`) — a pure, synchronous, in-memory lookup, no
+     * I/O inside the worker. Absent for a run with no packs configured, in
+     * which case `require "packName/..."` denies exactly as it always has
+     * (`@markii/lua`'s own "no resolver configured" capability denial).
+     */
+    packModules?: PackModulesMap;
+    /**
+     * The DNS-rebinding / private-range policy (GitHub issue #10) this run's
+     * `net.*` calls are pinned under — see `./net-pinning.ts`'s `PinPolicy`.
+     * Threaded the same way `trigger` and `packModules` are: forwarded
+     * verbatim from `SpawnRunOptions` (`./run-host.ts`) through to here, with
+     * no note content able to influence it. FAIL CLOSED: absent (an older
+     * host, or a caller that hasn't been updated) means
+     * `allowRestrictedAddresses: false` — the safe default — not "no policy
+     * at all".
+     */
+    netPolicy?: PinPolicy;
+}
+/** One failed script, in the shape the host needs to drive the grant/UI flow — never a raw thrown error. */
+export interface RunFailure {
+    /** The script's declared `name`, or `'<document>'` for a failure that happened outside any single script (e.g. the text failed to parse). */
+    name: string;
+    message: string;
+    kind: FailureKind;
+}
+/** The one result message this worker ever posts back. Every field is structured-clone-safe. */
+export interface RunResult {
+    /** `ValueStore.snapshot()` — every script's outcome, keyed by name. */
+    values: Record<string, StoredValue>;
+    failures: RunFailure[];
+    /** The mutated cache state, to be persisted by the host for the next run. */
+    cacheSnapshot: Record<string, CacheEntry>;
+    /**
+     * Present only when `RunJob.bundle` was set: the FULL, post-run contents
+     * of the bundle snapshot's `.cache/` subtree (not a diff) — the host
+     * persists this verbatim (directory form: written back into the bundle
+     * dir; zip form: extension storage keyed by bundle identity) and seeds
+     * the next run's snapshot from it. Absent for a bare `.mk.md` run.
+     */
+    cacheOut?: Record<string, Uint8Array>;
+}
+/** Runs one job to completion, never throwing — see this module's top doc comment. */
+export declare function runJob(job: RunJob, deps: RunJobDeps): Promise<RunResult>;
+/** Turns any unexpected internal failure into an ordinary result — see the top doc comment's "never an unhandled rejection" guarantee. */
+export declare function resultForInternalError(err: unknown, fallbackCacheSnapshot: Record<string, CacheEntry>): RunResult;
+export declare function isRunJob(value: unknown): value is RunJob;