@markii/host 0.0.1 → 0.17.0-next.3

package/dist/packs/prebuilt.d.ts

@@ -0,0 +1,49 @@
+import type { DiscoveredPack } from './discover.js';
+export declare const PREBUILT_SCRIPT_FILENAME = "webview.js";
+export declare const PREBUILT_STYLESHEET_FILENAME = "webview.css";
+/** The terminal engine's prebuilt registration module, beside `webview.js` (docs/packs.md). Optional: a pack with no terminal views never has one. */
+export declare const PREBUILT_TERMINAL_SCRIPT_FILENAME = "terminal.js";
+/** Absolute path of a pack folder's prebuilt terminal script. No existence check. */
+export declare function prebuiltTerminalScriptPathFor(folder: string): string;
+/**
+ * The `webview.js` an export writes for a pack that has terminal views but
+ * no React ones: a registration with no components, so the archive keeps
+ * its required `webview.js` and a React host loads the pack as having
+ * nothing for it (every directive falls back).
+ */
+export declare function emptyWebviewScript(manifestJson: string): string;
+/** Absolute path of a pack folder's prebuilt registration script. No existence check. */
+export declare function prebuiltScriptPathFor(folder: string): string;
+/** Absolute path of a pack folder's prebuilt sibling stylesheet. No existence check. */
+export declare function prebuiltStylesheetPathFor(folder: string): string;
+/** Whether an absolute path exists. Injected so this module needs no real disk to test; may be sync or async. */
+export type PackPathExists = (absolutePath: string) => boolean | Promise<boolean>;
+export interface PrebuiltPackResolution {
+    /** Absolute path to the pack's prebuilt webview.js (it exists). */
+    readonly scriptPath: string;
+    /** Absolute path to the sibling webview.css, present only when that file exists. */
+    readonly stylesheetPath?: string;
+    /**
+     * Absolute paths of the manifest-declared component sources that are
+     * present on disk and therefore shadowed by the prebuilt script. Empty
+     * when the pack ships no sources (the ordinary distribution shape:
+     * `webview.js` alone, docs/packs.md's "This is the form to ship when
+     * other people will use your pack").
+     */
+    readonly shadowedComponentSources: readonly string[];
+}
+/**
+ * Resolves the prebuilt artifacts of one discovered pack, or `undefined`
+ * when the pack ships no `webview.js` at all (the from-source path, which a
+ * host compiles via `./pack-build.ts` instead).
+ *
+ * `pack.scriptPath` (already `folder/webview.js` from `./discover.ts`) is
+ * used as the script path rather than recomputed, but the stylesheet path
+ * is derived from the script path's own directory so the two always stay
+ * siblings even if a caller ever hands this a `DiscoveredPack` copy whose
+ * `folder` and `scriptPath` were computed independently.
+ *
+ * Never throws: an `exists` that throws is treated as "does not exist" for
+ * every path this function checks.
+ */
+export declare function resolvePrebuiltPack(pack: Pick<DiscoveredPack, 'folder' | 'componentPaths' | 'scriptPath'>, exists: PackPathExists): Promise<PrebuiltPackResolution | undefined>;

package/dist/packs/prebuilt.js

@@ -0,0 +1,97 @@
+/**
+ * The prebuilt-pack convention (docs/packs.md's "Two ways to run a pack:
+ * prebuilt and from source"): a pack that ships a compiled `webview.js`
+ * sibling to its `pack.json` is used as-is, no compiler runs. This module
+ * adds the second half of that convention (issue #15): an OPTIONAL sibling
+ * `webview.css`, injected/removed by a host's own pack-context composition
+ * keyed by namespace exactly like a compiled pack's own emitted stylesheet
+ * (`./pack-build.ts`'s `stylesheetPath`). A prebuilt pack with no
+ * `webview.css` simply has no stylesheet — never an error, matching
+ * `./discover.ts`'s "the file need not actually exist" posture for every
+ * other pack artifact.
+ *
+ * Also detects the SHADOWING case docs/packs.md names: "When a pack folder
+ * holds both a `webview.js` and sources, the prebuilt script wins and the
+ * sources are ignored." `resolvePrebuiltPack` reports exactly which of the
+ * manifest-declared component sources are present on disk, so a host's own
+ * diagnostics surface can name them (host-specific wording; this module
+ * only supplies the facts).
+ *
+ * Filesystem access is injected (`PackPathExists`), not imported directly,
+ * so this module is testable with plain in-memory fakes — matching every
+ * other module in this directory.
+ */
+import { dirnamePath, joinPath } from '../path-util.js';
+export const PREBUILT_SCRIPT_FILENAME = 'webview.js';
+export const PREBUILT_STYLESHEET_FILENAME = 'webview.css';
+/** The terminal engine's prebuilt registration module, beside `webview.js` (docs/packs.md). Optional: a pack with no terminal views never has one. */
+export const PREBUILT_TERMINAL_SCRIPT_FILENAME = 'terminal.js';
+/** Absolute path of a pack folder's prebuilt terminal script. No existence check. */
+export function prebuiltTerminalScriptPathFor(folder) {
+    return joinPath(folder, PREBUILT_TERMINAL_SCRIPT_FILENAME);
+}
+/**
+ * The `webview.js` an export writes for a pack that has terminal views but
+ * no React ones: a registration with no components, so the archive keeps
+ * its required `webview.js` and a React host loads the pack as having
+ * nothing for it (every directive falls back).
+ */
+export function emptyWebviewScript(manifestJson) {
+    return [
+        "if (typeof window !== 'undefined' && typeof window.__markiiRegisterPack === 'function') {",
+        `  window.__markiiRegisterPack(${JSON.stringify(manifestJson)}, {});`,
+        '}',
+        '',
+    ].join('\n');
+}
+/** Absolute path of a pack folder's prebuilt registration script. No existence check. */
+export function prebuiltScriptPathFor(folder) {
+    return joinPath(folder, PREBUILT_SCRIPT_FILENAME);
+}
+/** Absolute path of a pack folder's prebuilt sibling stylesheet. No existence check. */
+export function prebuiltStylesheetPathFor(folder) {
+    return joinPath(folder, PREBUILT_STYLESHEET_FILENAME);
+}
+/** Calls `exists`, treating a thrown error the same as "does not exist" — an unreadable path is not proof a file is absent, but this module's contract (like every other filesystem-adjacent module in this directory) is to degrade quietly rather than surface a raw I/O error here. */
+async function existsQuietly(exists, absolutePath) {
+    try {
+        return await exists(absolutePath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves the prebuilt artifacts of one discovered pack, or `undefined`
+ * when the pack ships no `webview.js` at all (the from-source path, which a
+ * host compiles via `./pack-build.ts` instead).
+ *
+ * `pack.scriptPath` (already `folder/webview.js` from `./discover.ts`) is
+ * used as the script path rather than recomputed, but the stylesheet path
+ * is derived from the script path's own directory so the two always stay
+ * siblings even if a caller ever hands this a `DiscoveredPack` copy whose
+ * `folder` and `scriptPath` were computed independently.
+ *
+ * Never throws: an `exists` that throws is treated as "does not exist" for
+ * every path this function checks.
+ */
+export async function resolvePrebuiltPack(pack, exists) {
+    const scriptExists = await existsQuietly(exists, pack.scriptPath);
+    if (!scriptExists)
+        return undefined;
+    const stylesheetPath = joinPath(dirnamePath(pack.scriptPath), PREBUILT_STYLESHEET_FILENAME);
+    const stylesheetExists = await existsQuietly(exists, stylesheetPath);
+    const shadowedComponentSources = [];
+    for (const sourcePath of Object.values(pack.componentPaths)) {
+        if (sourcePath === undefined)
+            continue;
+        if (await existsQuietly(exists, sourcePath)) {
+            shadowedComponentSources.push(sourcePath);
+        }
+    }
+    return {
+        scriptPath: pack.scriptPath,
+        ...(stylesheetExists ? { stylesheetPath } : {}),
+        shadowedComponentSources,
+    };
+}

package/dist/path-util.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Small, environment-free path helpers for the paths the host layer hands to
+ * a `HostAdapter` (`readFile`, `writeFile`, `listFolder`). They are adapter
+ * paths, not OS paths: this layer never touches a file system itself, so it
+ * must not import `node:path`.
+ *
+ * They stay correct for a Windows host, where the VS Code adapter does hand
+ * over `C:\Users\ana\packs` style strings (from `os.homedir()`, a
+ * `globalStorageUri.fsPath`, or a hand-written setting). The separator is
+ * taken from the base path: a base that uses backslashes and no forward
+ * slashes is a Windows path, joined and split with backslashes (forward
+ * slashes inside later segments are accepted as separators too, as
+ * `path.win32` does). Any other base is posix.
+ */
+/** True for a rooted path: `/x`, `\x`, `\\server\share`, or `C:\x` / `C:/x`. */
+export declare function isAbsolutePath(path: string): boolean;
+/**
+ * Joins `base` and `parts` with the separator `base` uses, collapsing `.`,
+ * `..` and repeated separators the way `path.join` does. An empty result is
+ * `.`.
+ */
+export declare function joinPath(base: string, ...parts: string[]): string;
+/** The parent folder of `path`, `path.dirname`-style (a root's parent is itself). */
+export declare function dirnamePath(path: string): string;

package/dist/path-util.js

@@ -0,0 +1,82 @@
+/**
+ * Small, environment-free path helpers for the paths the host layer hands to
+ * a `HostAdapter` (`readFile`, `writeFile`, `listFolder`). They are adapter
+ * paths, not OS paths: this layer never touches a file system itself, so it
+ * must not import `node:path`.
+ *
+ * They stay correct for a Windows host, where the VS Code adapter does hand
+ * over `C:\Users\ana\packs` style strings (from `os.homedir()`, a
+ * `globalStorageUri.fsPath`, or a hand-written setting). The separator is
+ * taken from the base path: a base that uses backslashes and no forward
+ * slashes is a Windows path, joined and split with backslashes (forward
+ * slashes inside later segments are accepted as separators too, as
+ * `path.win32` does). Any other base is posix.
+ */
+const DRIVE_PREFIX = /^[A-Za-z]:/;
+function separatorOf(path) {
+    return path.includes('\\') && !path.includes('/') ? '\\' : '/';
+}
+/** True for a rooted path: `/x`, `\x`, `\\server\share`, or `C:\x` / `C:/x`. */
+export function isAbsolutePath(path) {
+    return (path.startsWith('/') ||
+        path.startsWith('\\') ||
+        /^[A-Za-z]:[\\/]/.test(path));
+}
+function parse(path, sep) {
+    const splitter = sep === '\\' ? /[\\/]+/ : /\/+/;
+    let root = '';
+    let rest = path;
+    if (sep === '\\') {
+        const drive = DRIVE_PREFIX.exec(rest);
+        if (drive) {
+            root = drive[0];
+            rest = rest.slice(2);
+        }
+        if (/^[\\/]{2}[^\\/]/.test(path) && root === '') {
+            root = '\\\\';
+            rest = rest.replace(/^[\\/]+/, '');
+        }
+        else if (/^[\\/]/.test(rest)) {
+            root += '\\';
+        }
+    }
+    else if (rest.startsWith('/')) {
+        root = '/';
+    }
+    const segments = [];
+    for (const part of rest.split(splitter)) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            const last = segments[segments.length - 1];
+            if (last !== undefined && last !== '..')
+                segments.pop();
+            else if (root === '')
+                segments.push('..');
+            continue;
+        }
+        segments.push(part);
+    }
+    return { root, segments };
+}
+function format({ root, segments }, sep) {
+    const body = segments.join(sep);
+    if (body === '')
+        return root === '' ? '.' : root;
+    return root + body;
+}
+/**
+ * Joins `base` and `parts` with the separator `base` uses, collapsing `.`,
+ * `..` and repeated separators the way `path.join` does. An empty result is
+ * `.`.
+ */
+export function joinPath(base, ...parts) {
+    const sep = separatorOf(base);
+    return format(parse([base, ...parts].filter((p) => p !== '').join(sep), sep), sep);
+}
+/** The parent folder of `path`, `path.dirname`-style (a root's parent is itself). */
+export function dirnamePath(path) {
+    const sep = separatorOf(path);
+    const parsed = parse(path, sep);
+    return format({ root: parsed.root, segments: parsed.segments.slice(0, -1) }, sep);
+}

package/dist/run/browser-isolate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A `RunIsolate` backed by a Web Worker, for hosts whose runtime cannot
+ * create a worker thread (see `./isolate.ts`).
+ *
+ * Two details are load-bearing.
+ *
+ * The worker is started from a BLOB URL built from the bundle's own bytes,
+ * read off disk by the host. Loading a worker from a `file://` URL is
+ * refused by Chromium, and an Electron app's custom protocols are not
+ * something this package can assume, so reading the file the host already
+ * has and handing it over as a blob sidesteps the question entirely.
+ * `glue.wasm` travels the same way, because wasmoon fetches it by URL and
+ * there is no `__dirname` inside a worker to find it beside the bundle.
+ *
+ * Network is served by the HOST, not the worker: `serveNetRequests` wires
+ * every `markii:net-request` to the caller's own `NetProvider`. Lua cannot
+ * reach JavaScript, and the worker entry removes its own network globals
+ * before the first script runs (`./worker-entry-browser.ts`), so the
+ * provider's allowlist is the only path to the network.
+ *
+ * What this CANNOT do, stated plainly because it is a real difference: a
+ * Web Worker takes no `maxOldGenerationSizeMb`, so `options`'s heap cap is
+ * accepted and ignored. Lua's own memory limit and the external watchdog
+ * still apply; a runaway JavaScript-side allocation inside the isolate is
+ * bounded only by the browser engine, and exhausting it can take the host
+ * renderer down. docs/security.md records this.
+ */
+import type { NetProvider } from '@markii/lua';
+import type { RunIsolate, SpawnIsolateOptions } from './isolate.js';
+/** The Web Worker surface this uses, declared structurally so the package needs no DOM lib. */
+export interface WorkerLike {
+    postMessage: (message: unknown) => void;
+    terminate: () => void;
+    addEventListener: (type: 'message' | 'error' | 'messageerror', listener: (event: unknown) => void) => void;
+}
+export interface BrowserIsolateOptions {
+    /** Creates the worker. Injected so a test never needs a real one, and so a host can decide how it mints the URL. */
+    createWorker: (entryPath: string) => WorkerLike;
+    /** The host's own pinned provider. Every `net.*` call the script makes is answered by this, in the host, never in the isolate. */
+    netProvider: (netAllowlist: string[], maxFetchBytes: number, netPolicy: unknown, signal?: AbortSignal) => NetProvider;
+    /** Where the worker should fetch wasmoon's `glue.wasm`; sent along with the job. */
+    wasmUri?: string;
+}
+/** Builds the spawner a host passes as `SpawnRunOptions.spawnIsolate`. */
+export declare function createBrowserIsolate(options: BrowserIsolateOptions): (spawn: SpawnIsolateOptions) => RunIsolate;

package/dist/run/browser-isolate.js

@@ -0,0 +1,85 @@
+import { isNetBridgeRequest, serveNetRequest, } from './net-bridge.js';
+/** Pulls the fields the host needs to build the same provider the worker would have built for itself. */
+function netArgsFrom(job) {
+    const j = (job ?? {});
+    return {
+        allowlist: Array.isArray(j.netAllowlist)
+            ? j.netAllowlist.filter((h) => typeof h === 'string')
+            : [],
+        maxFetchBytes: typeof j.limits?.maxFetchBytes === 'number'
+            ? j.limits.maxFetchBytes
+            : 2 * 1024 * 1024,
+        // Fail closed, exactly as the worker does with an absent policy.
+        policy: j.netPolicy ?? { allowRestrictedAddresses: false },
+    };
+}
+/** Builds the spawner a host passes as `SpawnRunOptions.spawnIsolate`. */
+export function createBrowserIsolate(options) {
+    return (spawn) => {
+        const worker = options.createWorker(spawn.entryPath);
+        let provider;
+        let alive = true;
+        // Aborted by `kill()`: a request still in flight when the run ends is
+        // cancelled rather than left running in the host.
+        const requests = new AbortController();
+        const messageListeners = [];
+        const errorListeners = [];
+        worker.addEventListener('message', (event) => {
+            const data = event?.data;
+            if (isNetBridgeRequest(data)) {
+                if (!provider)
+                    return;
+                void serveNetRequest(data, provider, (reply) => {
+                    // A reply posted to a worker that is already gone would throw and
+                    // take out this handler; the run is over either way.
+                    if (alive)
+                        worker.postMessage(reply);
+                });
+                return;
+            }
+            for (const listener of messageListeners)
+                listener(data);
+        });
+        worker.addEventListener('error', (event) => {
+            const message = event?.message ?? 'worker error';
+            for (const listener of errorListeners) {
+                listener(new Error(String(message)));
+            }
+        });
+        // A message that could not be deserialized is a failed run, not silence.
+        worker.addEventListener('messageerror', () => {
+            for (const listener of errorListeners) {
+                listener(new Error('worker sent an undeserializable message'));
+            }
+        });
+        return {
+            send: (job) => {
+                const { allowlist, maxFetchBytes, policy } = netArgsFrom(job);
+                provider = options.netProvider(allowlist, maxFetchBytes, policy, requests.signal);
+                worker.postMessage({
+                    ...job,
+                    ...(options.wasmUri !== undefined
+                        ? { wasmUri: options.wasmUri }
+                        : {}),
+                });
+            },
+            kill: () => {
+                if (!alive)
+                    return;
+                alive = false;
+                requests.abort();
+                worker.terminate();
+            },
+            onMessage: (listener) => {
+                messageListeners.push(listener);
+            },
+            onError: (listener) => {
+                errorListeners.push(listener);
+            },
+            // A Web Worker has no exit event: `terminate()` is immediate and
+            // silent. `spawnRun`'s watchdog path settles on its own timer rather
+            // than waiting for one, so there is nothing to report here.
+            onExit: () => { },
+        };
+    };
+}

package/dist/run/bundle-document.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a bundle's note lives and what a bundle is called on disk. Every
+ * host that opens a `.mkz` (the VS Code preview, the CLI) asks these
+ * questions, so the answers live here once.
+ */
+import type { BundleManifest } from '@markii/bundle';
+/** The conventional document path inside a bundle when the manifest does not name one (docs/bundles.md). */
+export declare const DEFAULT_BUNDLE_DOCUMENT_PATH = "note.mk.md";
+/** The current bundle extension; new bundles are always written with this one. */
+export declare const BUNDLE_EXTENSION = ".mkz";
+/** The legacy bundle extension, still recognized. */
+export declare const LEGACY_BUNDLE_EXTENSION = ".mkbundle";
+/**
+ * True when `name` ends with `.mkz` or the legacy `.mkbundle`
+ * (case-insensitively) AND has a non-empty base name before the extension.
+ */
+export declare function isBundleName(name: string): boolean;
+/**
+ * The bundle-relative path of the document to open: the manifest's own
+ * `document` field when it names one, normalized through the same path jail
+ * every other bundle path goes through so a manifest cannot point outside
+ * the bundle; otherwise the conventional `note.mk.md`.
+ *
+ * Returns `undefined` when a `document` field is present but not a usable
+ * bundle-relative path (wrong type, or rejected by `normalizeBundlePath`,
+ * including any path with a `..` segment). That is a manifest authoring
+ * error, not something to ignore silently.
+ */
+export declare function resolveBundleDocumentPath(manifest: BundleManifest): string | undefined;

package/dist/run/bundle-document.js

@@ -0,0 +1,40 @@
+import { normalizeBundlePath } from '@markii/bundle';
+/** The conventional document path inside a bundle when the manifest does not name one (docs/bundles.md). */
+export const DEFAULT_BUNDLE_DOCUMENT_PATH = 'note.mk.md';
+/** The current bundle extension; new bundles are always written with this one. */
+export const BUNDLE_EXTENSION = '.mkz';
+/** The legacy bundle extension, still recognized. */
+export const LEGACY_BUNDLE_EXTENSION = '.mkbundle';
+/**
+ * True when `name` ends with `.mkz` or the legacy `.mkbundle`
+ * (case-insensitively) AND has a non-empty base name before the extension.
+ */
+export function isBundleName(name) {
+    const lower = name.toLowerCase();
+    for (const extension of [BUNDLE_EXTENSION, LEGACY_BUNDLE_EXTENSION]) {
+        if (lower.endsWith(extension) && lower.length > extension.length) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The bundle-relative path of the document to open: the manifest's own
+ * `document` field when it names one, normalized through the same path jail
+ * every other bundle path goes through so a manifest cannot point outside
+ * the bundle; otherwise the conventional `note.mk.md`.
+ *
+ * Returns `undefined` when a `document` field is present but not a usable
+ * bundle-relative path (wrong type, or rejected by `normalizeBundlePath`,
+ * including any path with a `..` segment). That is a manifest authoring
+ * error, not something to ignore silently.
+ */
+export function resolveBundleDocumentPath(manifest) {
+    const raw = manifest.document;
+    if (raw === undefined)
+        return DEFAULT_BUNDLE_DOCUMENT_PATH;
+    if (typeof raw !== 'string')
+        return undefined;
+    const normalized = normalizeBundlePath(raw);
+    return normalized.ok ? normalized.path : undefined;
+}

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

@@ -0,0 +1,188 @@
+/**
+ * Slice 2 of the `.mkz` Run-path arc (GitHub issue #9's locked design
+ * comment): the host-side pieces that turn a bundle's `@markii/bundle`
+ * `BundleStorage` into the SNAPSHOT a worker run is handed, and back a
+ * worker's `.cache/` output into something the host can persist. Kept
+ * `vscode`-free, like every other module under `./run` — `preview-panel.ts`
+ * (the only file allowed to import `vscode` alongside `extension.ts`)
+ * supplies the actual `BundleStorage`/`Memento`/filesystem calls.
+ *
+ * ## Why a snapshot at all
+ *
+ * The worker is a separate `worker_thread` and must never hold a live
+ * handle to a zip archive or the user's disk (docs/security.md's isolate
+ * requirement, restated in issue #9's design comment) — so the host reads
+ * whatever a run may legitimately touch into plain bytes BEFORE spawning
+ * the worker, and the worker's `@markii/bundle` `ScriptView` is backed by
+ * that in-memory snapshot alone (`./snapshot-storage.ts`), never by the
+ * real storage.
+ *
+ * ## What's in the snapshot
+ *
+ * The design comment scopes this to "the `scripts/` tree, the subset of
+ * `assets/` reachable, and current `.cache/` contents" — deliberately NOT
+ * `manifest.json` or the document itself, even though `@markii/bundle`'s
+ * `ScriptView.read` places no path restriction on a granted read (only
+ * `write` is jailed to `.cache/`). A script that specifically wants to
+ * introspect its own manifest or document text cannot do so through
+ * `bundle.read` in this slice — `bundle.read("manifest.json")` comes back
+ * `undefined`, indistinguishable from "no such file", exactly like any
+ * other path the snapshot didn't collect (AGENTS.md's cleanliness
+ * principle: a quiet miss, never a special-cased error). This is a
+ * deliberate scope line for this slice, not an oversight — flagged in the
+ * slice's own report rather than silently widened.
+ *
+ * ## Consent unification (SECURITY-RELEVANT)
+ *
+ * Two rules this module and its callers (`./run-flow.ts`, `./grant-flow.ts`)
+ * now hold to, so a bundle's consent story matches a bare `.mk.md`
+ * document's exactly:
+ *
+ * - `manifestNetHosts` (the manifest's `permissions.net` declaration) is
+ *   never merged into what a run prompts for. The static scan
+ *   (`./script-requirements.ts`) is the only source of prompted hostnames,
+ *   for a bundle too — see `netDeclarationDiagnostics` below for how a
+ *   mismatch is surfaced instead.
+ * - The `bundle` capability (`permissions.bundle`) needs no user-facing
+ *   prompt at all: `@markii/bundle`'s path-jail confines every read to the
+ *   snapshot and every write to `.cache/`, and the read-only tier for
+ *   auto/scheduled triggers blocks `bundle.write` outright regardless of
+ *   what the manifest declares. `manifestBundleFsGrants`'s result is passed
+ *   straight through as the run's granted bundle-fs permissions — see
+ *   `./run-flow.ts`.
+ */
+import type { BundleManifest, BundleStorage } from '@markii/bundle';
+import type { BundleFsGrant } from '@markii/bundle';
+import type { GrantClosureScript } from '@markii/runtime';
+/**
+ * Total byte budget for one run's bundle snapshot (across `scripts/` +
+ * `.cache/` + `assets/` combined). Mirrors the same order of magnitude as
+ * `bundle-resolve.ts`'s `DEFAULT_MAX_EMBEDDED_ASSET_BYTES` (20MB) — a
+ * personal note bundle's scripts and cache are typically tiny; this budget
+ * exists so a hostile or oversized bundle degrades quietly (files beyond
+ * the cap are simply absent from the snapshot, exactly like a path the
+ * snapshot never collected) rather than exhausting worker/host memory or
+ * ballooning the `postMessage` structured-clone payload.
+ */
+export declare const DEFAULT_MAX_BUNDLE_SNAPSHOT_BYTES: number;
+/**
+ * Per-file cap applied on top of the total budget (C-1, PENTEST-REPORT
+ * follow-up): a single huge file could otherwise consume the ENTIRE total
+ * budget by itself, and — before this fix — would be read into memory in
+ * full before the total-budget check ever saw it. Sized the same as the
+ * total budget by default; a caller wanting a stricter per-file limit can
+ * override it independently via `maxFileBytes`.
+ */
+export declare const DEFAULT_MAX_BUNDLE_SNAPSHOT_FILE_BYTES: number;
+export interface BuildBundleSnapshotOptions {
+    readonly maxTotalBytes?: number;
+    readonly maxFileBytes?: number;
+}
+export interface BundleSnapshotResult {
+    /** Bundle-relative path -> file bytes, ready to hand to `spawnRun`'s `bundle.snapshot`. */
+    readonly files: Record<string, Uint8Array>;
+    /** `true` when at least one otherwise-eligible file was left out because the budget was reached — a quiet degrade, never a thrown error. */
+    readonly truncated: boolean;
+}
+/**
+ * Reads every file under `scripts/`, `.cache/`, and `assets/` out of
+ * `storage`, up to `maxTotalBytes` total. `storage.list()` already returns
+ * paths sorted, so which files get dropped once the budget is hit is
+ * deterministic rather than depending on iteration order.
+ */
+export declare function buildBundleSnapshot(storage: BundleStorage, options?: BuildBundleSnapshotOptions): Promise<BundleSnapshotResult>;
+/**
+ * F-1 fix: the `bundleModules` half of the grant closure `computeGrantKey`
+ * (`@markii/runtime`) hashes — resolved from `snapshot` (the same in-memory
+ * bundle snapshot a run's `ScriptView` is backed by, see this module's top
+ * doc comment) rather than left empty.
+ *
+ * Before this fix, `grant-flow.ts`'s `closureFrom` always passed
+ * `bundleModules: {}`, so a `src=scripts/etl.lua` block's `code` was `""`
+ * (@markii/core's `ScriptBlock` leaves it empty for a `src=` reference — the
+ * actual source lives in the referenced file) and the grant key never
+ * reflected that file's bytes at all: swapping the file's contents while
+ * the note's own text stayed byte-identical re-ran new code under an old,
+ * un-reprompted grant.
+ *
+ * Only `src=` targets are resolved here — `require()` (bundle-local or
+ * pack) stays unwired for the whole `.mkz` Run-path arc (see
+ * `grant-flow.ts`'s top doc comment), so a script's closure has no other
+ * bundle-local code to fold in yet. A `src=` path missing from `snapshot`
+ * (file deleted, or dropped by `buildBundleSnapshot`'s own budget) is
+ * simply omitted from the result — never thrown — so a note whose script
+ * references a missing file still gets a (now-narrower, but well-defined)
+ * grant key instead of failing the whole grant flow.
+ */
+export declare function bundleModulesFromSnapshot(scripts: readonly GrantClosureScript[], snapshot: Record<string, Uint8Array>): Record<string, string>;
+/** Every `.cache/`-prefixed entry in `files`, unchanged — the shape a worker's `RunResult.cacheOut` carries back and a host persists. */
+export declare function cacheFilesFrom(files: Record<string, Uint8Array>): Record<string, Uint8Array>;
+/**
+ * Overlays `persisted` (a prior run's `.cache/` output, read back from
+ * wherever the host keeps it) onto `base` (a freshly built snapshot),
+ * persisted entries winning on a path collision — the "seed the next run's
+ * snapshot from the persisted cache" half of the design. Used for the
+ * zip-form path, where the archive's own on-disk `.cache/` entries (if any)
+ * are stale the moment a run has written a persisted cache elsewhere (the
+ * host never rewrites the user's zip — see `docs` design comment).
+ */
+export declare function withPersistedCache(base: Record<string, Uint8Array>, persisted: Record<string, Uint8Array>): Record<string, Uint8Array>;
+/** Bare, lowercased hostnames a manifest declares under `permissions.net.get`/`.post`, deduplicated. */
+export declare function manifestNetHosts(manifest: BundleManifest): string[];
+/**
+ * Consent unification (SECURITY-RELEVANT, GitHub issue #9 follow-up): a
+ * bundle's manifest `permissions.net` is DECLARED INTENT only. The static
+ * scan of the run's executable closure (`./script-requirements.ts`) is the
+ * ONLY source of the hostnames a run prompts for, for a bundle exactly as
+ * for a bare `.mk.md` document — the manifest's declaration never widens
+ * that prompt (a declared-but-unused host is never prompted for) and never
+ * narrows it (a host a script actually reaches is always prompted for,
+ * declared or not).
+ *
+ * A mismatch between the two is not silently absorbed: this pure function
+ * returns one diagnostics line per mismatched host, in both directions, for
+ * the host's diagnostics surface (docs/integration.md) — never the rendered
+ * page. Wording lives here, the one place both apps' adapters read it from,
+ * so it can never drift between VS Code's output channel and Obsidian's
+ * console/notice surface.
+ *
+ * Returns `[]` when the two sets agree (including when both are empty).
+ * Order: every declared-but-unused host first (in `declaredHosts` order),
+ * then every used-but-undeclared host (in `scannedHosts` order) — matching
+ * how `manifestNetHosts`/`extractRunRequirements` already dedupe and order
+ * their inputs, so this function does no case-folding or deduping of its
+ * own.
+ */
+export declare function netDeclarationDiagnostics(declaredHosts: readonly string[], scannedHosts: readonly string[]): string[];
+/** The bundle-filesystem grants a manifest declares under `permissions.bundle` (`'read'` / `'write:.cache/'`), or `[]` when it declares none. */
+export declare function manifestBundleFsGrants(manifest: BundleManifest): BundleFsGrant[];
+/**
+ * Cap on a zip-form bundle's persisted `.cache/` state (extension storage,
+ * keyed by bundle identity — see `preview-panel.ts`'s adapters). Mirrors
+ * `run-flow.ts`'s `MAX_CACHE_SNAPSHOT_BYTES` for the unrelated `cache.get`
+ * Memento snapshot: real script-written cache files are small, so this
+ * exists purely to guarantee a runaway/adversarial bundle can never grow
+ * `workspaceState` without bound. Oversize state is DROPPED wholesale, not
+ * partially persisted — see that constant's doc comment for why a partial
+ * write is worse than none.
+ */
+export declare const MAX_PERSISTED_BUNDLE_CACHE_BYTES = 1000000;
+/** A JSON-safe, base64-encoded form of a `path -> bytes` cache map, suitable for a `vscode.Memento` value. */
+export type EncodedBundleCache = Record<string, string>;
+/**
+ * Encodes `files` (a bundle run's `.cache/` output) for Memento storage, or
+ * `undefined` when it must be dropped instead — either it doesn't encode at
+ * all, or the encoded form exceeds `MAX_PERSISTED_BUNDLE_CACHE_BYTES`.
+ * Callers write `undefined` back to storage in that case, exactly like
+ * `run-flow.ts`'s `serializeCacheSnapshotIfSmallEnough`.
+ */
+export declare function encodeBundleCacheForStorage(files: Record<string, Uint8Array>): EncodedBundleCache | undefined;
+/**
+ * Decodes a value read back from a `vscode.Memento` into a `path -> bytes`
+ * cache map — never trusts the stored shape further than "every value is a
+ * string that decodes as base64"; a corrupt/foreign/hand-edited value
+ * degrades to an empty map (no persisted cache), matching this whole
+ * module's fail-safe posture (`grant-flow.ts`'s `isStoredGrant` takes the
+ * same stance for its own Memento reads).
+ */
+export declare function decodeBundleCacheFromStorage(value: unknown): Record<string, Uint8Array>;