@sdxc/spec 0.0.0-pre.1

package/dist/registry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Name resolution for the whole suite: which callable a dotted target means,
+ * given the plugins that are connected, the definitions that are loaded, and
+ * the namespaces a file imported with `use`. Ambiguity is always an error —
+ * the runtime never guesses.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { CommandNode, FixtureNode } from "./ast.js";
+import type { Plugin, ToolDescriptor } from "./plugin.js";
+import type { LoadedSuite } from "./sources.js";
+import { ResolutionError } from "./errors.js";
+/** What a call target resolved to: a plugin tool or a suite command. */
+export type ResolvedCallable = {
+    kind: "tool";
+    /** The plugin owning the tool. */
+    plugin: Plugin;
+    /** The resolved tool's descriptor. */
+    descriptor: ToolDescriptor;
+    /** The tool's namespace, for diagnostics (`fs.write`). */
+    namespace: string;
+} | {
+    kind: "command";
+    /** The resolved command definition. */
+    command: CommandNode;
+};
+/**
+ * The suite's resolution table, built once after loading and consulted for
+ * every call. A dotted target resolves inside its namespace; a bare target
+ * resolves among suite commands and imported namespaces, erring on ambiguity.
+ */
+export interface Registry {
+    /**
+     * Resolve a call target as written in some file.
+     *
+     * @param target - The dotted target text, e.g. `"login"` or `"http.post"`.
+     * @param uses - The namespaces the calling file imported, in order.
+     */
+    resolveCallable(target: string, uses: readonly string[]): Result<ResolvedCallable, ResolutionError>;
+    /** Resolve `fixture NAME` to its definition. */
+    resolveFixture(name: string): Result<FixtureNode, ResolutionError>;
+    /** Whether a bare name could resolve to anything callable (for `expect`). */
+    isCallable(target: string, uses: readonly string[]): boolean;
+}
+/**
+ * Build the suite's resolution table from the connected plugins and loaded
+ * definitions. Each plugin's descriptors are read once, since a plugin's tool
+ * set is stable for its lifetime, making every later resolution a map lookup.
+ *
+ * @param plugins - The connected plugins, one namespace each.
+ * @param suite - The loaded suite whose commands and fixtures resolve here.
+ * @returns The registry the executor consults for every call.
+ */
+export declare function createRegistry(plugins: Plugin[], suite: LoadedSuite): Registry;

package/dist/registry.js

@@ -0,0 +1,110 @@
+/**
+ * Name resolution for the whole suite: which callable a dotted target means,
+ * given the plugins that are connected, the definitions that are loaded, and
+ * the namespaces a file imported with `use`. Ambiguity is always an error —
+ * the runtime never guesses.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isSuccess, success } from "@sdxc/result";
+import { ResolutionError } from "./errors.js";
+/**
+ * Build the suite's resolution table from the connected plugins and loaded
+ * definitions. Each plugin's descriptors are read once, since a plugin's tool
+ * set is stable for its lifetime, making every later resolution a map lookup.
+ *
+ * @param plugins - The connected plugins, one namespace each.
+ * @param suite - The loaded suite whose commands and fixtures resolve here.
+ * @returns The registry the executor consults for every call.
+ */
+export function createRegistry(plugins, suite) {
+    let namespaces = new Map();
+    for (let plugin of plugins) {
+        let tools = new Map();
+        for (let descriptor of plugin.describe())
+            tools.set(descriptor.name, descriptor);
+        namespaces.set(plugin.namespace, { plugin, tools });
+    }
+    /** Resolve a `ns.tool` target inside its namespace, never elsewhere. */
+    function resolveQualified(target, namespace, tool) {
+        let entry = namespaces.get(namespace);
+        if (!entry) {
+            return failure(new ResolutionError("unknown-name", `Unknown name "${target}": no plugin provides the namespace "${namespace}".`));
+        }
+        let descriptor = entry.tools.get(tool);
+        if (!descriptor) {
+            let available = [...entry.tools.keys()].map((name) => `${namespace}.${name}`);
+            let listing = available.length > 0 ? `Its tools are: ${available.join(", ")}.` : `It exposes no tools.`;
+            return failure(new ResolutionError("unknown-name", `Unknown tool "${tool}" in namespace "${namespace}". ${listing}`));
+        }
+        let resolved = {
+            kind: "tool",
+            plugin: entry.plugin,
+            descriptor,
+            namespace,
+        };
+        return success(resolved);
+    }
+    /**
+     * Resolve a bare target among suite commands (which never need `use`) and
+     * the tools of the namespaces the calling file imported. More than one
+     * candidate is an ambiguity error — the runtime never guesses.
+     */
+    function resolveBare(target, uses) {
+        let candidates = [];
+        let command = suite.commands.get(target);
+        if (command)
+            candidates.push({ qualified: target, resolved: { kind: "command", command } });
+        let visited = new Set();
+        for (let namespace of uses) {
+            if (visited.has(namespace))
+                continue;
+            visited.add(namespace);
+            let entry = namespaces.get(namespace);
+            if (!entry)
+                continue;
+            let descriptor = entry.tools.get(target);
+            if (!descriptor)
+                continue;
+            candidates.push({
+                qualified: `${namespace}.${target}`,
+                resolved: { kind: "tool", plugin: entry.plugin, descriptor, namespace },
+            });
+        }
+        let [first] = candidates;
+        if (first && candidates.length === 1)
+            return success(first.resolved);
+        if (candidates.length === 0) {
+            return failure(new ResolutionError("unknown-name", `Unknown name "${target}": it is not a suite command, and no namespace imported with \`use\` provides it.`));
+        }
+        let qualified = candidates.map((candidate) => candidate.qualified);
+        let described = candidates.map((candidate) => candidate.resolved.kind === "command"
+            ? `the command "${candidate.qualified}"`
+            : candidate.qualified);
+        return failure(new ResolutionError("ambiguous-name", `Ambiguous name "${target}": it matches ${described.join(" and ")}. Use the fully qualified name.`, qualified));
+    }
+    /** Dispatch on the target's shape: bare, `ns.tool`, or too many dots. */
+    function resolveCallable(target, uses) {
+        let segments = target.split(".");
+        if (segments.length > 2) {
+            return failure(new ResolutionError("unknown-name", `Unknown name "${target}": a call target has at most one dot (namespace.tool).`));
+        }
+        let [head, tail] = segments;
+        if (head !== undefined && tail !== undefined)
+            return resolveQualified(target, head, tail);
+        return resolveBare(target, uses);
+    }
+    return {
+        resolveCallable,
+        resolveFixture(name) {
+            let fixture = suite.fixtures.get(name);
+            if (fixture)
+                return success(fixture);
+            return failure(new ResolutionError("unknown-name", `Unknown fixture "${name}".`));
+        },
+        isCallable(target, uses) {
+            return isSuccess(resolveCallable(target, uses));
+        },
+    };
+}

package/dist/reporter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The human reporter: renders a suite's structured results, and fatal
+ * pre-run failures, onto a `Sink` as plain text. It branches on diagnostic
+ * codes and structured error fields, never on error message text.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Sink, SuiteResult } from "./diagnostics.js";
+import type { SpecError } from "./errors.js";
+import type { SourceFile } from "./source.js";
+/**
+ * Render a finished suite: a status line per test, denials sharing a remedy
+ * collapsed into one block naming the grant and its affected tests, and a
+ * summary reporting the run's wall-clock duration, accurate under concurrency.
+ *
+ * @param suite - The suite roll-up the runner produced.
+ * @param sources - Loaded file texts by path, for turning spans into lines.
+ * @param sink - Where the report is written.
+ */
+export declare function reportSuite(suite: SuiteResult, sources: Map<string, SourceFile>, sink: Sink): void;
+/**
+ * Render a failure that prevented any test from running — an unreadable
+ * suite directory, a duplicate definition, or a file that failed to parse —
+ * naming the file (with line:column when known), the code, message, and remedy.
+ *
+ * @param error - The load-time failure.
+ * @param sink - Where the report is written.
+ */
+export declare function reportFatal(error: SpecError, sink: Sink): void;

package/dist/reporter.js

@@ -0,0 +1,237 @@
+/**
+ * The human reporter: renders a suite's structured results, and fatal
+ * pre-run failures, onto a `Sink` as plain text. It branches on diagnostic
+ * codes and structured error fields, never on error message text.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { readFileSync } from "node:fs";
+import { positionAt } from "./source.js";
+import { formatValue } from "./values.js";
+/** Indentation prefixing every non-empty line of a failure's detail block. */
+const DETAIL_INDENT = "  ";
+/**
+ * Render a finished suite: a status line per test, denials sharing a remedy
+ * collapsed into one block naming the grant and its affected tests, and a
+ * summary reporting the run's wall-clock duration, accurate under concurrency.
+ *
+ * @param suite - The suite roll-up the runner produced.
+ * @param sources - Loaded file texts by path, for turning spans into lines.
+ * @param sink - Where the report is written.
+ */
+export function reportSuite(suite, sources, sink) {
+    let separated = true;
+    let groups = [];
+    let byRemedy = new Map();
+    for (let result of suite.results) {
+        if (result.status === "passed") {
+            sink.write(`✓ ${result.title}\n`);
+            separated = false;
+            continue;
+        }
+        let grouping = result.error === undefined ? undefined : groupableDenial(result.error);
+        if (grouping !== undefined) {
+            accumulateDenial(groups, byRemedy, grouping, {
+                title: result.title,
+                location: failureLocation(result, sources),
+            });
+            continue;
+        }
+        sink.write(`✗ ${result.title} (${failureLocation(result, sources)})\n`);
+        separated = false;
+        if (result.error !== undefined) {
+            for (let line of detailLines(result.error)) {
+                sink.write(line === "" ? "\n" : `${DETAIL_INDENT}${line}\n`);
+            }
+            sink.write("\n");
+            separated = true;
+        }
+    }
+    for (let group of groups) {
+        if (!separated)
+            sink.write("\n");
+        sink.write(`✗ ${groupHeader(group)}\n`);
+        for (let line of groupDetailLines(group)) {
+            sink.write(line === "" ? "\n" : `${DETAIL_INDENT}${line}\n`);
+        }
+        sink.write("\n");
+        separated = true;
+    }
+    if (!separated)
+        sink.write("\n");
+    sink.write(`${suite.passed} passed, ${suite.failed} failed (${Math.round(suite.wallMs)}ms)\n`);
+}
+/**
+ * Render a failure that prevented any test from running — an unreadable
+ * suite directory, a duplicate definition, or a file that failed to parse —
+ * naming the file (with line:column when known), the code, message, and remedy.
+ *
+ * @param error - The load-time failure.
+ * @param sink - Where the report is written.
+ */
+export function reportFatal(error, sink) {
+    let location = fatalLocation(error);
+    let suffix = location === undefined ? "" : ` (${location})`;
+    sink.write(`✗ ${error.code}: ${error.message}${suffix}\n`);
+    if (error.remedy !== undefined) {
+        sink.write(`${DETAIL_INDENT}remedy: ${error.remedy}\n`);
+    }
+    if (error.hint !== undefined) {
+        sink.write(`${DETAIL_INDENT}${error.hint}\n`);
+    }
+}
+/**
+ * Where a failing test points: `file:line` when the error's span falls in a
+ * loaded source, the bare file path otherwise.
+ */
+function failureLocation(result, sources) {
+    let file = result.error?.file ?? result.file;
+    let span = result.error?.span;
+    let source = sources.get(file);
+    if (span !== undefined && source !== undefined) {
+        let position = positionAt(source, span.start);
+        return `${file}:${position.line}`;
+    }
+    return file;
+}
+/**
+ * The unindented lines of a failure's detail block: the ADR-007-shaped
+ * denial block for permission failures, otherwise the diagnostic code and
+ * message followed by `expected:`/`observed:` and the remedy when carried.
+ */
+function detailLines(error) {
+    let denial = denialBlock(error);
+    if (denial !== undefined) {
+        if (error.hint !== undefined)
+            return [...denial, "", error.hint];
+        return denial;
+    }
+    let lines = [`${error.code}: ${error.message}`];
+    let comparison = error;
+    if (comparison.expected !== undefined)
+        pushLabeledValue(lines, "expected", comparison.expected);
+    if (comparison.observed !== undefined)
+        pushLabeledValue(lines, "observed", comparison.observed);
+    if (error.remedy !== undefined)
+        lines.push(`remedy: ${error.remedy}`);
+    if (error.hint !== undefined)
+        lines.push(error.hint);
+    return lines;
+}
+/**
+ * The grouping fields of a permission denial the reporter accumulates, or
+ * undefined when {@link denialBlock} could not render it — a denial missing
+ * `permission`, `resource`, or `remedy` falls back to the inline detail path.
+ */
+function groupableDenial(error) {
+    if (denialBlock(error) === undefined)
+        return undefined;
+    let denial = error;
+    let permission = denial.permission;
+    let resource = denial.resource;
+    let remedy = error.remedy;
+    if (permission === undefined || resource === undefined || remedy === undefined)
+        return undefined;
+    return { permission, resource, remedy, hint: error.hint };
+}
+/**
+ * Fold one denial into the group its remedy keys — creating the group in
+ * first-seen order when new — recording the resource (deduplicated, first-seen
+ * order) and the affected test in execution order.
+ */
+function accumulateDenial(groups, byRemedy, grouping, test) {
+    let group = byRemedy.get(grouping.remedy);
+    if (group === undefined) {
+        group = {
+            permission: grouping.permission,
+            resources: [],
+            remedy: grouping.remedy,
+            hint: grouping.hint,
+            tests: [],
+        };
+        byRemedy.set(grouping.remedy, group);
+        groups.push(group);
+    }
+    if (!group.resources.includes(grouping.resource))
+        group.resources.push(grouping.resource);
+    group.tests.push(test);
+}
+/**
+ * The header of a denial group's block: the permission and how many tests it
+ * accounts for, with `test`/`tests` agreeing in number.
+ */
+function groupHeader(group) {
+    let count = group.tests.length;
+    return `Permission denied: ${group.permission} (${count} ${count === 1 ? "test" : "tests"})`;
+}
+/**
+ * The unindented body lines of a denial group's block: the attempted
+ * resources, the shared remedy, and the affected tests. The two label lines
+ * stay verbatim so the design suite's substring assertions keep matching.
+ */
+function groupDetailLines(group) {
+    let lines = ["", "The spec attempted to reach:"];
+    for (let resource of group.resources)
+        lines.push(`> ${resource}`);
+    lines.push("", "Re-run with an appropriate permission, for example:", `> ${group.remedy}`);
+    if (group.hint !== undefined)
+        lines.push("", group.hint);
+    lines.push("", "Affected tests:");
+    for (let test of group.tests)
+        lines.push(`- ${test.title} (${test.location})`);
+    return lines;
+}
+/**
+ * The denial block the design suite requires: the permission, the attempted
+ * resource, and the exact flag that would grant it. Returns undefined when
+ * the error is not a permission denial or lacks the structured fields.
+ */
+function denialBlock(error) {
+    if (error.code !== "permission-denied")
+        return undefined;
+    let denial = error;
+    if (denial.permission === undefined || denial.resource === undefined)
+        return undefined;
+    if (denial.remedy === undefined)
+        return undefined;
+    return [
+        `Permission denied: ${denial.permission}`,
+        "",
+        "The spec attempted to reach:",
+        `> ${denial.resource}`,
+        "",
+        "Re-run with an appropriate permission, for example:",
+        `> ${denial.remedy}`,
+    ];
+}
+/**
+ * Append `label: value` to the detail lines, keeping each line of a
+ * multi-line rendering its own detail line so indentation stays consistent.
+ */
+function pushLabeledValue(lines, label, value) {
+    let parts = formatValue(value).split("\n");
+    lines.push(`${label}: ${parts[0] ?? ""}`);
+    for (let part of parts.slice(1))
+        lines.push(part);
+}
+/**
+ * Where a fatal error points: `file:line:column` when the span is known and
+ * the file is readable — re-read from disk since fatal errors predate any
+ * loaded-source map — the bare file path otherwise, undefined without a file.
+ */
+function fatalLocation(error) {
+    if (error.file === undefined)
+        return undefined;
+    if (error.span === undefined)
+        return error.file;
+    let text;
+    try {
+        text = readFileSync(error.file, "utf8");
+    }
+    catch {
+        return error.file;
+    }
+    let position = positionAt({ path: error.file, text }, error.span.start);
+    return `${error.file}:${position.line}:${position.column}`;
+}

package/dist/run.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Executing an already-loaded suite: give every test a fresh workspace, run it,
+ * and collect structured results in source order. Everything the run depends on
+ * arrives as an argument — the suite, the plugin set, the grants, the workspace
+ * factory — so nothing here reaches for a filesystem, a process, or a specific
+ * runtime. `runner.ts` is the host convenience that supplies the usual answers;
+ * an embedder on a runtime without those answers calls this directly.
+ *
+ * Language semantics live in the executor and rendering lives in the reporter;
+ * this module owns only the lifecycle glue.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { Seed } from "@sdxc/sample";
+import type { SuiteResult } from "./diagnostics.js";
+import type { SpecError } from "./errors.js";
+import type { Grants, PermissionSet } from "./permissions.js";
+import type { Plugin } from "./plugin.js";
+import type { LoadedSuite } from "./sources.js";
+import type { Workspace } from "./workspace.js";
+/** Creates the isolated workspace one test runs in. */
+export type WorkspaceFactory = (permissions: PermissionSet) => Promise<Result<Workspace, SpecError>>;
+/** Everything executing a loaded suite depends on, all of it injected. */
+export interface RunTestsOptions {
+    /** The parsed suite, from `loadSuite` (a directory) or `loadSources` (strings). */
+    suite: LoadedSuite;
+    /**
+     * Every plugin whose namespace this run understands — the complete set, not
+     * additions to a default one. Leaving a namespace out makes it nonexistent
+     * to a spec, not merely forbidden, so referencing it fails to resolve.
+     *
+     * @see createBuiltinPlugins
+     */
+    plugins: Plugin[];
+    /** The caller's permission grants, scoping what the registered plugins may reach. */
+    grants: Grants;
+    /** How each test's workspace is created; called once per test. */
+    createWorkspace: WorkspaceFactory;
+    /**
+     * How many tests may execute at once, each in its own isolated workspace.
+     * Results stay source-ordered regardless of completion order, though a
+     * shared, mutable app under test may still require `concurrency: 1`.
+     *
+     * @default 1
+     */
+    concurrency?: number;
+    /**
+     * The run's seed, which every test's generated data descends from. A fixed
+     * default makes two runs of a suite produce identical data; pass a drawn
+     * seed to shake a suite for hidden dependence on particular values.
+     *
+     * @default "spec"
+     */
+    seed?: Seed;
+    /**
+     * The suite directory, which a test's seed measures its file against so the
+     * data a suite generates does not follow the suite's absolute location on
+     * disk. Omit when the sources came from strings rather than a directory.
+     */
+    root?: string;
+}
+/** The run seed used when a caller names none, so a bare run repeats exactly. */
+export declare const DEFAULT_SEED = "spec";
+/**
+ * Execute every test in a loaded suite. Test failures land as outcomes in the
+ * returned result, not thrown errors; only a workspace-creation failure aborts
+ * the run, since a test that never got a place to run has no pass or fail.
+ *
+ * @param options - The suite, its plugin set, the grants, and the workspace factory.
+ * @returns Per-test outcomes in source order, or the error that aborted the run.
+ */
+export declare function runTests(options: RunTestsOptions): Promise<Result<SuiteResult, SpecError>>;

package/dist/run.js

@@ -0,0 +1,179 @@
+/**
+ * Executing an already-loaded suite: give every test a fresh workspace, run it,
+ * and collect structured results in source order. Everything the run depends on
+ * arrives as an argument — the suite, the plugin set, the grants, the workspace
+ * factory — so nothing here reaches for a filesystem, a process, or a specific
+ * runtime. `runner.ts` is the host convenience that supplies the usual answers;
+ * an embedder on a runtime without those answers calls this directly.
+ *
+ * Language semantics live in the executor and rendering lives in the reporter;
+ * this module owns only the lifecycle glue.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { relative, sep } from "node:path";
+import { isFailure, success } from "@sdxc/result";
+import { createRandom } from "@sdxc/sample";
+import { executeTest } from "./executor.js";
+import { createPermissionSet } from "./permissions.js";
+import { createRegistry } from "./registry.js";
+/** The run seed used when a caller names none, so a bare run repeats exactly. */
+export const DEFAULT_SEED = "spec";
+/**
+ * The stream one test draws from: the run's seed and the test's identity, and
+ * nothing about when or in what order it ran. Two tests that share a file and
+ * a title share a stream, which is the same data for what is already the same
+ * name.
+ *
+ * A test is identified by its file's path inside the suite, never the absolute
+ * one, so a suite generates the same data wherever it is checked out and
+ * however the runner was pointed at it.
+ */
+function streamFor(seed, file, title, root) {
+    let within = root === undefined ? file : relative(root, file);
+    return createRandom(`${seed} ${within.split(sep).join("/")}#${title}`);
+}
+/**
+ * Execute every test in a loaded suite. Test failures land as outcomes in the
+ * returned result, not thrown errors; only a workspace-creation failure aborts
+ * the run, since a test that never got a place to run has no pass or fail.
+ *
+ * @param options - The suite, its plugin set, the grants, and the workspace factory.
+ * @returns Per-test outcomes in source order, or the error that aborted the run.
+ */
+export async function runTests(options) {
+    let suite = options.suite;
+    let plugins = options.plugins;
+    let registry = createRegistry(plugins, suite);
+    let permissions = createPermissionSet(options.grants);
+    /**
+     * `use` is file-scoped: a definition's body resolves bare names against the
+     * imports of the file that defined it, so errors raised inside a shared
+     * command report that file's location, not the calling test's.
+     */
+    let usesByDefinition = new Map();
+    let fileByDefinition = new Map();
+    for (let file of suite.files) {
+        let imported = file.uses.map((use) => use.namespace);
+        for (let definition of file.definitions) {
+            usesByDefinition.set(definition, imported);
+            fileByDefinition.set(definition, file.path);
+        }
+    }
+    /**
+     * Every test flattened into one source-ordered work list; each unit carries
+     * its own file path and `use` imports, so a worker needs nothing but the
+     * shared registry and permissions to run it.
+     */
+    let pending = [];
+    for (let file of suite.files) {
+        let imported = file.uses.map((use) => use.namespace);
+        for (let test of file.tests)
+            pending.push({ test, filePath: file.path, imported });
+    }
+    let concurrency = Math.max(1, Math.trunc(options.concurrency ?? 1));
+    let results = Array.from({ length: pending.length });
+    let nextIndex = 0;
+    /**
+     * The first fatal workspace-creation failure, if any. In-flight tests still
+     * finish and no new work is pulled once this is set; the run then returns
+     * this failure.
+     */
+    let fatal;
+    /**
+     * Claims the next source index and runs it in a fresh workspace, repeating
+     * until the list drains or a fatal failure appears. Claiming `nextIndex` is
+     * race-free: nothing awaits between reading and incrementing it.
+     */
+    async function runWorker() {
+        while (fatal === undefined) {
+            let index = nextIndex;
+            nextIndex += 1;
+            if (index >= pending.length)
+                return;
+            let unit = pending[index];
+            if (unit === undefined)
+                return;
+            let workspace = await options.createWorkspace(permissions);
+            if (isFailure(workspace)) {
+                fatal ??= workspace;
+                return;
+            }
+            let startedAt = performance.now();
+            let outcome = await executeTest(unit.test, {
+                registry,
+                workspace: workspace.data,
+                permissions,
+                random: streamFor(options.seed ?? DEFAULT_SEED, unit.filePath, unit.test.title, options.root),
+                now: new Date(),
+                uses: unit.imported,
+                usesFor: (definition) => usesByDefinition.get(definition) ?? unit.imported,
+                fileFor: (definition) => fileByDefinition.get(definition),
+                grants: options.grants,
+            });
+            let durationMs = performance.now() - startedAt;
+            await workspace.data.cleanup();
+            if (isFailure(outcome)) {
+                let error = outcome.error;
+                if (error.file === undefined)
+                    error.file = unit.filePath;
+                results[index] = {
+                    title: unit.test.title,
+                    file: unit.filePath,
+                    status: "failed",
+                    error,
+                    durationMs,
+                };
+            }
+            else {
+                results[index] = {
+                    title: unit.test.title,
+                    file: unit.filePath,
+                    status: "passed",
+                    durationMs,
+                };
+            }
+        }
+    }
+    /**
+     * Wall-clock spans only the test-execution phase: captured immediately
+     * before workers start and immediately after the last one finishes, giving
+     * real elapsed time whether the run was sequential or concurrent.
+     */
+    let wallStart = performance.now();
+    let wallMs = 0;
+    try {
+        let workerCount = Math.min(concurrency, pending.length);
+        let workers = [];
+        for (let slot = 0; slot < workerCount; slot += 1)
+            workers.push(runWorker());
+        await Promise.all(workers);
+        wallMs = performance.now() - wallStart;
+        if (fatal !== undefined)
+            return fatal;
+    }
+    finally {
+        /**
+         * Plugins with external state (a browser session, a connection) release
+         * it here, once per test. A throwing dispose here still lets a completed
+         * run return its results.
+         */
+        for (let plugin of plugins) {
+            if (plugin.dispose === undefined)
+                continue;
+            try {
+                await plugin.dispose();
+            }
+            catch { }
+        }
+    }
+    /**
+     * Every slot is filled once the run completes without a fatal failure,
+     * since each claimed index writes exactly one result; filtering here only
+     * narrows the sparse `undefined` type while preserving source order.
+     */
+    let ordered = results.filter((result) => result !== undefined);
+    let passed = ordered.filter((result) => result.status === "passed").length;
+    return success({ results: ordered, passed, failed: ordered.length - passed, wallMs });
+}