@struktoai/mirage-node 0.0.7-alpha.2 → 0.0.7

package/dist/config.js

@@ -11,28 +11,34 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 // ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { CommandSpec } from '@struktoai/mirage-core/commands/spec/types';
+import { IOConfig } from '@struktoai/mirage-core/io/config';
+import { parseCommandLimits } from '@struktoai/mirage-core/policy/builtin/output_cap';
 import { randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { parse as parseYaml } from 'yaml';
-import { CLISpec } from '@struktoai/mirage-core/commands/cli/types';
+import { parseYaml } from "./utils/yaml.js";
+import { CLI } from '@struktoai/mirage-core/commands/cli/types';
 import { Runtime } from '@struktoai/mirage-core/runtime/base';
-import { ScriptSource } from '@struktoai/mirage-core/runtime/routing/index';
+import { ScriptSource } from '@struktoai/mirage-core/runtime/types';
 import { buildRuntime, checkRuntimeOptions } from '@struktoai/mirage-core/runtime/table';
 import { EnvVarSchema, SecretSourceSchema, } from '@struktoai/mirage-core/secrets/config';
-import { ConsistencyPolicy, KERNEL_BACKENDS, Limit, MountBackend, MountMode, OnExceed, parseMountMode, } from '@struktoai/mirage-core/types';
+import { KERNEL_BACKENDS, MountBackend, MountMode, ReadPolicy, parseMountMode, } from '@struktoai/mirage-core/types';
+import { Mount } from '@struktoai/mirage-core/workspace/mount/spec';
+import { coerceReadPolicy, resolveReadSpec, } from '@struktoai/mirage-core/workspace/mount/read_policy';
+import { coerceWritePolicy } from '@struktoai/mirage-core/workspace/mount/write_policy';
 import { snakeToCamel } from '@struktoai/mirage-core/utils/normalize';
-import { parseSessionProfile } from '@struktoai/mirage-core/policy/profile';
+import { parseProgram, parseSessionProfile, } from '@struktoai/mirage-core/policy/profile';
 import { RAMWorkspaceStateStore } from '@struktoai/mirage-core/workspace/store/ram';
 import { S3WorkspaceStateStore } from '@struktoai/mirage-core/workspace/store/s3';
-import { normalizeS3Config } from "./resource/s3/config.js";
-import { isModulePath, loadAttr, splitRef } from "./resource/loader.js";
-// The config door is a workspace entry point of its own (the daemon
+import { normalizeS3Config } from "./vfs/s3/config.js";
+import { isModulePath, loadAttr, splitRef } from "./utils/loader.js";
+// The config loader is a workspace entry point of its own (the daemon
 // builds from here), so it arms the builtin secrets sources like the
 // node Workspace module does.
 import { configHoldsPointer, resolveConfigSecrets, resolveSourcesFor, } from '@struktoai/mirage-core/secrets/sources';
 import "./secrets/constants.js";
-import { buildResource } from "./resource/registry.js";
+import { buildVfs } from "./vfs/registry.js";
 import { RedisConsoleStore } from "./shell/console/redis/index.js";
 import { DiskWorkspaceStateStore } from "./workspace/store/disk.js";
 import { RedisWorkspaceStateStore } from "./workspace/store/redis.js";
@@ -43,16 +49,14 @@ function coerceMountMode(value, fallback) {
         return fallback;
     return parseMountMode(value.toLowerCase());
 }
-const VALID_CONSISTENCY = new Set([ConsistencyPolicy.LAZY, ConsistencyPolicy.ALWAYS]);
 /** True for the docker-style single-line script path form (.py/.js/.mjs). */
 function isScriptPath(value) {
     return !value.includes('\n') && ['.py', '.js', '.mjs'].some((ext) => value.trim().endsWith(ext));
 }
 // Config carries a reference, the wire carries content (the docker
-// build-context model): the value must be a path to a .py/.js file,
-// read at load time. In code, scripts are functions; config is the
-// only door for script source. The extension stamps the script's
-// language so the policy engine can pick a matching evaluator.
+// build-context model): the value must be a path to a .py/.js/.mjs file,
+// read at load time. In code, a program is passed as a ScriptSource. The
+// extension stamps the script's language.
 function loadScriptSource(value) {
     if (!isScriptPath(value)) {
         throw new Error(`a config script must reference a .py/.js file (e.g. script: guard.py), got '${value}'`);
@@ -64,11 +68,11 @@ function loadScriptSource(value) {
 /**
  * Load the `Runtime` subclass a `source:Class` reference names.
  *
- * The runtime twin of the `resource:` and `cli:` reference forms: a
+ * The runtime twin of the `vfs:` and `cli:` reference forms: a
  * deployment ships a runtime as a file and names it from yaml with no
  * host program calling `registerRuntime`. The class is constructed with
- * the uniform `(captures, config, script)` options like a builtin, so
- * the entry's other keys reach it unchanged. Mirrors `_runtime_class` in
+ * the uniform `(captures, config)` options like a builtin, so the entry's
+ * other keys reach it unchanged. Mirrors `_runtime_class` in
  * `mirage/config.py`.
  */
 async function loadRuntimeClass(ref) {
@@ -93,43 +97,24 @@ async function buildRuntimeEntries(entries) {
         }
         if (!isPlainObject(entry))
             throw new Error('runtime entry must be a name or a mapping');
-        const { name, script, ...options } = entry;
+        const { name, ...options } = entry;
         if (typeof name !== 'string' || name === '') {
             throw new Error("runtime entry needs a non-empty 'name'");
         }
-        if (script !== undefined && typeof script !== 'string') {
-            throw new Error('a runtime entry script must be a .py path string');
-        }
-        const withScript = script !== undefined ? { ...options, script: loadScriptSource(script) } : options;
         if (name.includes(':')) {
             // The key check `buildRuntime` runs for a name: the base
             // constructor ignores a key it does not read, so without it a typo
             // would leave the runtime on its defaults where Python's
             // `**options` refuses the entry.
             const cls = await loadRuntimeClass(name);
-            checkRuntimeOptions(name, withScript);
-            out.push(new cls(withScript));
+            checkRuntimeOptions(name, options);
+            out.push(new cls(options));
             continue;
         }
-        out.push(buildRuntime(name, withScript));
+        out.push(buildRuntime(name, options));
     }
     return out;
 }
-function coerceConsistency(value) {
-    if (value === undefined)
-        return ConsistencyPolicy.LAZY;
-    const lower = value.toLowerCase();
-    if (!VALID_CONSISTENCY.has(lower))
-        throw new Error(`invalid consistency: ${value}`);
-    return lower;
-}
-const VALID_ON_EXCEED = new Set([OnExceed.ERROR, OnExceed.TRUNCATE]);
-function coerceOnExceed(value) {
-    if (!VALID_ON_EXCEED.has(value.toLowerCase())) {
-        throw new Error(`invalid onExceed: ${value}`);
-    }
-    return value.toLowerCase();
-}
 function camelizeKeys(obj) {
     const out = {};
     for (const [k, v] of Object.entries(obj))
@@ -149,21 +134,23 @@ function isPlainObject(v) {
 // which is the same portability break pointing the other way.
 //
 // `mounts.*.config` is the one block with no table, because Python types
-// it as a bare dict and validates it in the resource's own model. Do not
+// it as a bare dict and validates it in the VFS's own model. Do not
 // generalize that to every credential-carrying block: an s3 store group
 // has a strict Python model (`S3StoreBlock`, extra="forbid"), so it is
 // tabled here like the rest.
 const TOP_LEVEL_KEYS = [
     'mounts',
+    'io',
+    'command_limits',
     'clis',
     'runtimes',
     'route_policy',
     'profiles',
     'profile',
     'mode',
-    'consistency',
+    'read',
+    'write',
     'default_session_id',
-    'default_agent_id',
     'workspace_id',
     'cache',
     'index',
@@ -173,12 +160,16 @@ const TOP_LEVEL_KEYS = [
     'secrets',
 ];
 const MOUNT_KEYS = [
-    'resource',
+    'vfs',
     'mode',
     'config',
     'command_limits',
     'backend',
     'mountpoint',
+    'read',
+    'ttl',
+    'write',
+    'index',
 ];
 // A source instance is a type beside a config, the way a mount is. Its
 // `config:` block has no table for the same reason `mounts.*.config`
@@ -271,6 +262,22 @@ function validateTypedBlock(value, table, what, fallback) {
     const type = blockType(value, what, Object.keys(table), fallback);
     rejectUnknownKeys(value, table[type] ?? [], `${what} (${type})`);
 }
+// Python's index block models refuse a ttl that is not a number
+// (StrictFloat) and a non-string url or key_prefix at load. This stops at
+// the first bad value, so it checks them in the models' field order.
+function validateIndexValues(value, what) {
+    if (!isPlainObject(value))
+        return;
+    if (value.ttl !== undefined && typeof value.ttl !== 'number') {
+        throw new Error(`config \`${what}.ttl\` must be a number`);
+    }
+    if (value.url !== undefined && typeof value.url !== 'string') {
+        throw new Error(`config \`${what}.url\` must be a string`);
+    }
+    if (value.key_prefix !== undefined && typeof value.key_prefix !== 'string') {
+        throw new Error(`config \`${what}.key_prefix\` must be a string`);
+    }
+}
 // Key names alone are not enough here: Python's Pydantic model rejects
 // `url: 123` at load, so the TS loader must refuse the same file at the
 // same boundary instead of deferring it to Redis client creation.
@@ -319,17 +326,66 @@ function validateStoreBlock(value) {
 function asConfig(value) {
     return isPlainObject(value) ? value : {};
 }
+/**
+ * Refuse a mount block whose read policy and bound disagree.
+ *
+ * Both rules live at the config loader rather than in the mount-time
+ * verdict: once a ReadSpec exists its ttl has already defaulted, so
+ * `bounded` written without a bound is indistinguishable from `read:`
+ * left out entirely. Python refuses the same pair in `MountBlock`'s
+ * model validator, which is the same entry point.
+ */
+function validateReadBlock(prefix, block) {
+    // Coerce once, then apply both dependent-key rules to the normalised
+    // value. Comparing the raw one let `read: BOUNDED` -- a spelling both
+    // languages accept -- skip the bound rule that Python enforces.
+    const declared = block.read ?? undefined;
+    const policy = declared === undefined ? undefined : coerceReadPolicy(declared);
+    const ttl = block.ttl ?? undefined;
+    // The bound's type is judged whatever `read:` says, and before the
+    // dependent-key rules, because that is where Python judges it: a
+    // field validator, which runs ahead of the model validator carrying
+    // those rules. Left until after them, `ttl: "30"` with no `read:`
+    // came back naming the missing policy on one host and the unusable
+    // bound on the other.
+    if (ttl !== undefined && (typeof ttl !== 'number' || !Number.isInteger(ttl))) {
+        throw new Error(`mount \`${prefix}\`: ttl must be whole seconds, got ${JSON.stringify(ttl)}`);
+    }
+    if (ttl !== undefined && policy === undefined) {
+        throw new Error(`mount \`${prefix}\`: ttl pins the read bound; it takes read: bounded`);
+    }
+    if (policy === ReadPolicy.BOUNDED && ttl === undefined) {
+        throw new Error(`mount \`${prefix}\`: read: bounded needs a bound; set ttl:`);
+    }
+    if (ttl !== undefined && ttl < 1) {
+        throw new Error(`mount \`${prefix}\`: ttl must be at least 1 second, got ${String(ttl)}`);
+    }
+}
 /**
  * Reject any key no Python config model declares, before normalization
  * folds snake_case into camelCase and the distinction is gone.
  */
 function validateConfigKeys(raw) {
     rejectUnknownKeys(raw, TOP_LEVEL_KEYS, 'config');
+    parseCommandLimits(raw.command_limits);
+    // At the sync entry point, as Python's WorkspaceConfig validator is, so the CLI
+    // refuses a bad value before it POSTs the document to the daemon.
+    if (raw.read !== undefined && raw.read !== null)
+        resolveReadSpec(raw.read, undefined);
+    if (raw.write !== undefined && raw.write !== null)
+        coerceWritePolicy(raw.write);
     if (isPlainObject(raw.mounts)) {
         for (const [prefix, block] of Object.entries(raw.mounts)) {
             if (!isPlainObject(block))
                 throw new Error(`mount \`${prefix}\` must be a mapping`);
             rejectUnknownKeys(block, MOUNT_KEYS, `mount \`${prefix}\``);
+            // Before the read rules, as pydantic checks fields before them.
+            validateTypedBlock(block.index, INDEX_KEYS, `mounts.${prefix}.index`);
+            validateIndexValues(block.index, `mounts.${prefix}.index`);
+            validateReadBlock(prefix, block);
+            if (block.write !== undefined && block.write !== null)
+                coerceWritePolicy(block.write);
+            parseCommandLimits(block.command_limits);
         }
     }
     if (isPlainObject(raw.clis)) {
@@ -342,7 +398,7 @@ function validateConfigKeys(raw) {
             // opaque: nothing declares which key is a credential, so the
             // snapshot captures it verbatim, and a pointer resolved into it
             // would be written out as the value it fetched. Refused here, on
-            // the block, so every door that reads a config inherits the rule.
+            // the block, so every entry point that reads a config inherits the rule.
             if (typeof block.script === 'string' && configHoldsPointer(asConfig(block.config))) {
                 throw new Error(`clis entry '${name}': a script's config is opaque and a pointer in it would be ` +
                     'written into every snapshot; read the credential from a managed env var instead');
@@ -355,6 +411,9 @@ function validateConfigKeys(raw) {
     if (raw.profiles !== undefined && raw.profiles !== null) {
         parseProfiles(raw.profiles);
     }
+    if (raw.route_policy !== undefined && raw.route_policy !== null) {
+        parseProgram(raw.route_policy, 'route_policy');
+    }
     if (raw.profile !== undefined && raw.profile !== null) {
         if (typeof raw.profile !== 'string')
             throw new Error('profile must be a string');
@@ -363,8 +422,15 @@ function validateConfigKeys(raw) {
             throw new Error(`unknown profile ${JSON.stringify(raw.profile)}`);
         }
     }
+    if (raw.io !== undefined) {
+        if (!isPlainObject(raw.io))
+            throw new Error('io must be a mapping');
+        rejectUnknownKeys(raw.io, ['buffer_bytes'], 'io');
+        new IOConfig(camelizeKeys(raw.io));
+    }
     validateTypedBlock(raw.cache, CACHE_KEYS, 'cache');
     validateTypedBlock(raw.index, INDEX_KEYS, 'index');
+    validateIndexValues(raw.index, 'index');
     validateTypedBlock(raw.console, CONSOLE_KEYS, 'console');
     validateConsoleValues(raw.console);
     validateStoreBlock(raw.store);
@@ -423,17 +489,29 @@ function validateEnvBlock(value) {
 // Workspace YAML uses Python's snake_case keys (default_session_id, the
 // cache/index key_prefix/max_drain_bytes, ...). TS code stays camelCase, so
 // normalize at the boundary: camelize the top-level keys plus the cache and
-// index blocks. Mounts are left untouched on purpose, their `config:` blocks
-// carry resource credentials whose snake_case keys (aws_access_key_id, ...)
-// are consumed downstream as-is, and command_limits is camelized later.
+// index blocks. A mount block is left in its own spelling but for its
+// `index:`: its `config:` carries VFS credentials whose snake_case keys
+// (aws_access_key_id, ...) are consumed downstream as-is, and
+// command_limits is parsed separately. The mounts map is rebuilt, as
+// the store block is, rather than edited.
 function normalizeConfigKeys(raw) {
     const out = camelizeKeys(raw);
+    if (isPlainObject(out.io))
+        out.io = camelizeKeys(out.io);
     if (isPlainObject(out.cache))
         out.cache = camelizeKeys(out.cache);
     if (isPlainObject(out.index))
         out.index = camelizeKeys(out.index);
     if (isPlainObject(out.console))
         out.console = camelizeKeys(out.console);
+    if (isPlainObject(out.mounts)) {
+        out.mounts = Object.fromEntries(Object.entries(out.mounts).map(([prefix, block]) => [
+            prefix,
+            isPlainObject(block) && isPlainObject(block.index)
+                ? { ...block, index: camelizeKeys(block.index) }
+                : block,
+        ]));
+    }
     if (isPlainObject(out.store)) {
         const store = camelizeKeys(out.store);
         for (const group of STORE_GROUPS) {
@@ -464,22 +542,6 @@ function normalizeConfigKeys(raw) {
     }
     return out;
 }
-// Workspace YAML uses Python's snake_case keys (command_limits, max_lines,
-// on_exceed, ...). The in-memory config stays camelCase, so normalize each
-// block's keys at the boundary before constructing the limit.
-function parseLimits(raw) {
-    const out = {};
-    for (const [cmd, rawBlock] of Object.entries(raw ?? {})) {
-        const block = camelizeKeys(rawBlock);
-        out[cmd] = new Limit({
-            ...(block.maxBytes !== undefined ? { maxBytes: block.maxBytes } : {}),
-            ...(block.maxLines !== undefined ? { maxLines: block.maxLines } : {}),
-            ...(block.timeoutSeconds !== undefined ? { timeoutSeconds: block.timeoutSeconds } : {}),
-            ...(block.onExceed !== undefined ? { onExceed: coerceOnExceed(block.onExceed) } : {}),
-        });
-    }
-    return out;
-}
 /**
  * Validate the `profiles:` block: every entry through the core profile
  * validator, so a misspelled field is a load error rather than a
@@ -492,18 +554,24 @@ function parseProfiles(raw) {
     const out = {};
     for (const [name, block] of Object.entries(raw)) {
         // A path-form script stays the string the config wrote: the check
-        // door validates shape only, and runs before `absolutizeScripts`
+        // entry point validates shape only, and runs before `absolutizeScripts`
         // has rebased the path onto the config file's directory, so reading
-        // it here would resolve against the process cwd. The workspace door
+        // it here would resolve against the process cwd. The workspace entry point
         // (`toWorkspaceOptions`) loads it, the python loader's split.
         out[name] = parseSessionProfile(block, `profile \`${name}\``);
     }
     return out;
 }
+/** A path-form policy program with its script loaded; one carrying source is left alone. */
+function loadProgram(program) {
+    return typeof program.script === 'string'
+        ? { ...program, script: loadScriptSource(program.script) }
+        : program;
+}
 /**
- * Load each profile's path-form policy into a ScriptSource.
+ * Load each profile's path-form policy programs into ScriptSources.
  *
- * By this door the path is absolute for a file config (the check door
+ * By this entry point the path is absolute for a file config (the check entry point
  * rebased it onto the config file's directory); an object config's
  * relative path resolves against the process cwd, as in Python. Code
  * that passes a loaded ScriptSource is left alone.
@@ -513,9 +581,15 @@ function loadProfileScripts(profiles) {
     for (const [name, profile] of Object.entries(profiles)) {
         const policy = profile.policy;
         out[name] =
-            policy != null && typeof policy.script === 'string'
-                ? { ...profile, policy: { ...policy, script: loadScriptSource(policy.script) } }
-                : profile;
+            policy == null
+                ? profile
+                : {
+                    ...profile,
+                    policy: Object.fromEntries(Object.entries(policy).map(([method, programs]) => [
+                        method,
+                        programs.map(loadProgram),
+                    ])),
+                };
     }
     return out;
 }
@@ -556,7 +630,8 @@ export function interpolateEnv(value, env) {
     }
     return out;
 }
-function readProcessEnv() {
+/** The process environment with its unset entries dropped. */
+export function readProcessEnv() {
     const out = {};
     for (const [k, v] of Object.entries(process.env)) {
         if (typeof v === 'string')
@@ -595,8 +670,8 @@ export function loadWorkspaceConfig(source, env) {
  * Resolve relative script paths and code refs against the config file's
  * directory.
  *
- * A path-form `script`/`route_policy`, a `cli: ./tool.mjs:TREE`, a
- * `resource: ./wiki.mjs:WikiResource` and a runtime entry's
+ * A path-form `script`, a `cli: ./tool.mjs:TREE`, a
+ * `vfs: ./wiki.mjs:WikiVFS` and a runtime entry's
  * `name: ./box.mjs:EchoBox` in a config file all mean "next to the file"
  * (the docker build-context model), never "wherever the server happens
  * to run". In-memory object configs are untouched. Exported so
@@ -606,14 +681,11 @@ export function loadWorkspaceConfig(source, env) {
  * `mirage/config.py`.
  */
 export function absolutizeScripts(raw, base) {
-    const policy = raw.route_policy;
-    if (typeof policy === 'string' && isScriptPath(policy) && !isAbsolute(policy.trim())) {
-        raw.route_policy = join(base, policy.trim());
-    }
+    if (isPlainObject(raw.route_policy))
+        absolutizeScriptKey(raw.route_policy, base);
     if (Array.isArray(raw.runtimes)) {
         raw.runtimes.forEach((entry, i) => {
             if (isPlainObject(entry)) {
-                absolutizeScriptKey(entry, base);
                 absolutizeCodeRef(entry, 'name', base);
             }
             else if (typeof entry === 'string') {
@@ -633,20 +705,27 @@ export function absolutizeScripts(raw, base) {
     if (isPlainObject(raw.mounts)) {
         for (const block of Object.values(raw.mounts)) {
             if (isPlainObject(block))
-                absolutizeCodeRef(block, 'resource', base);
+                absolutizeCodeRef(block, 'vfs', base);
         }
     }
     if (isPlainObject(raw.profiles)) {
         for (const block of Object.values(raw.profiles)) {
-            // A profile's policy block carries its program the way a clis
-            // entry does, so its `script` rebases the same way.
-            if (isPlainObject(block) && isPlainObject(block.policy)) {
-                absolutizeScriptKey(block.policy, base);
+            // A profile's policy programs carry their scripts the way a clis
+            // entry does, so each `script` rebases the same way.
+            if (!isPlainObject(block) || !isPlainObject(block.policy))
+                continue;
+            for (const programs of Object.values(block.policy)) {
+                if (!Array.isArray(programs))
+                    continue;
+                for (const program of programs) {
+                    if (isPlainObject(program))
+                        absolutizeScriptKey(program, base);
+                }
             }
         }
     }
 }
-/** Rebase one runtimes/clis/policy entry's relative `script` path onto `base`. */
+/** Rebase one clis entry's, policy program's or route_policy's relative `script` path onto `base`. */
 function absolutizeScriptKey(entry, base) {
     const script = entry.script;
     if (typeof script === 'string' && isScriptPath(script) && !isAbsolute(script.trim())) {
@@ -656,7 +735,7 @@ function absolutizeScriptKey(entry, base) {
 /**
  * Rebase a path-form colon reference under `key` onto `base`.
  *
- * `cli: ./tool.mjs:TREE`, `resource: ./wiki.mjs:WikiResource` and a
+ * `cli: ./tool.mjs:TREE`, `vfs: ./wiki.mjs:WikiVFS` and a
  * runtime entry's `name: ./box.mjs:EchoBox` all mean "next to the config
  * file", the same build-context rule `script:` follows; without this the
  * pointer reaches `loadAttr` relative and
@@ -704,7 +783,7 @@ export function checkWorkspaceConfigFile(path, env) {
 export function loadWorkspaceConfigFile(path, env) {
     return normalizeConfigKeys(checkWorkspaceConfigFile(path, env));
 }
-function buildIndex(block) {
+function buildIndexConfig(block) {
     if (block === null || block === undefined)
         return undefined;
     if (block.type === 'redis') {
@@ -794,22 +873,36 @@ function buildStateStore(block) {
 }
 export async function configToWorkspaceArgs(cfg) {
     const wsMode = coerceMountMode(cfg.mode, MountMode.WRITE);
-    const consistency = coerceConsistency(cfg.consistency);
-    const resources = {};
+    const defaultRead = resolveReadSpec(cfg.read, undefined);
+    const defaultWrite = coerceWritePolicy(cfg.write);
+    const mounts = {};
     const kernelMounts = {};
     // Built before the mounts, because a mount's config may point at one:
-    // `resolveConfigSecrets` inside `buildResource` fetches through these.
+    // `resolveConfigSecrets` inside `buildVfs` fetches through these.
     const blocks = [...Object.values(cfg.mounts), ...Object.values(cfg.clis ?? {})];
     const sources = await resolveSourcesFor(cfg.secrets, blocks.map((block) => block.config ?? {}));
     for (const [prefix, block] of Object.entries(cfg.mounts)) {
-        const r = await buildResource(block.resource, block.config ?? {}, sources);
+        const r = await buildVfs(block.vfs, block.config ?? {}, sources);
         const m = coerceMountMode(block.mode, wsMode);
-        resources[prefix] = [r, m, parseLimits(block.command_limits)];
-        const backend = (block.backend ?? MountBackend.VFS);
+        // Already validated by the sync entry point (validateReadBlock).
+        const read = block.read === undefined ? defaultRead : resolveReadSpec(block.read, block.ttl);
+        const mountIndex = buildIndexConfig(block.index);
+        const write = block.write === undefined || block.write === null
+            ? defaultWrite
+            : coerceWritePolicy(block.write);
+        mounts[prefix] = new Mount(r, {
+            mode: m,
+            read,
+            write,
+            commandLimits: parseCommandLimits(block.command_limits),
+            vfsRef: block.vfs,
+            ...(mountIndex !== undefined ? { index: mountIndex } : {}),
+        });
+        const backend = (block.backend ?? MountBackend.WORKSPACE);
         if (KERNEL_BACKENDS.includes(backend))
             kernelMounts[prefix] = [backend, block.mountpoint];
     }
-    const index = buildIndex(cfg.index);
+    const index = buildIndexConfig(cfg.index);
     const stateStore = buildStateStore(cfg.store);
     const cliEntries = cfg.clis !== undefined && cfg.clis !== null
         ? await buildCliEntries(cfg.clis, sources)
@@ -819,12 +912,14 @@ export async function configToWorkspaceArgs(cfg) {
         : undefined;
     const consoleFactory = buildConsoleFactory(cfg.console);
     return {
-        resources,
+        mounts,
         options: {
             mode: wsMode,
-            consistency,
+            commandLimits: parseCommandLimits(cfg.commandLimits),
+            io: new IOConfig(cfg.io),
+            read: defaultRead,
+            write: defaultWrite,
             ...(cfg.defaultSessionId !== undefined ? { sessionId: cfg.defaultSessionId } : {}),
-            ...(cfg.defaultAgentId !== undefined ? { agentId: cfg.defaultAgentId } : {}),
             ...(cfg.workspaceId !== undefined ? { workspaceId: cfg.workspaceId } : {}),
             ...(cfg.cache !== undefined && cfg.cache !== null ? { cache: cfg.cache } : {}),
             ...(index !== undefined ? { index } : {}),
@@ -836,7 +931,7 @@ export async function configToWorkspaceArgs(cfg) {
             ...(consoleFactory !== undefined ? { consoleFactory } : {}),
             ...(runtimeEntries !== undefined ? { runtimes: runtimeEntries } : {}),
             ...(cfg.routePolicy !== undefined && cfg.routePolicy !== null
-                ? { routePolicy: loadScriptSource(cfg.routePolicy) }
+                ? { routePolicy: loadProgram(parseProgram(cfg.routePolicy, 'route_policy')) }
                 : {}),
             ...(cfg.profiles !== undefined && cfg.profiles !== null
                 ? { profiles: loadProfileScripts(parseProfiles(cfg.profiles)) }
@@ -845,7 +940,7 @@ export async function configToWorkspaceArgs(cfg) {
                 ? { profile: cfg.profile }
                 : {}),
             ...(cliEntries !== undefined ? { clis: cliEntries } : {}),
-            // Passed through as-is: this door resolves resources, and
+            // Passed through as-is: this entry point resolves mounts, and
             // env-plane fetching is async at command time, so no fetching
             // here (the workspace translates and validates sources).
             ...(cfg.env !== undefined && cfg.env !== null ? { env: cfg.env } : {}),
@@ -864,35 +959,51 @@ async function resolveCliRef(ref, name) {
         return ref;
     return asCliSpec(await loadAttr(ref), name, ref);
 }
-/**
- * True when a value carries every field the CLI walker reads, at every
- * level of the tree.
- *
- * This is the invariant `CLISpec`'s own constructor enforces, checked
- * again here because the constructor that ran was not necessarily ours.
- * The fields are the ones dispatch and `man` actually touch
- * (`subcommands.find`, `aliases.includes`, `options.some`), so a value
- * that passes cannot fail later reading a missing one. A class name is
- * not enough on its own: any class called `CLISpec`, or an object with a
- * `constructor` property that says so, would answer to that and then
- * crash on the first line an agent types.
- */
+/** Validate the shared grammar and execution shape from another core copy. */
 function looksLikeCliSpec(value) {
     if (value === null || typeof value !== 'object')
         return false;
-    const node = value;
-    if (typeof node.name !== 'string' || node.name === '' || /\s/.test(node.name))
-        return false;
-    if (!Array.isArray(node.aliases) || !Array.isArray(node.options))
-        return false;
-    if (!Array.isArray(node.subcommands))
-        return false;
-    const runnable = typeof node.fn === 'function' ||
-        (node.script !== null && node.script !== undefined) ||
-        node.subcommands.length > 0;
-    if (!runnable)
+    const definition = value;
+    if (!isPlainObject(definition.handlers))
         return false;
-    return node.subcommands.every(looksLikeCliSpec);
+    for (const handler of Object.values(definition.handlers)) {
+        if (handler === null || typeof handler !== 'object')
+            return false;
+        const binding = handler;
+        if (binding.fn !== null && typeof binding.fn !== 'function')
+            return false;
+        if (typeof binding.write !== 'boolean')
+            return false;
+    }
+    const pending = [definition.spec];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const candidate = pending.pop();
+        if (candidate === null || typeof candidate !== 'object')
+            return false;
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        const node = candidate;
+        if (typeof node.name !== 'string' || node.name === '' || /\s/.test(node.name))
+            return false;
+        if (!Array.isArray(node.aliases) || !node.aliases.every((alias) => typeof alias === 'string'))
+            return false;
+        if (!Array.isArray(node.arguments) || !Array.isArray(node.subcommands))
+            return false;
+        if (typeof node.addHelp !== 'boolean' || typeof node.allowAbbrev !== 'boolean')
+            return false;
+        for (const argument of node.arguments) {
+            if (argument === null || typeof argument !== 'object')
+                return false;
+            const input = argument;
+            if (!Array.isArray(input.names) || !input.names.every((name) => typeof name === 'string'))
+                return false;
+        }
+        const subcommands = node.subcommands;
+        pending.push(...subcommands);
+    }
+    return true;
 }
 /**
  * Check that a `cli:` reference resolved to a program tree.
@@ -900,18 +1011,18 @@ function looksLikeCliSpec(value) {
  * `instanceof` is the fast path, not the test. The referenced file lives
  * in someone else's project, which is the whole point of the ref form,
  * and that project may resolve its own copy of `@struktoai/mirage-core`:
- * a real CLISpec carrying every method, built off a different class
+ * a real CLI carrying every method, built off a different class
  * object. Demanding `instanceof` would refuse exactly the case this
  * exists to serve, so anything else is admitted on its shape instead,
  * and refused at create time rather than when an agent first types the
  * head word.
  */
 function asCliSpec(value, name, ref) {
-    if (value instanceof CLISpec)
+    if (value instanceof CLI)
         return value;
     if (looksLikeCliSpec(value))
-        return value;
-    throw new Error(`clis entry '${name}': ${ref} is not a CLISpec`);
+        return new CLI(value);
+    throw new Error(`clis entry '${name}': ${ref} is not a CLI`);
 }
 async function buildCliEntries(clis, sources) {
     const out = {};
@@ -944,18 +1055,18 @@ async function buildCliEntries(clis, sources) {
         // a name for the workspace to resolve against the registered specs.
         // Mirrors the `":" in name` branch of Python's `cli_spec_for`, one
         // layer up: `cliSpecFor` lives in core, which has no filesystem and
-        // is synchronous. A `resource:` value reads the same way, resolved by
-        // `buildResource` rather than here, because a mount block reaches the
+        // is synchronous. A `vfs:` value reads the same way, resolved by
+        // `buildVfs` rather than here, because a mount block reaches the
         // registry and a `clis` block does not.
         const entry = hasScript
-            ? new CLISpec({
-                name,
+            ? new CLI({
+                spec: new CommandSpec({ name }),
                 script: loadScriptSource(block.script),
                 runtime: block.runtime ?? null,
             })
             : await resolveCliRef(block.cli, name);
         // A CLI credential reads a pointer the way a mount's does: the
-        // account CLI's `config_model` is the same model a resource
+        // account CLI's `config_model` is the same model a VFS
         // parses, so it must receive the credential, not the pointer.
         out[name] = [
             entry,