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

package/dist/run/node-isolate.js

@@ -0,0 +1,117 @@
+/**
+ * The Node half of the Run path's isolate seam: a `node:worker_threads`
+ * worker, plus the dev/Vitest worker-entry fallback. Split out of
+ * `./run-host.ts` so the watchdog, the exactly-once settlement and the
+ * never-rejects contract stay in a module with no `node:*` import and run
+ * unchanged for every host kind. Reached only through `@markii/host/node`.
+ */
+import { Worker } from 'node:worker_threads';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { spawnRun } from './run-host.js';
+/** `execArgv` needed to run a `.ts` worker entry directly (dev/Vitest only) — see `./worker-entry.ts`'s doc comment on why a plain `node` `.ts` import can't resolve this repo's `@markii/*` bare specifiers or its `./foo.js` -> `./foo.ts` import convention on its own. `--require tsx/cjs` (rather than `tsx/esm`) is deliberate: empirically, the ESM loader hook deadlocks Node's CJS/ESM interop translator for a worker thread requiring `.js`-suffixed relative imports that resolve to `.ts` files (this repo's convention throughout `@markii/*`), while the CJS `require` hook has no such issue. */
+const TSX_DEV_EXEC_ARGV = ['--require', 'tsx/cjs'];
+/**
+ * The ONLY fallback this shared package supplies for an unset `workerPath`:
+ * the sibling `worker-entry.ts`, run straight from source via `tsx`
+ * (`TSX_DEV_EXEC_ARGV`, above). That is correct for this package's own
+ * dev/Vitest runs — `__dirname` at that point is this real source
+ * directory — but it says nothing about where a packaged host's bundled
+ * worker lives, because this package does not know that host's `dist/`
+ * layout. A packaged host (e.g. `apps/vscode`) MUST resolve its own bundled
+ * worker path itself and pass it as `SpawnRunOptions.workerPath`; see
+ * `apps/vscode/src/worker-path.ts` for that host's resolution and
+ * `apps/vscode/esbuild.config.mjs`'s worker build for where it bundles to.
+ */
+export function defaultWorkerPath() {
+    // The built package is ESM, where `__dirname` does not exist: a packaged
+    // host always passes its own bundled worker, so say so instead of
+    // throwing a ReferenceError.
+    const devSource = typeof __dirname === 'undefined'
+        ? undefined
+        : path.join(__dirname, 'worker-entry.ts');
+    if (devSource !== undefined && existsSync(devSource))
+        return devSource;
+    throw new Error('spawnRun: could not resolve the worker entry file (looked for ' +
+        `${devSource ?? 'worker-entry.ts beside the package source'}) — pass workerPath explicitly`);
+}
+function execArgvFor(workerPath) {
+    return workerPath.endsWith('.ts') ? TSX_DEV_EXEC_ARGV : undefined;
+}
+/**
+ * Dev/Vitest only: point `tsx` at the repo's `tsconfig.dev.json` so a
+ * `.ts` worker entry resolves `@markii/*` to each package's SOURCE.
+ *
+ * Without this the worker is a plain Node resolution: a bare `@markii/lua`
+ * goes through `node_modules` to that package's `exports`, which name the
+ * built `dist/`. `npm run build` only type-checks (`tsc --noEmit`); the
+ * emitting script is `build:dist`, which runs at release. So `dist/` is
+ * whatever a past release left behind, and a real-isolate probe would
+ * silently exercise that stale code instead of the source it is written to
+ * test. A capability added since the last `build:dist` simply would not
+ * exist inside the worker.
+ *
+ * Gated on a `.ts` entry, the same signal `execArgvFor` already uses for
+ * the tsx hook, so a packaged host passing its own bundled `.js` worker is
+ * never touched by this.
+ */
+function devTsconfigEnv(entryPath) {
+    if (!entryPath.endsWith('.ts') || typeof __dirname === 'undefined') {
+        return undefined;
+    }
+    const tsconfig = path.resolve(__dirname, '../../../..', 'tsconfig.dev.json');
+    if (!existsSync(tsconfig))
+        return undefined;
+    return { env: { ...process.env, TSX_TSCONFIG_PATH: tsconfig } };
+}
+/**
+ * The default isolate: a `node:worker_threads` worker, which is what every
+ * Node host (the VS Code extension host, this package's own tests) uses. It
+ * is the only kind that accepts `resourceLimits`, so it is also the only
+ * kind whose V8 heap is bounded — see `./isolate.ts` for why a host might
+ * still have to supply the other one.
+ */
+export const workerThreadIsolate = (options) => {
+    const execArgv = options.execArgv ?? execArgvFor(options.entryPath);
+    const worker = new Worker(options.entryPath, {
+        ...(execArgv ? { execArgv } : {}),
+        ...(devTsconfigEnv(options.entryPath) ?? {}),
+        resourceLimits: {
+            maxOldGenerationSizeMb: options.maxOldGenerationSizeMb,
+        },
+    });
+    return {
+        send: (job) => {
+            worker.postMessage(job);
+        },
+        kill: () => {
+            void worker.terminate();
+        },
+        onMessage: (listener) => {
+            // `on`, not `once`: a run now sends one progress message per script
+            // (GitHub issue #35) ahead of its single result message, and
+            // `spawnRun` is what tells the two apart. Messages arriving after
+            // the run settles are harmless — `settled` guards every path — and
+            // the worker is terminated on settle anyway.
+            worker.on('message', listener);
+        },
+        onError: (listener) => {
+            worker.once('error', listener);
+        },
+        onExit: (listener) => {
+            worker.once('exit', listener);
+        },
+    };
+};
+/**
+ * `spawnRun` with the Node defaults filled in: the worker-thread isolate and
+ * the dev/Vitest worker entry. For this package's own tests and any Node
+ * caller that wants them; a packaged host passes its own `workerPath`.
+ */
+export function spawnRunInThread(options) {
+    return spawnRun({
+        ...options,
+        workerPath: options.workerPath ?? defaultWorkerPath(),
+        spawnIsolate: options.spawnIsolate ?? workerThreadIsolate,
+    });
+}

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

@@ -0,0 +1,187 @@
+import type { GrantMemento, PromptHost, PromptManyHosts, PromptUnknownHosts } from './grant-flow.js';
+import type { RunResult, SpawnRunRequest } from './run-host.js';
+import type { ValuesFailure } from '../values-failure.js';
+import type { RunTrigger, StoredValue } from '@markii/runtime';
+import type { BundleManifest } from '@markii/bundle';
+import type { PackModulesMap } from './lua-resolver.js';
+/** A `CacheEntry`-keyed snapshot, structurally — this module never imports `@markii/lua` just for the type; it only ever passes the value through. */
+export type CacheSnapshot = Record<string, unknown>;
+/**
+ * A sane upper bound on a persisted cache snapshot: real cached `net.*`
+ * responses are small JSON payloads, so the cap exists to guarantee a
+ * runaway/adversarial script can never grow `workspaceState` without
+ * bound. A snapshot over this size is DROPPED, not truncated — a partial
+ * cache would silently look valid while missing entries a script assumed
+ * were still there, which is worse than starting the next run with none
+ * at all.
+ */
+export declare const MAX_CACHE_SNAPSHOT_BYTES = 1000000;
+/** The single `workspaceState`/Memento key a document's cache snapshot lives under. */
+export declare function cacheStorageKeyFor(documentKey: string): string;
+/**
+ * The `workspaceState`/Memento key a document's LAST-KNOWN values live under
+ * (GitHub issue #11, gap 1). Separate from the cache snapshot
+ * (`cacheStorageKeyFor`): the cache is the sandbox's own `cache.get` state,
+ * keyed and TTL'd inside Lua; THIS is the rendered value store
+ * (`ValueStore.snapshot()`), the numbers a data-bound component actually
+ * showed. Persisting it is what lets a reopened monitoring note render its
+ * last figures instantly and offline, marked stale, before (or without) any
+ * re-run — exactly the "opening a note ... showing its last data marked as
+ * stale" behavior docs/scripting.md and docs/spec.md require.
+ */
+export declare function valuesStorageKeyFor(documentKey: string): string;
+/** Same cap and drop-not-truncate posture as `MAX_CACHE_SNAPSHOT_BYTES` — a runaway value store never grows `workspaceState` without bound, and a too-large snapshot is dropped whole (a partial value store would silently omit names a note binds). */
+export declare const MAX_VALUES_SNAPSHOT_BYTES = 1000000;
+/**
+ * Reads a document's persisted last-known value store, or `{}` when there is
+ * none / it is unusable. Never throws, never trusts the stored shape past
+ * "plain object" — see `isStoredValueRecord`.
+ */
+export declare function readPersistedValues(memento: GrantMemento, documentKey: string): Record<string, StoredValue>;
+/**
+ * Merges a completed run's value store onto the previously-persisted one,
+ * keeping the LAST-KNOWN-GOOD value for any name whose fresh run FAILED
+ * (GitHub issue #11). A scheduled/auto run that hits a transient failure
+ * (offline, an API hiccup, an ungranted host under the read-only tier) must
+ * not wipe the good numbers a monitoring note was already showing — mirroring
+ * the same "the cache only ever remembers good data" guarantee
+ * docs/scripting.md gives `cache.get`. For each name in the new run: a
+ * non-error outcome always wins; an error outcome is kept ONLY if there is no
+ * prior good value to fall back to (so the error surfaces on a note that
+ * never succeeded), otherwise the prior value is retained and marked stale.
+ * Names present only in the prior store (a script the note no longer has) are
+ * dropped — the note's current scripts define the namespace.
+ */
+export declare function mergePersistedValues(previous: Record<string, StoredValue>, next: Record<string, StoredValue>): Record<string, StoredValue>;
+/** A plausible cache-snapshot shape read back from storage — never trusts it further than "is this a plain object at all" (an old/foreign/corrupt value degrades to "no cache", matching this whole module's fail-safe posture). */
+export declare function isCacheSnapshotShape(value: unknown): value is CacheSnapshot;
+/**
+ * The JSON text for `snapshot`, or `undefined` when it must be dropped
+ * instead of persisted: either it isn't serializable at all (a value
+ * `JSON.stringify` cannot handle), or its serialized size exceeds
+ * `MAX_CACHE_SNAPSHOT_BYTES`. Callers write `undefined` back to storage in
+ * that case — see `MAX_CACHE_SNAPSHOT_BYTES`'s doc comment on why a partial
+ * write is never attempted.
+ */
+export declare function serializeCacheSnapshotIfSmallEnough(snapshot: CacheSnapshot): string | undefined;
+export interface RunOnceOptions {
+    /** Stable identity for the note this run belongs to — `vscode.Uri.toString()` of the document, in the real adapter. Shared with `./grant-flow.ts`'s `documentKey`. */
+    documentKey: string;
+    text: string;
+    /**
+     * How this run was triggered (GitHub issue #11). `'manual'` (the default
+     * when omitted) is the only trigger that runs the INTERACTIVE grant flow
+     * (`runGrantFlow`) — prompting on a miss and persisting the answer — and
+     * the only one the worker maps to the full `'manual'` capability tier.
+     * `'auto'` (run-on-open) and `'scheduled'` (interval) both resolve grants
+     * NON-INTERACTIVELY (`resolveStoredGrant`): they reuse a grant the user
+     * already made by hand, never prompt, never persist, and the worker runs
+     * them at the read-only tier (`@markii/runtime`'s `tierForTrigger`). This
+     * is the run-path half of the "effects always cost a click" rule
+     * (docs/scripting.md); the tier gate in the worker is the other half.
+     */
+    trigger?: RunTrigger;
+    /**
+     * The DNS-rebinding / private-range policy (GitHub issue #10), forwarded
+     * verbatim to `spawnRun`'s `netPolicy` — see `./net-pinning.ts`'s
+     * `PinPolicy`. Omitted defaults to the fail-closed posture the worker
+     * itself applies (`allowRestrictedAddresses: false`); this is the
+     * deployment-level opt-in `markii.allowPrivateNetworkAddresses` maps to
+     * (`preview-panel.ts`), never something a note can set for itself.
+     */
+    netPolicy?: SpawnRunRequest['netPolicy'];
+    memento: GrantMemento;
+    promptHost: PromptHost;
+    promptUnknownHosts: PromptUnknownHosts;
+    /** PROMPT-STORM guard's consolidated gate — see `./grant-flow.ts`'s `MAX_HOST_PROMPTS`. */
+    promptManyHosts: PromptManyHosts;
+    /** Injected so this function is testable with a fake worker runner — the real adapter passes `./run-host.ts`'s `spawnRun`. */
+    spawnRun: (options: SpawnRunRequest) => Promise<RunResult>;
+    /**
+     * Called once per script as its value arrives, while the run is still
+     * going (GitHub issue #35) — a host uses it to un-stale one bound
+     * component at a time instead of waiting for the whole batch. The value
+     * handed over has already been through `scrubStoredValueForWire`, so it
+     * is safe to post straight to a renderer, exactly like the `values` this
+     * function finally returns.
+     *
+     * Purely a notification. Persistence is NOT done here: the merged value
+     * store is written once, at the end (see below), so a run killed
+     * half-way can never leave a half-written record behind.
+     */
+    onValue?: (name: string, value: StoredValue) => void;
+    timeoutMs: number;
+    /**
+     * Slice 2 of the `.mkz` Run-path arc (GitHub issue #9): present only for a
+     * bundle-backed document. `buildSnapshot` is called exactly once per run
+     * (`./bundle-run.ts`'s `buildBundleSnapshot`, already applied to whatever
+     * `BundleStorage` the caller has) — deferred to run time rather than
+     * built eagerly, so a snapshot is only ever read when a run actually
+     * happens. As of the F-1 fix it is built BEFORE the grant flow rather
+     * than immediately before `spawnRun`, so a `src=` script's resolved
+     * content (`bundleModulesFromSnapshot`) can be folded into the grant
+     * closure `computeGrantKey` hashes, ahead of any prompting — still the
+     * same single call per run, just earlier. `persistCacheOut` receives the
+     * worker's `RunResult.cacheOut`
+     * (its bundle `.cache/` subtree, post-run) when the run produced one, and
+     * is the caller's own persistence: writing back into a directory-form
+     * bundle on disk, or into extension storage keyed by bundle identity for
+     * a read-only zip form (see `preview-panel.ts`'s adapters).
+     */
+    bundle?: {
+        manifest: BundleManifest;
+        buildSnapshot: () => Promise<Record<string, Uint8Array>>;
+        persistCacheOut: (cacheOut: Record<string, Uint8Array>) => Promise<void>;
+    };
+    /**
+     * Slice 5 of the pack-loading arc (GitHub issue #3): pre-read pack Lua
+     * modules for every installed pack (`../packs/pack-scripts.ts`'s
+     * `loadPackModules`), forwarded verbatim to `spawnRun`'s `packModules` so
+     * the worker's `require "packName/..."` can resolve them. Absent when no
+     * packs are configured — `require` for a pack namespace then denies
+     * exactly as it did before packs existed.
+     */
+    packModules?: PackModulesMap;
+}
+export interface RunOnceResult {
+    values: Record<string, StoredValue>;
+    failures: ValuesFailure[];
+    /**
+     * The same failures, message included, for the host's DIAGNOSTICS
+     * surface only (the "Markii" output channel, a developer console) —
+     * never for the rendered page or any per-note UI, which take the
+     * scrubbed `failures` above (D-1: a message can be a raw Lua traceback,
+     * or a denial that embeds the request URL). AGENTS.md's "clean is not
+     * silent": a failure whose reason reaches neither surface is a bug, and
+     * `{name, kind}` alone is not a reason a user can act on.
+     */
+    failureDetails: {
+        name: string;
+        kind: ValuesFailure['kind'];
+        message: string;
+    }[];
+    /**
+     * Consent unification (SECURITY-RELEVANT): lines describing any mismatch
+     * between what is DECLARED (a bundle manifest's `permissions.net`, and/or
+     * an individual script's own `permissions` fence attribute — batch 7
+     * #47) and the hosts this run's scripts actually reach, from
+     * `./bundle-run.ts`'s `netDeclarationDiagnostics`. `[]` when there is
+     * nothing to compare against (no bundle manifest and no script declares
+     * `permissions`) or every declared host agrees with the scan. For the
+     * host's diagnostics surface only — never the rendered page — same
+     * posture as `failureDetails` above.
+     */
+    netDeclarationDiagnostics: string[];
+}
+/**
+ * Runs one manual pass of `options.text`'s scripts end to end: the grant
+ * flow decides the net allowlist (prompting only on a miss), the persisted
+ * cache snapshot seeds the run, and the run's own (possibly mutated) cache
+ * snapshot is written back — capped, never partially. The returned shape
+ * is exactly what the `values` wire message (`../protocol.ts`) needs,
+ * minus the `revision` tag, which the caller (who knows what revision this
+ * run was actually performed against) attaches. Every `StoredValue`'s raw
+ * `error` text is stripped before it is returned (D-1, `scrubValuesForWire`
+ * above) — same treatment `failures` already got.
+ */
+export declare function runOnce(options: RunOnceOptions): Promise<RunOnceResult>;

package/dist/run/run-flow.js

@@ -0,0 +1,323 @@
+/**
+ * Slice 2's top-level orchestration for one `markii.runScripts` press:
+ * extract requirements -> run the grant flow -> read/spawn/persist the
+ * cache snapshot -> shape the result for the `values` wire message
+ * (`../protocol.ts`). Deliberately vscode-free, like every other module
+ * under `./`: the ONLY vscode-shaped things this needs (a Memento, a
+ * `spawnRun`-like runner, and two prompt functions) arrive as plain
+ * parameters, so `extension.ts`/`preview-panel.ts` — the only files
+ * allowed to import `vscode` — reduce to supplying those and posting the
+ * resulting message. See `./grant-flow.ts` and `./run-host.ts` for the
+ * pieces this file composes.
+ */
+import { extractScriptBlocks, scanRunRequirementHosts, scriptDeclaredHosts, } from './script-requirements.js';
+import { resolveStoredGrant, runGrantFlow } from './grant-flow.js';
+import { bundleModulesFromSnapshot, manifestBundleFsGrants, manifestNetHosts, netDeclarationDiagnostics, } from './bundle-run.js';
+/**
+ * Strips a `StoredValue`'s `error` field before it ever reaches the wire
+ * (D-1): `.error` is whatever text the executor happened to produce —
+ * a raw Lua traceback, or (worse, per B-3) a net-provider denial message
+ * that can embed the actual request URL/host — and none of that is meant
+ * for the rendered page (AGENTS.md's cleanliness principle: quiet markers,
+ * never error dumps). This mirrors exactly what `runOnce` below already
+ * does to `RunResult.failures` (reduced to `{name, kind}`, never the raw
+ * message): `failureKind` is kept, so a renderer (`@markii/react`'s
+ * `failure-presentation.ts`) still branches on the closed `FailureKind`
+ * taxonomy — nothing in this reference renderer ever reads `.error` for
+ * display, only for a value that DIDN'T fail (`status !== 'error'`), where
+ * `error` is absent anyway.
+ */
+function scrubStoredValueForWire(value) {
+    if (value.status !== 'error' || value.error === undefined)
+        return value;
+    const { error: _error, ...rest } = value;
+    return rest;
+}
+function scrubValuesForWire(values) {
+    // `Object.fromEntries` for the same reason `mergePersistedValues` uses it:
+    // a plain `scrubbed[name] = ...` silently loses the value of a script
+    // legitimately named `__proto__`.
+    return Object.fromEntries(Object.entries(values).map(([name, value]) => [
+        name,
+        scrubStoredValueForWire(value),
+    ]));
+}
+/**
+ * A sane upper bound on a persisted cache snapshot: real cached `net.*`
+ * responses are small JSON payloads, so the cap exists to guarantee a
+ * runaway/adversarial script can never grow `workspaceState` without
+ * bound. A snapshot over this size is DROPPED, not truncated — a partial
+ * cache would silently look valid while missing entries a script assumed
+ * were still there, which is worse than starting the next run with none
+ * at all.
+ */
+export const MAX_CACHE_SNAPSHOT_BYTES = 1_000_000;
+/** The single `workspaceState`/Memento key a document's cache snapshot lives under. */
+export function cacheStorageKeyFor(documentKey) {
+    return `markii.runCache:${documentKey}`;
+}
+/**
+ * The `workspaceState`/Memento key a document's LAST-KNOWN values live under
+ * (GitHub issue #11, gap 1). Separate from the cache snapshot
+ * (`cacheStorageKeyFor`): the cache is the sandbox's own `cache.get` state,
+ * keyed and TTL'd inside Lua; THIS is the rendered value store
+ * (`ValueStore.snapshot()`), the numbers a data-bound component actually
+ * showed. Persisting it is what lets a reopened monitoring note render its
+ * last figures instantly and offline, marked stale, before (or without) any
+ * re-run — exactly the "opening a note ... showing its last data marked as
+ * stale" behavior docs/scripting.md and docs/spec.md require.
+ */
+export function valuesStorageKeyFor(documentKey) {
+    return `markii.runValues:${documentKey}`;
+}
+/** Same cap and drop-not-truncate posture as `MAX_CACHE_SNAPSHOT_BYTES` — a runaway value store never grows `workspaceState` without bound, and a too-large snapshot is dropped whole (a partial value store would silently omit names a note binds). */
+export const MAX_VALUES_SNAPSHOT_BYTES = 1_000_000;
+/**
+ * True for a value this module is willing to persist and re-hydrate as a
+ * last-known value store — the same "is this a plain object at all"
+ * shallow trust `isCacheSnapshotShape` applies. A renderer-side hostile-shape
+ * guard (`../protocol.ts`'s `isWireStoredValueRecord`) still re-validates
+ * every entry when the host re-posts these over the wire, so this only needs
+ * to keep a corrupt/foreign top-level value from being merged.
+ */
+function isStoredValueRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads a document's persisted last-known value store, or `{}` when there is
+ * none / it is unusable. Never throws, never trusts the stored shape past
+ * "plain object" — see `isStoredValueRecord`.
+ */
+export function readPersistedValues(memento, documentKey) {
+    const raw = memento.get(valuesStorageKeyFor(documentKey));
+    return isStoredValueRecord(raw) ? raw : {};
+}
+/**
+ * Merges a completed run's value store onto the previously-persisted one,
+ * keeping the LAST-KNOWN-GOOD value for any name whose fresh run FAILED
+ * (GitHub issue #11). A scheduled/auto run that hits a transient failure
+ * (offline, an API hiccup, an ungranted host under the read-only tier) must
+ * not wipe the good numbers a monitoring note was already showing — mirroring
+ * the same "the cache only ever remembers good data" guarantee
+ * docs/scripting.md gives `cache.get`. For each name in the new run: a
+ * non-error outcome always wins; an error outcome is kept ONLY if there is no
+ * prior good value to fall back to (so the error surfaces on a note that
+ * never succeeded), otherwise the prior value is retained and marked stale.
+ * Names present only in the prior store (a script the note no longer has) are
+ * dropped — the note's current scripts define the namespace.
+ */
+export function mergePersistedValues(previous, next) {
+    // Built through entries and `Object.fromEntries` rather than
+    // `merged[name] = ...`: assigning the name `__proto__` on a plain object
+    // sets its prototype instead of creating an own property, silently losing
+    // that value, and `__proto__` is a legal script name (docs/spec.md's
+    // `[A-Za-z_][A-Za-z0-9_-]*`). The same guard is in `./stale-values.ts`.
+    const merged = [];
+    for (const [name, value] of Object.entries(next)) {
+        if (typeof value !== 'object' || value === null)
+            continue;
+        if (value.status !== 'error') {
+            merged.push([name, value]);
+            continue;
+        }
+        // `previous` is a PERSISTED store, guarded only down to "plain object"
+        // when it was read back, so an individual entry can be anything.
+        const priorRaw = Object.hasOwn(previous, name) ? previous[name] : undefined;
+        const prior = typeof priorRaw === 'object' && priorRaw !== null ? priorRaw : undefined;
+        merged.push([
+            name,
+            prior && prior.status !== 'error' ? { ...prior, status: 'stale' } : value,
+        ]);
+    }
+    return Object.fromEntries(merged);
+}
+/** The JSON-and-size-guarded form of a value store to persist, or `undefined` to drop it (unserializable, or over `MAX_VALUES_SNAPSHOT_BYTES`) — same contract as `serializeCacheSnapshotIfSmallEnough`. */
+function valuesSnapshotIsSmallEnough(values) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(values);
+    }
+    catch {
+        return false;
+    }
+    return serialized.length <= MAX_VALUES_SNAPSHOT_BYTES;
+}
+/** A plausible cache-snapshot shape read back from storage — never trusts it further than "is this a plain object at all" (an old/foreign/corrupt value degrades to "no cache", matching this whole module's fail-safe posture). */
+export function isCacheSnapshotShape(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The JSON text for `snapshot`, or `undefined` when it must be dropped
+ * instead of persisted: either it isn't serializable at all (a value
+ * `JSON.stringify` cannot handle), or its serialized size exceeds
+ * `MAX_CACHE_SNAPSHOT_BYTES`. Callers write `undefined` back to storage in
+ * that case — see `MAX_CACHE_SNAPSHOT_BYTES`'s doc comment on why a partial
+ * write is never attempted.
+ */
+export function serializeCacheSnapshotIfSmallEnough(snapshot) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(snapshot);
+    }
+    catch {
+        return undefined;
+    }
+    return serialized.length <= MAX_CACHE_SNAPSHOT_BYTES ? serialized : undefined;
+}
+/**
+ * Runs one manual pass of `options.text`'s scripts end to end: the grant
+ * flow decides the net allowlist (prompting only on a miss), the persisted
+ * cache snapshot seeds the run, and the run's own (possibly mutated) cache
+ * snapshot is written back — capped, never partially. The returned shape
+ * is exactly what the `values` wire message (`../protocol.ts`) needs,
+ * minus the `revision` tag, which the caller (who knows what revision this
+ * run was actually performed against) attaches. Every `StoredValue`'s raw
+ * `error` text is stripped before it is returned (D-1, `scrubValuesForWire`
+ * above) — same treatment `failures` already got.
+ */
+export async function runOnce(options) {
+    const { scripts, grantScripts } = extractScriptBlocks(options.text);
+    // F-1 fix, still true under the consent-unification change below: the
+    // bundle snapshot is built BEFORE the host scan so a `src=` script's
+    // resolved content can both (a) be folded into the grant closure
+    // `computeGrantKey` hashes (`bundleModulesFromSnapshot`'s doc comment)
+    // and (b) let the scan resolve that block's `net.*` hosts instead of
+    // folding it into `hasUnknownHosts` — see `./bundle-run.ts`'s "Consent
+    // unification" section. Built exactly once per run either way.
+    const bundleSnapshot = options.bundle
+        ? await options.bundle.buildSnapshot()
+        : undefined;
+    const bundleModules = options.bundle && bundleSnapshot
+        ? bundleModulesFromSnapshot(grantScripts, bundleSnapshot)
+        : undefined;
+    // SECURITY-RELEVANT (consent unification): the static scan of this run's
+    // executable closure is the ONLY source of the hostnames prompted for —
+    // for a bundle too. A `src=` block resolves through `bundleModules` when
+    // its file is in the snapshot; otherwise it folds into
+    // `hasUnknownHosts`, exactly like a plain `.mk.md` document's `src=`
+    // reference always has. The manifest's `permissions.net` is never
+    // consulted here — see below for how it's compared instead.
+    const { hosts: scannedHosts, hasUnknownHosts } = scanRunRequirementHosts(scripts, bundleModules
+        ? (block) => block.src !== undefined ? bundleModules[block.src] : undefined
+        : undefined);
+    // The manifest's declared `permissions.net` (for a bundle) and each
+    // script's own `permissions` fence attribute are BOTH declared intent
+    // only: neither widens or narrows `scannedHosts` above. A mismatch
+    // between what is declared (either source) and what is scanned is
+    // surfaced as diagnostics lines instead (host's diagnostics surface
+    // only, never the rendered page) — see `netDeclarationDiagnostics`'s
+    // doc comment. The two declared sets are merged into one comparison:
+    // a host a script declares but a bundle manifest does not (or vice
+    // versa) is not itself a mismatch worth its own line, only a mismatch
+    // against what actually runs.
+    const declaredNetHosts = [
+        ...(options.bundle ? manifestNetHosts(options.bundle.manifest) : []),
+        ...scriptDeclaredHosts(scripts),
+    ];
+    const netDiagnostics = netDeclarationDiagnostics(declaredNetHosts, scannedHosts);
+    // The `bundle` capability needs no user-facing prompt any more (consent
+    // unification): the manifest's declared bundle-fs grants are passed
+    // straight through as this run's granted permissions.
+    // `@markii/bundle`'s `createScriptView` still intersects this against
+    // the manifest's own declaration, the path-jail still confines every
+    // read/write, and the read-only tier for auto/scheduled triggers still
+    // blocks `bundle.write` outright — only the prompt is gone.
+    const grantedBundlePermissions = options.bundle
+        ? manifestBundleFsGrants(options.bundle.manifest)
+        : [];
+    const trigger = options.trigger ?? 'manual';
+    const grantRequirements = {
+        scripts,
+        grantScripts,
+        hosts: scannedHosts,
+        hasUnknownHosts,
+        ...(bundleModules ? { bundleModules } : {}),
+    };
+    // GitHub issue #11: only a MANUAL run prompts and persists. An auto/
+    // scheduled run resolves grants non-interactively from what the user
+    // already granted by hand for this exact closure — never a modal on a
+    // timer, never a widened allowlist. See `resolveStoredGrant`'s doc comment.
+    const grant = trigger === 'manual'
+        ? await runGrantFlow({
+            documentKey: options.documentKey,
+            requirements: grantRequirements,
+            memento: options.memento,
+            promptHost: options.promptHost,
+            declaredHosts: scriptDeclaredHosts(scripts),
+            promptUnknownHosts: options.promptUnknownHosts,
+            promptManyHosts: options.promptManyHosts,
+        })
+        : await resolveStoredGrant({
+            documentKey: options.documentKey,
+            requirements: grantRequirements,
+            memento: options.memento,
+        });
+    const cacheKey = cacheStorageKeyFor(options.documentKey);
+    const rawCache = options.memento.get(cacheKey);
+    const cacheSnapshot = isCacheSnapshotShape(rawCache) ? rawCache : {};
+    const result = await options.spawnRun({
+        text: options.text,
+        trigger,
+        // GitHub issue #35: forwarded per script, scrubbed the same way the
+        // final `values` are (D-1) so a raw executor message can never reach a
+        // renderer through the faster path either.
+        ...(options.onValue
+            ? {
+                onValue: (name, value) => {
+                    options.onValue?.(name, scrubStoredValueForWire(value));
+                },
+            }
+            : {}),
+        netAllowlist: grant.allowedHosts,
+        ...(options.netPolicy !== undefined
+            ? { netPolicy: options.netPolicy }
+            : {}),
+        cacheSnapshot: cacheSnapshot,
+        timeoutMs: options.timeoutMs,
+        ...(options.packModules !== undefined
+            ? { packModules: options.packModules }
+            : {}),
+        ...(options.bundle && bundleSnapshot
+            ? {
+                bundle: {
+                    snapshot: bundleSnapshot,
+                    manifest: options.bundle.manifest,
+                    grantedBundlePermissions,
+                },
+            }
+            : {}),
+    });
+    const nextSnapshotText = serializeCacheSnapshotIfSmallEnough(result.cacheSnapshot);
+    await options.memento.update(cacheKey, nextSnapshotText === undefined ? undefined : result.cacheSnapshot);
+    if (options.bundle && result.cacheOut) {
+        await options.bundle.persistCacheOut(result.cacheOut);
+    }
+    // GitHub issue #11, gap 1: persist the (wire-scrubbed) value store as this
+    // note's last-known values, merged onto the prior store so a failed
+    // scheduled/auto run never wipes good numbers (`mergePersistedValues`).
+    // Dropped whole, never partially, if it fails the size/serialize guard.
+    //
+    // GitHub issue #35 deliberately did NOT move this write per value. One
+    // write at the end is the only way a killed run cannot leave a partial
+    // record, and there is nothing to gain from the earlier writes: a run
+    // that dies half-way still arrives here, because `spawnRun` carries the
+    // values that already landed into its synthetic failure result, so the
+    // scripts that finished are persisted either way.
+    const scrubbedValues = scrubValuesForWire(result.values);
+    const valuesKey = valuesStorageKeyFor(options.documentKey);
+    const mergedValues = mergePersistedValues(readPersistedValues(options.memento, options.documentKey), scrubbedValues);
+    await options.memento.update(valuesKey, valuesSnapshotIsSmallEnough(mergedValues) ? mergedValues : undefined);
+    return {
+        values: scrubbedValues,
+        failures: result.failures.map((failure) => ({
+            name: failure.name,
+            kind: failure.kind,
+        })),
+        failureDetails: result.failures.map((failure) => ({
+            name: failure.name,
+            kind: failure.kind,
+            message: failure.message,
+        })),
+        netDeclarationDiagnostics: netDiagnostics,
+    };
+}