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

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>;

package/dist/run/bundle-run.js

@@ -0,0 +1,232 @@
+/** The three bundle-relative prefixes a run's snapshot ever collects — see this module's top doc comment. */
+const SNAPSHOT_PREFIXES = ['scripts/', '.cache/', 'assets/'];
+/**
+ * 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 const DEFAULT_MAX_BUNDLE_SNAPSHOT_BYTES = 20 * 1024 * 1024;
+/**
+ * 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 const DEFAULT_MAX_BUNDLE_SNAPSHOT_FILE_BYTES = DEFAULT_MAX_BUNDLE_SNAPSHOT_BYTES;
+/**
+ * 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 async function buildBundleSnapshot(storage, options = {}) {
+    const maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_BUNDLE_SNAPSHOT_BYTES;
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_BUNDLE_SNAPSHOT_FILE_BYTES;
+    const allPaths = await storage.list();
+    const eligible = allPaths.filter((path) => SNAPSHOT_PREFIXES.some((prefix) => path.startsWith(prefix)));
+    const files = {};
+    let total = 0;
+    let truncated = false;
+    for (const path of eligible) {
+        // C-1: consult `size()` BEFORE ever calling `read()` — a file whose
+        // declared size alone would blow the per-file or remaining total budget
+        // is skipped without materializing its bytes at all, which is the whole
+        // point: a host-side `readFile` of a multi-gigabyte file (directory
+        // form) would otherwise allocate that much in the extension host before
+        // any cap ever saw it. `size()` returning `undefined` (path vanished
+        // between `list()` and here, or the storage form has no size for it) is
+        // treated exactly like the file being absent: a quiet skip, never a
+        // fallback to reading it blind.
+        const size = await storage.size(path);
+        if (size === undefined)
+            continue;
+        if (size > maxFileBytes || total + size > maxTotalBytes) {
+            truncated = true;
+            continue;
+        }
+        const bytes = await storage.read(path);
+        if (bytes === undefined)
+            continue;
+        // Defense in depth: re-check the actual byte length against the budget.
+        // A well-behaved `BundleStorage` never disagrees between `size()` and
+        // `read()`, but the total-budget accounting below must never trust
+        // `size()` blindly if it ever did.
+        if (total + bytes.length > maxTotalBytes) {
+            truncated = true;
+            continue;
+        }
+        total += bytes.length;
+        files[path] = bytes;
+    }
+    return { files, truncated };
+}
+const utf8Decoder = new TextDecoder('utf-8', { fatal: false });
+/**
+ * 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 function bundleModulesFromSnapshot(scripts, snapshot) {
+    const modules = {};
+    for (const script of scripts) {
+        if (script.src === undefined)
+            continue;
+        const bytes = snapshot[script.src];
+        if (bytes === undefined)
+            continue;
+        modules[script.src] = utf8Decoder.decode(bytes);
+    }
+    return modules;
+}
+/** Every `.cache/`-prefixed entry in `files`, unchanged — the shape a worker's `RunResult.cacheOut` carries back and a host persists. */
+export function cacheFilesFrom(files) {
+    const out = {};
+    for (const [path, bytes] of Object.entries(files)) {
+        if (path.startsWith('.cache/'))
+            out[path] = bytes;
+    }
+    return out;
+}
+/**
+ * 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 function withPersistedCache(base, persisted) {
+    return { ...base, ...persisted };
+}
+/** Bare, lowercased hostnames a manifest declares under `permissions.net.get`/`.post`, deduplicated. */
+export function manifestNetHosts(manifest) {
+    const get = manifest.permissions?.net?.get ?? [];
+    const post = manifest.permissions?.net?.post ?? [];
+    return [...new Set([...get, ...post].map((host) => host.toLowerCase()))];
+}
+/**
+ * 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 function netDeclarationDiagnostics(declaredHosts, scannedHosts) {
+    const declared = new Set(declaredHosts);
+    const scanned = new Set(scannedHosts);
+    const lines = [];
+    for (const host of declaredHosts) {
+        if (!scanned.has(host)) {
+            lines.push(`The manifest declares net access to ${host}. No script in this run uses that host.`);
+        }
+    }
+    for (const host of scannedHosts) {
+        if (!declared.has(host)) {
+            lines.push(`A script in this run uses net access to ${host}. The manifest does not declare that host.`);
+        }
+    }
+    return lines;
+}
+/** The bundle-filesystem grants a manifest declares under `permissions.bundle` (`'read'` / `'write:.cache/'`), or `[]` when it declares none. */
+export function manifestBundleFsGrants(manifest) {
+    return manifest.permissions?.bundle ?? [];
+}
+/**
+ * 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 const MAX_PERSISTED_BUNDLE_CACHE_BYTES = 1_000_000;
+/**
+ * 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 function encodeBundleCacheForStorage(files) {
+    const encoded = {};
+    let total = 0;
+    for (const [path, bytes] of Object.entries(files)) {
+        total += bytes.length;
+        if (total > MAX_PERSISTED_BUNDLE_CACHE_BYTES)
+            return undefined;
+        encoded[path] = Buffer.from(bytes).toString('base64');
+    }
+    return encoded;
+}
+/**
+ * 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 function decodeBundleCacheFromStorage(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return {};
+    }
+    const out = {};
+    for (const [path, encoded] of Object.entries(value)) {
+        if (typeof encoded !== 'string')
+            continue;
+        try {
+            out[path] = new Uint8Array(Buffer.from(encoded, 'base64'));
+        }
+        catch {
+            // Skip a value that isn't valid base64 rather than failing the whole
+            // decode — one corrupt entry shouldn't take down every other cached
+            // file.
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,232 @@
+/**
+ * Slice 2's grant/prompt flow (docs: GitHub issue #1's locked design
+ * comment) — vscode-free by design, same split as `./run-host.ts` and
+ * `./script-requirements.ts`: this module decides WHAT to prompt and WHAT
+ * to persist, but never calls `vscode.window.showInformationMessage` or
+ * `context.workspaceState` directly. The extension-host adapter
+ * (`extension.ts`/`preview-panel.ts` — the only files allowed to import
+ * `vscode`) supplies the actual prompt UI and Memento, both behind the thin
+ * interfaces below, so this file stays unit-testable with plain fakes.
+ *
+ * ## Keying
+ *
+ * `computeGrantKey` (`@markii/runtime`) hashes the note's executable
+ * closure — that closure is its own script blocks
+ * (`RunRequirements.grantScripts`) plus, for a bundle-backed run, the
+ * resolved source text of every `src=`-referenced script file
+ * (`GrantFlowRequirements.bundleModules`, F-1 fix), with `vaultModules`/
+ * `packs` left empty: `require` (bundle-local or pack) stays unwired for
+ * the whole `.mkz` Run-path arc (GitHub issue #9's design comment), so a
+ * bundle-backed run's closure has no OTHER bundle-local code to fold in
+ * yet beyond its `src=` targets. Any edit to any script's code — inline or
+ * `src=`-referenced — changes the hash, which is what makes "any code
+ * change re-prompts" fall out of the keying scheme for free rather than
+ * needing its own diffing logic here.
+ *
+ * The bundle-fs capability (`permissions.bundle`) is out of this module
+ * entirely (consent unification, SECURITY-RELEVANT): it needs no
+ * user-facing prompt, so it is never part of `GrantFlowRequirements`, the
+ * stored grant, or the grant key. `./run-flow.ts` passes the manifest's
+ * declared bundle-fs grants straight through to `spawnRun` — see its own
+ * comment on why that is still safe (path-jail + the read-only tier for
+ * auto/scheduled, both unaffected by this module).
+ *
+ * ## Storage
+ *
+ * One `{key, allowedHosts}` record per document, keyed by the document's
+ * URI string, all held under one Memento key (`GRANTS_STORAGE_KEY`) as a
+ * plain map. A stored record whose `key` no longer matches the freshly
+ * computed one is a MISS — this module never trusts a stale record's
+ * `allowedHosts`, even partially; the whole grant re-derives from scratch.
+ * A record is only ever WRITTEN when `allowedHosts` ends up non-empty — a
+ * full decline is never persisted, so it simply re-prompts next time (see
+ * `runGrantFlow`'s own comment on this, C-3) — and `clearGrantForDocument`
+ * removes a document's record outright, for the `markii.resetScriptGrants`
+ * command.
+ *
+ * ## The prompt shapes
+ *
+ * - One prompt per statically-known host (`promptHost`), worded exactly
+ *   "This note's scripts can send data to <host>. Allow?" — see
+ *   `hostPromptMessage`. Used only while the distinct safe host count is at
+ *   or under `MAX_HOST_PROMPTS`; above that, `promptManyHosts` (below) takes
+ *   over instead so a note can never turn one Run press into a wall of
+ *   modals (the PROMPT-STORM fix — see `MAX_HOST_PROMPTS`'s doc comment).
+ * - `promptManyHosts`, exactly once, in place of the whole per-host loop
+ *   when there are more than `MAX_HOST_PROMPTS` distinct safe hosts: one
+ *   all-or-nothing gate ("This note requests network access to many hosts
+ *   (N). Allow all or deny all?", `manyHostsPromptMessage`) rather than N
+ *   separate dialogs.
+ * - Exactly one extra prompt (`promptUnknownHosts`,
+ *   `UNKNOWN_HOSTS_PROMPT_MESSAGE`) when the closure could reach hosts that
+ *   cannot be listed in advance (`RunRequirements.hasUnknownHosts`, or a
+ *   host string this module refuses to render — see `isSafeHostForPrompt`).
+ *   Accepting it does NOT add anything to `allowedHosts` — there is no host
+ *   name to grant — it is a consent gate: declining it clears every
+ *   already-collected per-host answer too, since a script that can reach
+ *   addresses it never named cannot be trusted to only use the hosts it DID
+ *   name. A dynamically-built address a script hits at RUN TIME, whether or
+ *   not this prompt was accepted, is never added to `allowedHosts` here (it
+ *   is not known in advance); it fails at execution with the ordinary
+ *   `'capability-denied'` kind, same as any other ungranted host.
+ */
+import { type GrantClosureScript } from '@markii/runtime';
+/** The subset of `RunRequirements` (`./script-requirements.ts`) this flow needs — kept structural rather than importing the whole interface, so a fake in tests doesn't need to fabricate `scripts`. */
+export interface GrantFlowRequirements {
+    readonly hosts: readonly string[];
+    readonly hasUnknownHosts: boolean;
+    readonly grantScripts: readonly GrantClosureScript[];
+    /**
+     * Bundle-relative `src=` script path -> source text, for every `src=`
+     * block among `grantScripts` whose file content the host has resolved
+     * (F-1 fix) — `./bundle-run.ts`'s `bundleModulesFromSnapshot`, run over
+     * the same in-memory bundle snapshot the run itself will use. Omitted or
+     * empty for a bare `.mk.md` document (which has no bundle to resolve
+     * `src=` targets from) or a bundle whose scripts have no `src=` blocks.
+     * Folded into `closureFrom`'s `GrantClosure.bundleModules` so
+     * `computeGrantKey` hashes the REFERENCED file's bytes, not just the
+     * (empty) `code` field a `src=` block carries in the note's own text —
+     * without this, swapping a bundle script's contents while the note text
+     * stays byte-identical would silently re-run new code under an old,
+     * un-reprompted grant.
+     */
+    readonly bundleModules?: Readonly<Record<string, string>>;
+}
+/**
+ * The `Thenable` shape `vscode.Memento.update` actually returns — restated
+ * here (rather than importing `vscode`, which this file must never do) so
+ * a real `vscode.Memento` is assignable to `GrantMemento` with no adapter
+ * class, and a plain `Promise`-returning fake satisfies it in tests too.
+ */
+export interface Thenable<T> {
+    then<TResult1 = T, TResult2 = never>(onFulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onRejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
+}
+/** The exact shape of `vscode.Memento` this module uses — `context.workspaceState` satisfies this directly. */
+export interface GrantMemento {
+    get<T>(key: string): T | undefined;
+    get<T>(key: string, defaultValue: T): T;
+    update(key: string, value: unknown): Thenable<void>;
+}
+/** Prompts once for `host`, resolving `true` for Allow, `false` for Don't allow (or the prompt being dismissed). */
+export type PromptHost = (host: string, declaredHosts: readonly string[]) => Promise<boolean>;
+/** Prompts once for the "this note builds a network address dynamically" consent gate. */
+export type PromptUnknownHosts = () => Promise<boolean>;
+/** Prompts once for the consolidated "many hosts" gate (PROMPT-STORM fix) — resolves `true` for Allow all, `false` for Deny all. */
+export type PromptManyHosts = (hostCount: number) => Promise<boolean>;
+export interface GrantFlowOptions {
+    /** Stable identity for the note this run belongs to — `vscode.Uri.toString()` of the document, in the real adapter. */
+    documentKey: string;
+    requirements: GrantFlowRequirements;
+    memento: GrantMemento;
+    promptHost: PromptHost;
+    /**
+     * Hostnames the note's own scripts declare through their `permissions`
+     * fence attribute, for `hostPromptMessage` to show beside the host being
+     * asked about. Display only: what is actually prompted for, and what can
+     * be granted, comes from `requirements.hosts` (the literal-URL scan) and
+     * nothing else.
+     */
+    declaredHosts?: readonly string[];
+    promptUnknownHosts: PromptUnknownHosts;
+    /** Consolidated gate used instead of the per-host loop once the distinct static host count exceeds `MAX_HOST_PROMPTS` — see that constant's doc comment. */
+    promptManyHosts: PromptManyHosts;
+}
+export interface GrantFlowResult {
+    /** The hostnames this run's `net.*` calls may reach — exactly what `spawnRun`'s `netAllowlist` (`./run-host.ts`) expects. */
+    allowedHosts: string[];
+}
+/**
+ * Exact prompt wording — normative per the locked design comment. Exported
+ * so a test (and the adapter that renders it) both anchor on the same
+ * string.
+ *
+ * `declaredHosts` is what the note's own scripts declare through their
+ * `permissions` fence attribute (`./script-requirements.ts`'s
+ * `scriptDeclaredHosts`). It is DISPLAY-ONLY: it never changes what is
+ * prompted for or granted, only what the user reads before answering, so
+ * a note cannot talk its way into a host the literal-URL scan did not
+ * find. `host` is always the one host this prompt asks about. With no
+ * declaration the wording is unchanged, so a host that does not pass the
+ * list sees exactly the message it saw before.
+ */
+export declare function hostPromptMessage(host: string, declaredHosts?: readonly string[]): string;
+/** Exact wording of the one extra "hosts can't be listed in advance" prompt. */
+export declare const UNKNOWN_HOSTS_PROMPT_MESSAGE = "This note builds network addresses at run time, which can't be listed in advance and will be denied; only the hosts written directly in the note can be granted. Allow those?";
+/** Button labels every prompt in this flow uses — both a plain "Allow" and a "Don't allow" refusal are always offered, never a bare dismiss-only message. */
+export declare const ALLOW_LABEL = "Allow";
+export declare const DONT_ALLOW_LABEL = "Don't allow";
+/**
+ * PROMPT-STORM fix (report section 8, item 6, docs/archive/PENTEST-REPORT-2026-08-23.md):
+ * `runGrantFlow`'s per-host loop below is sequential and modal, one dialog
+ * per statically-extracted host. A hostile note with hundreds of literal
+ * `net.fetch_json("https://hostN/")` calls would otherwise re-open hundreds
+ * of modals on EVERY `markii.runScripts` press — and because a FULL decline
+ * is deliberately never persisted (C-3, so one mis-click can't permanently
+ * lock out network access), nothing about answering them once makes them
+ * stop recurring on the next Run press either. That makes the per-host loop
+ * itself a denial-of-service surface against the user's own attention, not
+ * just an annoyance.
+ *
+ * The guard: cap how many per-host prompts one run will ever show. When the
+ * distinct SAFE static host count is at or under this cap, the ordinary
+ * per-host flow runs exactly as before (this is overwhelmingly the common
+ * case — most notes touch a small, fixed set of APIs). Above the cap, the
+ * per-host loop is skipped entirely in favor of ONE consolidated prompt
+ * (`promptManyHosts`) that grants either every one of those hosts or none of
+ * them — still a single, honest, all-or-nothing consent decision, just sized
+ * to the actual scale of what's being asked, rather than a wall of modals a
+ * user would rationally start rubber-stamping. 10 is comfortably above what
+ * a legitimate dashboard-style note (docs/scripting.md's callout on
+ * dashboards being a first-class use case) is expected to reach while still
+ * catching a hostile host list before it becomes hundreds of dialogs.
+ */
+export declare const MAX_HOST_PROMPTS = 10;
+/** Exact wording of the consolidated "many hosts" gate — normative, mirroring `hostPromptMessage`/`UNKNOWN_HOSTS_PROMPT_MESSAGE`'s pattern of an exported, test-anchored string. */
+export declare function manyHostsPromptMessage(hostCount: number): string;
+export declare function isSafeHostForPrompt(host: string): boolean;
+/**
+ * Runs the whole grant flow for one Run press: computes the closure's grant
+ * key, reuses a matching stored grant with NO prompting at all, or (on a
+ * miss — first run or any code change) prompts fresh for every host and the
+ * unknown-hosts gate, persists the result, and returns the allowlist
+ * `spawnRun` should use.
+ */
+export declare function runGrantFlow(options: GrantFlowOptions): Promise<GrantFlowResult>;
+/**
+ * The NON-INTERACTIVE half of `runGrantFlow`, for auto/scheduled runs
+ * (GitHub issue #11): resolves this note's effective net + bundle-fs
+ * allowlist from ONLY what is already persisted, and NEVER prompts, NEVER
+ * writes. It is exactly `runGrantFlow`'s stored-grant fast path in
+ * isolation.
+ *
+ * This is the code half of the security promise auto/scheduled execution
+ * makes (docs/security.md, docs/scripting.md): a run that was not triggered
+ * by a click must never open a modal on a timer, and must never widen what
+ * the note can reach beyond a grant the user already made by hand under the
+ * exact same executable closure. On ANY miss — no stored grant, a grant for
+ * different code (the key no longer matches), or a stored host that fails
+ * today's `isSafeHostForPrompt` re-check (N-6) — this returns an EMPTY
+ * allowlist rather than falling back to prompting. An ungranted host then
+ * fails at execution with the ordinary `'capability-denied'` kind, exactly
+ * as it would on a manual run the user declined, and the consuming
+ * component shows its quiet stale/empty state.
+ *
+ * The read-only tier (`tierForTrigger('auto'|'scheduled')` in
+ * `@markii/runtime`) is a SEPARATE, independent gate applied in the worker;
+ * this function governs only which hosts are reachable, that one governs
+ * which capabilities (no POST/PATCH/bundle-write) may run at all.
+ */
+export declare function resolveStoredGrant(options: {
+    documentKey: string;
+    requirements: GrantFlowRequirements;
+    memento: GrantMemento;
+}): Promise<GrantFlowResult>;
+/**
+ * Clears the persisted grant (if any) for `documentKey` — the
+ * `markii.resetScriptGrants` command's whole implementation (C-3): with no
+ * stored record, `runGrantFlow`'s next call for this document is
+ * indistinguishable from a first run, so it prompts fresh for every host
+ * again. A no-op, not an error, when there is nothing stored for this
+ * document.
+ */
+export declare function clearGrantForDocument(memento: GrantMemento, documentKey: string): Promise<void>;