@markii/host 0.0.1 → 0.17.0-next.3

package/dist/run/run-job.js

@@ -0,0 +1,279 @@
+/**
+ * The engine-neutral half of a run: everything between "a job arrived" and
+ * "here is its result", with nothing in it that binds to one JavaScript
+ * runtime.
+ *
+ * This exists because the two hosts cannot spawn the same kind of isolate
+ * (see `./isolate.ts`). The VS Code extension runs a `node:worker_threads`
+ * worker; an Obsidian plugin, living in an Electron renderer, can only run
+ * a Web Worker, where `node:http`, `node:dns`, and `Buffer` do not exist.
+ * Rather than keep two copies of the run logic in step with each other,
+ * the parts that genuinely differ are injected: how a network request is
+ * made, and where wasmoon's `glue.wasm` is found.
+ *
+ * `./worker-entry.ts` supplies the Node ones (a pinned `node:https`
+ * request, `glue.wasm` beside the bundle on disk).
+ * `./worker-entry-browser.ts` supplies the Web Worker ones (a request
+ * bridged to the host over `postMessage`, `glue.wasm` as a blob URL).
+ * Everything below runs identically under both, which is the point: the
+ * sandbox, the tier gate, the marshaling limits, and the failure
+ * classification cannot drift between hosts, because there is only one of
+ * each.
+ */
+import { extractScripts, parse } from '@markii/core';
+import { buildDirectiveListing, createValueStore, runDocumentScripts, } from '@markii/runtime';
+import { createLuaExecutor, DEFAULT_MAX_FETCH_BYTES, } from '@markii/lua';
+import { createScriptView } from '@markii/bundle';
+import { cacheFilesFrom } from './bundle-run.js';
+import { createSnapshotStorage } from './snapshot-storage.js';
+import { createPackModuleResolver } from './lua-resolver.js';
+export { isRunProgress } from './run-progress.js';
+/**
+ * A policy denial this module's `NetProvider` raises (an ungranted host, a
+ * redirect off the allowlist, too many redirects, an over-size response, a
+ * credential-bearing redirect target, a pinning refusal from
+ * `./net-pinning.ts`). This is NOT the same kind of denial as
+ * `@markii/lua`'s own `netGrants` check inside `buildCapabilities` (which
+ * records on its own out-of-band `CapabilityDenials` handle): a denial
+ * detected HERE happens inside this provider's own `get`/`post`/`patch`, one
+ * level below that check. `netProviderDenial` (`@markii/lua`) brands the
+ * thrown `Error` with a JS `Symbol`; `@markii/lua` checks that brand on the
+ * JS side of the provider call, BEFORE the error crosses into Lua, records
+ * the denial on the same non-spoofable handle its own grant check uses, and
+ * re-throws a sanitized capability error. So a provider policy refusal comes
+ * back as `'capability-denied'` with no help from `runJob`, and no
+ * classification signal ever rides in a Lua-visible string.
+ *
+ * P2-c fix (docs/archive/PENTEST-REPORT-2026-08-23.md §9.3): the previous approach put a
+ * per-run random tag INSIDE the thrown message so `runJob` could reclassify
+ * the failure by scanning that message. But the message crosses back into
+ * Lua, where a script's own `pcall`/`tostring` reads the tag and then forges
+ * it into `error(tag .. ": ...")` to relabel an unrelated failure as
+ * capability-denied. The brand lives on the JS `Error` object and is consumed
+ * before the Lua boundary, so there is nothing for a script to observe or
+ * forge, and `runJob` no longer post-processes failure kinds at all.
+ */
+/**
+ * `hostname` with IPv6 brackets stripped, for the `hostname` option
+ * `http.request`/`https.request` take: Node re-adds the brackets itself
+ * (for the `Host` header and TLS SNI) whenever the raw address contains a
+ * `:`, so passing an already-bracketed literal through would double them.
+ */
+/** A `CacheProvider` over a plain snapshot object, with the writes it accumulates readable back out. */
+function createSnapshotCacheProvider(snapshot) {
+    const store = { ...snapshot };
+    return {
+        provider: {
+            get: (key) => Promise.resolve(store[key]),
+            set: (key, entry) => {
+                store[key] = entry;
+                return Promise.resolve();
+            },
+        },
+        snapshot: () => ({ ...store }),
+    };
+}
+function describeThrown(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Runs one job to completion, never throwing — see this module's top doc comment. */
+export async function runJob(job, deps) {
+    const cache = createSnapshotCacheProvider(job.cacheSnapshot ?? {});
+    const netAllowlist = job.netAllowlist ?? [];
+    // The SAME cap governs this worker's own bounded body read
+    // (`issueRequest`, B-2) and `@markii/lua`'s own `maxFetchBytes` check —
+    // computed once, here, rather than letting each side default
+    // independently, so the two can never quietly disagree.
+    const maxFetchBytes = job.limits?.maxFetchBytes ?? DEFAULT_MAX_FETCH_BYTES;
+    // GitHub issue #10, fail closed: an absent `netPolicy` (an older host, or
+    // a caller that hasn't been updated) means restricted addresses are NOT
+    // allowed — the same posture `@markii/lua`'s own defaults take, never the
+    // opposite.
+    const netPolicy = job.netPolicy ?? {
+        allowRestrictedAddresses: false,
+    };
+    const net = deps.createNet(netAllowlist, maxFetchBytes, netPolicy);
+    const tree = parse(job.text);
+    const scripts = extractScripts(tree);
+    // GitHub issue #33: the note's own directives, as capped plain data for
+    // the `doc` table a script sees. Built from the tree ALREADY parsed on
+    // the line above, so a run still parses the note exactly once, and built
+    // HERE rather than in either host so both isolates (the Node worker and
+    // the Web Worker) get a listing produced by one piece of code.
+    const directives = buildDirectiveListing(tree);
+    // Slice 2 of the .mkz Run-path arc (GitHub issue #9): a bundle-backed run
+    // gets a snapshot-backed ScriptView (never a live zip/disk handle — see
+    // `./snapshot-storage.ts`), scoped to exactly the intersection
+    // `createScriptView` (@markii/bundle) computes between the manifest's
+    // declared `permissions.bundle` and what the host's grant flow actually
+    // granted.
+    const bundleStorage = job.bundle
+        ? createSnapshotStorage(job.bundle.snapshot)
+        : undefined;
+    const bundleView = bundleStorage && job.bundle
+        ? createScriptView(bundleStorage, job.bundle.manifest, {
+            bundle: job.bundle.grantedBundlePermissions,
+        })
+        : undefined;
+    const executor = createLuaExecutor({
+        net,
+        // One allowlist governs GET/POST/PATCH alike (B-6, docs/security.md:
+        // "the per-host allowlist is the real boundary") — the grant prompt's
+        // wording ("can send data to <host>") already promises exactly this,
+        // so POST/PATCH must be wired to the same hosts GET is, not silently
+        // disabled.
+        netGrants: { get: netAllowlist, post: netAllowlist },
+        cache: cache.provider,
+        bundle: bundleView,
+        ...(job.packModules
+            ? { packModuleResolver: createPackModuleResolver(job.packModules) }
+            : {}),
+        maxFetchBytes,
+        limits: {
+            ...(job.limits?.wallClockMs !== undefined
+                ? { wallClockMs: job.limits.wallClockMs }
+                : {}),
+            ...(job.limits?.maxInstructions !== undefined
+                ? { maxInstructions: job.limits.maxInstructions }
+                : {}),
+            ...(job.limits?.maxMemoryBytes !== undefined
+                ? { maxMemoryBytes: job.limits.maxMemoryBytes }
+                : {}),
+        },
+        wasmUri: deps.wasmUri,
+    });
+    const store = createValueStore();
+    // GitHub issue #35: the ordinal is assigned HERE rather than by either
+    // worker entry, so the two hosts cannot number their runs differently.
+    let progressIndex = 0;
+    const postProgress = deps.postProgress;
+    const summary = await runDocumentScripts({
+        scripts,
+        executor,
+        // Announced per script, in document order, as each value is stored —
+        // `runDocumentScripts` swallows anything this throws, so a failing
+        // channel costs the run nothing.
+        ...(postProgress
+            ? {
+                onValue: (name, value) => {
+                    postProgress({
+                        kind: 'markii:run-progress',
+                        index: progressIndex++,
+                        name,
+                        value,
+                    });
+                },
+            }
+            : {}),
+        // GitHub issue #11: the trigger the host sent (default `'manual'`) — its
+        // mapping to a capability tier (`tierForTrigger`) is the sandbox's own
+        // read-only gate for auto/scheduled runs. Never note-influenced.
+        trigger: job.trigger ?? 'manual',
+        store,
+        // Read-only and tier-free: the listing is the note's own content, so
+        // it is handed to an auto/scheduled run exactly as to a manual one.
+        doc: { directives },
+        // `src=scripts/foo.lua` resolution (design point 4): the referenced
+        // file's source lives in the snapshot under its own bundle-relative
+        // path (`ScriptBlock.src` already carries the full "scripts/..." path
+        // — see @markii/core's `scripts.ts`), read through the SAME jailed
+        // snapshot storage a script's own `bundle.read` would use. A bare
+        // `.mk.md` run (no `job.bundle`) never sets `loadSource` at all, so a
+        // `src=` block there is reported as the pre-existing "no loadSource
+        // provided" error, unchanged.
+        ...(bundleStorage
+            ? {
+                loadSource: async (src) => {
+                    const bytes = await bundleStorage.read(src);
+                    if (bytes === undefined) {
+                        throw new Error(`bundle script "${src}" was not found`);
+                    }
+                    return new TextDecoder().decode(bytes);
+                },
+            }
+            : {}),
+    });
+    // A net-provider policy denial already arrives here classified as
+    // 'capability-denied': `@markii/lua` records it on its non-spoofable
+    // `CapabilityDenials` handle when the branded `netProviderDenial` crosses
+    // its provider-call boundary (see the `NetProvider` doc comment above,
+    // P2-c). So `runJob` no longer post-processes any failure kind — it reads
+    // `entry.failureKind` verbatim, and the value store already carries the
+    // same kind for the corresponding `StoredValue`.
+    const failures = summary.results
+        .filter((entry) => entry.status === 'error')
+        .map((entry) => ({
+        name: entry.name,
+        message: entry.error ?? 'script failed',
+        kind: entry.failureKind ?? 'script-error',
+    }));
+    // Copied entry-by-entry onto a fresh plain object rather than returned as
+    // `store.snapshot()` directly: this preserves the exact N-11 pinned shape
+    // (a script literally named `__proto__` assigns through and leaves no own
+    // key), which a direct structured-clone of the store's own object would
+    // not. The values are otherwise passed through verbatim — failure kinds
+    // arrive already correct (see the failures comment above).
+    const values = {};
+    for (const [name, entry] of Object.entries(store.snapshot())) {
+        values[name] = entry;
+    }
+    return {
+        values,
+        failures,
+        cacheSnapshot: cache.snapshot(),
+        ...(bundleStorage
+            ? { cacheOut: cacheFilesFrom(bundleStorage.currentFiles()) }
+            : {}),
+    };
+}
+/** Turns any unexpected internal failure into an ordinary result — see the top doc comment's "never an unhandled rejection" guarantee. */
+export function resultForInternalError(err, fallbackCacheSnapshot) {
+    return {
+        values: {},
+        failures: [
+            {
+                name: '<document>',
+                message: describeThrown(err),
+                kind: 'script-error',
+            },
+        ],
+        cacheSnapshot: fallbackCacheSnapshot,
+    };
+}
+const RUN_TRIGGERS = new Set([
+    'manual',
+    'auto',
+    'scheduled',
+]);
+export function isRunJob(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const job = value;
+    // `trigger` is optional, but a PRESENT one must be a known trigger — a
+    // malformed job is rejected outright (fail-closed) rather than silently
+    // coerced, so a bad `trigger` can never quietly fall through to the
+    // full-capability `'manual'` default. Only the trusted host sets this, but
+    // validating it keeps the tier gate's input honest regardless.
+    if (Object.prototype.hasOwnProperty.call(job, 'trigger') &&
+        job.trigger !== undefined &&
+        (typeof job.trigger !== 'string' || !RUN_TRIGGERS.has(job.trigger))) {
+        return false;
+    }
+    // Same fail-closed shape check for `netPolicy` (GitHub issue #10): a
+    // PRESENT but malformed policy is rejected outright rather than silently
+    // falling through to the safe default, keeping the pinning gate's input
+    // as honest as the tier gate's above.
+    if (Object.prototype.hasOwnProperty.call(job, 'netPolicy') &&
+        job.netPolicy !== undefined &&
+        (typeof job.netPolicy !== 'object' ||
+            job.netPolicy === null ||
+            typeof job.netPolicy
+                .allowRestrictedAddresses !== 'boolean')) {
+        return false;
+    }
+    return (typeof job.text === 'string' &&
+        Array.isArray(job.netAllowlist) &&
+        job.netAllowlist.every((h) => typeof h === 'string') &&
+        typeof job.cacheSnapshot === 'object' &&
+        job.cacheSnapshot !== null);
+}

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

@@ -0,0 +1,55 @@
+/**
+ * The per-script progress message (GitHub issue #35): its shape and its
+ * hostile-shape guard, and nothing else.
+ *
+ * WHY IT IS ITS OWN MODULE. The message is BUILT inside the isolate
+ * (`./run-job.ts`, so both worker entries emit an identical one) and READ
+ * on the host (`./run-host.ts`, which tells progress from the run's single
+ * result message). `./run-job.ts` imports `@markii/lua`, and that import
+ * pulls a whole WebAssembly Lua engine in behind it — a host bundle must
+ * never carry one, least of all the Obsidian plugin's, which runs in an
+ * Electron renderer and delegates every Lua execution to a Web Worker. So
+ * the protocol lives apart from the code that speaks it, exactly as
+ * `./net-bridge.ts` does for the net bridge.
+ *
+ * Nothing here imports anything but a type.
+ */
+import type { StoredValue } from '@markii/runtime';
+/**
+ * Worker -> host, one per script, sent the moment that script's value was
+ * written to the run's store and always BEFORE the single `RunResult`
+ * message that settles the run. Scripts run sequentially in one isolate,
+ * so the last script's value can be many seconds younger than the first's;
+ * without this the preview shows every value as stale until the whole
+ * batch is done.
+ *
+ * `index` is this message's ordinal within the run, counted from 0 in
+ * document order. The host uses it to drop a duplicate or out-of-order
+ * message rather than trusting arrival order alone — the channel preserves
+ * order, but the isolate runs untrusted script content, so nothing coming
+ * out of it is taken on trust.
+ *
+ * Every field is structured-clone-safe, exactly like `RunResult`: `value`
+ * is the same already-marshaled `StoredValue` that ends up in
+ * `RunResult.values`.
+ */
+export interface RunProgress {
+    kind: 'markii:run-progress';
+    index: number;
+    name: string;
+    value: StoredValue;
+}
+/**
+ * Hostile-shape guard for a `RunProgress` message, applied by
+ * `./run-host.ts` to every message an isolate sends. The isolate runs
+ * untrusted script content, so a message claiming to be progress is
+ * validated the same way `./run-job.ts`'s `isRunJob` validates a job:
+ * every field checked, own properties only, no coercion, and `value`
+ * reduced to a plain object carrying one of `@markii/runtime`'s four
+ * closed statuses.
+ *
+ * A message that fails this is NOT progress — the caller then treats it as
+ * the run's final result, where `RunResult`'s own consumers already handle
+ * a malformed shape.
+ */
+export declare function isRunProgress(value: unknown): value is RunProgress;

package/dist/run/run-progress.js

@@ -0,0 +1,42 @@
+/**
+ * Hostile-shape guard for a `RunProgress` message, applied by
+ * `./run-host.ts` to every message an isolate sends. The isolate runs
+ * untrusted script content, so a message claiming to be progress is
+ * validated the same way `./run-job.ts`'s `isRunJob` validates a job:
+ * every field checked, own properties only, no coercion, and `value`
+ * reduced to a plain object carrying one of `@markii/runtime`'s four
+ * closed statuses.
+ *
+ * A message that fails this is NOT progress — the caller then treats it as
+ * the run's final result, where `RunResult`'s own consumers already handle
+ * a malformed shape.
+ */
+export function isRunProgress(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const message = value;
+    // Own properties only, the same discipline `apps/vscode/src/protocol.ts`
+    // applies to every wire message: an object that merely INHERITS `kind`
+    // from its prototype is not a progress message.
+    const own = (key) => Object.prototype.hasOwnProperty.call(message, key);
+    if (!own('kind') || message.kind !== 'markii:run-progress')
+        return false;
+    if (!own('index') || !own('name') || !own('value'))
+        return false;
+    if (typeof message.index !== 'number' ||
+        !Number.isInteger(message.index) ||
+        message.index < 0) {
+        return false;
+    }
+    if (typeof message.name !== 'string')
+        return false;
+    const stored = message.value;
+    if (typeof stored !== 'object' || stored === null || Array.isArray(stored)) {
+        return false;
+    }
+    const status = stored.status;
+    return (status === 'fresh' ||
+        status === 'stale' ||
+        status === 'error' ||
+        status === 'missing');
+}

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

@@ -0,0 +1,44 @@
+/**
+ * ITEM 3 (AGENTS.md "clean is not silent"): a `'scheduled'`/`'auto'` run
+ * that produces identical values is otherwise indistinguishable from one
+ * that never happened — no value changed, so nothing in the rendered note
+ * moves. This module records the last run's OUTCOME (when it ran, whether
+ * it succeeded, and why not if it failed) per document, independent of
+ * whatever values it produced, and reads it back for `preview-panel.ts`'s
+ * `postUpdate` to surface as a quiet marker — the same "last-known state,
+ * persisted, rehydrated on reopen" design `./stale-values.ts` and
+ * `./run-flow.ts`'s value persistence already use.
+ *
+ * `vscode`-free: takes a `GrantMemento`-shaped store (the same minimal
+ * `get`/`update` interface `./grant-flow.ts` already defines, which a real
+ * `vscode.Memento` and a plain in-memory fake both satisfy), so this stays
+ * plain TypeScript vitest can run directly.
+ */
+import type { RunTrigger } from '@markii/runtime';
+import type { GrantMemento, Thenable } from './grant-flow.js';
+/**
+ * One run's recorded outcome. `reason` is present only when `ok` is
+ * `false`, and is a short, human phrase (never a raw stack or the full
+ * caught error) — the same "quiet marker + tooltip, never an error dump"
+ * posture every other failure surface in this codebase follows.
+ */
+export interface RunTrace {
+    readonly trigger: RunTrigger;
+    /** Epoch milliseconds this run completed (or failed) at. */
+    readonly ranAt: number;
+    readonly ok: boolean;
+    readonly reason?: string;
+}
+/** The `workspaceState`/Memento key a document's last-run trace lives under, mirroring `./run-flow.ts`'s `valuesStorageKeyFor`/`cacheStorageKeyFor` naming. */
+export declare function lastRunStorageKeyFor(documentKey: string): string;
+/**
+ * A plausible `RunTrace` shape read back from storage — never trusted
+ * further than this, matching `./run-flow.ts`'s `isStoredValueRecord`'s own
+ * fail-safe posture: a corrupt or foreign persisted value degrades to "no
+ * trace", not a thrown error.
+ */
+export declare function isRunTrace(value: unknown): value is RunTrace;
+/** Reads a document's persisted last-run trace, or `undefined` when there is none / it is unusable. Never throws. */
+export declare function readLastRunTrace(memento: GrantMemento, documentKey: string): RunTrace | undefined;
+/** Persists `trace` as `documentKey`'s last-run outcome, superseding whatever was there before. */
+export declare function writeLastRunTrace(memento: GrantMemento, documentKey: string, trace: RunTrace): Thenable<void>;

package/dist/run/run-trace.js

@@ -0,0 +1,36 @@
+/** The `workspaceState`/Memento key a document's last-run trace lives under, mirroring `./run-flow.ts`'s `valuesStorageKeyFor`/`cacheStorageKeyFor` naming. */
+export function lastRunStorageKeyFor(documentKey) {
+    return `markii.lastRun:${documentKey}`;
+}
+function isValidTrigger(value) {
+    return value === 'manual' || value === 'auto' || value === 'scheduled';
+}
+/**
+ * A plausible `RunTrace` shape read back from storage — never trusted
+ * further than this, matching `./run-flow.ts`'s `isStoredValueRecord`'s own
+ * fail-safe posture: a corrupt or foreign persisted value degrades to "no
+ * trace", not a thrown error.
+ */
+export function isRunTrace(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (!isValidTrigger(v.trigger))
+        return false;
+    if (typeof v.ranAt !== 'number' || !Number.isFinite(v.ranAt))
+        return false;
+    if (typeof v.ok !== 'boolean')
+        return false;
+    if (v.reason !== undefined && typeof v.reason !== 'string')
+        return false;
+    return true;
+}
+/** Reads a document's persisted last-run trace, or `undefined` when there is none / it is unusable. Never throws. */
+export function readLastRunTrace(memento, documentKey) {
+    const raw = memento.get(lastRunStorageKeyFor(documentKey));
+    return isRunTrace(raw) ? raw : undefined;
+}
+/** Persists `trace` as `documentKey`'s last-run outcome, superseding whatever was there before. */
+export function writeLastRunTrace(memento, documentKey, trace) {
+    return memento.update(lastRunStorageKeyFor(documentKey), trace);
+}

package/dist/run/script-requirements.d.ts

@@ -0,0 +1,98 @@
+import { type ScriptBlock } from '@markii/core';
+import type { GrantClosureScript } from '@markii/runtime';
+/** One document's static run requirements. */
+export interface RunRequirements {
+    /** Every script block found, in document order — `@markii/core`'s `extractScripts` result, unmodified. */
+    scripts: ScriptBlock[];
+    /**
+     * Hostnames this run's scripts are statically known to reach via
+     * `net.*`, deduplicated, in first-seen (document) order. Does NOT
+     * include hosts that could only be discovered by actually running the
+     * script (see `hasUnknownHosts`).
+     */
+    hosts: string[];
+    /**
+     * `true` when at least one `net.fetch_json`/`net.post`/`net.patch` call
+     * site's URL argument could not be resolved to a literal (a
+     * concatenation, a variable, any non-literal expression), OR when any
+     * script block is a `src=` reference (its actual Lua source lives in a
+     * bundle file this function never reads, so its `net.*` usage — if any —
+     * is entirely unknown). The caller should read this as "prompt for
+     * network access more broadly" rather than trusting `hosts` alone to be
+     * the complete set.
+     */
+    hasUnknownHosts: boolean;
+    /**
+     * `scripts` reshaped into `@markii/runtime`'s `GrantClosureScript` — the
+     * exact per-script record `computeGrantKey`'s `GrantClosure.scripts`
+     * field expects (`{ name, lang, src, code }`). `computeGrantKey` itself
+     * sorts records by their own encoded bytes before hashing, so array
+     * order here does not affect the resulting key — this is already in
+     * document order (from `extractScripts`), which is what makes repeated
+     * extraction over the same text byte-identical, satisfying the "stable
+     * order" requirement without this module needing to reimplement any of
+     * `computeGrantKey`'s own sorting.
+     */
+    grantScripts: GrantClosureScript[];
+}
+/**
+ * Bare, already-lowercased hostnames every script block in `scripts`
+ * declares via its own `permissions` fence attribute
+ * (`@markii/core`'s `ScriptBlock.permissions`), deduplicated, in
+ * first-seen (document, then per-script list) order. Mirrors
+ * `./bundle-run.ts`'s `manifestNetHosts` for the bundle-manifest
+ * equivalent: this is DECLARED INTENT only, exactly like a manifest's
+ * `permissions.net` — `scanRunRequirementHosts` above stays the ONLY
+ * source of the hostnames a run is actually prompted for. A caller
+ * compares this against the scanned set with
+ * `./bundle-run.ts`'s `netDeclarationDiagnostics` (the same
+ * declared-vs-scanned diff a bundle manifest already gets), and may show
+ * it next to the scanned hosts in a grant prompt as "declares: ...".
+ */
+export declare function scriptDeclaredHosts(scripts: readonly ScriptBlock[]): string[];
+/**
+ * Parses `text` and returns its script blocks, in both the raw
+ * `@markii/core` `ScriptBlock` shape and the `GrantClosureScript` shape
+ * `computeGrantKey` hashes. Split out from `extractRunRequirements` (below)
+ * so a caller that needs to resolve `src=` script content BEFORE scanning
+ * for hosts — a bundle run, which must read the referenced file out of its
+ * snapshot first — can do so without parsing the document twice.
+ */
+export declare function extractScriptBlocks(text: string): {
+    scripts: ScriptBlock[];
+    grantScripts: GrantClosureScript[];
+};
+/**
+ * Resolves a `src=` block's actual Lua source, when the caller has one —
+ * for a bundle-backed run, this is the file's content out of the run's
+ * snapshot (`./bundle-run.ts`'s `bundleModulesFromSnapshot`). Returning
+ * `undefined` for a block (path missing from the snapshot, or a plain
+ * `.mk.md` document with no bundle to resolve from at all) leaves that
+ * block's hosts unknown, exactly as before this seam existed.
+ */
+export type ResolveScriptSource = (block: ScriptBlock) => string | undefined;
+/**
+ * Scans `scripts` for statically-resolvable `net.*` hosts — an INLINE
+ * block's own `code`, or (when `resolveScriptSource` is given and resolves
+ * it) a `src=` block's referenced source. A `src=` block with no resolution
+ * available folds into `hasUnknownHosts`, same as this module has always
+ * done for a bare `.mk.md` document's `src=` references (their source
+ * genuinely isn't in `text` at all).
+ */
+export declare function scanRunRequirementHosts(scripts: readonly ScriptBlock[], resolveScriptSource?: ResolveScriptSource): {
+    hosts: string[];
+    hasUnknownHosts: boolean;
+};
+/**
+ * Computes `RunRequirements` for `text` — parses it with `@markii/core`'s
+ * `parse`, pulls its script blocks with `extractScripts`, and scans each
+ * INLINE block's own source for statically-resolvable `net.*` hosts. Pure:
+ * no I/O, no `vscode`, safe to call on every keystroke if a future slice
+ * wants a live preview of what a run would ask for.
+ *
+ * `resolveScriptSource`, when given, lets a `src=` block's hosts be
+ * resolved too (a bundle run passes one backed by its snapshot); omitted,
+ * every `src=` block folds into `hasUnknownHosts` exactly as before this
+ * option existed.
+ */
+export declare function extractRunRequirements(text: string, resolveScriptSource?: ResolveScriptSource): RunRequirements;