@sdxc/spec 0.0.0-pre.1

package/dist/transport-stdio.js

@@ -0,0 +1,400 @@
+/**
+ * The NDJSON-over-stdio plugin transport: how an external executable becomes
+ * a `Plugin`, one JSON document per line over the child's stdio, with
+ * strictly increasing request ids and in-order replies. The child inherits
+ * no environment beyond PATH.
+ *
+ * `workspaceRoot` crosses the wire so a plugin can resolve its own paths, but
+ * scoped permission enforcement over the wire is still an open design
+ * question — the host's coarse `requires` gate runs before every call.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { failure, isFailure, isSuccess, success } from "@sdxc/result";
+import { createRandom } from "@sdxc/sample";
+import { PermissionDeniedError, SpecError, ToolError, WorkspaceEscapeError } from "./errors.js";
+/** How long `connectStdioPlugin` waits for the describe reply. */
+const HANDSHAKE_TIMEOUT_MS = 5000;
+/** Every code a plugin may put on the wire; anything else maps to tool-error. */
+const WIRE_CODES = new Set([
+    "parse-error",
+    "load-error",
+    "duplicate-definition",
+    "unknown-name",
+    "ambiguous-name",
+    "expectation-failed",
+    "permission-denied",
+    "tool-error",
+    "workspace-escape",
+    "usage-error",
+]);
+/** The seed a served plugin's stream opens on. */
+const WIRE_SEED = "spec-plugin";
+/**
+ * Spawn an external plugin process and connect it as a `Plugin`: send the
+ * describe handshake (5s timeout), cache the returned descriptors, and hand
+ * back a `call()` that round-trips over the child's stdio.
+ *
+ * @param command - The argv to spawn, e.g. `["bun", "plugins/demo.ts"]`.
+ * @param namespace - The namespace the connected plugin's tools live under.
+ * @returns The connected plugin, or the failure that prevented the handshake.
+ */
+export async function connectStdioPlugin(command, namespace) {
+    if (command.length === 0) {
+        return failure(new ToolError("Cannot connect a stdio plugin: the command is empty"));
+    }
+    let child;
+    try {
+        child = await spawnChild(command);
+    }
+    catch (error) {
+        return failure(new ToolError(`Failed to spawn plugin command "${command.join(" ")}": ${errorMessage(error)}`));
+    }
+    let connection = openConnection(child);
+    let handshake = await connection.request({ method: "describe" }, HANDSHAKE_TIMEOUT_MS);
+    if (isFailure(handshake)) {
+        connection.kill();
+        return handshake;
+    }
+    if (!Array.isArray(handshake.data)) {
+        connection.kill();
+        return failure(new ToolError(`Plugin "${command.join(" ")}" answered the describe handshake with ${JSON.stringify(handshake.data)} instead of a tool descriptor list`));
+    }
+    let descriptors = handshake.data;
+    return success({
+        namespace,
+        describe() {
+            return descriptors;
+        },
+        async call(tool, args, context) {
+            let reply = await connection.request({
+                method: "call",
+                tool,
+                args,
+                workspaceRoot: context.workspace.root,
+                now: context.now.toISOString(),
+            });
+            if (isFailure(reply))
+                return reply;
+            return success(reply.data);
+        },
+        /**
+         * Kills the child and fails any in-flight request. The runner calls this
+         * once after the suite, so the launched process never lingers.
+         */
+        async dispose() {
+            connection.kill();
+        },
+    });
+}
+/**
+ * The plugin-side serve loop: read requests from stdin, dispatch each to the
+ * given plugin, and write matching replies to stdout, in order. A line that
+ * fails to parse carries no id, so parsing simply continues to the next one.
+ *
+ * @param plugin - The local plugin implementation to expose over the wire.
+ */
+export async function servePlugin(plugin) {
+    for await (let line of readLines(process.stdin)) {
+        if (line.trim() === "")
+            continue;
+        let request = parseWireRequest(line);
+        if (request === null)
+            continue;
+        if (request.method === "describe") {
+            writeReply({ id: request.id, result: plugin.describe() });
+            continue;
+        }
+        if (request.method === "call") {
+            let outcome = await plugin.call(request.tool ?? "", request.args ?? [], createWireContext(request.workspaceRoot ?? "", request.now));
+            if (isSuccess(outcome)) {
+                writeReply({ id: request.id, result: outcome.data });
+            }
+            else {
+                writeReply({
+                    id: request.id,
+                    error: { code: outcome.error.code, message: outcome.error.message },
+                });
+            }
+            continue;
+        }
+        writeReply({
+            id: request.id,
+            error: { code: "usage-error", message: `Unknown method "${request.method}"` },
+        });
+    }
+    return undefined;
+}
+/**
+ * Spawn a plugin command, resolving only once the OS confirms it started, so
+ * a bad executable fails here instead of later. It inherits nothing but
+ * PATH; a mid-call exit's broken stdin pipe surfaces via the pending request.
+ *
+ * @param command - The argv to spawn, first element being the executable.
+ * @returns The started child, narrowed to what the transport reads and writes.
+ * @throws When the executable cannot be started.
+ */
+async function spawnChild(command) {
+    let child = spawn(command[0] ?? "", command.slice(1), {
+        stdio: ["pipe", "pipe", "ignore"],
+        env: { PATH: process.env.PATH ?? "" },
+    });
+    child.stdin?.on("error", () => { });
+    let failed = await new Promise((settle) => {
+        child.once("spawn", () => settle(undefined));
+        child.once("error", (error) => settle(error));
+    });
+    if (failed !== undefined)
+        throw failed;
+    let stdin = child.stdin;
+    let stdout = child.stdout;
+    if (stdin === null || stdout === null) {
+        child.kill();
+        throw new Error("the child was started without usable stdio pipes");
+    }
+    return {
+        stdin,
+        stdout,
+        kill() {
+            child.kill();
+        },
+    };
+}
+/** Wire one spawned child into a request/reply connection. */
+function openConnection(child) {
+    let nextId = 1;
+    let closed = false;
+    let pending = new Map();
+    function settle(id, outcome) {
+        let entry = pending.get(id);
+        if (entry === undefined)
+            return undefined;
+        pending.delete(id);
+        entry.settle(outcome);
+        return undefined;
+    }
+    function close(error) {
+        if (closed)
+            return undefined;
+        closed = true;
+        for (let id of pending.keys())
+            settle(id, failure(error));
+        return undefined;
+    }
+    async function pumpReplies() {
+        try {
+            for await (let line of readLines(child.stdout)) {
+                if (line.trim() === "")
+                    continue;
+                let reply = parseWireReply(line);
+                if (reply === null) {
+                    close(new ToolError(`The plugin broke the wire protocol with a malformed reply line: ${truncate(line)}`));
+                    child.kill();
+                    return undefined;
+                }
+                if ("error" in reply) {
+                    settle(reply.id, failure(reconstructWireError(reply.error)));
+                }
+                else {
+                    settle(reply.id, success(reply.result));
+                }
+            }
+            close(new ToolError("The plugin process closed the connection"));
+        }
+        catch (error) {
+            close(new ToolError(`Reading from the plugin failed: ${errorMessage(error)}`));
+        }
+        return undefined;
+    }
+    void pumpReplies();
+    return {
+        request(body, timeoutMs) {
+            if (closed) {
+                return Promise.resolve(failure(new ToolError("The plugin process is no longer running")));
+            }
+            let id = nextId;
+            nextId += 1;
+            return new Promise((resolve) => {
+                let timer;
+                pending.set(id, {
+                    settle(outcome) {
+                        if (timer !== undefined)
+                            clearTimeout(timer);
+                        resolve(outcome);
+                    },
+                });
+                if (timeoutMs !== undefined) {
+                    timer = setTimeout(() => {
+                        settle(id, failure(new ToolError(`The plugin did not reply to "${body.method}" within ${timeoutMs}ms`)));
+                    }, timeoutMs);
+                }
+                try {
+                    child.stdin.write(`${JSON.stringify({ id, ...body })}\n`);
+                }
+                catch (error) {
+                    settle(id, failure(new ToolError(`Writing to the plugin failed: ${errorMessage(error)}`)));
+                }
+            });
+        },
+        /** An already-exited child counts as killed too, so the close below always runs. */
+        kill() {
+            try {
+                child.kill();
+            }
+            catch { }
+            close(new ToolError("The plugin connection was closed"));
+        },
+    };
+}
+/**
+ * Build the `ToolContext` the serving side hands its local plugin: relative
+ * paths resolve inside the forwarded workspace root and traversal out is
+ * refused, while permission checks stay permissive behind the host's gate.
+ *
+ * The instant crosses the wire, so a plugin here reads the same time the test
+ * started. The stream does not: it opens on a fixed seed, giving a served
+ * plugin values that repeat run to run. Carrying the host's stream position
+ * across a process boundary waits for a plugin that generates data.
+ */
+function createWireContext(workspaceRoot, now) {
+    let workspace = {
+        root: workspaceRoot,
+        resolve(target) {
+            if (path.isAbsolute(target)) {
+                return failure(new PermissionDeniedError("host-fs", target, "spec run --allow-host-fs=<directory>"));
+            }
+            let resolved = path.resolve(workspaceRoot, target);
+            let relative = path.relative(workspaceRoot, resolved);
+            if (relative === ".." || relative.startsWith(`..${path.sep}`)) {
+                return failure(new WorkspaceEscapeError(target));
+            }
+            return success(resolved);
+        },
+        async cleanup() {
+            return undefined;
+        },
+    };
+    let permissions = {
+        checkRun() {
+            return success(undefined);
+        },
+        checkNet() {
+            return success(undefined);
+        },
+        checkEnv() {
+            return success(undefined);
+        },
+        checkHostFs() {
+            return success(undefined);
+        },
+        grantedEnvNames() {
+            return [];
+        },
+    };
+    return {
+        workspace,
+        permissions,
+        random: createRandom(WIRE_SEED),
+        now: now === undefined ? new Date() : new Date(now),
+    };
+}
+/** Write one reply line to stdout, the serving side's half of the wire. */
+function writeReply(reply) {
+    process.stdout.write(`${JSON.stringify(reply)}\n`);
+    return undefined;
+}
+/**
+ * Split a byte stream into newline-delimited lines.
+ *
+ * @yields One line at a time, without its terminating newline.
+ */
+async function* readLines(stream) {
+    let decoder = new TextDecoder();
+    let buffer = "";
+    for await (let chunk of stream) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let index = buffer.indexOf("\n");
+        while (index !== -1) {
+            yield buffer.slice(0, index);
+            buffer = buffer.slice(index + 1);
+            index = buffer.indexOf("\n");
+        }
+    }
+    buffer += decoder.decode();
+    if (buffer.length > 0)
+        yield buffer;
+    return undefined;
+}
+/** Parse one plugin→host reply line; null means the line broke the protocol. */
+function parseWireReply(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    let record = parsed;
+    if (typeof record.id !== "number")
+        return null;
+    if ("error" in record) {
+        if (typeof record.error !== "object" || record.error === null)
+            return null;
+        let wire = record.error;
+        return {
+            id: record.id,
+            error: {
+                code: typeof wire.code === "string" ? wire.code : "tool-error",
+                message: typeof wire.message === "string"
+                    ? wire.message
+                    : "The plugin reported an error without a message",
+            },
+        };
+    }
+    return { id: record.id, result: record.result ?? null };
+}
+/** Parse one host→plugin request line; null means it broke the protocol. */
+function parseWireRequest(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    let record = parsed;
+    if (typeof record.id !== "number" || typeof record.method !== "string")
+        return null;
+    return {
+        id: record.id,
+        method: record.method,
+        tool: typeof record.tool === "string" ? record.tool : undefined,
+        args: Array.isArray(record.args) ? record.args : undefined,
+        workspaceRoot: typeof record.workspaceRoot === "string" ? record.workspaceRoot : undefined,
+        now: typeof record.now === "string" ? record.now : undefined,
+    };
+}
+/** Rebuild a `SpecError` from its wire form, defaulting unknown codes. */
+function reconstructWireError(wire) {
+    let code = WIRE_CODES.has(wire.code)
+        ? wire.code
+        : "tool-error";
+    return new SpecError(code, wire.message);
+}
+/** Render an unknown thrown value as a one-line message. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Cap a wire line for inclusion in an error message. */
+function truncate(line) {
+    if (line.length <= 120)
+        return line;
+    return `${line.slice(0, 120)}…`;
+}

package/dist/values.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The runtime value model: what `.spec` expressions evaluate to and what
+ * tools receive and return. Values are deliberately JSON-shaped so they
+ * cross the plugin protocol boundary already serialized.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** An object value: string keys to nested values, as literal syntax builds. */
+export interface ValueObject {
+    [key: string]: Value;
+}
+/**
+ * Everything a `.spec` expression can evaluate to. Duration literals
+ * evaluate to their number of milliseconds, represented by the plain
+ * `number` case above.
+ */
+export type Value = string | number | boolean | null | Value[] | ValueObject;
+/**
+ * One argument to a tool call. A `word` is a bare identifier in argument
+ * position (`exists`, `textbox`, `with`) — a symbol the tool's descriptor
+ * interprets, carrying its own tag apart from a same-spelled string value.
+ */
+export type ToolArg = {
+    kind: "value";
+    value: Value;
+} | {
+    kind: "word";
+    word: string;
+};
+/**
+ * Deep structural equality over runtime values — the semantics of the
+ * two-argument `expect A B` form. Arrays compare by index, objects by key
+ * set, primitives by `===`.
+ *
+ * @param left - One value.
+ * @param right - The other value.
+ * @returns Whether the two values are structurally identical.
+ */
+export declare function valueEquals(left: Value, right: Value): boolean;
+/**
+ * Render a value for diagnostics: JSON with stable key order and indentation
+ * only when the value spans structures, so simple failures stay on one line.
+ *
+ * @param value - The value to render.
+ * @returns A human-readable, deterministic rendering.
+ */
+export declare function formatValue(value: Value): string;

package/dist/values.js

@@ -0,0 +1,52 @@
+/**
+ * The runtime value model: what `.spec` expressions evaluate to and what
+ * tools receive and return. Values are deliberately JSON-shaped so they
+ * cross the plugin protocol boundary already serialized.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Deep structural equality over runtime values — the semantics of the
+ * two-argument `expect A B` form. Arrays compare by index, objects by key
+ * set, primitives by `===`.
+ *
+ * @param left - One value.
+ * @param right - The other value.
+ * @returns Whether the two values are structurally identical.
+ */
+export function valueEquals(left, right) {
+    if (left === right)
+        return true;
+    if (Array.isArray(left) && Array.isArray(right)) {
+        if (left.length !== right.length)
+            return false;
+        return left.every((item, index) => valueEquals(item, right[index] ?? null));
+    }
+    if (typeof left === "object" &&
+        left !== null &&
+        !Array.isArray(left) &&
+        typeof right === "object" &&
+        right !== null &&
+        !Array.isArray(right)) {
+        let leftKeys = Object.keys(left);
+        let rightKeys = Object.keys(right);
+        if (leftKeys.length !== rightKeys.length)
+            return false;
+        return leftKeys.every((key) => key in right && valueEquals(left[key] ?? null, right[key] ?? null));
+    }
+    return false;
+}
+/**
+ * Render a value for diagnostics: JSON with stable key order and indentation
+ * only when the value spans structures, so simple failures stay on one line.
+ *
+ * @param value - The value to render.
+ * @returns A human-readable, deterministic rendering.
+ */
+export function formatValue(value) {
+    let flat = JSON.stringify(value);
+    if (flat !== undefined && flat.length <= 60)
+        return flat;
+    return JSON.stringify(value, null, 2);
+}

package/dist/workers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The entry point for running specs inside a V8-isolate runtime — a
+ * Cloudflare Worker and anywhere else without a process, filesystem, or
+ * shell. It exports the language core plus the pure `http`, `url`, `jwt`, and
+ * `sample` capabilities; `db`, `cli`, `browser`, and stdio pull in Bun's SQL
+ * client or the `Bun` global, so importing them would break here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { Random, Seed } from "@sdxc/sample";
+export type * from "./ast.js";
+export type { Sink, SuiteResult, TestResult, TestStatus } from "./diagnostics.js";
+export { ExpectationError, LoadError, ParseError, PermissionDeniedError, ResolutionError, SpecError, ToolError, WorkspaceEscapeError, } from "./errors.js";
+export type { DiagnosticCode } from "./errors.js";
+export { executeTest } from "./executor.js";
+export type { ExecutionContext } from "./executor.js";
+export { lex } from "./lexer.js";
+export { parse } from "./parser.js";
+export { createPermissionSet, parseGrants } from "./permissions.js";
+export type { Grant, Grants, PermissionKind, PermissionSet } from "./permissions.js";
+export type { Plugin, ToolContext, ToolDescriptor, ToolParam } from "./plugin.js";
+export { createHttpPlugin } from "./plugins/http.js";
+export { createJwtPlugin } from "./plugins/jwt.js";
+export { createSamplePlugin } from "./plugins/sample.js";
+export { createUrlPlugin } from "./plugins/url.js";
+export { createRegistry } from "./registry.js";
+export type { Registry, ResolvedCallable } from "./registry.js";
+export { runTests } from "./run.js";
+export type { RunTestsOptions, WorkspaceFactory } from "./run.js";
+export { positionAt } from "./source.js";
+export type { Position, SourceFile, Span } from "./source.js";
+export { loadSources } from "./sources.js";
+export type { LoadedSuite, SpecSource } from "./sources.js";
+export type { Token, TokenKind } from "./tokens.js";
+export { KEYWORDS } from "./tokens.js";
+export { formatValue, valueEquals } from "./values.js";
+export type { ToolArg, Value, ValueObject } from "./values.js";
+export type { Workspace } from "./workspace.js";
+export { createNoFilesystemWorkspace } from "./workspace-none.js";

package/dist/workers.js

@@ -0,0 +1,26 @@
+/**
+ * The entry point for running specs inside a V8-isolate runtime — a
+ * Cloudflare Worker and anywhere else without a process, filesystem, or
+ * shell. It exports the language core plus the pure `http`, `url`, `jwt`, and
+ * `sample` capabilities; `db`, `cli`, `browser`, and stdio pull in Bun's SQL
+ * client or the `Bun` global, so importing them would break here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { ExpectationError, LoadError, ParseError, PermissionDeniedError, ResolutionError, SpecError, ToolError, WorkspaceEscapeError, } from "./errors.js";
+export { executeTest } from "./executor.js";
+export { lex } from "./lexer.js";
+export { parse } from "./parser.js";
+export { createPermissionSet, parseGrants } from "./permissions.js";
+export { createHttpPlugin } from "./plugins/http.js";
+export { createJwtPlugin } from "./plugins/jwt.js";
+export { createSamplePlugin } from "./plugins/sample.js";
+export { createUrlPlugin } from "./plugins/url.js";
+export { createRegistry } from "./registry.js";
+export { runTests } from "./run.js";
+export { positionAt } from "./source.js";
+export { loadSources } from "./sources.js";
+export { KEYWORDS } from "./tokens.js";
+export { formatValue, valueEquals } from "./values.js";
+export { createNoFilesystemWorkspace } from "./workspace-none.js";

package/dist/workspace-none.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The workspace for a runtime that has no filesystem: every path is refused
+ * and `cleanup` is a no-op, since there is nothing to remove. Without `fs`
+ * or `cli` registered, a spec can never reach `resolve`; this workspace
+ * makes that absence legible, so a spec naming a path gets a `ToolError` in
+ * the language's normal diagnostic shape, naming the exact path it tried.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { SpecError } from "./errors.js";
+import type { Workspace } from "./workspace.js";
+/**
+ * Create a workspace that refuses every path, shaped as an async factory
+ * returning a `Result` so it works directly as `runTests`'s `createWorkspace`
+ * like the on-disk factory that can genuinely fail — this one never does.
+ *
+ * @returns A workspace whose `resolve` always fails, whose `cleanup` does
+ * nothing, and whose `root` is a placeholder string that no resolution ever
+ * joins onto.
+ */
+export declare function createNoFilesystemWorkspace(): Promise<Result<Workspace, SpecError>>;

package/dist/workspace-none.js

@@ -0,0 +1,33 @@
+/**
+ * The workspace for a runtime that has no filesystem: every path is refused
+ * and `cleanup` is a no-op, since there is nothing to remove. Without `fs`
+ * or `cli` registered, a spec can never reach `resolve`; this workspace
+ * makes that absence legible, so a spec naming a path gets a `ToolError` in
+ * the language's normal diagnostic shape, naming the exact path it tried.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { ToolError } from "./errors.js";
+/**
+ * Create a workspace that refuses every path, shaped as an async factory
+ * returning a `Result` so it works directly as `runTests`'s `createWorkspace`
+ * like the on-disk factory that can genuinely fail — this one never does.
+ *
+ * @returns A workspace whose `resolve` always fails, whose `cleanup` does
+ * nothing, and whose `root` is a placeholder string that no resolution ever
+ * joins onto.
+ */
+export async function createNoFilesystemWorkspace() {
+    let workspace = {
+        root: "<no filesystem>",
+        resolve(path) {
+            return failure(new ToolError(`Cannot resolve "${path}": this run has no filesystem, so no path can be read or written.`));
+        },
+        async cleanup() {
+            return undefined;
+        },
+    };
+    return success(workspace);
+}

package/dist/workspace.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The isolated per-test workspace: a runtime primitive every capability
+ * shares, not a filesystem-plugin detail. Each test gets a fresh ephemeral
+ * directory that `fs` tools write into, `cli` processes start in, and
+ * assertions inspect; the runtime cleans it up when the test ends.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { PermissionSet } from "./permissions.js";
+import { SpecError } from "./errors.js";
+/**
+ * One test's isolated workspace. Path resolution is the safety boundary:
+ * workspace-relative paths are safe by default, while absolute paths and
+ * paths that traverse out of the root require a host-filesystem grant.
+ */
+export interface Workspace {
+    /** Absolute host path of the workspace root (a fresh temp directory). */
+    root: string;
+    /**
+     * Resolve a spec-written path to an absolute host path. Relative paths
+     * must stay inside the root, symlinks re-resolved before the check;
+     * absolute paths delegate to the host-fs permission grant.
+     *
+     * @param path - The spec-written path to resolve.
+     * @returns The absolute host path, or a `WorkspaceEscapeError` when the
+     * path would escape the root — including when an existing ancestor's
+     * symlink target cannot be verified — or the host-fs permission's denial
+     * for absolute paths.
+     */
+    resolve(path: string): Result<string, SpecError>;
+    /**
+     * Remove the workspace directory and everything in it; resolves
+     * unconditionally, keeping removal failures harmless to the test run.
+     */
+    cleanup(): Promise<undefined>;
+}
+/**
+ * Create a fresh isolated workspace: a temp directory whose real path
+ * (often behind a symlink) bounds every relative path, symlinked
+ * ancestors included; absolute paths delegate to the host-fs permission.
+ *
+ * @param permissions - The run's permission set, consulted for absolute paths.
+ * @returns The workspace, or the error that prevented creating its directory.
+ */
+export declare function createWorkspace(permissions: PermissionSet): Promise<Result<Workspace, SpecError>>;