@markii/runtime 0.1.0 → 0.2.0

package/dist/failure.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The closed, runtime-owned failure taxonomy for a script execution outcome
+ * (DESIGN.md §8). This is the ONE vocabulary every concrete `ScriptExecutor`
+ * (e.g. `@markii/lua`'s `createLuaExecutor`) is expected to map its own
+ * language-specific failure shape down to, and the one vocabulary
+ * `@markii/react` (and any other renderer) is expected to branch its
+ * presentation on. No UI text lives in this package — `normalizeFailureKind`
+ * only classifies; a renderer decides what each kind is called on screen.
+ *
+ * - `'script-error'`      — the script itself threw, had a syntax error, or
+ *   returned a value that couldn't be marshaled back out. The default/
+ *   fallback bucket: anything not clearly one of the other three lands here,
+ *   INCLUDING a value this package cannot trust (see `normalizeFailureKind`).
+ * - `'capability-denied'` — the grant was absent, or the host actively
+ *   refused (an ungranted net host, a bundle path-jail rejection, a
+ *   fetch-size cap). The script asked for something it was never allowed.
+ * - `'tier-blocked'`      — the capability genuinely exists in the granted
+ *   set, but the CURRENT execution tier forbids exercising it (an effectful
+ *   op — `net.post`, `bundle.write` — attempted under the read-only
+ *   `'auto'`/`'scheduled'` tier). Distinct from `'capability-denied'`: a
+ *   manual run of the exact same script, with the exact same grants, would
+ *   succeed.
+ * - `'limit'`             — a resource limit was breached: instruction
+ *   count, wall-clock, or memory. The run was killed, not refused.
+ */
+export type FailureKind = 'script-error' | 'capability-denied' | 'tier-blocked' | 'limit';
+/** Every valid `FailureKind`, for exhaustive iteration/validation. Keep in sync with the `FailureKind` union by construction — see `normalizeFailureKind`'s runtime check against this exact tuple. */
+export declare const FAILURE_KINDS: readonly ["script-error", "capability-denied", "tier-blocked", "limit"];
+/**
+ * Normalizes an arbitrary, UNTRUSTED value into a `FailureKind`. This is the
+ * boundary guard for the whole taxonomy: `value` may be anything an
+ * executor — third-party code at runtime even when it's typed at compile
+ * time — chooses to hand back, including a forged string an untrusted
+ * executor supplied, a prototype-pollution attempt (`'__proto__'`,
+ * `'constructor'`), a stale/renamed kind from an older version of some
+ * executor, `undefined`, a number, or an object. ANYTHING not exactly one of
+ * `FAILURE_KINDS` normalizes to `'script-error'` — the safest default, since
+ * an unrecognized failure is treated as "the script did something wrong",
+ * never silently upgraded to a more privileged-sounding category like
+ * `'tier-blocked'` or `'capability-denied'`.
+ *
+ * Never throws.
+ */
+export declare function normalizeFailureKind(value: unknown): FailureKind;

package/dist/failure.js

@@ -0,0 +1,28 @@
+/** Every valid `FailureKind`, for exhaustive iteration/validation. Keep in sync with the `FailureKind` union by construction — see `normalizeFailureKind`'s runtime check against this exact tuple. */
+export const FAILURE_KINDS = [
+    'script-error',
+    'capability-denied',
+    'tier-blocked',
+    'limit',
+];
+/**
+ * Normalizes an arbitrary, UNTRUSTED value into a `FailureKind`. This is the
+ * boundary guard for the whole taxonomy: `value` may be anything an
+ * executor — third-party code at runtime even when it's typed at compile
+ * time — chooses to hand back, including a forged string an untrusted
+ * executor supplied, a prototype-pollution attempt (`'__proto__'`,
+ * `'constructor'`), a stale/renamed kind from an older version of some
+ * executor, `undefined`, a number, or an object. ANYTHING not exactly one of
+ * `FAILURE_KINDS` normalizes to `'script-error'` — the safest default, since
+ * an unrecognized failure is treated as "the script did something wrong",
+ * never silently upgraded to a more privileged-sounding category like
+ * `'tier-blocked'` or `'capability-denied'`.
+ *
+ * Never throws.
+ */
+export function normalizeFailureKind(value) {
+    return typeof value === 'string' &&
+        FAILURE_KINDS.includes(value)
+        ? value
+        : 'script-error';
+}

package/dist/grant-key.d.ts

@@ -0,0 +1,167 @@
+/**
+ * DESIGN.md §10 ("Security model"): "Grants are remembered per note, keyed
+ * by a hash of the note's full *executable closure* — its inline scripts,
+ * `src=` script files, required bundle-local modules, vault-library
+ * modules, and the versions of any pack modules it requires. If any of that
+ * code changes, the grant is stale and the host re-prompts; otherwise
+ * edited shared code would silently inherit grants that were made to
+ * different code."
+ *
+ * This module is that hash. It is deliberately inert: nothing here parses
+ * markdown, reads a file, or touches the network — the host (the piece that
+ * already knows how to walk a note's scripts, resolve its `src=` files,
+ * follow its `require`s into the bundle and the vault library, and read the
+ * installed pack manifest) assembles a `GrantClosure` and hands it in.
+ * `@markii/core`'s `ScriptBlock` is NOT imported here on purpose — this
+ * package stays independent of the parser layer (see CLAUDE.md's import
+ * rule); `GrantClosureScript` below is a local structural type that mirrors
+ * the fields that matter to the closure.
+ *
+ * ## Canonical serialization ("markii-grant-key/1")
+ *
+ * `computeGrantKey` serializes a `GrantClosure` to a single byte string and
+ * returns the lowercase hex SHA-256 digest of those bytes. The byte string
+ * is built as follows, and a second implementation (in any language) that
+ * follows this precisely reproduces byte-identical output for the same
+ * closure:
+ *
+ * Primitives:
+ * - `u32(n)`: 4 bytes, big-endian unsigned.
+ * - `str(s)`: `u32(byteLength)` followed by `s`'s UTF-8 bytes, where
+ *   `byteLength` is the UTF-8 *byte* length (as `TextEncoder` would
+ *   produce), never the string's UTF-16 code-unit `.length`. Every string
+ *   in the closure is framed this way — a length prefix, not a delimiter —
+ *   specifically so no delimiter character embedded in a name, path, or
+ *   source text can ever be mistaken for a field or section boundary.
+ * - `opt(s)`: one tag byte — `0x00` if `s` is `undefined`, `0x01` followed
+ *   by `str(s)` if it is present. This is what makes an absent optional
+ *   field distinguishable from one holding `""`  (`opt(undefined)` is one
+ *   byte; `opt("")` is `0x01` + `u32(0)`, five bytes).
+ *
+ * A *record* is the concatenation of its fields' encodings, in the fixed
+ * field order given below — records never carry their own outer length
+ * prefix, because their field-level length prefixes already make the byte
+ * stream self-delimiting given the record's known schema.
+ *
+ * A *set* of same-shaped records (used for anything that is conceptually
+ * unordered — an array of scripts, the entries of a `Record<string, …>`
+ * map) is encoded as `u32(count)` followed by each record's bytes, IN
+ * ASCENDING ORDER OF THE RECORD'S OWN ENCODED BYTES (lexicographic,
+ * shorter-is-less on equal prefix). Sorting by encoded bytes rather than by
+ * some "obvious" key (a name, a path) is what makes the digest depend only
+ * on the closure's *content*, never on the order the host happened to
+ * collect scripts in, or a `Record`'s key iteration order.
+ *
+ * A *section* is `tag(1 byte)` + a set, where `tag` is a fixed per-section
+ * constant (`0x01` scripts, `0x02` bundle modules, `0x03` vault modules,
+ * `0x04` packs). The tag exists so that two structurally different record
+ * shapes (e.g. a 2-field module record vs. a 4-field script record) can
+ * never be confused for each other even if some pathological input made
+ * their encoded byte counts coincide.
+ *
+ * The whole closure is:
+ *
+ * ```
+ * str("markii-grant-key/1")            // scheme/version marker
+ * section(0x01, scripts)                // GrantClosureScript records:
+ *                                        //   str(name) str(lang) opt(src) str(code)
+ * section(0x02, bundleModules)          // module records: str(path) str(source)
+ * section(0x03, vaultModules)           // namespace records:
+ *                                        //   str(namespace) + moduleSet
+ *                                        //   (moduleSet = u32(count) + sorted
+ *                                        //   module records: str(path) str(source);
+ *                                        //   note: no section tag inside — it's
+ *                                        //   nested in an already-tagged section)
+ * section(0x04, packs)                  // pack records:
+ *                                        //   str(namespace) str(version) opt-flag(1 byte)
+ *                                        //   + moduleSet only when the flag is 0x01
+ * ```
+ *
+ * `SHA-256(bytes)`, rendered as 64 lowercase hex characters, is the grant
+ * key. Bumping `markii-grant-key/1` to `/2` (or later) is how a future
+ * change to this scheme is made explicit and visible — any consumer keying
+ * off the literal string sees a different marker rather than a silent
+ * reinterpretation of old digests.
+ */
+/**
+ * One of the note's own script blocks — the inline `` ```lang {name=...}
+ * `` `` fences and the `src=`-referenced ones, in any order. Mirrors the
+ * fields of `@markii/core`'s `ScriptBlock` that are part of what actually
+ * *executes* (not `publish` or `position`, which don't change what code
+ * runs). Deliberately a local type — see this module's top doc comment for
+ * why `@markii/core` is never imported here.
+ */
+export interface GrantClosureScript {
+    /** The script fence's `name=` attribute — the value-store key it writes to. */
+    name: string;
+    /** The fence's language tag (e.g. `"lua"`), or `""` if the fence had none. */
+    lang: string;
+    /**
+     * Bundle-relative path when this block is a `src=` reference to a
+     * long-script file; `undefined` for an inline block. The referenced
+     * file's own source text is NOT here — it belongs in `bundleModules`,
+     * keyed by this same path, so its content participates in the closure
+     * too.
+     */
+    src?: string;
+    /**
+     * The fence's own body text. Empty (`""`) for a `src=` reference, whose
+     * code lives in the referenced file instead.
+     */
+    code: string;
+}
+/**
+ * One installed pack's identity, plus its module sources when the host has
+ * them. A pack's `version` alone must move the key even if the host never
+ * fetched its source — DESIGN.md §10 keys the grant to "the versions of any
+ * pack modules it requires", not only to code the host happens to have
+ * bytes for.
+ */
+export interface GrantClosurePack {
+    /** The pack's namespace (its directive-resolution prefix). */
+    namespace: string;
+    /** The installed version string (semver or otherwise). */
+    version: string;
+    /**
+     * Module path -> source text, when the host has resolved the pack's
+     * module sources. Omit the field entirely (not `{}`) when the host only
+     * knows the pack's identity, not its code — an empty map and "no map"
+     * are different closures and must hash differently.
+     */
+    modules?: Record<string, string>;
+}
+/**
+ * The full executable closure a grant is keyed to (DESIGN.md §10). Every
+ * field here must be populated by the host from whatever it has already
+ * resolved; `computeGrantKey` does no resolution of its own.
+ */
+export interface GrantClosure {
+    /** The note's own script blocks — inline and `src=`-referenced, in any order. */
+    scripts: GrantClosureScript[];
+    /**
+     * Bundle-relative script-file path -> source text, for every bundle-local
+     * module the closure requires: `src=` targets, and any modules those
+     * files (transitively) `require`.
+     */
+    bundleModules: Record<string, string>;
+    /**
+     * Vault-library module sources, keyed by vault namespace, then by module
+     * path -> source text.
+     */
+    vaultModules: Record<string, Record<string, string>>;
+    /** Installed pack modules the closure requires. */
+    packs: GrantClosurePack[];
+}
+/**
+ * Computes the grant key for a note's executable closure (DESIGN.md §10):
+ * the lowercase hex SHA-256 digest of the closure's canonical serialization
+ * — see this module's top doc comment for the exact byte form. Pure and
+ * side-effect free: this function does not parse, fetch, or read anything;
+ * the host must have already assembled `closure` from the note's scripts,
+ * resolved `src=`/`require` targets, and installed pack manifest.
+ *
+ * Uses `globalThis.crypto.subtle` (Web Crypto — available in Node >=20 and
+ * every browser) rather than `node:crypto`, so this package stays
+ * browser-safe with no added dependency.
+ */
+export declare function computeGrantKey(closure: GrantClosure): Promise<string>;

package/dist/grant-key.js

@@ -0,0 +1,224 @@
+/**
+ * DESIGN.md §10 ("Security model"): "Grants are remembered per note, keyed
+ * by a hash of the note's full *executable closure* — its inline scripts,
+ * `src=` script files, required bundle-local modules, vault-library
+ * modules, and the versions of any pack modules it requires. If any of that
+ * code changes, the grant is stale and the host re-prompts; otherwise
+ * edited shared code would silently inherit grants that were made to
+ * different code."
+ *
+ * This module is that hash. It is deliberately inert: nothing here parses
+ * markdown, reads a file, or touches the network — the host (the piece that
+ * already knows how to walk a note's scripts, resolve its `src=` files,
+ * follow its `require`s into the bundle and the vault library, and read the
+ * installed pack manifest) assembles a `GrantClosure` and hands it in.
+ * `@markii/core`'s `ScriptBlock` is NOT imported here on purpose — this
+ * package stays independent of the parser layer (see CLAUDE.md's import
+ * rule); `GrantClosureScript` below is a local structural type that mirrors
+ * the fields that matter to the closure.
+ *
+ * ## Canonical serialization ("markii-grant-key/1")
+ *
+ * `computeGrantKey` serializes a `GrantClosure` to a single byte string and
+ * returns the lowercase hex SHA-256 digest of those bytes. The byte string
+ * is built as follows, and a second implementation (in any language) that
+ * follows this precisely reproduces byte-identical output for the same
+ * closure:
+ *
+ * Primitives:
+ * - `u32(n)`: 4 bytes, big-endian unsigned.
+ * - `str(s)`: `u32(byteLength)` followed by `s`'s UTF-8 bytes, where
+ *   `byteLength` is the UTF-8 *byte* length (as `TextEncoder` would
+ *   produce), never the string's UTF-16 code-unit `.length`. Every string
+ *   in the closure is framed this way — a length prefix, not a delimiter —
+ *   specifically so no delimiter character embedded in a name, path, or
+ *   source text can ever be mistaken for a field or section boundary.
+ * - `opt(s)`: one tag byte — `0x00` if `s` is `undefined`, `0x01` followed
+ *   by `str(s)` if it is present. This is what makes an absent optional
+ *   field distinguishable from one holding `""`  (`opt(undefined)` is one
+ *   byte; `opt("")` is `0x01` + `u32(0)`, five bytes).
+ *
+ * A *record* is the concatenation of its fields' encodings, in the fixed
+ * field order given below — records never carry their own outer length
+ * prefix, because their field-level length prefixes already make the byte
+ * stream self-delimiting given the record's known schema.
+ *
+ * A *set* of same-shaped records (used for anything that is conceptually
+ * unordered — an array of scripts, the entries of a `Record<string, …>`
+ * map) is encoded as `u32(count)` followed by each record's bytes, IN
+ * ASCENDING ORDER OF THE RECORD'S OWN ENCODED BYTES (lexicographic,
+ * shorter-is-less on equal prefix). Sorting by encoded bytes rather than by
+ * some "obvious" key (a name, a path) is what makes the digest depend only
+ * on the closure's *content*, never on the order the host happened to
+ * collect scripts in, or a `Record`'s key iteration order.
+ *
+ * A *section* is `tag(1 byte)` + a set, where `tag` is a fixed per-section
+ * constant (`0x01` scripts, `0x02` bundle modules, `0x03` vault modules,
+ * `0x04` packs). The tag exists so that two structurally different record
+ * shapes (e.g. a 2-field module record vs. a 4-field script record) can
+ * never be confused for each other even if some pathological input made
+ * their encoded byte counts coincide.
+ *
+ * The whole closure is:
+ *
+ * ```
+ * str("markii-grant-key/1")            // scheme/version marker
+ * section(0x01, scripts)                // GrantClosureScript records:
+ *                                        //   str(name) str(lang) opt(src) str(code)
+ * section(0x02, bundleModules)          // module records: str(path) str(source)
+ * section(0x03, vaultModules)           // namespace records:
+ *                                        //   str(namespace) + moduleSet
+ *                                        //   (moduleSet = u32(count) + sorted
+ *                                        //   module records: str(path) str(source);
+ *                                        //   note: no section tag inside — it's
+ *                                        //   nested in an already-tagged section)
+ * section(0x04, packs)                  // pack records:
+ *                                        //   str(namespace) str(version) opt-flag(1 byte)
+ *                                        //   + moduleSet only when the flag is 0x01
+ * ```
+ *
+ * `SHA-256(bytes)`, rendered as 64 lowercase hex characters, is the grant
+ * key. Bumping `markii-grant-key/1` to `/2` (or later) is how a future
+ * change to this scheme is made explicit and visible — any consumer keying
+ * off the literal string sees a different marker rather than a silent
+ * reinterpretation of old digests.
+ */
+const SCHEME_VERSION = 'markii-grant-key/1';
+const SECTION_TAG = {
+    scripts: 0x01,
+    bundleModules: 0x02,
+    vaultModules: 0x03,
+    packs: 0x04,
+};
+const textEncoder = new TextEncoder();
+/**
+ * Concatenates byte chunks into ONE freshly allocated buffer. The return
+ * type is pinned to `Uint8Array<ArrayBuffer>` (never the default
+ * `ArrayBufferLike`, which also admits `SharedArrayBuffer`) by allocating
+ * through an explicit `new ArrayBuffer` — that is what lets the digest call
+ * in `computeGrantKey` pass this straight to `SubtleCrypto.digest`, whose
+ * `BufferSource` parameter excludes shared memory, with no cast anywhere.
+ */
+function concatBytes(chunks) {
+    let total = 0;
+    for (const chunk of chunks)
+        total += chunk.length;
+    const out = new Uint8Array(new ArrayBuffer(total));
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/** `u32(n)`: 4 bytes, big-endian. See the module doc comment's canonical form. */
+function encodeU32(n) {
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, n, false);
+    return bytes;
+}
+/**
+ * `str(s)`: length-prefixed UTF-8 bytes. The prefix is the UTF-8 BYTE
+ * length (via `TextEncoder`), never `s.length` (UTF-16 code units) — this
+ * is what keeps multi-byte text framed correctly.
+ */
+function encodeString(value) {
+    const bytes = textEncoder.encode(value);
+    return concatBytes([encodeU32(bytes.length), bytes]);
+}
+/** `opt(s)`: one tag byte, then `str(s)` only when present. See top doc comment. */
+function encodeOptionalString(value) {
+    if (value === undefined)
+        return new Uint8Array([0x00]);
+    return concatBytes([new Uint8Array([0x01]), encodeString(value)]);
+}
+/** Lexicographic byte-array comparison: shorter-is-less on equal prefix. */
+function compareBytes(a, b) {
+    const length = Math.min(a.length, b.length);
+    for (let i = 0; i < length; i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return a.length - b.length;
+}
+/** Sorts records by their own encoded bytes — never by an original array/map order. */
+function sortRecords(records) {
+    return [...records].sort(compareBytes);
+}
+/** `section(tag, records)`: 1 tag byte + `u32(count)` + sorted record bytes. */
+function encodeSection(tag, records) {
+    const sorted = sortRecords(records);
+    return concatBytes([
+        new Uint8Array([tag]),
+        encodeU32(sorted.length),
+        ...sorted,
+    ]);
+}
+function encodeScriptRecord(script) {
+    return concatBytes([
+        encodeString(script.name),
+        encodeString(script.lang),
+        encodeOptionalString(script.src),
+        encodeString(script.code),
+    ]);
+}
+function encodeModuleRecord(path, source) {
+    return concatBytes([encodeString(path), encodeString(source)]);
+}
+/** `moduleSet`: `u32(count)` + sorted `str(path) str(source)` records. No section tag — always nested inside an already-tagged section/record. */
+function encodeModuleSet(modules) {
+    const records = Object.entries(modules).map(([path, source]) => encodeModuleRecord(path, source));
+    const sorted = sortRecords(records);
+    return concatBytes([encodeU32(sorted.length), ...sorted]);
+}
+function encodeVaultNamespaceRecord(namespace, modules) {
+    return concatBytes([encodeString(namespace), encodeModuleSet(modules)]);
+}
+function encodePackRecord(pack) {
+    const modules = pack.modules;
+    return concatBytes([
+        encodeString(pack.namespace),
+        encodeString(pack.version),
+        new Uint8Array([modules === undefined ? 0x00 : 0x01]),
+        modules === undefined ? new Uint8Array(0) : encodeModuleSet(modules),
+    ]);
+}
+function encodeClosure(closure) {
+    const scriptRecords = closure.scripts.map(encodeScriptRecord);
+    const bundleRecords = Object.entries(closure.bundleModules).map(([path, source]) => encodeModuleRecord(path, source));
+    const vaultRecords = Object.entries(closure.vaultModules).map(([namespace, modules]) => encodeVaultNamespaceRecord(namespace, modules));
+    const packRecords = closure.packs.map(encodePackRecord);
+    return concatBytes([
+        encodeString(SCHEME_VERSION),
+        encodeSection(SECTION_TAG.scripts, scriptRecords),
+        encodeSection(SECTION_TAG.bundleModules, bundleRecords),
+        encodeSection(SECTION_TAG.vaultModules, vaultRecords),
+        encodeSection(SECTION_TAG.packs, packRecords),
+    ]);
+}
+function toHex(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let hex = '';
+    for (const byte of bytes) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+/**
+ * Computes the grant key for a note's executable closure (DESIGN.md §10):
+ * the lowercase hex SHA-256 digest of the closure's canonical serialization
+ * — see this module's top doc comment for the exact byte form. Pure and
+ * side-effect free: this function does not parse, fetch, or read anything;
+ * the host must have already assembled `closure` from the note's scripts,
+ * resolved `src=`/`require` targets, and installed pack manifest.
+ *
+ * Uses `globalThis.crypto.subtle` (Web Crypto — available in Node >=20 and
+ * every browser) rather than `node:crypto`, so this package stays
+ * browser-safe with no added dependency.
+ */
+export async function computeGrantKey(closure) {
+    const bytes = encodeClosure(closure);
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return toHex(digest);
+}

package/dist/index.d.ts

@@ -1,2 +1,5 @@
 export { createValueStore, type StoredValue, type ValueStatus, type ValueStore, } from './store.js';
+export { FAILURE_KINDS, normalizeFailureKind, type FailureKind, } from './failure.js';
+export { computeGrantKey, type GrantClosure, type GrantClosurePack, type GrantClosureScript, } from './grant-key.js';
+export { createVaultStore, type CreateVaultStoreOptions, type VaultPublishFailure, type VaultPublishResult, type VaultPublishSuccess, type VaultStore, type VaultStoreHandle, type VaultWriter, } from './vault.js';
 export { runDocumentScripts, tierForTrigger, type ExecuteFailure, type ExecuteResult, type ExecuteSuccess, type ExecutionTier, type RunDocumentScriptsOptions, type RunSummary, type RunSummaryEntry, type RunTrigger, type ScriptExecutor, } from './run.js';

package/dist/index.js

@@ -1,2 +1,5 @@
 export { createValueStore, } from './store.js';
+export { FAILURE_KINDS, normalizeFailureKind, } from './failure.js';
+export { computeGrantKey, } from './grant-key.js';
+export { createVaultStore, } from './vault.js';
 export { runDocumentScripts, tierForTrigger, } from './run.js';

package/dist/run.d.ts

@@ -1,5 +1,7 @@
 import type { ScriptBlock } from '@markii/core';
+import { type FailureKind } from './failure.js';
 import type { ValueStore } from './store.js';
+import type { VaultWriter } from './vault.js';
 /**
  * Slice 2 of the scripting-usability layer (DESIGN.md §8): the run
  * orchestrator that executes a document's script blocks and writes their
@@ -32,18 +34,23 @@ export interface ExecuteSuccess {
     value: unknown;
 }
 /**
- * A failed script execution. `kind` is intentionally a plain `string`
- * (not a fixed union) here — `@markii/runtime` stays language-agnostic and
- * does not know the specific failure taxonomy of any one language runtime
- * (e.g. `@markii/lua`'s `'limit' | 'capability' | 'marshal' | 'runtime'`).
- * `runDocumentScripts` only ever special-cases the literal string
- * `'capability'`, by convention every executor is expected to use for a
- * denied-capability failure.
+ * A failed script execution. `kind` is the CLOSED `FailureKind` union
+ * (`./failure.ts`) — every concrete `ScriptExecutor` (e.g. `@markii/lua`'s
+ * `createLuaExecutor`) is expected to map its own language-specific failure
+ * shape (e.g. Lua's `'limit' | 'capability' | 'marshal' | 'runtime'`) down
+ * to this shared vocabulary before returning. Even though this is typed as
+ * `FailureKind` at compile time, an executor is untrusted third-party code
+ * at RUNTIME (a forged string, a stale value from an older executor
+ * version, ...) — `runDocumentScripts` therefore runs every incoming
+ * `kind` through `normalizeFailureKind` at the boundary regardless of what
+ * the type system already promises, so a hostile or buggy executor can
+ * never produce a `StoredValue`/`RunSummaryEntry` carrying an
+ * out-of-taxonomy `failureKind`.
  */
 export interface ExecuteFailure {
     ok: false;
     error: {
-        kind: string;
+        kind: FailureKind;
         message: string;
     };
 }
@@ -66,6 +73,30 @@ export interface RunSummaryEntry {
     name: string;
     status: 'fresh' | 'error';
     error?: string;
+    /**
+     * Set alongside `error` on every `status: 'error'` entry — the closed
+     * `FailureKind` (`./failure.ts`) this failure was classified as. Already
+     * normalized (see `ExecuteFailure`'s doc comment), so a caller can branch
+     * on it directly without re-deriving trust. Absent for a `'fresh'` entry.
+     */
+    failureKind?: FailureKind;
+    /**
+     * Publish outcome (DESIGN.md §8's vault). Set ONLY for a script block
+     * whose fence carried the bare `publish` attribute (`ScriptBlock.publish
+     * === true`) AND whose run succeeded (`status === 'fresh'`) — a
+     * non-publish block never gets this field, and a publish-flagged block
+     * whose run FAILED never gets it either (its `status` already says
+     * `'error'`; there is nothing to publish).
+     * - `'published'`    — `vault.publish` accepted the value.
+     * - `'rejected'`     — a writer was present but declined (see
+     *   `publishError`); the note's own `status` STAYS `'fresh'` regardless —
+     *   a vault rejection is not a script failure.
+     * - `'not-granted'`  — no `vault` was supplied to `runDocumentScripts` at
+     *   all; publishing was flagged but no grant existed to act on it.
+     */
+    publish?: 'published' | 'rejected' | 'not-granted';
+    /** Set only when `publish === 'rejected'`; the writer's rejection message. */
+    publishError?: string;
 }
 /**
  * The result of one `runDocumentScripts` call. `results` has one entry per
@@ -83,6 +114,8 @@ export interface RunSummary {
     freshCount: number;
     errorCount: number;
     duplicateNames: string[];
+    /** Count of `results` entries with `publish === 'published'`. */
+    publishedCount: number;
 }
 export interface RunDocumentScriptsOptions {
     scripts: ScriptBlock[];
@@ -96,6 +129,29 @@ export interface RunDocumentScriptsOptions {
      * block is recorded as an error (never a thrown exception).
      */
     loadSource?: (src: string) => Promise<string> | string;
+    /**
+     * The publish grant (DESIGN.md §8: "Publishing requires a grant ...
+     * because it writes beyond the note"). ITS PRESENCE IS THE GRANT — there
+     * is no separate flag to enable publishing, and no per-script grant
+     * check; a host that hands in a `vault` is thereby authorizing every
+     * `publish`-flagged block in this batch to write to it. Absent =>
+     * publish-flagged blocks simply do not publish (`publish: 'not-granted'`
+     * on their `RunSummaryEntry`); this is NOT an error and the run still
+     * succeeds.
+     *
+     * Publishing is allowed under BOTH execution tiers (`'manual'` and
+     * `'auto'`) whenever a writer is present — the grant is the gate here,
+     * NOT the trigger/tier. This is deliberately orthogonal to
+     * `tierForTrigger`'s security gate: that gate governs what CAPABILITIES a
+     * script may exercise while running (network access, cache writes, ...)
+     * via the tier passed to the executor; it says nothing about whether the
+     * host is willing to copy an already-computed, already-successful return
+     * value into its own vault afterward. A read-only `'auto'`-tier run can
+     * still publish, because publishing isn't a capability the SCRIPT
+     * exercises — it's something the HOST does with a value the script already
+     * (successfully) produced.
+     */
+    vault?: VaultWriter;
 }
 /**
  * Runs every script block in `scripts`, in document order, against
@@ -112,6 +168,15 @@ export interface RunDocumentScriptsOptions {
  * per-script, matching DESIGN.md §8 (a run is manual, auto, or scheduled as
  * a whole; individual scripts don't choose their own tier).
  *
+ * Publishing (§8's vault): after a `publish`-flagged block's run SUCCEEDS,
+ * if `options.vault` was supplied its `publish` is called with the same
+ * `StoredValue` just written to `store` — see `RunDocumentScriptsOptions.
+ * vault`'s doc comment for why the grant, not the trigger/tier, is what
+ * gates this. A writer that rejects, throws, or has its promise reject
+ * never aborts the batch and never changes the note's own `status` (which
+ * stays `'fresh'`) — only `RunSummaryEntry.publish`/`.publishError` record
+ * the outcome. This function still never throws.
+ *
  * Duplicate `name`s: every attempt gets its own `RunSummary.results` entry,
  * but `store.set` is called once per script in document order, so the LAST
  * run for a given name is what's left in the store afterward — see

package/dist/run.js

@@ -1,3 +1,4 @@
+import { normalizeFailureKind } from './failure.js';
 /**
  * DESIGN.md §8's trigger x capability table, expressed as a pure lookup —
  * THIS IS THE SECURITY GATE for the whole run path. `'manual'` is the only
@@ -22,27 +23,38 @@ export function tierForTrigger(trigger) {
 function describeThrown(err) {
     return err instanceof Error ? err.message : String(err);
 }
-/**
- * §8: "An effectful call under an auto trigger fails cleanly; the
- * consuming component shows a 'requires manual run' marker." When the tier
- * a script ran at was the read-only `'auto'` tier and the executor reports
- * a `'capability'`-kind failure, the stored error message is rewritten to
- * clearly say so, so a component (or a human reading the value store) does
- * not have to re-derive "this needs a manual run" from a generic capability
- * message.
- */
-function messageForFailure(tier, error) {
-    if (tier === 'auto' && error.kind === 'capability') {
-        return `${error.message} (requires manual run: this capability is only available on a manual run)`;
-    }
-    return error.message;
-}
 /**
  * Runs exactly one script block and never throws: every way it can fail
  * (missing `loadSource` for a `src=` reference, `loadSource` itself
  * throwing, the executor rejecting/throwing, or the executor reporting
  * `ok: false`) is caught here and turned into an `error`-status outcome, so
  * one bad script can never abort the rest of a `runDocumentScripts` batch.
+ *
+ * Failure classification (`failureKind`): the three failure paths this
+ * function owns OUTRIGHT — a `src=` block with no `loadSource` configured,
+ * `loadSource` itself throwing/rejecting, and the executor throwing or its
+ * returned promise rejecting (as opposed to resolving with `ok: false`) —
+ * are all classified as `'script-error'`. None of these are the executor
+ * reporting a considered, typed failure; they are this package's OWN
+ * plumbing failing (a missing host wire-up, or the executor misbehaving by
+ * throwing instead of returning `ExecuteResult`), so there is no more
+ * specific taxonomy member that legitimately applies — `'script-error'` is
+ * both correct (something about running the script went wrong) and the safe
+ * default (never guesses a more privileged-sounding kind like
+ * `'capability-denied'` or `'tier-blocked'` for a failure this package can't
+ * actually attribute to a capability decision). Only the fourth path —
+ * `result.ok === false` from a normally-returning executor — carries a
+ * `kind` the executor itself chose, and even that is passed through
+ * `normalizeFailureKind` before being trusted (see `ExecuteFailure`'s doc
+ * comment): the executor is untrusted third-party code at runtime.
+ *
+ * Stored/reported messages are the executor's `error.message` VERBATIM —
+ * this function never rewrites or appends to it (see `ExecuteFailure`'s doc
+ * comment; the previous `messageForFailure` auto-tier rewrite is gone: a
+ * `'tier-blocked'` failure's own message already says what happened, and a
+ * `'capability-denied'` failure is not a "needs manual run" situation at
+ * all, so rewriting every capability-kind auto-tier failure that way was
+ * simply wrong).
  */
 async function runOne(script, executor, tier, loadSource) {
     let code;
@@ -61,8 +73,19 @@ async function runOne(script, executor, tier, loadSource) {
         const message = describeThrown(err);
         const ranAt = Date.now();
         return {
-            entry: { name: script.name, status: 'error', error: message },
-            storedValue: { value: undefined, status: 'error', error: message, ranAt },
+            entry: {
+                name: script.name,
+                status: 'error',
+                error: message,
+                failureKind: 'script-error',
+            },
+            storedValue: {
+                value: undefined,
+                status: 'error',
+                error: message,
+                failureKind: 'script-error',
+                ranAt,
+            },
         };
     }
     let result;
@@ -73,8 +96,19 @@ async function runOne(script, executor, tier, loadSource) {
         const message = describeThrown(err);
         const ranAt = Date.now();
         return {
-            entry: { name: script.name, status: 'error', error: message },
-            storedValue: { value: undefined, status: 'error', error: message, ranAt },
+            entry: {
+                name: script.name,
+                status: 'error',
+                error: message,
+                failureKind: 'script-error',
+            },
+            storedValue: {
+                value: undefined,
+                status: 'error',
+                error: message,
+                failureKind: 'script-error',
+                ranAt,
+            },
         };
     }
     const ranAt = Date.now();
@@ -84,10 +118,17 @@ async function runOne(script, executor, tier, loadSource) {
             storedValue: { value: result.value, status: 'fresh', ranAt },
         };
     }
-    const message = messageForFailure(tier, result.error);
+    const failureKind = normalizeFailureKind(result.error.kind);
+    const message = result.error.message;
     return {
-        entry: { name: script.name, status: 'error', error: message },
-        storedValue: { value: undefined, status: 'error', error: message, ranAt },
+        entry: { name: script.name, status: 'error', error: message, failureKind },
+        storedValue: {
+            value: undefined,
+            status: 'error',
+            error: message,
+            failureKind,
+            ranAt,
+        },
     };
 }
 /**
@@ -105,13 +146,22 @@ async function runOne(script, executor, tier, loadSource) {
  * per-script, matching DESIGN.md §8 (a run is manual, auto, or scheduled as
  * a whole; individual scripts don't choose their own tier).
  *
+ * Publishing (§8's vault): after a `publish`-flagged block's run SUCCEEDS,
+ * if `options.vault` was supplied its `publish` is called with the same
+ * `StoredValue` just written to `store` — see `RunDocumentScriptsOptions.
+ * vault`'s doc comment for why the grant, not the trigger/tier, is what
+ * gates this. A writer that rejects, throws, or has its promise reject
+ * never aborts the batch and never changes the note's own `status` (which
+ * stays `'fresh'`) — only `RunSummaryEntry.publish`/`.publishError` record
+ * the outcome. This function still never throws.
+ *
  * Duplicate `name`s: every attempt gets its own `RunSummary.results` entry,
  * but `store.set` is called once per script in document order, so the LAST
  * run for a given name is what's left in the store afterward — see
  * `RunSummary.duplicateNames`.
  */
 export async function runDocumentScripts(options) {
-    const { scripts, executor, trigger, store, loadSource } = options;
+    const { scripts, executor, trigger, store, loadSource, vault } = options;
     const tier = tierForTrigger(trigger);
     const results = [];
     const seenNames = new Set();
@@ -122,16 +172,49 @@ export async function runDocumentScripts(options) {
         }
         seenNames.add(script.name);
         const outcome = await runOne(script, executor, tier, loadSource);
-        results.push(outcome.entry);
         store.set(script.name, outcome.storedValue);
+        // Publishing (DESIGN.md §8): only for a block that both asked to
+        // publish (bare `publish` on its fence — see `ScriptBlock.publish`) and
+        // actually succeeded. A failed run has nothing to publish; `runOne`
+        // already recorded its failure in `outcome.entry.status`/`.error`, and
+        // `publish` is left `undefined` on that entry (per `RunSummaryEntry`'s
+        // doc comment) rather than getting a misleading 'not-granted'/'rejected'.
+        if (script.publish === true && outcome.entry.status === 'fresh') {
+            if (!vault) {
+                outcome.entry.publish = 'not-granted';
+            }
+            else {
+                let result;
+                try {
+                    result = await vault.publish(script.name, outcome.storedValue);
+                }
+                catch (err) {
+                    result = {
+                        ok: false,
+                        error: { kind: 'error', message: describeThrown(err) },
+                    };
+                }
+                if (result.ok) {
+                    outcome.entry.publish = 'published';
+                }
+                else {
+                    outcome.entry.publish = 'rejected';
+                    outcome.entry.publishError = result.error.message;
+                }
+            }
+        }
+        results.push(outcome.entry);
     }
     let freshCount = 0;
     let errorCount = 0;
+    let publishedCount = 0;
     for (const entry of results) {
         if (entry.status === 'fresh')
             freshCount++;
         else
             errorCount++;
+        if (entry.publish === 'published')
+            publishedCount++;
     }
     return {
         trigger,
@@ -140,5 +223,6 @@ export async function runDocumentScripts(options) {
         freshCount,
         errorCount,
         duplicateNames: [...duplicateNames],
+        publishedCount,
     };
 }

package/dist/store.d.ts

@@ -6,6 +6,7 @@
  * the script's declared `name`. "Rendering is pure; running is an event" —
  * this store is the pure side of that split.
  */
+import type { FailureKind } from './failure.js';
 /**
  * Freshness of one stored value:
  * - `fresh`   — produced by the most recent successful run.
@@ -19,6 +20,17 @@ export interface StoredValue {
     value: unknown;
     status: ValueStatus;
     error?: string;
+    /**
+     * Set alongside `error` on every `status: 'error'` outcome (see
+     * `./run.ts`'s `runDocumentScripts`) — the closed `FailureKind` (`./
+     * failure.ts`) the failure was classified as, already run through
+     * `normalizeFailureKind` at the run-path boundary so it is safe for a
+     * renderer to branch on directly. Absent for a non-error status, and
+     * absent for an error `StoredValue` written by something other than the
+     * run path (e.g. a hand-constructed fixture) — a renderer must still
+     * degrade gracefully when this is missing.
+     */
+    failureKind?: FailureKind;
     ranAt?: number;
 }
 /**

package/dist/vault.d.ts

@@ -0,0 +1,97 @@
+import type { StoredValue } from './store.js';
+/**
+ * Slice 3 of the scripting-usability layer (DESIGN.md §8, "Vault-published
+ * values (the bulletin board)"): the APP-SCOPED store that a `publish`-
+ * flagged script block's result lands in, as distinct from `store.ts`'s
+ * NOTE-scoped `ValueStore`. "The store is app-side (§9): publishing adds no
+ * files to the vault" — this module holds no persistence of its own either;
+ * it is purely an in-memory reference implementation a host may use as-is or
+ * replace with its own (e.g. one backed by disk or a database).
+ *
+ * The read/write split mirrors `store.ts`'s null-proto, `Object.hasOwn`-
+ * guarded defensive posture (protection against `name`s like `__proto__` or
+ * `constructor` resolving to an inherited `Object.prototype` member instead
+ * of a real, or correctly-absent, entry), but goes one step further:
+ * `VaultStore` (read) and `VaultWriter` (write) are separate interfaces
+ * backed by the same data, so a host can hand a renderer the read seam alone
+ * and withhold the write capability entirely. §8: "Reading is render-time
+ * and pure ... Publishing requires a grant ... because it writes beyond the
+ * note" — possessing a `VaultWriter` reference IS that grant. There is no
+ * ambient "is this note allowed to publish" check anywhere in this module;
+ * the capability itself is the permission.
+ */
+/**
+ * Read-only view of the vault-level, app-managed store (§8). Deliberately
+ * has NO `set` — rendering reads the vault and must never be able to write
+ * it; only a `VaultWriter` (obtained separately, and only by something the
+ * host trusts with the publish grant) can do that.
+ */
+export interface VaultStore {
+    get(name: string): StoredValue | undefined;
+    has(name: string): boolean;
+    snapshot(): Record<string, StoredValue>;
+}
+/**
+ * A publish rejection. `kind` is a plain `string` (not a fixed union),
+ * mirroring `ExecuteFailure.error.kind` in `run.ts` — callers are expected
+ * to branch on `ok`, never on `message` text. This module's own writer only
+ * ever produces `'claimed'` (see `createVaultStore`'s `canPublish`) or
+ * `'policy'` (a throwing `canPublish` hook); a host's own `VaultWriter`
+ * implementation is free to define further `kind`s for its own policies.
+ */
+export interface VaultPublishFailure {
+    ok: false;
+    error: {
+        kind: string;
+        message: string;
+    };
+}
+export interface VaultPublishSuccess {
+    ok: true;
+}
+export type VaultPublishResult = VaultPublishSuccess | VaultPublishFailure;
+/**
+ * The capability-style write side: possessing a `VaultWriter` IS the host's
+ * publish grant (§8: "Publishing requires a grant ... because it writes
+ * beyond the note"). Hosts may implement this themselves — e.g. one that
+ * closes over the publishing note's identity and a persistent claim table —
+ * rather than using `createVaultStore`'s reference implementation.
+ * `publish` may be async so a host-backed implementation (network call,
+ * disk write, claim negotiation) fits the same shape as the in-memory one.
+ */
+export interface VaultWriter {
+    publish(name: string, entry: StoredValue): VaultPublishResult | Promise<VaultPublishResult>;
+}
+export interface CreateVaultStoreOptions {
+    /** Seeds the vault, e.g. from a previous session's persisted snapshot. */
+    initial?: Record<string, StoredValue>;
+    /**
+     * Single-writer-per-name hook — APP POLICY, not runtime policy (§8: "The
+     * app rejects a second note publishing an already-claimed name"). Given
+     * the candidate `name` and `entry`, return `false` to reject the claim.
+     * Absent => every publish is accepted (no claim tracking at all). A hook
+     * that throws is treated as a rejection (`kind: 'policy'`), never
+     * propagated — a buggy policy hook must fail closed, not crash the run.
+     */
+    canPublish?: (name: string, entry: StoredValue) => boolean;
+}
+/**
+ * Reference in-memory `VaultStore`/`VaultWriter` pair. `store` and `writer`
+ * are deliberately SEPARATE objects backed by the same data, so a host can
+ * hand `store` to a renderer while withholding `writer` from anything that
+ * shouldn't be able to publish. No persistence of its own: storage is the
+ * host's concern (§9, "publishing adds no files to the vault") — a host
+ * that needs persistence wraps or replaces this with its own `VaultWriter`.
+ */
+export interface VaultStoreHandle {
+    store: VaultStore;
+    writer: VaultWriter;
+}
+/**
+ * Creates an in-memory `VaultStoreHandle`. Backed by a null-prototype
+ * object, exactly like `createValueStore` — a vault `name` colliding with an
+ * inherited `Object.prototype` member (`__proto__`, `constructor`,
+ * `toString`, `hasOwnProperty`, ...) can never resolve to that inherited
+ * member instead of a real (or correctly-absent) entry.
+ */
+export declare function createVaultStore(options?: CreateVaultStoreOptions): VaultStoreHandle;

package/dist/vault.js

@@ -0,0 +1,63 @@
+function describeThrown(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Creates an in-memory `VaultStoreHandle`. Backed by a null-prototype
+ * object, exactly like `createValueStore` — a vault `name` colliding with an
+ * inherited `Object.prototype` member (`__proto__`, `constructor`,
+ * `toString`, `hasOwnProperty`, ...) can never resolve to that inherited
+ * member instead of a real (or correctly-absent) entry.
+ */
+export function createVaultStore(options = {}) {
+    const { initial = {}, canPublish } = options;
+    const values = Object.create(null);
+    for (const [name, entry] of Object.entries(initial)) {
+        values[name] = entry;
+    }
+    const store = {
+        get(name) {
+            return Object.hasOwn(values, name) ? values[name] : undefined;
+        },
+        has(name) {
+            return Object.hasOwn(values, name);
+        },
+        // Shallow copy, exactly like `ValueStore.snapshot`: this is a fresh
+        // plain object, but each `StoredValue` it holds is the same object
+        // reference already in the vault — mutating a returned entry in place
+        // would be visible to the vault too. The returned object's own
+        // prototype is the ordinary `Object.prototype` (a plain `{ ...values }`
+        // spread, not `Object.create(null)`), since it's a caller-facing value
+        // with no further hostile-key lookups performed against it here.
+        snapshot() {
+            return { ...values };
+        },
+    };
+    const writer = {
+        publish(name, entry) {
+            if (canPublish) {
+                let allowed;
+                try {
+                    allowed = canPublish(name, entry);
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        error: { kind: 'policy', message: describeThrown(err) },
+                    };
+                }
+                if (!allowed) {
+                    return {
+                        ok: false,
+                        error: {
+                            kind: 'claimed',
+                            message: `vault name "${name}" is already claimed by another writer`,
+                        },
+                    };
+                }
+            }
+            values[name] = entry;
+            return { ok: true };
+        },
+    };
+    return { store, writer };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Host-side scripting glue for Mark (.mk.md): a null-proto value store and document-script execution with trigger-tier gating (auto/scheduled stay read-only). Framework-agnostic; the script executor is injected by the host (e.g. @markii/lua).",
   "keywords": [
     "markdown",
@@ -42,6 +42,6 @@
     "lint": "eslint ."
   },
   "dependencies": {
-    "@markii/core": "0.1.0"
+    "@markii/core": "0.2.0"
   }
 }