@sdxc/spec 0.0.0-pre.1

package/dist/errors.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The error taxonomy every fallible function in this package returns through
+ * `@sdxc/result`. Each class carries the structured fields diagnostics need —
+ * spans, expected/observed values, denial remedies — so the reporter formats
+ * errors without string-parsing them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { PermissionKind } from "./permissions.js";
+import type { Span } from "./source.js";
+import type { Value } from "./values.js";
+/**
+ * Machine-readable category of a failure, stable across message rewording.
+ * Reporters branch on this, never on message text.
+ */
+export type DiagnosticCode = "parse-error" | "load-error" | "duplicate-definition" | "unknown-name" | "ambiguous-name" | "expectation-failed" | "permission-denied" | "tool-error" | "workspace-escape" | "usage-error";
+/** Base class for every failure this package reports as a `Result` error. */
+export declare class SpecError extends Error {
+    /** Stable failure category; see {@link DiagnosticCode}. */
+    code: DiagnosticCode;
+    /** Path of the `.spec` file involved, when the failure has one. */
+    file?: string;
+    /** Source range of the failing statement, when known. */
+    span?: Span;
+    /** An actionable suggestion, e.g. the exact `--allow-*` flag to add. */
+    remedy?: string;
+    /**
+     * An extra, situational line appended after the remedy — set by the CLI
+     * when it has extra context, e.g. that `spec/config.jsonc` would grant
+     * the permission. Never weakens the primary {@link remedy}.
+     */
+    hint?: string;
+    /**
+     * @param code - Stable failure category.
+     * @param message - Human-readable one-line description.
+     */
+    constructor(code: DiagnosticCode, message: string);
+}
+/** A lexical or syntactic failure while reading a `.spec` file. */
+export declare class ParseError extends SpecError {
+    /**
+     * @param message - What the parser expected and what it found.
+     * @param file - Path of the file being parsed.
+     * @param span - Range of the offending text.
+     */
+    constructor(message: string, file?: string, span?: Span);
+}
+/**
+ * A suite-level failure before any test runs: unreadable directories,
+ * duplicate definitions, or a file that failed to parse during loading.
+ */
+export declare class LoadError extends SpecError {
+    /**
+     * @param code - `"load-error"` or `"duplicate-definition"`.
+     * @param message - What prevented the suite from loading.
+     */
+    constructor(code: DiagnosticCode, message: string);
+}
+/**
+ * A name that resolved to nothing (`unknown-name`) or to more than one
+ * candidate (`ambiguous-name`). The runtime never guesses; it reports the
+ * candidates and asks for a qualified name.
+ */
+export declare class ResolutionError extends SpecError {
+    /** Fully qualified candidates, populated for ambiguity errors. */
+    candidates: string[];
+    /**
+     * @param code - `"unknown-name"` or `"ambiguous-name"`.
+     * @param message - The name and, when ambiguous, its candidates.
+     * @param candidates - Fully qualified candidates for ambiguous names.
+     */
+    constructor(code: DiagnosticCode, message: string, candidates?: string[]);
+}
+/** An `expect` that did not hold, carrying both sides for the reporter. */
+export declare class ExpectationError extends SpecError {
+    /** The value the specification demanded, when the form has one. */
+    expected?: Value;
+    /** The value actually observed. */
+    observed?: Value;
+    /**
+     * @param message - One-line statement of the failed expectation.
+     * @param expected - The demanded value, when applicable.
+     * @param observed - The observed value, when applicable.
+     */
+    constructor(message: string, expected?: Value, observed?: Value);
+}
+/**
+ * A capability use the caller never granted. Always names the permission,
+ * the attempted resource, and the exact flag that would grant it — the
+ * design suite makes this diagnostic quality a requirement, not a nicety.
+ */
+export declare class PermissionDeniedError extends SpecError {
+    /** Which permission family was required. */
+    permission: PermissionKind;
+    /** What the spec attempted to reach: an executable, host, variable, path. */
+    resource: string;
+    /**
+     * Whether the coarse family gate raised this denial before the resource
+     * was known, in which case {@link resource} holds the qualified tool name.
+     * Governs whether `--allow-config` needs family- or scope-level coverage.
+     */
+    familyGate: boolean;
+    /**
+     * @param permission - The required permission family.
+     * @param resource - The attempted resource.
+     * @param remedy - The exact `spec run` flag that would grant it.
+     * @param familyGate - Whether the coarse family gate raised this denial.
+     */
+    constructor(permission: PermissionKind, resource: string, remedy: string, familyGate?: boolean);
+}
+/** A tool that was reached and ran, but failed on its own terms. */
+export declare class ToolError extends SpecError {
+    /**
+     * @param message - The tool's own account of the failure.
+     */
+    constructor(message: string);
+}
+/**
+ * A path that would leave the isolated workspace without a host-filesystem
+ * grant — reported distinctly from permission denials so traversal attempts
+ * are visible as what they are.
+ */
+export declare class WorkspaceEscapeError extends SpecError {
+    /** The offending path as written in the spec. */
+    attemptedPath: string;
+    /**
+     * @param attemptedPath - The path as the spec wrote it.
+     */
+    constructor(attemptedPath: string);
+}

package/dist/errors.js

@@ -0,0 +1,159 @@
+/**
+ * The error taxonomy every fallible function in this package returns through
+ * `@sdxc/result`. Each class carries the structured fields diagnostics need —
+ * spans, expected/observed values, denial remedies — so the reporter formats
+ * errors without string-parsing them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Base class for every failure this package reports as a `Result` error. */
+export class SpecError extends Error {
+    /** Stable failure category; see {@link DiagnosticCode}. */
+    code;
+    /** Path of the `.spec` file involved, when the failure has one. */
+    file;
+    /** Source range of the failing statement, when known. */
+    span;
+    /** An actionable suggestion, e.g. the exact `--allow-*` flag to add. */
+    remedy;
+    /**
+     * An extra, situational line appended after the remedy — set by the CLI
+     * when it has extra context, e.g. that `spec/config.jsonc` would grant
+     * the permission. Never weakens the primary {@link remedy}.
+     */
+    hint;
+    /**
+     * @param code - Stable failure category.
+     * @param message - Human-readable one-line description.
+     */
+    constructor(code, message) {
+        super(message);
+        this.name = "SpecError";
+        this.code = code;
+    }
+}
+/** A lexical or syntactic failure while reading a `.spec` file. */
+export class ParseError extends SpecError {
+    /**
+     * @param message - What the parser expected and what it found.
+     * @param file - Path of the file being parsed.
+     * @param span - Range of the offending text.
+     */
+    constructor(message, file, span) {
+        super("parse-error", message);
+        this.name = "ParseError";
+        this.file = file;
+        this.span = span;
+    }
+}
+/**
+ * A suite-level failure before any test runs: unreadable directories,
+ * duplicate definitions, or a file that failed to parse during loading.
+ */
+export class LoadError extends SpecError {
+    /**
+     * @param code - `"load-error"` or `"duplicate-definition"`.
+     * @param message - What prevented the suite from loading.
+     */
+    constructor(code, message) {
+        super(code, message);
+        this.name = "LoadError";
+    }
+}
+/**
+ * A name that resolved to nothing (`unknown-name`) or to more than one
+ * candidate (`ambiguous-name`). The runtime never guesses; it reports the
+ * candidates and asks for a qualified name.
+ */
+export class ResolutionError extends SpecError {
+    /** Fully qualified candidates, populated for ambiguity errors. */
+    candidates;
+    /**
+     * @param code - `"unknown-name"` or `"ambiguous-name"`.
+     * @param message - The name and, when ambiguous, its candidates.
+     * @param candidates - Fully qualified candidates for ambiguous names.
+     */
+    constructor(code, message, candidates = []) {
+        super(code, message);
+        this.name = "ResolutionError";
+        this.candidates = candidates;
+    }
+}
+/** An `expect` that did not hold, carrying both sides for the reporter. */
+export class ExpectationError extends SpecError {
+    /** The value the specification demanded, when the form has one. */
+    expected;
+    /** The value actually observed. */
+    observed;
+    /**
+     * @param message - One-line statement of the failed expectation.
+     * @param expected - The demanded value, when applicable.
+     * @param observed - The observed value, when applicable.
+     */
+    constructor(message, expected, observed) {
+        super("expectation-failed", message);
+        this.name = "ExpectationError";
+        this.expected = expected;
+        this.observed = observed;
+    }
+}
+/**
+ * A capability use the caller never granted. Always names the permission,
+ * the attempted resource, and the exact flag that would grant it — the
+ * design suite makes this diagnostic quality a requirement, not a nicety.
+ */
+export class PermissionDeniedError extends SpecError {
+    /** Which permission family was required. */
+    permission;
+    /** What the spec attempted to reach: an executable, host, variable, path. */
+    resource;
+    /**
+     * Whether the coarse family gate raised this denial before the resource
+     * was known, in which case {@link resource} holds the qualified tool name.
+     * Governs whether `--allow-config` needs family- or scope-level coverage.
+     */
+    familyGate;
+    /**
+     * @param permission - The required permission family.
+     * @param resource - The attempted resource.
+     * @param remedy - The exact `spec run` flag that would grant it.
+     * @param familyGate - Whether the coarse family gate raised this denial.
+     */
+    constructor(permission, resource, remedy, familyGate = false) {
+        super("permission-denied", `Permission denied: ${permission}. The spec attempted to reach: ${resource}`);
+        this.name = "PermissionDeniedError";
+        this.permission = permission;
+        this.resource = resource;
+        this.remedy = remedy;
+        this.familyGate = familyGate;
+    }
+}
+/** A tool that was reached and ran, but failed on its own terms. */
+export class ToolError extends SpecError {
+    /**
+     * @param message - The tool's own account of the failure.
+     */
+    constructor(message) {
+        super("tool-error", message);
+        this.name = "ToolError";
+    }
+}
+/**
+ * A path that would leave the isolated workspace without a host-filesystem
+ * grant — reported distinctly from permission denials so traversal attempts
+ * are visible as what they are.
+ */
+export class WorkspaceEscapeError extends SpecError {
+    /** The offending path as written in the spec. */
+    attemptedPath;
+    /**
+     * @param attemptedPath - The path as the spec wrote it.
+     */
+    constructor(attemptedPath) {
+        super("workspace-escape", `Path resolves outside the test workspace: ${attemptedPath}`);
+        this.name = "WorkspaceEscapeError";
+        this.attemptedPath = attemptedPath;
+        this.remedy = "spec run --allow-host-fs=<directory>";
+    }
+}

package/dist/executor.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The interpreter core of the runtime: executes one test's statements against
+ * the suite registry, an isolated workspace, and the caller's grants. Owns
+ * scopes, `let`/`return`, command and fixture invocation, and the central
+ * permission gate that refuses denied permission families before a plugin
+ * ever sees the call.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { Random } from "@sdxc/sample";
+import type { DefinitionNode, TestNode } from "./ast.js";
+import type { Grants, PermissionSet } from "./permissions.js";
+import type { Registry } from "./registry.js";
+import type { Workspace } from "./workspace.js";
+import { SpecError } from "./errors.js";
+/**
+ * Everything one test needs to execute: the suite's resolution table, its
+ * isolated workspace, the caller's grants, and the namespaces its file
+ * imported with `use`.
+ */
+export interface ExecutionContext {
+    /** The suite's name-resolution table. */
+    registry: Registry;
+    /** The test's isolated workspace, handed to every tool call. */
+    workspace: Workspace;
+    /** The caller's grant set, handed to every tool call for scoped checks. */
+    permissions: PermissionSet;
+    /** The test's seeded stream, handed to every tool call that generates data. */
+    random: Random;
+    /** The instant the test started, frozen for the whole test. */
+    now: Date;
+    /** Namespaces imported by the test's file, in `use` order. */
+    uses: readonly string[];
+    /**
+     * The namespaces imported by the file that DEFINED a command or fixture —
+     * `use` is file-scoped, so a definition's body resolves bare names against
+     * its own file's imports, never the caller's.
+     */
+    usesFor: (definition: DefinitionNode) => readonly string[];
+    /**
+     * The path of the file that DEFINED a command or fixture. Errors inside a
+     * definition's body anchor to the defining file so their spans map onto
+     * the source text they came from; when absent, errors keep the calling file.
+     */
+    fileFor?: (definition: DefinitionNode) => string | undefined;
+    /**
+     * The parsed grant modes: the executor refuses a denied permission family
+     * before its plugin runs, and scoped refinement (host, binary) happens
+     * inside the plugin through the runtime-owned `PermissionSet`.
+     */
+    grants: Grants;
+    /** Path of the file the test lives in, stamped onto every error. */
+    file?: string;
+}
+/**
+ * Execute one test: its `given`, `when`, and `then` phases share a single
+ * scope and run in order, and the first failing statement ends the test.
+ * Every error is stamped with the failing statement's span and file path.
+ *
+ * @param test - The test to execute.
+ * @param context - The suite services and grants the test runs against.
+ * @returns Success when every statement held, otherwise the first failure.
+ */
+export declare function executeTest(test: TestNode, context: ExecutionContext): Promise<Result<undefined, SpecError>>;

package/dist/executor.js

@@ -0,0 +1,320 @@
+/**
+ * The interpreter core of the runtime: executes one test's statements against
+ * the suite registry, an isolated workspace, and the caller's grants. Owns
+ * scopes, `let`/`return`, command and fixture invocation, and the central
+ * permission gate that refuses denied permission families before a plugin
+ * ever sees the call.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { PermissionDeniedError, ResolutionError, SpecError, ToolError } from "./errors.js";
+import { executeEventually, executeExpect } from "./expectation.js";
+/** How deep command/fixture invocations may nest before a cycle is suspected. */
+const MAX_CALL_DEPTH = 32;
+/** Maps a permission family to its key in the {@link Grants} record. */
+const GRANT_KEYS = {
+    run: "run",
+    net: "net",
+    env: "env",
+    "host-fs": "hostFs",
+};
+/**
+ * Execute one test: its `given`, `when`, and `then` phases share a single
+ * scope and run in order, and the first failing statement ends the test.
+ * Every error is stamped with the failing statement's span and file path.
+ *
+ * @param test - The test to execute.
+ * @param context - The suite services and grants the test runs against.
+ * @returns Success when every statement held, otherwise the first failure.
+ */
+export async function executeTest(test, context) {
+    let scope = new Map();
+    let environment = { ...context, depth: 0 };
+    let phases = [test.given, test.when, test.then];
+    for (let phase of phases) {
+        if (phase === undefined)
+            continue;
+        let outcome = await executeStatements(phase.statements, scope, environment, false);
+        if (isFailure(outcome))
+            return outcome;
+    }
+    return success(undefined);
+}
+/**
+ * Run a statement sequence in order, anchoring every failure to the failing
+ * statement, until it completes, returns, or fails.
+ */
+async function executeStatements(statements, scope, environment, allowReturn) {
+    for (let statement of statements) {
+        let result = await executeStatement(statement, scope, environment, allowReturn);
+        if (isFailure(result)) {
+            return failure(anchor(result.error, statement.span, environment.file));
+        }
+        if (result.data.kind === "returned")
+            return result;
+    }
+    return success({ kind: "completed" });
+}
+/** Dispatch one statement: let, return, call, expect, or eventually. */
+async function executeStatement(statement, scope, environment, allowReturn) {
+    if (statement.kind === "let") {
+        if (scope.has(statement.name)) {
+            return failure(new SpecError("usage-error", `"${statement.name}" is already bound; let never rebinds a name`));
+        }
+        let value = await evaluateRhs(statement.value, scope, environment);
+        if (isFailure(value))
+            return value;
+        scope.set(statement.name, value.data);
+        return success({ kind: "completed" });
+    }
+    if (statement.kind === "return") {
+        if (!allowReturn) {
+            return failure(new SpecError("usage-error", "return is only valid inside command and fixture bodies"));
+        }
+        let value = await evaluateRhs(statement.value, scope, environment);
+        if (isFailure(value))
+            return value;
+        return success({ kind: "returned", value: value.data });
+    }
+    if (statement.kind === "call") {
+        let result = await invokeCallable(statement.target, statement.args, statement.span, scope, environment);
+        if (isFailure(result))
+            return result;
+        return success({ kind: "completed" });
+    }
+    if (statement.kind === "expect") {
+        let result = await executeExpect(statement, makeHost(scope, environment));
+        if (isFailure(result))
+            return result;
+        return success({ kind: "completed" });
+    }
+    let result = await executeEventually(statement, makeHost(scope, environment));
+    if (isFailure(result))
+        return result;
+    return success({ kind: "completed" });
+}
+/** Evaluate a `let`/`return` right-hand side: expression, fixture, or call. */
+async function evaluateRhs(rhs, scope, environment) {
+    if (rhs.kind === "fixture-call")
+        return runFixture(rhs.name, rhs.span, environment);
+    if (rhs.kind === "call-expr") {
+        return invokeCallable(rhs.target, rhs.args, rhs.span, scope, environment);
+    }
+    if (rhs.kind === "reference") {
+        let call = zeroArgToolCall(rhs, scope, environment);
+        if (call !== undefined)
+            return call;
+    }
+    return evaluateExpression(rhs, scope);
+}
+/**
+ * A bare-path `let`/`return` right-hand side normally references the scope;
+ * an unbound head may instead name a zero-argument tool, dispatched through
+ * the ordinary tool path so the runtime's permission gate still applies.
+ */
+function zeroArgToolCall(reference, scope, environment) {
+    let head = reference.path[0];
+    if (head === undefined || scope.has(head))
+        return undefined;
+    let resolved = environment.registry.resolveCallable(reference.path.join("."), environment.uses);
+    if (isFailure(resolved) || resolved.data.kind !== "tool")
+        return undefined;
+    if (resolved.data.descriptor.params.some((param) => param.required))
+        return undefined;
+    return invokeTool(resolved.data, [], reference.span, scope, environment);
+}
+function evaluateExpression(expression, scope) {
+    if (expression.kind === "string")
+        return success(expression.value);
+    if (expression.kind === "number")
+        return success(expression.value);
+    if (expression.kind === "boolean")
+        return success(expression.value);
+    if (expression.kind === "duration")
+        return success(expression.milliseconds);
+    if (expression.kind === "object") {
+        let object = {};
+        for (let entry of expression.entries) {
+            let value = evaluateExpression(entry.value, scope);
+            if (isFailure(value))
+                return value;
+            object[entry.key] = value.data;
+        }
+        return success(object);
+    }
+    return resolveReference(expression, scope);
+}
+/**
+ * Resolve a dotted reference: the head segment must be a binding and every
+ * further segment a field of the value so far — a miss is an `unknown-name`
+ * error, never `null`.
+ */
+function resolveReference(reference, scope) {
+    let head = reference.path[0];
+    if (head === undefined || !scope.has(head)) {
+        return failure(anchor(new ResolutionError("unknown-name", `Unknown name "${head ?? ""}" — nothing is bound under it`), reference.span));
+    }
+    let current = scope.get(head) ?? null;
+    for (let index = 1; index < reference.path.length; index++) {
+        let segment = reference.path[index];
+        if (segment === undefined)
+            continue;
+        if (typeof current !== "object" ||
+            current === null ||
+            Array.isArray(current) ||
+            !(segment in current)) {
+            let prefix = reference.path.slice(0, index).join(".");
+            return failure(anchor(new ResolutionError("unknown-name", `Unknown field "${segment}" — "${prefix}" has no such field`), reference.span));
+        }
+        current = current[segment] ?? null;
+    }
+    return success(current);
+}
+/** Resolve a call target and invoke the tool or command it names. */
+async function invokeCallable(target, args, span, scope, environment) {
+    let resolved = environment.registry.resolveCallable(target, environment.uses);
+    if (isFailure(resolved))
+        return failure(anchor(resolved.error, span, environment.file));
+    if (resolved.data.kind === "tool") {
+        return invokeTool(resolved.data, args, span, scope, environment);
+    }
+    return invokeCommand(resolved.data.command, args, span, scope, environment);
+}
+/**
+ * Invoke one plugin tool: evaluate the arguments (words stay symbolic), pass
+ * the central permission gate, then hand the call to the plugin with the
+ * test's workspace and grants.
+ */
+async function invokeTool(tool, args, span, scope, environment) {
+    let toolArgs = [];
+    for (let argument of args) {
+        if (argument.kind === "word") {
+            toolArgs.push({ kind: "word", word: argument.word });
+            continue;
+        }
+        let value = evaluateExpression(argument, scope);
+        if (isFailure(value))
+            return value;
+        toolArgs.push({ kind: "value", value: value.data });
+    }
+    let gate = gateToolCall(tool, environment);
+    if (isFailure(gate))
+        return failure(anchor(gate.error, span, environment.file));
+    let result = await tool.plugin.call(tool.descriptor.name, toolArgs, {
+        workspace: environment.workspace,
+        permissions: environment.permissions,
+        random: environment.random,
+        now: environment.now,
+    });
+    if (isFailure(result))
+        return failure(anchor(result.error, span, environment.file));
+    return result;
+}
+/**
+ * The runtime's coarse permission gate: a tool whose required permission
+ * family is denied outright never reaches its plugin; scoped refinement
+ * happens inside the plugin through the runtime-owned `PermissionSet`.
+ */
+function gateToolCall(tool, environment) {
+    let required = tool.descriptor.requires;
+    if (required === undefined)
+        return success(undefined);
+    let grant = environment.grants[GRANT_KEYS[required]];
+    if (grant.mode !== "denied")
+        return success(undefined);
+    let qualified = `${tool.namespace}.${tool.descriptor.name}`;
+    return failure(new PermissionDeniedError(required, qualified, `spec run --allow-${required}`, true));
+}
+/**
+ * Invoke one suite command: arguments are evaluated as values (a bare word
+ * reads the caller's binding of that spelling) and bound positionally to a
+ * fresh scope; the body's `return` value (or `null`) is the call's value.
+ */
+async function invokeCommand(command, args, span, scope, environment) {
+    let values = [];
+    for (let argument of args) {
+        let value = evaluateValueArgument(argument, scope);
+        if (isFailure(value))
+            return value;
+        values.push(value.data);
+    }
+    if (values.length !== command.params.length) {
+        return failure(anchor(new SpecError("usage-error", `Command "${command.name}" expects ${command.params.length} argument(s), got ${values.length}`), span, environment.file));
+    }
+    let commandScope = new Map();
+    for (let index = 0; index < command.params.length; index++) {
+        let param = command.params[index];
+        if (param === undefined)
+            continue;
+        commandScope.set(param, values[index] ?? null);
+    }
+    return runBody(command, commandScope, span, environment);
+}
+/** Run `fixture NAME`: a fresh, empty scope; the body runs on every call. */
+async function runFixture(name, span, environment) {
+    let resolved = environment.registry.resolveFixture(name);
+    if (isFailure(resolved))
+        return failure(anchor(resolved.error, span, environment.file));
+    return runBody(resolved.data, new Map(), span, environment);
+}
+/**
+ * Run a command or fixture body under the recursion cap; a body that never
+ * returns produces `null`. Because `use` is file-scoped, the body resolves
+ * bare names against the defining file's imports, so its errors anchor there.
+ */
+async function runBody(definition, scope, span, environment) {
+    if (environment.depth >= MAX_CALL_DEPTH) {
+        return failure(anchor(new ToolError(`Call depth exceeded ${MAX_CALL_DEPTH} while invoking ${definition.kind} "${definition.name}" — a command or fixture cycle is suspected`), span, environment.file));
+    }
+    let nested = {
+        ...environment,
+        depth: environment.depth + 1,
+        uses: environment.usesFor(definition),
+    };
+    let definitionFile = environment.fileFor?.(definition);
+    if (definitionFile !== undefined)
+        nested.file = definitionFile;
+    let outcome = await executeStatements(definition.body.statements, scope, nested, true);
+    if (isFailure(outcome))
+        return outcome;
+    if (outcome.data.kind === "returned")
+        return success(outcome.data.value);
+    return success(null);
+}
+/**
+ * Evaluate one argument as a value: expressions evaluate in the scope, and a
+ * bare word reads the binding of the same spelling — words are only symbolic
+ * when a tool receives them.
+ */
+function evaluateValueArgument(argument, scope) {
+    if (argument.kind !== "word")
+        return evaluateExpression(argument, scope);
+    if (!scope.has(argument.word)) {
+        return failure(anchor(new ResolutionError("unknown-name", `Unknown name "${argument.word}" — nothing is bound under it`), argument.span));
+    }
+    return success(scope.get(argument.word) ?? null);
+}
+/** The seam `expect`/`eventually` use to evaluate and dispatch through us. */
+function makeHost(scope, environment) {
+    return {
+        scope,
+        registry: environment.registry,
+        uses: environment.uses,
+        evaluate(expression) {
+            return evaluateExpression(expression, scope);
+        },
+        callTool(tool, args, span) {
+            return invokeTool(tool, args, span, scope, environment);
+        },
+    };
+}
+/** Stamp a span and file onto an error that does not carry them yet. */
+function anchor(error, span, file) {
+    if (error.span === undefined)
+        error.span = span;
+    if (error.file === undefined && file !== undefined)
+        error.file = file;
+    return error;
+}