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

package/dist/run/script-requirements.js

@@ -0,0 +1,212 @@
+import { extractScripts, parse } from '@markii/core';
+/** The three host-reaching capability calls this scan looks for (docs/scripting.md's `net` table). */
+const NET_CALL_NAMES = ['fetch_json', 'post', 'patch'];
+const CALL_SITE_PATTERN = new RegExp(`\\bnet\\.(${NET_CALL_NAMES.join('|')})\\s*\\(`, 'g');
+/**
+ * Given `source` and the index of the character immediately after a call's
+ * opening `(` (already matched by `CALL_SITE_PATTERN`), returns the raw
+ * text of that call's FIRST argument — up to (not including) the first
+ * top-level `,` or the call's closing `)`, tracking nested
+ * `(`/`)`/`[`/`]`/`{`/`}` depth and quoted strings so a comma or paren
+ * INSIDE a nested expression or a quoted string never ends the scan early.
+ * Returns `undefined` if the call is unterminated (no matching close found
+ * before the source ends) — a malformed/incomplete script, treated the
+ * same as any other non-literal argument by the caller.
+ */
+function extractFirstArgument(source, argStart) {
+    let depth = 0;
+    let quote;
+    for (let i = argStart; i < source.length; i++) {
+        const ch = source[i];
+        if (quote) {
+            if (ch === '\\') {
+                i++; // skip the escaped character, whatever it is
+                continue;
+            }
+            if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '(' || ch === '[' || ch === '{') {
+            depth++;
+            continue;
+        }
+        if (ch === ')' || ch === ']' || ch === '}') {
+            if (depth === 0 && ch === ')') {
+                return source.slice(argStart, i);
+            }
+            depth--;
+            continue;
+        }
+        if (ch === ',' && depth === 0) {
+            return source.slice(argStart, i);
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether `text` is EXACTLY one quoted string literal with nothing else
+ * around it (only leading/trailing whitespace) — the one shape this scan
+ * trusts as "a literal URL", per this module's top doc comment. Anything
+ * else (a `..` concatenation, a bare identifier, a function call, a second
+ * literal joined to the first) fails this and is reported as unknown
+ * rather than guessed at.
+ */
+const SOLE_STRING_LITERAL = /^\s*(["'])((?:\\.|(?!\1)[^\\])*)\1\s*$/;
+function literalStringValue(argument) {
+    const match = SOLE_STRING_LITERAL.exec(argument);
+    if (!match)
+        return undefined;
+    // Unescape only the two escapes Lua string literals actually need for a
+    // URL to round-trip (`\\` and the literal's own quote character) — this
+    // is a best-effort textual scan, not a full Lua string-literal decoder;
+    // any other backslash escape is left as-is (harmless: it would simply
+    // fail `new URL(...)` below, falling through to "not a literal we can
+    // use" as intended for `hasUnknownHosts`, rather than corrupting a URL
+    // that didn't have JavaScript-different escapes to begin with).
+    return (match[2] ?? '').replace(/\\(.)/g, '$1');
+}
+/** Bare, lowercased hostname from a URL string, or `undefined` if it doesn't parse as an absolute URL. */
+function hostnameOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Scans one script block's Lua source for `net.*` call sites and folds
+ * their findings into `hosts`/`markUnknown` — see this module's top doc
+ * comment for the literal-only matching rule.
+ */
+function scanForHosts(code, hosts, markUnknown) {
+    CALL_SITE_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = CALL_SITE_PATTERN.exec(code)) !== null) {
+        const argStart = match.index + match[0].length;
+        const argument = extractFirstArgument(code, argStart);
+        if (argument === undefined) {
+            markUnknown();
+            continue;
+        }
+        const literal = literalStringValue(argument);
+        if (literal === undefined) {
+            // Present but not a sole literal -- a concatenation, a variable, a
+            // nested call, ... exactly the "cannot resolve statically" case.
+            markUnknown();
+            continue;
+        }
+        const host = hostnameOf(literal);
+        if (host === undefined) {
+            // Syntactically a literal, but not a URL `new URL()` can parse
+            // (e.g. a bare path or template-ish string) -- still unknown to us.
+            markUnknown();
+            continue;
+        }
+        hosts.add(host);
+    }
+}
+/**
+ * Bare, already-lowercased hostnames every script block in `scripts`
+ * declares via its own `permissions` fence attribute
+ * (`@markii/core`'s `ScriptBlock.permissions`), deduplicated, in
+ * first-seen (document, then per-script list) order. Mirrors
+ * `./bundle-run.ts`'s `manifestNetHosts` for the bundle-manifest
+ * equivalent: this is DECLARED INTENT only, exactly like a manifest's
+ * `permissions.net` — `scanRunRequirementHosts` above stays the ONLY
+ * source of the hostnames a run is actually prompted for. A caller
+ * compares this against the scanned set with
+ * `./bundle-run.ts`'s `netDeclarationDiagnostics` (the same
+ * declared-vs-scanned diff a bundle manifest already gets), and may show
+ * it next to the scanned hosts in a grant prompt as "declares: ...".
+ */
+export function scriptDeclaredHosts(scripts) {
+    const hosts = new Set();
+    for (const block of scripts) {
+        for (const host of block.permissions ?? []) {
+            hosts.add(host);
+        }
+    }
+    return [...hosts];
+}
+function toGrantClosureScript(block) {
+    const script = {
+        name: block.name,
+        lang: block.lang,
+        code: block.code,
+    };
+    if (block.src !== undefined)
+        script.src = block.src;
+    return script;
+}
+/**
+ * Parses `text` and returns its script blocks, in both the raw
+ * `@markii/core` `ScriptBlock` shape and the `GrantClosureScript` shape
+ * `computeGrantKey` hashes. Split out from `extractRunRequirements` (below)
+ * so a caller that needs to resolve `src=` script content BEFORE scanning
+ * for hosts — a bundle run, which must read the referenced file out of its
+ * snapshot first — can do so without parsing the document twice.
+ */
+export function extractScriptBlocks(text) {
+    const tree = parse(text);
+    const scripts = extractScripts(tree);
+    return { scripts, grantScripts: scripts.map(toGrantClosureScript) };
+}
+/**
+ * Scans `scripts` for statically-resolvable `net.*` hosts — an INLINE
+ * block's own `code`, or (when `resolveScriptSource` is given and resolves
+ * it) a `src=` block's referenced source. A `src=` block with no resolution
+ * available folds into `hasUnknownHosts`, same as this module has always
+ * done for a bare `.mk.md` document's `src=` references (their source
+ * genuinely isn't in `text` at all).
+ */
+export function scanRunRequirementHosts(scripts, resolveScriptSource) {
+    const hosts = new Set();
+    let hasUnknownHosts = false;
+    const markUnknown = () => {
+        hasUnknownHosts = true;
+    };
+    for (const block of scripts) {
+        if (block.src !== undefined) {
+            const resolved = resolveScriptSource?.(block);
+            if (resolved === undefined) {
+                // The referenced file's source isn't available to this scan --
+                // its net usage, if any, is entirely unknown. See this module's
+                // top doc comment.
+                markUnknown();
+                continue;
+            }
+            scanForHosts(resolved, hosts, markUnknown);
+            continue;
+        }
+        scanForHosts(block.code, hosts, markUnknown);
+    }
+    return { hosts: [...hosts], hasUnknownHosts };
+}
+/**
+ * Computes `RunRequirements` for `text` — parses it with `@markii/core`'s
+ * `parse`, pulls its script blocks with `extractScripts`, and scans each
+ * INLINE block's own source for statically-resolvable `net.*` hosts. Pure:
+ * no I/O, no `vscode`, safe to call on every keystroke if a future slice
+ * wants a live preview of what a run would ask for.
+ *
+ * `resolveScriptSource`, when given, lets a `src=` block's hosts be
+ * resolved too (a bundle run passes one backed by its snapshot); omitted,
+ * every `src=` block folds into `hasUnknownHosts` exactly as before this
+ * option existed.
+ */
+export function extractRunRequirements(text, resolveScriptSource) {
+    const { scripts, grantScripts } = extractScriptBlocks(text);
+    const { hosts, hasUnknownHosts } = scanRunRequirementHosts(scripts, resolveScriptSource);
+    return {
+        scripts,
+        hosts,
+        hasUnknownHosts,
+        grantScripts,
+    };
+}

package/dist/run/snapshot-storage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A `@markii/bundle` `BundleStorage` backed by a plain in-memory snapshot
+ * (a `path -> bytes` record) — never a live zip handle or a disk path. This
+ * is what the worker (`./worker-entry.ts`) hands to `@markii/bundle`'s
+ * `createScriptView`, so a run's `bundle.read`/`write`/`exists` calls never
+ * touch anything outside the bytes the host chose to include in the
+ * snapshot (`./bundle-run.ts`'s `buildBundleSnapshot`).
+ *
+ * `write` is reachable only through `ScriptView` (`@markii/bundle`), which
+ * already gates every write with `isWriteAllowed` before ever calling
+ * here — this storage does not re-derive that policy, matching
+ * `./storage.ts`'s own division of labor (`ScriptView` decides WHETHER a
+ * path may be written; a `BundleStorage` only knows HOW). What this module
+ * DOES enforce, unconditionally, is the same path-jail every
+ * `BundleStorage` implementation must (`@markii/bundle`'s own doc comment
+ * on `BundleStorage`): every path is normalized via `normalizeBundlePath`
+ * before it ever touches the underlying `Map`.
+ */
+import type { BundleStorage } from '@markii/bundle';
+export interface SnapshotStorage extends BundleStorage {
+    /** The storage's current contents, after any writes a run performed — used by the host to extract `.cache/` output once a run finishes. */
+    currentFiles(): Record<string, Uint8Array>;
+}
+/** Builds a `BundleStorage` over `initialFiles`, copying it so the caller's own object is never mutated by a later write. */
+export declare function createSnapshotStorage(initialFiles: Record<string, Uint8Array>): SnapshotStorage;

package/dist/run/snapshot-storage.js

@@ -0,0 +1,31 @@
+import { BundlePathError, normalizeBundlePath } from '@markii/bundle';
+function normalizeOrThrow(path) {
+    const result = normalizeBundlePath(path);
+    if (!result.ok) {
+        throw new BundlePathError(path, result.reason);
+    }
+    return result.path;
+}
+/** Builds a `BundleStorage` over `initialFiles`, copying it so the caller's own object is never mutated by a later write. */
+export function createSnapshotStorage(initialFiles) {
+    const map = new Map(Object.entries(initialFiles));
+    return {
+        async read(path) {
+            return map.get(normalizeOrThrow(path));
+        },
+        async write(path, data) {
+            map.set(normalizeOrThrow(path), data);
+        },
+        async list() {
+            return [...map.keys()].sort();
+        },
+        async exists(path) {
+            return map.has(normalizeOrThrow(path));
+        },
+        async size(path) {
+            const data = map.get(normalizeOrThrow(path));
+            return data === undefined ? undefined : data.length;
+        },
+        currentFiles: () => Object.fromEntries(map),
+    };
+}

package/dist/run/stale-values.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The tiny, vscode-free transform that turns a document's PERSISTED value
+ * store (`./run-flow.ts`'s `readPersistedValues`) into the value store the
+ * host re-posts to the webview when a note is (re)opened — GitHub issue #11,
+ * gap 1. "Opening a note ... showing its last data marked as stale where
+ * appropriate" (docs/spec.md, docs/scripting.md): a reopened monitoring note
+ * renders its last figures instantly and offline, visibly stale, before (or
+ * without) any re-run.
+ *
+ * The only transform is on `status`: a value that was `'fresh'` becomes
+ * `'stale'` (it is last-known data, not the product of the current session's
+ * run); a value that is already `'stale'` stays stale; an `'error'`/
+ * `'missing'` value is left untouched (there is nothing usable to mark
+ * stale — the consuming component shows its own error/empty state). Every
+ * other field is passed through verbatim, and the raw `error` text was
+ * already stripped before these values were ever persisted
+ * (`./run-flow.ts`'s `scrubValuesForWire`), so this never has to scrub again.
+ */
+import type { StoredValue } from '@markii/runtime';
+/**
+ * A copy of `persisted` with every `'fresh'` value demoted to `'stale'` —
+ * see this module's doc comment. Returns a fresh object; never mutates the
+ * input (which may be the caller's live persisted snapshot).
+ */
+export declare function staleValuesForRehydration(persisted: Record<string, StoredValue>): Record<string, StoredValue>;

package/dist/run/stale-values.js

@@ -0,0 +1,32 @@
+/** The `status` a persisted value is shown with on rehydration — `'fresh'` demotes to `'stale'`; everything else is unchanged. */
+function staleStatus(status) {
+    return status === 'fresh' ? 'stale' : status;
+}
+/**
+ * A copy of `persisted` with every `'fresh'` value demoted to `'stale'` —
+ * see this module's doc comment. Returns a fresh object; never mutates the
+ * input (which may be the caller's live persisted snapshot).
+ */
+export function staleValuesForRehydration(persisted) {
+    const entries = [];
+    for (const [name, value] of Object.entries(persisted)) {
+        // A persisted store is only guarded down to "plain object" when it is
+        // read back (`./run-flow.ts`'s `isStoredValueRecord`), so a corrupt or
+        // foreign ENTRY reaches here unchecked. Reading `.status` off a `null`
+        // entry would throw, and this transform runs on the host before the
+        // protocol guard ever sees the values, so the throw would land in the
+        // rehydration path rather than being rejected on the wire. Skip an
+        // unusable entry instead: a value that cannot be understood is exactly
+        // a value with nothing to re-show.
+        if (typeof value !== 'object' || value === null)
+            continue;
+        entries.push([name, { ...value, status: staleStatus(value.status) }]);
+    }
+    // `Object.fromEntries`, not `out[name] = ...`: a plain assignment of the
+    // name `__proto__` hits `Object.prototype`'s setter, which sets the
+    // object's prototype and creates NO own property, silently dropping that
+    // value. `__proto__` is a legal script name (docs/spec.md's
+    // `[A-Za-z_][A-Za-z0-9_-]*`), so this is reachable from an ordinary note.
+    // `fromEntries` defines each key as an own property, `__proto__` included.
+    return Object.fromEntries(entries);
+}

package/dist/run/worker-entry-browser.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The Web Worker isolate entry, for a host that cannot create a worker
+ * thread. An Obsidian plugin is the case that forced it: its Electron
+ * renderer rejects `node:worker_threads` outright ("The V8 platform used by
+ * this instance of Node does not support creating Workers"), and forking a
+ * Node child through `ELECTRON_RUN_AS_NODE` was measured failing there too.
+ *
+ * Everything a run actually DOES lives in `./run-job.ts` and is shared with
+ * the Node entry, so the sandbox, the tier gate, the marshaling limits, and
+ * the failure classification cannot drift between hosts. This file supplies
+ * only the two things a Web Worker has to do differently:
+ *
+ *   1. Network goes through `./net-bridge.ts` to the host, which still has
+ *      Node and runs the same pinned provider as before. The isolate itself
+ *      has no network stack, which makes the allowlist unbypassable from
+ *      inside it.
+ *   2. wasmoon's `glue.wasm` arrives as a URL on the job, because there is
+ *      no `__dirname` here to find it beside the bundle.
+ *
+ * The protocol is the same one-job-in, one-result-out shape `run-host.ts`
+ * expects, with net traffic interleaved: any message that is not a net
+ * reply is the job.
+ */
+import { type RunJob } from './run-job.js';
+/** The Web Worker global surface this entry uses, named so the file typechecks without DOM lib types. */
+interface WorkerGlobal {
+    postMessage: (message: unknown) => void;
+    addEventListener: (type: 'message', listener: (event: {
+        data: unknown;
+    }) => void) => void;
+}
+/**
+ * A job for this entry additionally carries where `glue.wasm` can be
+ * fetched from — a blob URL the host minted from the file on disk. Absent,
+ * wasmoon falls back to its own resolution, which in a Web Worker will not
+ * find anything; the host is expected to always send it.
+ */
+export interface BrowserRunJob extends RunJob {
+    wasmUri?: string;
+}
+declare function start(scope: WorkerGlobal): void;
+export { start as startBrowserWorker };

package/dist/run/worker-entry-browser.js

@@ -0,0 +1,77 @@
+/**
+ * The Web Worker isolate entry, for a host that cannot create a worker
+ * thread. An Obsidian plugin is the case that forced it: its Electron
+ * renderer rejects `node:worker_threads` outright ("The V8 platform used by
+ * this instance of Node does not support creating Workers"), and forking a
+ * Node child through `ELECTRON_RUN_AS_NODE` was measured failing there too.
+ *
+ * Everything a run actually DOES lives in `./run-job.ts` and is shared with
+ * the Node entry, so the sandbox, the tier gate, the marshaling limits, and
+ * the failure classification cannot drift between hosts. This file supplies
+ * only the two things a Web Worker has to do differently:
+ *
+ *   1. Network goes through `./net-bridge.ts` to the host, which still has
+ *      Node and runs the same pinned provider as before. The isolate itself
+ *      has no network stack, which makes the allowlist unbypassable from
+ *      inside it.
+ *   2. wasmoon's `glue.wasm` arrives as a URL on the job, because there is
+ *      no `__dirname` here to find it beside the bundle.
+ *
+ * The protocol is the same one-job-in, one-result-out shape `run-host.ts`
+ * expects, with net traffic interleaved: any message that is not a net
+ * reply is the job.
+ */
+import { isRunJob, resultForInternalError, runJob, } from './run-job.js';
+import { createNetBridge } from './net-bridge-worker.js';
+function start(scope) {
+    const bridge = createNetBridge((message) => {
+        scope.postMessage(message);
+    });
+    let running = false;
+    scope.addEventListener('message', (event) => {
+        const message = event.data;
+        // Net replies arrive throughout the run; the bridge ignores anything
+        // that is not one of its own.
+        bridge.handleMessage(message);
+        if (running)
+            return;
+        if (typeof message === 'object' &&
+            message !== null &&
+            message.kind === 'markii:net-reply') {
+            return;
+        }
+        running = true;
+        void (async () => {
+            if (!isRunJob(message)) {
+                scope.postMessage(resultForInternalError(new Error('worker received a malformed job message'), {}));
+                return;
+            }
+            const job = message;
+            let result;
+            try {
+                result = await runJob(job, {
+                    createNet: () => bridge.provider,
+                    wasmUri: job.wasmUri,
+                    // GitHub issue #35: the same per-script message the Node entry
+                    // sends, on the same channel this worker posts its result on, so
+                    // ordering (progress before result) holds here too. Built in
+                    // `./run-job.ts`, never here.
+                    postProgress: (progress) => {
+                        scope.postMessage(progress);
+                    },
+                });
+            }
+            catch (err) {
+                result = resultForInternalError(err, job.cacheSnapshot ?? {});
+            }
+            scope.postMessage(result);
+        })();
+    });
+}
+// Guarded so importing this module in a test (or anywhere that is not a
+// worker) is inert rather than throwing on a missing `self`.
+if (typeof self !== 'undefined' &&
+    typeof self.addEventListener === 'function') {
+    start(self);
+}
+export { start as startBrowserWorker };

package/dist/run/worker-entry.d.ts

@@ -0,0 +1 @@
+export type { RunJob, RunFailure, RunProgress, RunResult } from './run-job.js';

package/dist/run/worker-entry.js

@@ -0,0 +1,96 @@
+/**
+ * The `worker_thread` entry point for slice 1 of the extension's v2 Run
+ * arc (docs: GitHub issue #1's locked design comment). This file is
+ * vscode-free — it never imports `vscode` and knows nothing about VS
+ * Code's API — so it can be unit-tested directly with Vitest (spawned as a
+ * REAL `node:worker_threads` worker, exercising the real wasmoon sandbox)
+ * and, unmodified, be the bundled worker `esbuild.config.mjs` produces for
+ * the packaged extension.
+ *
+ * ## Why a whole worker per run
+ *
+ * The design (docs/security.md's isolate requirement) is "one ephemeral
+ * worker per run": the host spawns a fresh thread, this file boots
+ * `@markii/lua` + `@markii/runtime` once, runs exactly one batch, posts
+ * back one progress message per script and then exactly one result
+ * message, and the whole thread is expected to be
+ * torn down by the host afterward (`run-host.ts`) regardless of how this
+ * run went. That is what makes the external wall-clock watchdog
+ * (`worker.terminate()`) an unconditional, always-available kill switch:
+ * it can never be blocked by anything this file's own code does, because
+ * `terminate()` acts on the OS/V8 thread itself, not on anything
+ * cooperative running inside it.
+ *
+ * ## Never an unhandled rejection
+ *
+ * Every path through `main()` below is wrapped so that ANY failure —
+ * a malformed job message, `parse()` throwing on pathological input,
+ * `runDocumentScripts` itself misbehaving — becomes an ordinary result
+ * message carrying a synthetic failure, never a thrown/rejected error that
+ * could surface as an "Unhandled Promise Rejection" on the worker thread
+ * (which Node would otherwise report noisily, or in the worst case treat
+ * as fatal depending on the host's process-wide `--unhandled-rejections`
+ * setting). `run-host.ts` therefore never needs an `unhandledRejection`
+ * listener on the worker to stay safe.
+ */
+import { parentPort } from 'node:worker_threads';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { netProviderDenial } from '@markii/lua';
+import { createNetProvider } from './net-provider.js';
+import { isRunJob, resultForInternalError, runJob } from './run-job.js';
+/**
+ * Resolves the `wasmUri` to hand `createLuaExecutor` (forwarded to
+ * `@markii/lua`'s `runScript` -> `createEmptyLuaEngine` -> wasmoon's
+ * `LuaFactory`). In the BUNDLED extension, `esbuild.config.mjs`'s worker
+ * build copies wasmoon's `glue.wasm` next to this file's compiled output
+ * (`dist/run/glue.wasm`) specifically so this lookup succeeds; in
+ * dev/Vitest (this file run straight from `src/run/`, no copy step has
+ * ever run), the file is absent and `undefined` is returned, letting
+ * wasmoon fall back to its own default Node resolution (the real
+ * `node_modules/wasmoon/dist/glue.wasm`) — see `@markii/lua`'s
+ * `createEmptyLuaEngine` doc comment for why `undefined` is always safe to
+ * pass here.
+ */
+function resolveWasmUri() {
+    const candidate = path.join(__dirname, 'glue.wasm');
+    return existsSync(candidate) ? candidate : undefined;
+}
+async function main() {
+    if (!parentPort) {
+        // Not actually running as a worker thread (e.g. required directly by
+        // mistake) — nothing to do, and nothing to post a result to.
+        return;
+    }
+    const port = parentPort;
+    port.once('message', (message) => {
+        void (async () => {
+            if (!isRunJob(message)) {
+                port.postMessage(resultForInternalError(new Error('worker received a malformed job message'), {}));
+                return;
+            }
+            try {
+                const result = await runJob(message, {
+                    // GitHub issue #35: one message per script, on the SAME port the
+                    // final result goes out on, so the host receives them in order
+                    // and always ahead of the result. Identical to what
+                    // `./worker-entry-browser.ts` does; the message itself is built
+                    // in `./run-job.ts` so the two cannot drift.
+                    postProgress: (progress) => {
+                        port.postMessage(progress);
+                    },
+                    // The Lua brand is supplied HERE, where the runtime is already
+                    // present, rather than imported by the provider itself — see
+                    // `./net-provider.ts`'s doc comment.
+                    createNet: (allowlist, maxFetchBytes, policy) => createNetProvider(allowlist, maxFetchBytes, policy, netProviderDenial),
+                    wasmUri: resolveWasmUri(),
+                });
+                port.postMessage(result);
+            }
+            catch (err) {
+                port.postMessage(resultForInternalError(err, message.cacheSnapshot ?? {}));
+            }
+        })();
+    });
+}
+void main();

package/dist/values-failure.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `ValuesFailure` is the wire-protocol shape a host uses to report one
+ * script's failure back to its renderer/webview: the script's name and a
+ * closed `FailureKind`, never the raw error message (the rendered page
+ * shows quiet markers, never error dumps — see AGENTS.md's cleanliness
+ * principle). Defined here, in the shared host layer, so every host
+ * (`apps/vscode`, and any future host) and this package's own `run-flow.ts`
+ * agree on a single definition instead of drifting copies; a consuming
+ * app's own wire-protocol module (e.g. `apps/vscode/src/protocol.ts`) is
+ * expected to import and re-export this type rather than restate it.
+ */
+import type { FailureKind } from '@markii/runtime';
+/** One script's outcome, reduced to just its name and failure kind — never the raw error message. */
+export interface ValuesFailure {
+    readonly name: string;
+    readonly kind: FailureKind;
+}

package/dist/values-failure.js

@@ -0,0 +1 @@
+export {};

package/dist/values-merge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The one way a host folds a single arriving value into the value store its
+ * preview is rendering from (GitHub issue #35).
+ *
+ * A run reports its values one at a time, in document order, while it is
+ * still going. Each arrival has to replace exactly one name and leave every
+ * other name exactly as it was — that is what makes the bound component go
+ * fresh while the rest of the note stays visibly stale, instead of the
+ * whole page flipping at the end of the batch.
+ *
+ * It lives here, in the shared host layer, because both hosts do it: the VS
+ * Code webview folds a `value` wire message into its React state, and the
+ * Obsidian view folds a callback's value into the store it re-renders from.
+ * Two copies of a merge this small still drift, and the `__proto__` rule
+ * below is exactly the kind of detail one copy would quietly lose.
+ *
+ * Environment-free on purpose (no `node:*`, no React), so the main entry
+ * can export it and a browser bundle can import it.
+ */
+import type { StoredValue } from '@markii/runtime';
+/**
+ * `values` with `name` set to `value`, as a NEW object — the input is never
+ * mutated, so a caller holding the previous store (React state, a view's
+ * last-rendered snapshot) can still compare against it.
+ *
+ * A name already present keeps its POSITION and takes the new value; a new
+ * name is appended. Order is not semantically meaningful to a renderer, but
+ * a store whose keys reshuffle on every value would make any diff of two
+ * snapshots harder to read than it needs to be.
+ *
+ * Built through `Object.fromEntries` rather than `{...values, [name]: value}`
+ * because a script may legitimately be named `__proto__` (docs/spec.md's
+ * name grammar allows it): a computed assignment of that key hits
+ * `Object.prototype`'s setter, which sets the object's prototype and
+ * creates no own property at all, silently dropping the value. The same
+ * guard is in `run/run-flow.ts`'s `mergePersistedValues` and
+ * `run/stale-values.ts`, for the same reason.
+ */
+export declare function mergeArrivingValue(values: Readonly<Record<string, StoredValue>> | undefined, name: string, value: StoredValue): Record<string, StoredValue>;

package/dist/values-merge.js

@@ -0,0 +1,33 @@
+/**
+ * `values` with `name` set to `value`, as a NEW object — the input is never
+ * mutated, so a caller holding the previous store (React state, a view's
+ * last-rendered snapshot) can still compare against it.
+ *
+ * A name already present keeps its POSITION and takes the new value; a new
+ * name is appended. Order is not semantically meaningful to a renderer, but
+ * a store whose keys reshuffle on every value would make any diff of two
+ * snapshots harder to read than it needs to be.
+ *
+ * Built through `Object.fromEntries` rather than `{...values, [name]: value}`
+ * because a script may legitimately be named `__proto__` (docs/spec.md's
+ * name grammar allows it): a computed assignment of that key hits
+ * `Object.prototype`'s setter, which sets the object's prototype and
+ * creates no own property at all, silently dropping the value. The same
+ * guard is in `run/run-flow.ts`'s `mergePersistedValues` and
+ * `run/stale-values.ts`, for the same reason.
+ */
+export function mergeArrivingValue(values, name, value) {
+    const entries = [];
+    let replaced = false;
+    for (const [key, existing] of Object.entries(values ?? {})) {
+        if (key === name) {
+            entries.push([key, value]);
+            replaced = true;
+            continue;
+        }
+        entries.push([key, existing]);
+    }
+    if (!replaced)
+        entries.push([name, value]);
+    return Object.fromEntries(entries);
+}