@venn-lang/runtime 0.1.0

package/dist/index.js

@@ -0,0 +1,3314 @@
+import { CODES, PRELUDE_VALUES, ProblemError, buildDiff, buildProblem, callArgs, closureOfDecl, compileExpr, decoCannotCall, decorateCallable, display, evaluate, expand, invoke, isActionCall, isBlock, isCall, isCallable, isCaptureStmt, isConfigDecl, isDecoDecl, isFlowDecl, isFnDecl, isFragmentDecl, isIfStmt, isLetStmt, isLifecycleDecl, isMatcherClause, isMatrixDecl, isMember, isNamespaceValue, isPackageSpecifier, isRef, isRunStmt, isRunnable, isStepDecl, isStringLit, isUseDecl, isValueImport, memberValue, namespaceValue, nativeFn, parse, parseExpression, prune, readDecorations, readMeta, scanInterpolations, specToType, splitCall, truthy, typeName, walkAst } from "@venn-lang/core";
+import { ConsolePort, VennError, bindPort, missingCapabilities } from "@venn-lang/contracts";
+import { paramSpecs } from "@venn-lang/sdk";
+//#region src/scheduler/signals.ts
+var BreakSignal = class {};
+var ContinueSignal = class {};
+var ReturnSignal = class {
+	value;
+	constructor(value) {
+		this.value = value;
+	}
+};
+/** Thrown at a statement boundary when the branch's race has already been won. */
+var CancelSignal = class {};
+/**
+* Thrown by `exit`, carrying the code the host should leave with.
+*
+* A signal and not an error: a run that exits has not failed. The code it
+* carries is the whole verdict, and `exit 0` is a clean ending, which an error
+* unwinding as a failure could not express.
+*/
+var ExitSignal = class {
+	code;
+	constructor(code) {
+		this.code = code;
+	}
+};
+function isControlSignal(value) {
+	return value instanceof BreakSignal || value instanceof ContinueSignal || value instanceof ReturnSignal || value instanceof CancelSignal || value instanceof ExitSignal;
+}
+//#endregion
+//#region src/scheduler/absorb-exit.ts
+/**
+* Run `body`, letting an `exit` end it.
+*
+* The exit code travels on the engine rather than on the throw, so whatever
+* wraps this still finishes the way it always does: teardowns run, `run.finished`
+* is emitted, and the host reads one number off the result. Any other error keeps
+* unwinding untouched.
+*/
+async function absorbExit(engine, body) {
+	try {
+		await body();
+	} catch (error) {
+		if (!(error instanceof ExitSignal)) throw error;
+		engine.exit = error.code;
+	}
+}
+//#endregion
+//#region src/scheduler/aliases.ts
+/**
+* The namespaces this file actually brought in with `use`: the alias when one
+* was given, otherwise the namespace the package contributes. A name outside
+* this set was never imported, however well the registry knows it.
+*/
+function collectNamespaces(document, registry) {
+	const names = /* @__PURE__ */ new Set();
+	for (const decl of document.imports) {
+		if (!isUseDecl(decl)) continue;
+		const bound = decl.alias ?? registry.namespaceOf(decl.pkg);
+		if (bound) names.add(bound);
+	}
+	return names;
+}
+/**
+* The names this file binds at the top level.
+*
+* `page.click()` reads like a namespace and a verb, and is neither: it is a
+* method on something the file holds. The registry has no schema for it, so it
+* is known here and verified nowhere, which beats reporting it as an unknown
+* action it plainly is not.
+*/
+function collectBoundNames(document) {
+	const names = /* @__PURE__ */ new Set();
+	for (const decl of document.decls) if (isLetStmt(decl)) names.add(decl.name);
+	return names;
+}
+/** `use "venn/http" as h` → `{ h → "http" }`, resolved through the registry. */
+function collectAliases(document, registry) {
+	const aliases = /* @__PURE__ */ new Map();
+	for (const decl of document.imports) {
+		if (!isUseDecl(decl) || !decl.alias) continue;
+		const namespace = registry.namespaceOf(decl.pkg);
+		if (namespace) aliases.set(decl.alias, namespace);
+	}
+	return aliases;
+}
+//#endregion
+//#region src/scheduler/bind-globals.ts
+/**
+* Bind every top-level `fn` as a callable closure. Hoisted so a function can be
+* called before its textual position, and so functions may reference each other
+* regardless of order.
+*
+* A `deco` that asked to `wrap` one is honoured here, at the only moment the
+* function becomes a value: the name a caller reaches is already the decorated
+* one, so a middleware cannot be stepped around by calling from somewhere else.
+*/
+function bindFunctions(doc, scope) {
+	for (const decl of doc.decls) if (isFnDecl(decl)) scope.set(decl.name, decorateCallable(decl, closureOfDecl(decl, scope)));
+}
+/**
+* Bind top-level functions and the plain `const`/`let` globals every flow can
+* read without anything having run yet.
+*
+* Only pure values. One that calls a verb is a statement, and statements run in
+* the prologue, in order and once, before the flows: opening a database is
+* something a program *does*, not something a name quietly is.
+*/
+function bindGlobals(doc, scope) {
+	bindFunctions(doc, scope);
+	bindPlainValues(doc, scope);
+}
+/**
+* The `const`/`let` globals, evaluated where they stand.
+*
+* Separate from the functions because the order matters across files: a function
+* is hoisted and reads its scope when it is *called*, while a value is read now,
+* so anything a value might depend on has to be in place first.
+*/
+function bindPlainValues(doc, scope) {
+	for (const decl of doc.decls) if (isLetStmt(decl) && isPlainValue(decl)) scope.set(decl.name, evaluate(decl.value, scope));
+}
+function isPlainValue(decl) {
+	return decl.args.length === 0 && !decl.opts;
+}
+//#endregion
+//#region src/scheduler/bind-imports.ts
+/**
+* Bind the names a document imported, each to the value its own module made.
+*
+* A `pub fn` is a closure over the file it was written in (it calls that file's
+* private helpers and reads that file's globals) so it cannot simply be lifted
+* into the importer's scope. Each module gets a scope of its own, built the same
+* way the entry document's is, and the importer takes only the names it asked
+* for out of it.
+*
+* Three passes over every module at once, not one walk per import: two files
+* that call each other are ordinary, and no single order resolves them. Filling
+* every scope first and wiring afterwards has no order to get wrong, because a
+* function captures the scope object and wiring mutates that same object.
+*
+* Call this before the document's own globals are bound, so a local name of the
+* same spelling wins. That is the rule fragments already follow.
+*/
+function bindImports(args) {
+	const built = /* @__PURE__ */ new Map();
+	for (const [uri, module] of args.graph.modules) {
+		const scope = args.base();
+		built.set(uri, scope);
+		bindFunctions(module, scope);
+	}
+	for (const [uri, module] of args.graph.modules) wire({
+		document: module,
+		uri,
+		into: scopeAt(built, uri),
+		graph: args.graph,
+		built
+	});
+	for (const [uri, module] of args.graph.modules) bindPlainValues(module, scopeAt(built, uri));
+	wire({
+		document: args.document,
+		uri: args.uri,
+		into: args.scope,
+		graph: args.graph,
+		built
+	});
+}
+function scopeAt(built, uri) {
+	return built.get(uri);
+}
+function wire(args) {
+	for (const decl of args.document.imports) {
+		if (!isValueImport(decl)) continue;
+		if (isPackageSpecifier(decl.path)) {
+			takePackage({
+				decl,
+				graph: args.graph,
+				into: args.into
+			});
+			continue;
+		}
+		const from = args.graph.resolve(args.uri, decl.path);
+		const module = args.graph.modules.get(from);
+		const source = args.built.get(from);
+		if (module && source) take({
+			decl,
+			module,
+			source,
+			into: args.into
+		});
+	}
+}
+/**
+* The names an installed package published.
+*
+* Everything it exports is fair game: a package has no `pub`, its exports *are*
+* what it made public, so unlike a `.vn` module there is nothing to filter
+* against. `default` is bound too, under whichever name the import gave it,
+* because that is the only name it has here.
+*/
+function takePackage(args) {
+	const module = args.graph.npm?.get(args.decl.path);
+	if (!module) return;
+	if (args.decl.wildcard) return void args.into.set(args.decl.wildcard, { ...module });
+	if (args.decl.default) return void args.into.set(args.decl.default, module.default);
+	for (const name of args.decl.names) if (name in module) args.into.set(name, module[name]);
+}
+function take(args) {
+	const exported = exportedFunctions(args.module);
+	if (args.decl.wildcard) {
+		args.into.set(args.decl.wildcard, gathered(exported, args.source));
+		return;
+	}
+	for (const name of args.decl.names) if (exported.has(name)) args.into.set(name, args.source.lookup(name));
+}
+/** `import * as u`: one value holding everything the module published. */
+function gathered(names, source) {
+	const out = {};
+	for (const name of names) out[name] = source.lookup(name);
+	return out;
+}
+/** The names a module made `pub` that are values a caller can hold. */
+function exportedFunctions(document) {
+	const names = /* @__PURE__ */ new Set();
+	for (const decl of document.decls) if (isFnDecl(decl) && decl.export) names.add(decl.name);
+	return names;
+}
+//#endregion
+//#region src/scope/create-scope.ts
+/**
+* A lexical scope.
+*
+* A class, not an object literal: a `forEach` over 50k items builds 50k scopes,
+* and a literal allocates a closure per method for each of them. One prototype
+* does for all.
+*
+* Bindings live in cells rather than as bare values, so a compiled function can
+* address one once and read it by index on every call after. The cell exists as
+* soon as anyone asks for it, which is what lets a recursive `fn` work: the
+* closure asks for its own name while being built, before the binding fills it.
+*/
+var MapScope = class MapScope {
+	parent;
+	vars = /* @__PURE__ */ new Map();
+	constructor(parent) {
+		this.parent = parent;
+	}
+	lookup(name) {
+		const found = this.vars.get(name);
+		return found === void 0 ? this.parent?.lookup(name) : found.value;
+	}
+	set(name, value) {
+		const own = this.vars.get(name);
+		if (own) {
+			own.value = value;
+			return;
+		}
+		this.vars.set(name, { value });
+	}
+	/**
+	* The cell holding `name`, taken from wherever in the chain already has one.
+	*
+	* A function reading a global must get the global's own cell, not a fresh
+	* local one that the binding would never fill. Only a name nobody has bound
+	* anywhere gets its cell here, where a later `set` will land.
+	*/
+	cell(name) {
+		const own = this.vars.get(name);
+		if (own) return own;
+		const inherited = this.parent?.cell(name);
+		if (inherited) return inherited;
+		const made = { value: void 0 };
+		this.vars.set(name, made);
+		return made;
+	}
+	child() {
+		return new MapScope(this);
+	}
+};
+/**
+* Create a scope; `lookup` falls back to the parent, `set` writes locally.
+*
+* @param parent The enclosing scope, or nothing for a root scope.
+*/
+function createScope(parent) {
+	return new MapScope(parent);
+}
+//#endregion
+//#region src/scheduler/collect.ts
+/** Index the document's fragments by name for `run`. */
+function collectFragments(doc) {
+	const map = /* @__PURE__ */ new Map();
+	for (const decl of doc.decls) if (isFragmentDecl(decl)) map.set(decl.name, decl);
+	return map;
+}
+/** Evaluate the top-level `config { … }` block with `env` bound, for the action context. */
+function collectConfig(doc, env) {
+	const decl = doc.decls.find(isConfigDecl);
+	if (!decl) return {};
+	const scope = createScope();
+	scope.set("env", env);
+	return evaluate(decl.body, scope);
+}
+/** Gather top-level setup/teardown/beforeEach/afterEach blocks. */
+function collectHooks(doc) {
+	const hooks = {
+		setup: [],
+		teardown: [],
+		beforeEach: [],
+		afterEach: []
+	};
+	for (const decl of doc.decls) if (isLifecycleDecl(decl)) addHook(hooks, decl);
+	return hooks;
+}
+function addHook(hooks, decl) {
+	const bucket = hooks[decl.hook];
+	if (bucket) bucket.push(decl);
+}
+//#endregion
+//#region src/scheduler/create-cleanup-list.ts
+/**
+* The runtime's own sink, for a host that does not bring one.
+*
+* Closing runs newest first and survives a cleanup that throws: a program on its
+* way out still has to hand back everything else it was holding.
+*/
+function createCleanupList() {
+	const pending = [];
+	return {
+		add: (cleanup) => pending.push(cleanup),
+		close: async () => {
+			for (const cleanup of pending.splice(0).reverse()) await cleanup().catch(() => {});
+		}
+	};
+}
+//#endregion
+//#region src/scheduler/filter.ts
+/** A title matches when the needle is absent, or contained case-insensitively. */
+function matchesTitle(title, needle) {
+	if (!needle) return true;
+	return title.toLowerCase().includes(needle.toLowerCase());
+}
+//#endregion
+//#region src/scheduler/invocation.ts
+/**
+* The dotted path an expression spells, such as `http.post`, or undefined when
+* it is not a plain path. The parser cannot tell a namespace from a field; only
+* the registry can, so the path is carried this far as an expression.
+*/
+function actionTarget(expr) {
+	if (!expr) return void 0;
+	if (isRef(expr)) return expr.name;
+	if (!isMember(expr) || expr.optional) return void 0;
+	const receiver = actionTarget(expr.receiver);
+	return receiver === void 0 ? void 0 : `${receiver}.${expr.member}`;
+}
+/**
+* The bareword action a `let` spells: `let auth = http.post url { … }`. The
+* trailing arguments or options map are what mark it as a call. A parenthesised
+* call (`f(x)`) is an ordinary expression the evaluator runs, since it may be a
+* `fn` or a method rather than an action; only {@link actionCall} rescues the
+* case where it turns out to name a plugin action.
+*/
+function invocationOf(stmt) {
+	return remember(invocations, stmt, readInvocation);
+}
+function readInvocation(stmt) {
+	if (stmt.args.length === 0 && !stmt.opts) return void 0;
+	const target = actionTarget(stmt.value);
+	if (target === void 0) return void 0;
+	return {
+		target,
+		args: stmt.args,
+		opts: stmt.opts,
+		node: stmt
+	};
+}
+/**
+* An action written in expression position: the bare path `data.faker.uuid`, or
+* the parenthesised `data.faker.uuid()`. Returns the target and its arguments,
+* or undefined when it is not a dotted path at all.
+*/
+function actionCall(value) {
+	return remember(calls, value, readActionCall);
+}
+function readActionCall(value) {
+	const bare = actionTarget(value);
+	if (bare !== void 0) return {
+		target: bare,
+		args: []
+	};
+	if (!isCall(value)) return void 0;
+	const target = actionTarget(value.callee);
+	return target === void 0 ? void 0 : {
+		target,
+		args: argValues(value)
+	};
+}
+/**
+* What a node spells, worked out once.
+*
+* The shape of the tree decides whether `let y = x * 2` names an action, and the
+* tree does not change, so the answer is cached per node rather than rewalked
+* through the type guards on every execution. Whether the *name* resolves to an
+* action depends on the scope and the registry, so that part is not cached.
+*/
+const invocations = /* @__PURE__ */ new WeakMap();
+const calls = /* @__PURE__ */ new WeakMap();
+function remember(cache, key, read) {
+	const known = cache.get(key);
+	if (known !== void 0) return known ?? void 0;
+	const found = read(key) ?? null;
+	cache.set(key, found);
+	return found ?? void 0;
+}
+function argValues(call) {
+	return (call.args?.args ?? []).map((arg) => arg.value);
+}
+//#endregion
+//#region src/scheduler/node-span.ts
+/** The exact source text of an AST node, for the event stream. */
+function nodeSource(node) {
+	return node.$cstNode?.text ?? "";
+}
+/** A Span for an AST node, for a runtime Problem. */
+function nodeSpan(node, uri) {
+	const cst = node.$cstNode;
+	return {
+		uri,
+		offset: cst?.offset ?? 0,
+		length: cst?.length ?? 0,
+		line: (cst?.range?.start?.line ?? 0) + 1,
+		column: (cst?.range?.start?.character ?? 0) + 1
+	};
+}
+//#endregion
+//#region src/scheduler/annotations.ts
+/**
+* Whether a decorator set this flag on the node.
+*
+* The scheduler reads what expansion concluded, never the annotation list
+* itself, so a decorator is understood in exactly one place.
+*/
+function hasAnnotation(node, name) {
+	return readMeta(node, name) === true;
+}
+/** `@timeout(90s)` → milliseconds, or undefined. */
+function readTimeout(node) {
+	return readMeta(node, "timeout");
+}
+/** `@retry(2, { backoff: 500ms, factor: 2 })` → a retry spec, or undefined. */
+function readRetry(node) {
+	return readMeta(node, "retry");
+}
+/** `@lock("orders")` → the lock name, or undefined. */
+function readLock(node) {
+	return readMeta(node, "lock");
+}
+/** `@flaky(0.05)` → the tolerated failure ratio; bare `@flaky` tolerates all. */
+function readFlaky(node) {
+	return readMeta(node, "flaky");
+}
+/** `@tags(smoke, critical)` → the tag names. */
+function readTags(node) {
+	return readMeta(node, "tags") ?? [];
+}
+//#endregion
+//#region src/scheduler/bind-namespaces.ts
+/**
+* Put every plugin namespace in the root scope as a value, so its verbs work
+* inside any expression (`print(fmt.table(rows))`, `"${crypto.hash(x)}"`) and
+* not only as a bare statement.
+*
+* A verb reached this way runs synchronously: it is the pure corner of the
+* stdlib (`fmt`, `data`, `crypto`). An action that does I/O returns its promise,
+* so those stay written as statements, where the runtime awaits them.
+*/
+function bindNamespaces(args) {
+	const byNamespace = /* @__PURE__ */ new Map();
+	for (const entry of args.registry.actions()) {
+		const members = byNamespace.get(entry.namespace) ?? {};
+		place({
+			members,
+			path: entry.name,
+			action: entry.action,
+			ctx: args.ctx
+		});
+		byNamespace.set(entry.namespace, members);
+	}
+	for (const [namespace, members] of byNamespace) args.scope.set(namespace, namespaceValue(members));
+}
+/** `jwt.decode` nests: `{ jwt: { decode: fn } }`, so the dotted call reads naturally. */
+function place(args) {
+	const parts = args.path.split(".");
+	const leaf = parts.pop();
+	if (!leaf) return;
+	let level = args.members;
+	for (const part of parts) {
+		level[part] = level[part] ?? {};
+		level = level[part];
+	}
+	level[leaf] = verb(args.action, args.ctx);
+}
+function verb(action, ctx) {
+	return nativeFn((values) => action.run(ctx, {
+		args: values,
+		params: params(action)
+	}));
+}
+/** No options map in expression position, so let the schema supply its defaults. */
+function params(action) {
+	if (!action.params) return {};
+	try {
+		return action.params.parse({});
+	} catch {
+		return {};
+	}
+}
+//#endregion
+//#region src/scheduler/bind-prelude.ts
+/**
+* Put the pure prelude values (`len`, `range`, `pretty`, `str`, `min`…) in the
+* root scope. Being values rather than verbs is what lets them appear in any
+* expression: `xs.take(len(ys))`, `"${pretty(user)}"`.
+*/
+function bindPrelude(scope) {
+	for (const [name, value] of Object.entries(PRELUDE_VALUES)) scope.set(name, value);
+}
+//#endregion
+//#region src/scheduler/base-scope.ts
+/**
+* What every scope in a run starts as: the prelude, the plugin namespaces and
+* `env`, plus the matrix variant when there is one.
+*
+* One place, shared by test runs and program runs, so `venn test` and `venn run`
+* cannot drift apart. Every scope a module is read in starts here too, which is
+* what makes an imported function see the same world its own file did.
+*/
+function createBaseScope(args) {
+	const scope = createScope();
+	bindPrelude(scope);
+	bindNamespaces({
+		registry: args.engine.registry,
+		ctx: args.engine.ctx,
+		scope
+	});
+	scope.set("env", args.engine.env);
+	if (args.variant) scope.set("matrix", args.variant);
+	return scope;
+}
+//#endregion
+//#region src/scheduler/flaky.ts
+/** Record one execution of a `@flaky(ratio)` node, and how much it failed by. */
+function recordFlaky(engine, node, before) {
+	const ratio = readFlaky(node);
+	if (ratio === void 0) return;
+	const tally = engine.flaky.get(node) ?? {
+		ratio,
+		runs: 0,
+		failedRuns: 0,
+		failedUnits: 0
+	};
+	const delta = engine.result.failed - before;
+	tally.runs += 1;
+	tally.failedRuns += delta > 0 ? 1 : 0;
+	tally.failedUnits += delta > 0 ? delta : 0;
+	engine.flaky.set(node, tally);
+}
+/**
+* Forgive the failures of every `@flaky` node whose observed failure ratio
+* stayed within its declared tolerance. Settled once, so the verdict does not
+* depend on the order iterations happened to fail in.
+*/
+function settleFlaky(engine) {
+	for (const tally of engine.flaky.values()) {
+		if (tally.failedRuns === 0 || tally.failedRuns / tally.runs > tally.ratio) continue;
+		engine.result.failed = Math.max(0, engine.result.failed - tally.failedUnits);
+		engine.emitter.emit({
+			kind: "log",
+			data: {
+				level: "warn",
+				message: message(tally)
+			}
+		});
+	}
+}
+function message(tally) {
+	return `flaky tolerated: ${tally.failedRuns}/${tally.runs} runs failed, within ratio ${tally.ratio}`;
+}
+//#endregion
+//#region src/scheduler/run-around.ts
+/**
+* Run the `.before` and `.after` closures a `deco` left on a flow or a step.
+*
+* The language has no syntax for "around this body", so the verbs leave a fact
+* behind and this is where it is honoured. `.after` runs from a `finally`,
+* because a hook that only runs when nothing went wrong is the one case it was
+* written for.
+*/
+async function runAround(node, body) {
+	const around = readDecorations(node);
+	if (!around) {
+		await body();
+		return;
+	}
+	for (const fn of around.before) invoke(fn, []);
+	try {
+		await body();
+	} finally {
+		for (const fn of around.after) invoke(fn, []);
+	}
+}
+//#endregion
+//#region src/scheduler/run-attempts.ts
+/** Run a step/flow body applying its `@timeout` and `@retry` annotations. */
+async function runWithAnnotations(args) {
+	const timeout = readTimeout(args.node);
+	const retry = readRetry(args.node);
+	const attempt = () => withTimeout(timeout, args.run);
+	if (!retry || retry.attempts === 0) return attempt();
+	await withRetry({
+		engine: args.engine,
+		retry,
+		title: args.title,
+		run: attempt
+	});
+}
+/** Hold the named mutex (`@lock`/`@serial`) around `run`, releasing on exit. */
+async function withLock(engine, name, run) {
+	if (!name) return run();
+	const release = await engine.lock.acquire(name);
+	try {
+		await run();
+	} finally {
+		release();
+	}
+}
+async function withTimeout(timeoutMs, run) {
+	if (timeoutMs === void 0) return run();
+	let timer;
+	const guard = new Promise((_resolve, reject) => {
+		timer = setTimeout(() => reject(timeoutError(timeoutMs)), timeoutMs);
+	});
+	try {
+		await Promise.race([run(), guard]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+async function withRetry(args) {
+	const total = args.retry.attempts + 1;
+	for (let i = 1; i <= total; i++) {
+		const snapshot = { ...args.engine.result };
+		const outcome = await attempt(args.engine, args.run);
+		if (outcome.ok) return;
+		if (i >= total) {
+			if (outcome.error) throw outcome.error;
+			return;
+		}
+		Object.assign(args.engine.result, snapshot);
+		emitRetrying({
+			engine: args.engine,
+			title: args.title,
+			attempt: i
+		});
+		await args.engine.clock.sleep(backoff(args.retry, i));
+	}
+}
+async function attempt(engine, run) {
+	const before = engine.result.failed;
+	try {
+		await run();
+		return { ok: engine.result.failed === before };
+	} catch (error) {
+		if (isControlSignal(error)) throw error;
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+function emitRetrying(args) {
+	args.engine.emitter.emit({
+		kind: "flow.retrying",
+		data: {
+			title: args.title,
+			attempt: args.attempt,
+			reason: "previous attempt failed"
+		}
+	});
+}
+function backoff(retry, attempt) {
+	return retry.backoffMs * retry.factor ** (attempt - 1);
+}
+function timeoutError(ms) {
+	return new VennError({
+		code: "VN8001",
+		message: `Timed out after ${ms}ms.`
+	});
+}
+//#endregion
+//#region src/scheduler/unknown-option.ts
+/**
+* The keys an options map spells that the schema behind it never declared,
+* whether that schema is an action's or a matcher's.
+*
+* One list, two readers: the checker squiggles them before anything runs, the
+* runtime refuses them when the line executes. Same code, same words, so a typo
+* cannot read one way in the editor and another in the terminal.
+*
+* A schema that declares no keys accepts a free-form map, and nothing there is
+* unknown: `grpc.request` takes a `z.record`, `db.seed` takes no schema at all
+* and reads the whole map as table names.
+*/
+function unknownOptions(args) {
+	const specs = paramSpecs(args.params);
+	if (!args.opts || specs.length === 0 || welcomesMore(args.params)) return [];
+	const known = new Set(specs.map((spec) => spec.name));
+	return args.opts.entries.filter((entry) => !known.has(entry.key)).map((entry) => unknownOption({
+		entry,
+		specs,
+		uri: args.uri
+	}));
+}
+/**
+* A schema written with a catchall (`z.looseObject`, `.catchall(…)`) names some
+* keys and takes the rest as well. A key it never named is still a key it asked
+* to receive, so there is nothing to report. Read structurally, past the
+* wrappers `.optional()` and `.default()` add, the way {@link paramSpecs} reads
+* the shape.
+*/
+function welcomesMore(params) {
+	const def = params?.def;
+	if (def?.catchall !== void 0) return true;
+	return def?.innerType !== void 0 && welcomesMore(def.innerType);
+}
+function unknownOption(args) {
+	const { key } = args.entry;
+	const hint = nearest$1(key, args.specs);
+	const accepted = args.specs.map((spec) => spec.name).join(", ");
+	const title = hint ? `"${key}" is not an option here — did you mean "${hint}"?` : `"${key}" is not an option here. Accepted: ${accepted}.`;
+	return buildProblem({
+		spec: CODES.VN3001_UNKNOWN_OPTION,
+		span: nodeSpan(args.entry, args.uri),
+		title
+	});
+}
+/** The closest accepted key, when one is close enough to be worth suggesting. */
+function nearest$1(key, specs) {
+	const scored = specs.map((spec) => ({
+		name: spec.name,
+		distance: distance$1(key, spec.name)
+	})).sort((left, right) => left.distance - right.distance)[0];
+	return scored && scored.distance <= Math.max(2, Math.floor(key.length / 2)) ? scored.name : void 0;
+}
+/** Levenshtein, small enough to keep here and precise enough for a "did you mean". */
+function distance$1(left, right) {
+	let previous = Array.from({ length: right.length + 1 }, (_value, index) => index);
+	for (let i = 1; i <= left.length; i += 1) {
+		const current = [i];
+		for (let j = 1; j <= right.length; j += 1) {
+			const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+			current[j] = Math.min((current[j - 1] ?? 0) + 1, (previous[j] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+		}
+		previous = current;
+	}
+	return previous[right.length] ?? 0;
+}
+//#endregion
+//#region src/scheduler/call-params.ts
+/** Zod's word for a type, in the word the language uses for it. */
+const WORDS = {
+	object: "map",
+	record: "map",
+	array: "list",
+	boolean: "bool",
+	int: "number",
+	bigint: "number"
+};
+/**
+* The options map of a call, an action's or a matcher's, validated before the
+* thing it belongs to ever sees it.
+*
+* Unknown keys are refused rather than stripped, because `z.object` drops them
+* in silence and `crypto.hash "x" { algorithmm: "sha512" }` would then hash with
+* the default. A rejected value becomes a `Problem` rather than escaping as a
+* ZodError, whose `message` is a JSON dump of issues.
+*
+* @param args.site Where the call is written, for a failure with no smaller node
+* to point at: a required option nobody typed leaves nothing to underline.
+* @returns The parsed options.
+* @throws ProblemError `VN3010` when a key is unknown or a value is rejected.
+*/
+function callParams(args) {
+	const { schema, opts, raw, site, uri } = args;
+	if (!schema) return raw;
+	const unknown = unknownOptions({
+		opts,
+		params: schema,
+		uri
+	});
+	if (unknown[0]) throw new ProblemError(unknown[0]);
+	return parsed({
+		schema,
+		opts,
+		raw,
+		site,
+		uri
+	});
+}
+/** Parse, and turn a rejection into a sentence about the option that failed. */
+function parsed(args) {
+	try {
+		return args.schema.parse(args.raw);
+	} catch (error) {
+		const issue = firstIssue(error);
+		if (!issue) throw error;
+		const { raw, opts, site, uri } = args;
+		throw new ProblemError(badOption({
+			issue,
+			raw,
+			opts,
+			site,
+			uri
+		}));
+	}
+}
+function badOption(args) {
+	const path = args.issue.path ?? [];
+	return buildProblem({
+		spec: CODES.VN3010_TYPE_MISMATCH,
+		span: nodeSpan(entryFor(args.opts, path) ?? args.opts ?? args.site, args.uri),
+		title: title({
+			key: path.join("."),
+			issue: args.issue,
+			value: valueAt(args.raw, path)
+		})
+	});
+}
+/**
+* One line, naming the option and what it wanted. Only the shapes worth
+* modelling get their own sentence; anything else says so plainly rather than
+* dressing up an issue it does not understand.
+*/
+function title(args) {
+	const { key, issue, value } = args;
+	if (!key) return "These options are not valid here.";
+	if (issue.code === "invalid_value" && issue.values) return oneOf(key, issue.values, value);
+	if (issue.code !== "invalid_type" || !issue.expected) return `"${key}" is not a valid option.`;
+	const needs = WORDS[issue.expected] ?? issue.expected;
+	if (value === void 0) return `"${key}" is required here, and it takes a ${needs}.`;
+	return `"${key}" needs a ${needs}, and ${shown(value)} is a ${typeName(value)}.`;
+}
+/** `{ algorithm: "sha5" }` against a schema that lists the digests it knows. */
+function oneOf(key, values, value) {
+	return `"${key}" must be one of ${values.map((option) => shown(option)).join(", ")} — not ${shown(value)}.`;
+}
+/** A value as a message shows it: strings quoted, so `"soon"` reads as text. */
+function shown(value) {
+	return typeof value === "string" ? JSON.stringify(value) : display(value);
+}
+function valueAt(raw, path) {
+	let value = raw;
+	for (const key of path) value = value?.[key];
+	return value;
+}
+/** The written entry to underline, when the failure names a key this map spells. */
+function entryFor(opts, path) {
+	const key = String(path[0] ?? "");
+	return opts?.entries.find((entry) => entry.key === key);
+}
+/** Zod's failure, read structurally: the runtime does not depend on zod itself. */
+function firstIssue(error) {
+	const issues = error?.issues;
+	return Array.isArray(issues) ? issues[0] : void 0;
+}
+//#endregion
+//#region src/scheduler/declared-arity.ts
+/**
+* How many positional arguments a verb declared.
+*
+* Used to tell an argument that happens to be a map from the options map that
+* configures the call. A variadic verb such as `data.oneOf a b c` takes every
+* argument it is given, so nothing is left over to mistake for configuration.
+*/
+function takes(action) {
+	if (action.args?.some((each) => each.rest)) return Number.POSITIVE_INFINITY;
+	return action.args?.length ?? action.signature?.params.length ?? 0;
+}
+//#endregion
+//#region src/scheduler/local-call.ts
+/**
+* What a dotted statement target names, when it names something in scope.
+*
+* `conn.close()` and `http.get "url"` are written alike and mean different
+* things: one is a method on a value the program holds, the other a verb a
+* plugin contributes. Only the name can tell them apart, and a name the program
+* bound wins. That is the rule the evaluator already follows for `auth` the
+* variable against `auth` the namespace.
+*
+* Returns undefined whenever this is not that: no such name, a namespace, or a
+* path that leads somewhere uncallable. The caller then treats it as a verb,
+* and an unknown verb reports itself as it always did.
+*/
+function localCallee(target, scope) {
+	const segments = target.split(".");
+	const head = segments[0];
+	if (!head) return void 0;
+	const root = scope.lookup(head);
+	if (root === void 0 || isNamespaceValue(root)) return void 0;
+	let value = root;
+	for (let at = 1; at < segments.length; at += 1) value = memberValue(value, segments[at]);
+	return isCallable(value) ? value : void 0;
+}
+//#endregion
+//#region src/scheduler/settled.ts
+/**
+* Whether evaluating an expression produced something still running.
+*
+* Expressions compile synchronously, so a plugin verb called from inside one
+* hands back the promise it is running on rather than its result. Statement
+* position is already asynchronous, so it can wait, and `let id = newId()` binds
+* the id instead of `[object Promise]`.
+*
+* Callers branch on this rather than awaiting unconditionally: `await` on a
+* value that is not a promise still costs a turn of the event loop, and a
+* `forEach` over 50k items reads one expression per iteration.
+*/
+function isPending(value) {
+	return value instanceof Promise;
+}
+/** Wait for a value only if there is something to wait for. */
+async function settle(value) {
+	return isPending(value) ? await value : value;
+}
+//#endregion
+//#region src/scheduler/target.ts
+/**
+* Prelude verbs, callable without `use` (§12). `print` writes to the console,
+* `log` records into the event stream (what a reporter and a test see), and the
+* rest steer the run. Pure prelude *values* (`len`, `range`, `pretty`…) are not
+* here: they live in the root scope, so they work in any expression.
+*/
+const PRELUDE = /* @__PURE__ */ new Set([
+	"print",
+	"log",
+	"wait",
+	"skip",
+	"fail",
+	"exit"
+]);
+/** Split an action target `namespace.action` into parts (no dot ⇒ namespace only). */
+function splitTarget(target) {
+	const dot = target.indexOf(".");
+	if (dot < 0) return {
+		namespace: target,
+		name: ""
+	};
+	return {
+		namespace: target.slice(0, dot),
+		name: target.slice(dot + 1)
+	};
+}
+/** Split a target, mapping a `use "…" as h` alias back to its real namespace. */
+function resolveTarget(target, aliases) {
+	const { namespace, name } = splitTarget(target);
+	return {
+		namespace: aliases.get(namespace) ?? namespace,
+		name
+	};
+}
+//#endregion
+//#region src/scheduler/run-action.ts
+/**
+* Resolve, invoke and time an action call.
+*
+* @returns Whatever the action produced. The caller names it: there is no
+* implicit `res` for a reader to know about.
+* @throws VennError `VN2003` when no plugin provides the target.
+*/
+async function runAction(engine, call, scope) {
+	if (PRELUDE.has(call.target)) return runPrelude(engine, call, scope);
+	const callee = localCallee(call.target, scope);
+	if (callee !== void 0) return callMethod(callee, call, scope);
+	const { namespace, name } = resolveTarget(call.target, engine.aliases);
+	const resolved = engine.registry.action({
+		namespace,
+		name
+	});
+	if (!resolved) throw unknownAction(call.target);
+	engine.emitter.emit({
+		kind: "action.started",
+		data: {
+			namespace,
+			action: name
+		}
+	});
+	const start = engine.clock.now();
+	const value = await resolved.action.run(engine.ctx, await buildInput({
+		action: resolved.action,
+		call,
+		scope,
+		uri: engine.uri
+	}));
+	const durationMs = engine.clock.now() - start;
+	engine.emitter.emit({
+		kind: "action.finished",
+		data: {
+			namespace,
+			action: name,
+			status: "passed",
+			durationMs
+		}
+	});
+	return value;
+}
+/** Call a value the program holds, and wait for it as any other call is waited for. */
+async function callMethod(callee, call, scope) {
+	return settle(invoke(callee, await Promise.all(call.args.map((expr) => settle(evaluate(expr, scope))))));
+}
+/**
+* An action written as a bare statement: run it, drop what it returned.
+*
+* The arguments are normalised here because the two spellings, `conn.close()`
+* and `http.get "url"`, put them in different places on the node.
+*/
+async function runActionStatement(engine, call, scope) {
+	await runAction(engine, {
+		...call,
+		args: callArgs(call)
+	}, scope);
+}
+async function buildInput(args) {
+	const split = splitCall(args.call.args, takes(args.action));
+	const opts = args.call.opts ?? split.opts;
+	const positional = await Promise.all(split.args.map((expr) => settle(evaluate(expr, args.scope))));
+	const raw = await settle(opts ? evaluate(opts, args.scope) : {});
+	const schema = args.action.params;
+	return {
+		args: positional,
+		params: callParams({
+			schema,
+			opts,
+			raw,
+			site: siteOf(args.call),
+			uri: args.uri
+		})
+	};
+}
+/**
+* Where the call is written. A call spelled as a statement is its own node; one
+* rescued out of a `let` carries the statement that spells it, since the
+* invocation itself is a plain object with no place in the source.
+*/
+function siteOf(call) {
+	return call.node ?? call;
+}
+function unknownAction(target) {
+	return new VennError({
+		code: "VN2003",
+		message: `Unknown action "${target}".`,
+		detail: { target }
+	});
+}
+/** Prelude verbs, available without `use` (§12): print, log, wait, skip, fail, exit. */
+async function runPrelude(engine, call, scope) {
+	const args = await Promise.all(call.args.map((arg) => settle(evaluate(arg, scope))));
+	if (call.target === "print") return printLine(engine, args);
+	if (call.target === "log") return logLine(engine, args);
+	const message = String(args[0] ?? "");
+	if (call.target === "wait") await engine.clock.sleep(waitMs(args[0]));
+	else if (call.target === "skip") skipLog(engine, message);
+	else if (call.target === "exit") throw new ExitSignal(exitCode(args[0]));
+	else if (call.target === "fail") throw failError(message);
+}
+/**
+* `print x y`: the program's own output, on standard output. Distinct from
+* `log`, which records into the event stream a reporter reads.
+*/
+function printLine(engine, args) {
+	engine.ctx.port(ConsolePort).write(`${line(args)}\n`);
+}
+/** `log a b c`: every argument, spaced, objects shown as JSON not `[object Object]`. */
+function logLine(engine, args) {
+	engine.emitter.emit({
+		kind: "log",
+		data: {
+			level: "info",
+			message: line(args)
+		}
+	});
+}
+function line(args) {
+	return args.map(display).join(" ");
+}
+/**
+* The code `exit` leaves with. Anything the machine cannot use as one still
+* ended badly, so `exit "boom"` leaves with 1 and never with 0, which would read
+* as success to whatever is waiting on this process.
+*/
+function exitCode(value) {
+	const code = Math.trunc(Number(value ?? 0));
+	return Number.isFinite(code) ? code : 1;
+}
+function skipLog(engine, message) {
+	engine.emitter.emit({
+		kind: "log",
+		data: {
+			level: "warn",
+			message: `skipped: ${message}`
+		}
+	});
+}
+function waitMs(value) {
+	if (typeof value === "number") return value;
+	const duration = value;
+	return duration?.kind === "duration" ? duration.ms ?? 0 : 0;
+}
+function failError(message) {
+	return new VennError({
+		code: "VN6002",
+		message: message || "fail"
+	});
+}
+//#endregion
+//#region src/scheduler/run-bindings.ts
+/**
+* `let plan = "pro"` binds a value; `let auth = http.post url { … }` binds what
+* the action returned. Naming the result is what makes it readable: there is no
+* implicit variable to know about.
+*/
+function runLet(engine, stmt, scope) {
+	const call = invocationOf(stmt) ?? impliedCall(engine, stmt, scope);
+	if (!call) return bind$1(stmt.name, evaluate(stmt.value, scope), scope);
+	return runAction(engine, call, scope).then((value) => scope.set(stmt.name, value));
+}
+/**
+* `let id = data.faker.uuid` or `let id = data.faker.uuid()`: a dotted path
+* naming a plugin action is a call, exactly as it would be as a statement.
+*
+* A binding in scope always wins, so `let code = res.status` reads a field and
+* `let parts = name.split(" ")` calls a method. Neither turns into I/O, whatever
+* the registry happens to hold.
+*/
+function impliedCall(engine, stmt, scope) {
+	const call = actionCall(stmt.value);
+	const dot = call ? call.target.indexOf(".") : -1;
+	if (!call || dot < 0 || bound(scope, call.target.slice(0, dot))) return void 0;
+	return engine.registry.action(resolveTarget(call.target, engine.aliases)) ? {
+		target: call.target,
+		args: call.args,
+		node: stmt
+	} : void 0;
+}
+/** A name the user bound. A plugin namespace in scope is not one, so the verb still calls. */
+function bound(scope, name) {
+	const value = scope.lookup(name);
+	return value !== void 0 && !isNamespaceValue(value);
+}
+/** Bind now, or once the value it is waiting on arrives. */
+function bind$1(name, value, scope) {
+	if (isPending(value)) return value.then((settled) => scope.set(name, settled));
+	scope.set(name, value);
+}
+/** `capture` is removed in favour of `let`; still run, so old files keep working. */
+function runCapture(stmt, scope) {
+	scope.set(stmt.name, evaluate(stmt.value, scope));
+}
+/** `return expr`: unwind to the enclosing fragment with the value. */
+function runReturn(stmt, scope) {
+	throw new ReturnSignal(stmt.value ? evaluate(stmt.value, scope) : void 0);
+}
+//#endregion
+//#region src/scheduler/run-matcher.ts
+/** Resolve a bareword matcher from the registry and run it against the subject. */
+async function evalMatcher(args) {
+	const clause = args.stmt.matcher;
+	const resolved = args.engine.registry.matcher(clause.name);
+	if (!resolved) throw unknownMatcher(clause.name);
+	const input = buildArgs({
+		...args,
+		resolved,
+		clause
+	});
+	const raw = await resolved.matcher.test(input);
+	if (args.stmt.negate ? !raw : raw) return { passed: true };
+	return failure({
+		matcher: resolved.matcher,
+		input,
+		stmt: args.stmt
+	});
+}
+/**
+* A failing matcher hands back the two sides it compared, labelled with how the
+* flow spelled the subject. A negated expect gets no diff on purpose: under
+* `not` the two sides matched, and "expected 200, actual 200" explains nothing.
+*/
+function failure(args) {
+	const message = args.matcher.message(args.input);
+	const detail = args.stmt.negate ? void 0 : args.matcher.detail?.(args.input);
+	if (!detail) return {
+		passed: false,
+		message
+	};
+	return {
+		passed: false,
+		message,
+		diff: buildDiff({
+			label: subjectLabel(args.stmt),
+			...detail
+		})
+	};
+}
+/** The diff's header: the subject as the flow spelled it, on one line. */
+function subjectLabel(stmt) {
+	const source = stmt.subject ? nodeSource(stmt.subject).replace(/\s+/g, " ").trim() : "";
+	return source === "" ? "value" : source;
+}
+function buildArgs(args) {
+	const { stmt, clause, scope } = args;
+	return {
+		subject: stmt.subject ? evaluate(stmt.subject, scope) : void 0,
+		args: clause.args.map((expr) => evaluate(expr, scope)),
+		params: matcherOptions(args)
+	};
+}
+/**
+* A matcher's options map goes through the same gate an action's does: a key it
+* never declared is refused rather than dropped, and a value it rejects reads as
+* one line. Nothing checks these before the run, since `checkOptions` only ever
+* sees calls, so this is the only place `{ withinn: 1 }` is ever noticed.
+*/
+function matcherOptions(args) {
+	const { resolved, stmt, clause, scope, engine } = args;
+	const raw = clause.opts ? evaluate(clause.opts, scope) : {};
+	const schema = resolved.matcher.params;
+	return callParams({
+		schema,
+		opts: clause.opts,
+		raw,
+		site: stmt,
+		uri: engine.uri
+	});
+}
+function unknownMatcher(name) {
+	return new VennError({
+		code: "VN2004",
+		message: `Unknown matcher "${name}".`,
+		detail: { name }
+	});
+}
+//#endregion
+//#region src/scheduler/run-expect.ts
+/** Evaluate an `expect` (matcher clause, `.all` checks, negated, or subject) and emit the outcome. */
+async function runExpect(engine, stmt, scope) {
+	record({
+		engine,
+		stmt,
+		outcome: stmt.matcher ? await evalMatcher({
+			engine,
+			stmt,
+			scope
+		}) : { passed: await evalBoolean({
+			stmt,
+			scope
+		}) }
+	});
+}
+async function evalBoolean(args) {
+	return args.stmt.modifier === "all" ? evalChecks(args) : evalSubject(args);
+}
+async function evalSubject(args) {
+	if (!args.stmt.subject) return true;
+	const value = truthy(await settle(evaluate(args.stmt.subject, args.scope)));
+	return args.stmt.negate ? !value : value;
+}
+async function evalChecks(args) {
+	for (const check of args.stmt.checks) if (!truthy(await settle(evaluate(check, args.scope)))) return false;
+	return true;
+}
+function record(args) {
+	if (args.outcome.passed) {
+		args.engine.result.passed += 1;
+		args.engine.emitter.emit({
+			kind: "expect.passed",
+			data: { source: nodeSource(args.stmt) }
+		});
+		return;
+	}
+	args.engine.result.failed += 1;
+	const problem = buildProblem({
+		spec: CODES.VN6001_ASSERTION_FAILED,
+		span: nodeSpan(args.stmt, args.engine.uri),
+		title: args.outcome.message ?? `Expectation failed: ${nodeSource(args.stmt)}`,
+		diff: args.outcome.diff
+	});
+	args.engine.emitter.emit({
+		kind: "expect.failed",
+		data: { problem }
+	});
+}
+//#endregion
+//#region src/scheduler/concurrency.ts
+/** Run `task` over `items` with at most `limit` in flight at once. */
+async function runPool(items, limit, task) {
+	const size = Math.max(1, limit);
+	let cursor = 0;
+	const worker = async () => {
+		while (cursor < items.length) {
+			const index = cursor++;
+			await task(items[index], index);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(size, items.length) }, worker));
+}
+//#endregion
+//#region src/scheduler/opts.ts
+/** Read a numeric field from an options map literal (e.g. `{ concurrency: 4 }`). */
+function optsNumber(opts, key, scope) {
+	const entry = opts?.entries.find((candidate) => candidate.key === key);
+	if (!entry) return void 0;
+	const value = evaluate(entry.value, scope);
+	return typeof value === "number" ? value : void 0;
+}
+//#endregion
+//#region src/scheduler/run-foreach.ts
+/** `forEach x in list { concurrency: N } { … }`: iterate, up to N in flight. */
+async function runForEach(engine, stmt, scope) {
+	const source = await settle(evaluate(stmt.source, scope));
+	if (!Array.isArray(source)) throw notAList({
+		engine,
+		stmt,
+		source
+	});
+	const concurrency = optsNumber(stmt.opts, "concurrency", scope) ?? 1;
+	if (concurrency === 1) return sequential(engine, stmt, source, scope);
+	await runPool(source, concurrency, (item) => runIteration({
+		engine,
+		stmt,
+		item,
+		scope
+	}));
+}
+/**
+* Anything but a list is refused, because iterating it zero times would report
+* success: a test that checked nothing, dressed as one that passed. Built here,
+* off the iteration path, so the loop itself pays nothing for it.
+*/
+function notAList(args) {
+	return new ProblemError(buildProblem({
+		spec: CODES.VN3015_NOT_A_LIST,
+		span: nodeSpan(args.stmt.source, args.engine.uri),
+		title: `forEach needs a list, and this is a ${typeName(args.source)}.`,
+		help: helpFor(args.source)
+	}));
+}
+/** The everyday cause: an endpoint answering `{ data: [...] }` rather than a list. */
+function helpFor(source) {
+	if (typeName(source) !== "map") return void 0;
+	return "Name the list inside it, as in `forEach item in res.data`.";
+}
+/**
+* Walk the items one at a time, staying synchronous for as long as the body
+* does. A body of pure work (a binding, a comparison, arithmetic) never
+* suspends, so 50k iterations cost no promises at all. The first iteration that
+* does suspend hands the remainder to {@link resume}, from where it left off.
+*/
+function sequential(engine, stmt, items, scope) {
+	const plan = planOf$1(stmt.body);
+	const name = stmt.item;
+	if (plan.defers) return slowSequential(engine, stmt, items, scope);
+	const child = scope.child();
+	for (let at = 0; at < items.length; at += 1) try {
+		child.set(name, items[at]);
+		const pending = runSteps(engine, plan.steps, child);
+		if (pending) return resume$1(engine, stmt, items, at + 1, scope, pending);
+	} catch (error) {
+		if (error instanceof BreakSignal) return void 0;
+		if (error instanceof ContinueSignal) continue;
+		throw error;
+	}
+}
+function slowSequential(engine, stmt, items, scope) {
+	for (let at = 0; at < items.length; at += 1) try {
+		const pending = iterate(engine, stmt, items[at], scope);
+		if (pending) return resume$1(engine, stmt, items, at + 1, scope, pending);
+	} catch (error) {
+		if (error instanceof BreakSignal) return void 0;
+		if (error instanceof ContinueSignal) continue;
+		throw error;
+	}
+}
+function iterate(engine, stmt, item, scope) {
+	const child = scope.child();
+	child.set(stmt.item, item);
+	return runBlock(engine, stmt.body, child);
+}
+async function resume$1(engine, stmt, items, from, scope, pending) {
+	try {
+		await pending;
+	} catch (error) {
+		if (error instanceof BreakSignal) return;
+		if (!(error instanceof ContinueSignal)) throw error;
+	}
+	for (let at = from; at < items.length; at += 1) try {
+		await iterate(engine, stmt, items[at], scope);
+	} catch (error) {
+		if (error instanceof BreakSignal) return;
+		if (error instanceof ContinueSignal) continue;
+		throw error;
+	}
+}
+async function runIteration(args) {
+	const child = args.scope.child();
+	child.set(args.stmt.item, args.item);
+	try {
+		await runBlock(args.engine, args.stmt.body, child);
+	} catch (error) {
+		if (error instanceof BreakSignal || error instanceof ContinueSignal) return;
+		throw error;
+	}
+}
+//#endregion
+//#region src/scheduler/run-group.ts
+/** A group only clusters steps in the graph; it shares the enclosing scope. */
+async function runGroup(engine, stmt, scope) {
+	await runBlock(engine, stmt.body, scope);
+}
+//#endregion
+//#region src/scheduler/run-if.ts
+/** `if cond { … } else if … else { … }`: evaluate and run the taken branch. */
+function runIf(engine, stmt, scope) {
+	const cond = evaluate(stmt.cond, scope);
+	if (isPending(cond)) return cond.then((value) => void taken(engine, stmt, scope, truthy(value)));
+	return taken(engine, stmt, scope, truthy(cond));
+}
+function taken(engine, stmt, scope, yes) {
+	if (yes) return runBlock(engine, stmt.then, scope.child());
+	const branch = stmt.otherwise;
+	if (!branch) return void 0;
+	if (isIfStmt(branch)) return runIf(engine, branch, scope);
+	return runBlock(engine, branch, scope.child());
+}
+//#endregion
+//#region src/scheduler/branch-engine.ts
+/**
+* A per-branch view of the engine carrying the cancellation signal.
+*
+* Into `ctx` as well as onto the engine: the statement walker checks the signal
+* between statements, but a branch parked inside a long action is only reachable
+* through the context the action was handed. Without it, cancelling a branch
+* waits for whatever it is already doing to finish on its own.
+*/
+function branchEngine(engine, signal) {
+	return {
+		...engine,
+		signal,
+		ctx: {
+			...engine.ctx,
+			signal
+		}
+	};
+}
+//#endregion
+//#region src/scheduler/opts-text.ts
+/** Read a string field from an options map literal (e.g. `{ onError: "cancel" }`). */
+function optsText(opts, key, scope) {
+	const entry = opts?.entries.find((candidate) => candidate.key === key);
+	if (!entry) return void 0;
+	const value = evaluate(entry.value, scope);
+	return typeof value === "string" ? value : void 0;
+}
+//#endregion
+//#region src/scheduler/run-parallel.ts
+/**
+* `parallel { concurrency: 2, onError: "collect" } { … }`: run each child
+* statement concurrently.
+*
+* The block does not outlive itself. However it ends, every branch has either
+* finished or been cancelled by the time this returns: `Promise.all` on its own
+* rejects at the first failure and leaves the rest running, which is how a
+* finished test carries on making requests.
+*/
+async function runParallel(engine, stmt, scope) {
+	const limit = optsNumber(stmt.opts, "concurrency", scope) ?? stmt.body.stmts.length;
+	const onError = optsText(stmt.opts, "onError", scope) ?? "cancel";
+	const controller = new AbortController();
+	const failures = [];
+	await runPool(stmt.body.stmts, Math.max(1, limit), (child) => branch({
+		engine,
+		child,
+		scope,
+		controller,
+		failures,
+		onError
+	}));
+	report(failures);
+}
+/**
+* One branch, and what its failure means for the others.
+*
+* `cancel`, the default, stops the siblings at their next statement boundary,
+* because a run that has already failed should stop working. `collect` lets them
+* all finish and reports every failure, which is what a set of independent
+* checks wants.
+*/
+async function branch(args) {
+	const engine = branchEngine(args.engine, args.controller.signal);
+	try {
+		await runStatement(engine, args.child, args.scope.child());
+	} catch (error) {
+		if (error instanceof CancelSignal) return;
+		if (isControlSignal(error)) throw error;
+		args.failures.push(error);
+		if (args.onError === "cancel") args.controller.abort();
+	}
+}
+/**
+* One failure is raised as itself, so the reader sees the message the branch
+* produced. Several are raised together rather than one being picked.
+*/
+function report(failures) {
+	if (failures.length === 0) return;
+	if (failures.length === 1) throw failures[0];
+	throw new AggregateError(failures, `${failures.length} parallel branches failed.`);
+}
+//#endregion
+//#region src/scheduler/run-race.ts
+/** `race { … }`: the first branch to settle wins, the losers are cancelled. */
+async function runRace(engine, stmt, scope) {
+	const controller = new AbortController();
+	const branches = stmt.body.stmts.map((child) => Promise.resolve(runStatement(branchEngine(engine, controller.signal), child, scope.child())));
+	try {
+		await Promise.race(branches);
+	} finally {
+		controller.abort();
+		for (const branch of branches) branch.catch(() => {});
+	}
+}
+//#endregion
+//#region src/scheduler/run-repeat.ts
+/** `repeat N as i { … }`: run the body N times, honouring break/continue. */
+async function runRepeat(engine, stmt, scope) {
+	const count = toCount(engine, stmt, evaluate(stmt.count, scope));
+	for (let i = 1; i <= count; i++) {
+		const child = scope.child();
+		if (stmt.index) child.set(stmt.index, i);
+		try {
+			const pending = runBlock(engine, stmt.body, child);
+			if (pending) await pending;
+		} catch (error) {
+			if (error instanceof BreakSignal) break;
+			if (error instanceof ContinueSignal) continue;
+			throw error;
+		}
+	}
+}
+/**
+* A count the machine cannot read as one is refused, because running the body
+* zero times would report success: `repeat cfg.times` with nothing behind
+* `times` would check nothing and pass.
+*
+* Zero and below still mean "not at all": a bound that computes to none is a
+* program saying so, not a mistake.
+*/
+function toCount(engine, stmt, value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw notANumber(engine, stmt, value);
+	return value > 0 ? Math.floor(value) : 0;
+}
+function notANumber(engine, stmt, value) {
+	return new ProblemError(buildProblem({
+		spec: CODES.VN3016_NOT_A_NUMBER,
+		span: nodeSpan(stmt.count, engine.uri),
+		title: `repeat needs a number of times, and this is a ${typeName(value)}.`,
+		help: "Give it a count, as in `repeat 3 { … }`."
+	}));
+}
+//#endregion
+//#region src/scheduler/run-run.ts
+/** `run fragment(args) as x`: invoke a fragment and bind its return value. */
+async function runRun(engine, stmt, scope) {
+	const fragment = engine.fragments.get(stmt.target);
+	if (!fragment) throw unknownFragment(stmt.target);
+	const args = (stmt.args?.args ?? []).map((arg) => evaluate(arg.value, scope));
+	const fragScope = createScope();
+	bindParams(fragScope, fragment.params, args);
+	const value = await runFragment(engine, fragment, fragScope);
+	if (stmt.bind) scope.set(stmt.bind, value);
+}
+async function runFragment(engine, fragment, scope) {
+	try {
+		await runBlock(engine, fragment.body, scope);
+		return;
+	} catch (error) {
+		if (error instanceof ReturnSignal) return error.value;
+		throw error;
+	}
+}
+function bindParams(scope, params, args) {
+	(params?.params ?? []).forEach((param, index) => {
+		scope.set(param.name, args[index]);
+	});
+}
+function unknownFragment(name) {
+	return new VennError({
+		code: "VN2005",
+		message: `Unknown fragment "${name}".`,
+		detail: { fragment: name }
+	});
+}
+//#endregion
+//#region src/scheduler/run-step.ts
+/** Run a step honouring @skip/@only, @lock, @timeout and @retry; its bindings are step-local. */
+async function runStep(engine, step, parent) {
+	if (!included(engine, step)) return;
+	engine.emitter.emit({
+		kind: "step.started",
+		data: { title: step.title }
+	});
+	const before = engine.result.failed;
+	const scope = parent.child();
+	try {
+		await execute(engine, step, {
+			parent,
+			scope
+		});
+	} catch (error) {
+		if (!isControlSignal(error)) finished(engine, step.title, "failed");
+		throw error;
+	}
+	recordFlaky(engine, step, before);
+	finished(engine, step.title, engine.result.failed > before ? "failed" : "passed");
+}
+/**
+* The gate `selectFlows` puts on a flow, put on a step: `@only` focuses, `@skip`
+* drops, and only then the `--step` title filter.
+*
+* A step is focused among the steps it stands with, meaning the block it was
+* written in, the way a flow is focused among the flows of its document.
+*/
+function included(engine, step) {
+	if (hasAnnotation(step, "skip")) return false;
+	if (focusing(step.$container) && !hasAnnotation(step, "only")) return false;
+	return matchesTitle(step.title, engine.filter.step);
+}
+/** Whether any step in this block asked to be the only one that runs. */
+const focused = /* @__PURE__ */ new WeakMap();
+/**
+* Answered once per block: the source cannot change mid-run, and a step inside a
+* `forEach` would otherwise re-read its siblings on every pass.
+*/
+function focusing(container) {
+	if (!isBlock(container)) return false;
+	const known = focused.get(container);
+	if (known !== void 0) return known;
+	const found = container.stmts.some((stmt) => isStepDecl(stmt) && hasAnnotation(stmt, "only"));
+	focused.set(container, found);
+	return found;
+}
+function execute(engine, step, scopes) {
+	return withLock(engine, readLock(step), () => runWithAnnotations({
+		engine,
+		node: step,
+		scope: scopes.parent,
+		title: step.title,
+		run: () => runAround(step, () => runBlock(engine, step.body, scopes.scope))
+	}));
+}
+function finished(engine, title, status) {
+	engine.emitter.emit({
+		kind: "step.finished",
+		data: {
+			title,
+			status
+		}
+	});
+}
+//#endregion
+//#region src/scheduler/run-try.ts
+/** `try { } catch e { } finally { }`: control signals pass through, errors go to catch. */
+async function runTry(engine, stmt, scope) {
+	try {
+		await runBlock(engine, stmt.body, scope.child());
+	} catch (error) {
+		if (isControlSignal(error)) throw error;
+		await runCatch({
+			engine,
+			stmt,
+			scope,
+			error
+		});
+	} finally {
+		if (stmt.finalizer) await runBlock(engine, stmt.finalizer, scope.child());
+	}
+}
+async function runCatch(args) {
+	if (!args.stmt.handler) return;
+	const child = args.scope.child();
+	if (args.stmt.error) child.set(args.stmt.error, toErrorValue(args.error));
+	await runBlock(args.engine, args.stmt.handler, child);
+}
+function toErrorValue(error) {
+	const e = error;
+	return {
+		message: e?.message ?? String(error),
+		code: e?.code ?? "VN7000"
+	};
+}
+//#endregion
+//#region src/scheduler/run-while.ts
+/**
+* Every `while` has an inherited timeout in the language; this is the hard cap
+* that stands in for it until timeouts are wired.
+*/
+const MAX_ITERATIONS = 1e5;
+/** `while cond { … }`: loop while the condition is truthy. */
+async function runWhile(engine, stmt, scope) {
+	let guard = 0;
+	while (truthy(await settle(evaluate(stmt.cond, scope)))) {
+		if (++guard > MAX_ITERATIONS) throw neverFinished(engine, stmt);
+		try {
+			await runBlock(engine, stmt.body, scope.child());
+		} catch (error) {
+			if (error instanceof BreakSignal) break;
+			if (error instanceof ContinueSignal) continue;
+			throw error;
+		}
+	}
+}
+/**
+* Reaching the cap is not the loop finishing, so it is raised rather than
+* returned: stopping at the limit in silence would report a pass.
+*/
+function neverFinished(engine, stmt) {
+	return new ProblemError(buildProblem({
+		spec: CODES.VN8002_LOOP_LIMIT,
+		span: nodeSpan(stmt, engine.uri),
+		title: `This while loop ran ${MAX_ITERATIONS} times and its condition was still true.`,
+		help: "Change something the condition reads inside the loop, or use `repeat n` to bound it."
+	}));
+}
+//#endregion
+//#region src/scheduler/run-statements.ts
+/**
+* Dispatch one statement to its handler. This is the single boundary where a
+* cancelled `race` branch stops advancing.
+*
+* Switched on `$type`, not on the `isXxx` guards: each guard asks Langium's
+* reflection whether one type is a subtype of another, and a chain of them costs
+* a double-digit share of a large `forEach`. `$type` is a plain string every
+* node carries, so one switch answers what thirteen questions would.
+*/
+function runStatement(engine, stmt, scope) {
+	if (engine.signal?.aborted) throw new CancelSignal();
+	switch (stmt.$type) {
+		case "LetStmt": return runLet(engine, stmt, scope);
+		case "ActionCall": return runActionStatement(engine, stmt, scope);
+		case "ExpectStmt": return runExpect(engine, stmt, scope);
+		case "IfStmt": return runIf(engine, stmt, scope);
+		case "StepDecl": return runStep(engine, stmt, scope);
+		case "GroupDecl": return runGroup(engine, stmt, scope);
+		default: return control(engine, stmt, scope);
+	}
+}
+/** Loops, concurrency and the control-flow signals: the rarer half. */
+function control(engine, stmt, scope) {
+	switch (stmt.$type) {
+		case "ForEachStmt": return runForEach(engine, stmt, scope);
+		case "RepeatStmt": return runRepeat(engine, stmt, scope);
+		case "WhileStmt": return runWhile(engine, stmt, scope);
+		case "ParallelStmt": return runParallel(engine, stmt, scope);
+		case "RaceStmt": return runRace(engine, stmt, scope);
+		case "TryStmt": return runTry(engine, stmt, scope);
+		case "RunStmt": return runRun(engine, stmt, scope);
+		default: return leaf(stmt, scope);
+	}
+}
+function leaf(stmt, scope) {
+	if (stmt.$type === "CaptureStmt") return runCapture(stmt, scope);
+	if (stmt.$type === "ReturnStmt") return runReturn(stmt, scope);
+	if (stmt.$type === "BreakStmt") throw new BreakSignal();
+	if (stmt.$type === "ContinueStmt") throw new ContinueSignal();
+}
+//#endregion
+//#region src/scheduler/block-plan.ts
+const plans = /* @__PURE__ */ new WeakMap();
+/** The plan for a block, built on first use and cached against the node itself. */
+function planOf$1(block) {
+	const known = plans.get(block);
+	if (known) return known;
+	const built = {
+		steps: block.stmts.map(stepOf),
+		defers: block.stmts.some(isDefer$2)
+	};
+	plans.set(block, built);
+	return built;
+}
+function isDefer$2(stmt) {
+	return isLifecycleDecl(stmt) && stmt.hook === "defer";
+}
+function stepOf(stmt) {
+	return plainLet(stmt) ?? ((engine, scope) => runStatement(engine, stmt, scope));
+}
+/**
+* `const y = x * 2`: no trailing args, no options map, and a value that is not a
+* dotted path, so no registry lookup can turn it into a verb. The name, the
+* compiled expression and the decision are all fixed by the source.
+*/
+function plainLet(stmt) {
+	if (!isLetStmt(stmt)) return void 0;
+	const let_ = stmt;
+	if (let_.args.length > 0 || let_.opts) return void 0;
+	const call = actionCall(let_.value);
+	if (call && call.target.indexOf(".") >= 0) return void 0;
+	const name = let_.name;
+	const thunk = compileExpr(let_.value);
+	return (_engine, scope) => bind(name, thunk(scope), scope);
+}
+function bind(name, value, scope) {
+	if (isPending(value)) return value.then((settled) => scope.set(name, settled));
+	scope.set(name, value);
+}
+//#endregion
+//#region src/scheduler/run-block.ts
+/**
+* Run a block's statements in order, running any `defer { … }` bodies LIFO on
+* the way out, including on error or a control-flow signal.
+*/
+function runBlock(engine, block, scope) {
+	const plan = planOf$1(block);
+	if (plan.defers) return withDefers(engine, block, scope);
+	return runSteps(engine, plan.steps, scope);
+}
+/** The walk over a plan, reusable by a loop that hoists `planOf` out of it. */
+function runSteps(engine, steps, scope) {
+	for (let at = 0; at < steps.length; at += 1) {
+		if (engine.signal?.aborted) throw new CancelSignal();
+		const pending = steps[at](engine, scope);
+		if (pending) return resume(engine, steps, at + 1, scope, pending);
+	}
+}
+async function resume(engine, steps, from, scope, pending) {
+	await pending;
+	for (let at = from; at < steps.length; at += 1) {
+		if (engine.signal?.aborted) throw new CancelSignal();
+		const next = steps[at](engine, scope);
+		if (next) await next;
+	}
+}
+async function withDefers(engine, block, scope) {
+	const defers = [];
+	try {
+		for (const stmt of block.stmts) {
+			if (isDefer$1(stmt)) {
+				defers.unshift(stmt.body);
+				continue;
+			}
+			const pending = runStatement(engine, stmt, scope);
+			if (pending) await pending;
+		}
+	} finally {
+		const cleanup = {
+			...engine,
+			signal: void 0
+		};
+		for (const body of defers) await runBlock(cleanup, body, scope.child());
+	}
+}
+function isDefer$1(stmt) {
+	return isLifecycleDecl(stmt) && stmt.hook === "defer";
+}
+//#endregion
+//#region src/scheduler/run-lifecycle.ts
+/**
+* Run a set of lifecycle blocks (setup/teardown/beforeEach/afterEach) in order.
+*
+* The caller passes the scope the hooks belong to (the suite root for
+* setup/teardown, the flow's own scope for beforeEach/afterEach) and each body
+* runs in a child of it, the way the `on` handlers below do. In a parentless
+* scope `env`, the prelude, the top-level bindings and the open resources would
+* all read as undefined and the hook would run anyway: a teardown written as
+* `db.exec "DELETE FROM orders WHERE run = '${env.RUN_ID}'"` deletes the table
+* it was meant to tidy.
+*/
+async function runHooks(args) {
+	for (const hook of args.hooks) await runHook(args.engine, hook, args.scope);
+}
+/**
+* Run the `on <event>` handlers whose event matches (e.g. "failure"/"success").
+*
+* Through the same boundary as the hooks above: a handler that reacts to a
+* failure by failing itself is a second failure, not the end of the run.
+*/
+async function runOnHandlers(args) {
+	for (const handler of args.handlers) if (handler.event === args.event) await runHook(args.engine, handler, args.scope);
+}
+/**
+* A hook that throws fails the suite instead of ending the run: it is counted
+* and reported, and the walk carries on to `run.finished`, so the reporters
+* still close their files and the files after this one still run.
+*/
+async function runHook(engine, hook, scope) {
+	try {
+		await runBlock(engine, hook.body, scope.child());
+	} catch (error) {
+		if (error instanceof ExitSignal) throw error;
+		if (!isControlSignal(error)) recordFailure({
+			engine,
+			hook,
+			error
+		});
+	}
+}
+/**
+* Counted where a failing flow is counted, and carried on the event that already
+* puts a Problem in front of every reporter. A hook failure the reporters never
+* hear about ends as a green artifact over a broken run.
+*/
+function recordFailure(args) {
+	args.engine.result.failed += 1;
+	args.engine.emitter.emit({
+		kind: "expect.failed",
+		data: { problem: hookProblem(args) }
+	});
+}
+function hookProblem(args) {
+	return buildProblem({
+		spec: CODES.VN7004_HOOK_FAILED,
+		span: nodeSpan(args.hook, args.engine.uri),
+		title: `${hookLabel(args.hook)} failed: ${messageOf(args.error)}`
+	});
+}
+/** The block named the way the user wrote it: `setup`, or `on failure`. */
+function hookLabel(hook) {
+	return hook.hook ?? (hook.event ? `on ${hook.event}` : "lifecycle");
+}
+function messageOf(error) {
+	return error?.message ?? String(error);
+}
+//#endregion
+//#region src/scheduler/run-flow.ts
+/** Run a flow: body, then its `on failure`/`on success` handlers, then finish. */
+async function runFlow(engine, flow, scope) {
+	engine.emitter.emit({
+		kind: "flow.started",
+		data: { title: flow.title }
+	});
+	const before = engine.result.failed;
+	const handlers = flow.body.stmts.filter(isOnHandler);
+	await runFlowBody(engine, flow, scope);
+	recordFlaky(engine, flow, before);
+	const status = engine.result.failed > before ? "failed" : "passed";
+	await runOnHandlers({
+		engine,
+		handlers,
+		event: status === "failed" ? "failure" : "success",
+		scope
+	});
+	engine.emitter.emit({
+		kind: "flow.finished",
+		data: {
+			title: flow.title,
+			status
+		}
+	});
+}
+async function runFlowBody(engine, flow, scope) {
+	try {
+		await withLock(engine, flowLock(flow), () => runWithAnnotations({
+			engine,
+			node: flow,
+			scope,
+			title: flow.title,
+			run: () => runAround(flow, () => runBlock(engine, flow.body, scope))
+		}));
+	} catch (error) {
+		if (error instanceof ExitSignal) throw error;
+		if (!isControlSignal(error)) recordError(engine, error);
+	}
+}
+/** `@lock("x")` uses a named mutex; `@serial` serialises runs of the same flow. */
+function flowLock(flow) {
+	return readLock(flow) ?? (hasAnnotation(flow, "serial") ? `serial:${flow.title}` : void 0);
+}
+function isOnHandler(stmt) {
+	return isLifecycleDecl(stmt) && Boolean(stmt.event);
+}
+/**
+* A failure the flow itself could not handle.
+*
+* One that already knows what it is (a Problem, with its code, its span and its
+* help) travels on the event every reporter reads for failures. Flattening it to
+* a log line would strip the code and the location the raiser worked out.
+*/
+function recordError(engine, error) {
+	engine.result.failed += 1;
+	if (error instanceof ProblemError) {
+		engine.emitter.emit({
+			kind: "expect.failed",
+			data: { problem: error.problem }
+		});
+		return;
+	}
+	const message = error?.message ?? String(error);
+	engine.emitter.emit({
+		kind: "log",
+		data: {
+			level: "error",
+			message
+		}
+	});
+}
+//#endregion
+//#region src/scheduler/run-prologue.ts
+/**
+* A document's top-level statements, run once, in the order they are written.
+*
+* The same lines mean the same thing in both modes: a script *is* its prologue,
+* and a test file runs one before its flows. So a `const` calling a verb at the
+* top of a file opens the thing either way, and the flows never find `null`.
+*
+* @param args.into Where deferred cleanups accumulate, in written order. A
+* program's ending is registered before its statements run, so it has to see
+* what they defer as they reach it rather than afterwards.
+* @returns The teardowns collected, which is `into` when one was supplied.
+*/
+async function runPrologue(args) {
+	const teardowns = args.into ?? [];
+	for (const node of args.doc.decls) if (isDefer(node)) teardowns.push(deferred({
+		...args,
+		body: node.body
+	}));
+	else if (isRunnable(node)) await runStatement(args.engine, node, args.scope);
+	return teardowns;
+}
+/** `defer { … }` written at the top of a file: registered here, run on the way out. */
+function isDefer(node) {
+	return isLifecycleDecl(node) && node.hook === "defer";
+}
+function deferred(args) {
+	const engine = {
+		...args.engine,
+		signal: void 0
+	};
+	return async () => {
+		await runBlock(engine, args.body, args.scope.child());
+	};
+}
+/** Undo in reverse: what opened last is given back first. */
+async function runTeardowns(teardowns) {
+	for (const teardown of [...teardowns].reverse()) await teardown();
+}
+//#endregion
+//#region src/scheduler/run-document.ts
+/**
+* Walk a document: setup once, then for each `matrix` variant bind `env`/`matrix`
+* globals, open resources, run flows (with before/afterEach), close resources.
+*/
+async function runDocument(engine, doc) {
+	const flows = selectFlows(engine, doc.decls.filter(isFlowDecl));
+	const hooks = collectHooks(doc);
+	engine.emitter.emit({
+		kind: "run.started",
+		data: { plan: planOf(flows) }
+	});
+	const start = engine.clock.now();
+	await runSuite({
+		engine,
+		doc,
+		flows,
+		hooks
+	});
+	settleFlaky(engine);
+	const durationMs = engine.clock.now() - start;
+	engine.emitter.emit({
+		kind: "run.finished",
+		data: {
+			...engine.result,
+			durationMs
+		}
+	});
+}
+/**
+* Suite hooks run once, on either side of every variant, so they get a root of
+* their own: the document's bindings without any one variant's `matrix`.
+*
+* An `exit` in `setup` ends the run where it stands, so the variants never
+* start, and `teardown` still runs, because what `setup` opened is still open.
+* Both sides absorb their own, so the code reaches the host and `run.finished`
+* is still emitted above.
+*/
+async function runSuite(args) {
+	const { engine, hooks } = args;
+	const suite = rootScope({
+		engine,
+		doc: args.doc,
+		variant: {}
+	});
+	await absorbExit(engine, async () => {
+		await runHooks({
+			engine,
+			hooks: hooks.setup,
+			scope: suite
+		});
+		await runVariants(args);
+	});
+	await absorbExit(engine, () => runHooks({
+		engine,
+		hooks: hooks.teardown,
+		scope: suite
+	}));
+}
+/** Every `matrix` variant is a full pass over the flows, one after the other. */
+async function runVariants(args) {
+	for (const variant of matrixVariants(args.engine, args.doc)) await runVariant({
+		...args,
+		variant
+	});
+}
+async function runVariant(args) {
+	const root = rootScope({
+		engine: args.engine,
+		doc: args.doc,
+		variant: args.variant
+	});
+	const teardowns = await runPrologue({
+		engine: args.engine,
+		doc: args.doc,
+		scope: root
+	});
+	try {
+		await runFlows({
+			...args,
+			root
+		});
+	} finally {
+		await runTeardowns(teardowns);
+	}
+}
+async function runFlows(args) {
+	for (const flow of args.flows) {
+		await runFlowWithHooks({
+			engine: args.engine,
+			flow,
+			hooks: args.hooks,
+			root: args.root
+		});
+		if (args.engine.bail && args.engine.result.failed > 0) break;
+	}
+}
+async function runFlowWithHooks(args) {
+	const scope = args.root.child();
+	const each = {
+		engine: args.engine,
+		scope
+	};
+	await runHooks({
+		...each,
+		hooks: args.hooks.beforeEach
+	});
+	await runFlow(args.engine, args.flow, scope);
+	await runHooks({
+		...each,
+		hooks: args.hooks.afterEach
+	});
+}
+/**
+* The scope a run reads from: the prelude, the plugin namespaces, `env`, the
+* matrix variant and the document's own globals. One per variant, so what one
+* variant binds is never visible to the next.
+*/
+function rootScope(args) {
+	const base = () => createBaseScope({
+		engine: args.engine,
+		variant: args.variant
+	});
+	const root = base();
+	const graph = args.engine.imports;
+	if (graph) bindImports({
+		document: args.doc,
+		uri: args.engine.uri,
+		scope: root,
+		graph,
+		base
+	});
+	bindGlobals(args.doc, root);
+	return root;
+}
+/** The cartesian product of the `matrix { … }` dimensions, else one empty variant. */
+function matrixVariants(engine, doc) {
+	const matrix = doc.decls.find(isMatrixDecl);
+	if (!matrix) return [{}];
+	const scope = createScope();
+	scope.set("env", engine.env);
+	return product(evaluate(matrix.body, scope));
+}
+function product(dims) {
+	let combos = [{}];
+	for (const [key, values] of Object.entries(dims)) {
+		const list = Array.isArray(values) ? values : [values];
+		combos = combos.flatMap((combo) => list.map((value) => ({
+			...combo,
+			[key]: value
+		})));
+	}
+	return combos;
+}
+/** `@only` focuses, `@skip` drops, then the runner's own `--flow` / `--tags` filters. */
+function selectFlows(engine, flows) {
+	const only = flows.filter((flow) => hasAnnotation(flow, "only"));
+	return byTags((only.length > 0 ? only : flows).filter((flow) => !hasAnnotation(flow, "skip")).filter((flow) => matchesTitle(flow.title, engine.filter.flow)), engine.filter.tags);
+}
+function byTags(flows, tags) {
+	if (!tags || tags.length === 0) return flows;
+	return flows.filter((flow) => readTags(flow).some((tag) => tags.includes(tag)));
+}
+function planOf(flows) {
+	return { flows: flows.map((flow) => ({
+		title: flow.title,
+		steps: stepTitles(flow)
+	})) };
+}
+function stepTitles(flow) {
+	return flow.body.stmts.filter(isStepDecl).map((step) => ({ title: step.title }));
+}
+//#endregion
+//#region src/scheduler/script-lifecycle.ts
+/**
+* The program's `setup`, run before its first statement.
+*
+* It reads what the file declared, its functions, rather than what its
+* statements bind, because none of them has run yet. A `setup` that wants a
+* connection opens one.
+*/
+async function runSetup(args) {
+	await runHooks({
+		engine: args.engine,
+		hooks: collectHooks(args.doc).setup,
+		scope: args.scope
+	});
+}
+/**
+* Say how the program ends, before it starts.
+*
+* Registered up front because the ending has to be in place for an interrupt
+* that arrives mid-statement, while what it runs is decided later, as the
+* statements defer things. One entry rather than one per `defer`, so the order
+* is stated here instead of falling out of a stack: `teardown` first, while the
+* connections it needs are still open, then the deferred work in reverse.
+*/
+function registerEnding(args) {
+	const ending = { deferred: [] };
+	const teardown = collectHooks(args.doc).teardown;
+	args.engine.cleanup.add(async () => {
+		await runHooks({
+			engine: args.engine,
+			hooks: teardown,
+			scope: args.scope
+		});
+		await runTeardowns(ending.deferred);
+	});
+	return ending;
+}
+//#endregion
+//#region src/scheduler/run-script.ts
+/**
+* Run a document as a program: its top-level statements, in order, top to
+* bottom, because the file itself is the entry point. Declarations (`flow`,
+* `fn`, `type`, …) are definitions and run only when something calls them.
+*
+* `setup`, `teardown` and `defer` are the program's own lifetime: `setup` runs
+* before the first statement and the rest are handed to the host to run on the
+* way out, because a program that serves outlives its last line.
+*/
+async function runScript(engine, doc) {
+	const base = () => createBaseScope({ engine });
+	const root = base();
+	const graph = engine.imports;
+	if (graph) bindImports({
+		document: doc,
+		uri: engine.uri,
+		scope: root,
+		graph,
+		base
+	});
+	bindFunctions(doc, root);
+	engine.emitter.emit({
+		kind: "run.started",
+		data: { plan: { flows: [] } }
+	});
+	const start = engine.clock.now();
+	await absorbExit(engine, () => runProgram(engine, doc, root));
+	const durationMs = engine.clock.now() - start;
+	engine.emitter.emit({
+		kind: "run.finished",
+		data: {
+			...engine.result,
+			durationMs
+		}
+	});
+}
+/**
+* The program's lifetime: its `setup`, the ending it declared, then its
+* statements, all inside the one absorb, because `setup` is as much the program
+* as its first line. Outside it, an `exit` in `setup` would escape past
+* `run.finished` and leave the stream open.
+*
+* The ending is registered whatever happens to `setup`: a setup that exited or
+* failed still opened what it opened, and `teardown` is how it gives it back.
+*/
+async function runProgram(engine, doc, scope) {
+	const ending = registerEnding({
+		engine,
+		doc,
+		scope
+	});
+	await runSetup({
+		engine,
+		doc,
+		scope
+	});
+	await runPrologue({
+		engine,
+		doc,
+		scope,
+		into: ending.deferred
+	});
+}
+//#endregion
+//#region src/check/check-options.ts
+/**
+* Check the keys of an options map against the action's own schema.
+*
+* The runtime refuses an unknown key too, but only when the flow reaches that
+* line. Both read the same list and say the same sentence, so the editor can
+* mark the word before anything runs.
+*/
+function checkOptions(args) {
+	return unknownOptions({
+		opts: args.opts,
+		params: args.params,
+		uri: args.ctx.uri
+	});
+}
+//#endregion
+//#region src/check/check-calls.ts
+/** `http.get "…"` written as a statement. */
+function checkAction(call, ctx) {
+	return checkTarget({
+		node: call,
+		target: call.target,
+		opts: call.opts,
+		ctx
+	});
+}
+/**
+* `let auth = http.post url { … }`. Only the unmistakable call is checked: with
+* no arguments the path could be a field of a variable this pass cannot see, and
+* a false "unknown action" is worse than a missed one.
+*/
+function checkLet(stmt, ctx) {
+	if (stmt.args.length === 0 && !stmt.opts) return [];
+	const target = actionTarget(stmt.value);
+	if (target === void 0) return [problem$2(stmt, ctx, CODES.VN2003_UNKNOWN_ACTION, "This is not an action to call.")];
+	return checkTarget({
+		node: stmt,
+		target,
+		opts: stmt.opts,
+		ctx
+	});
+}
+/** `capture` is folded into `let`; say so where it is written. */
+function checkCapture(stmt, ctx) {
+	return problem$2(stmt, ctx, CODES.VN5001_REMOVED_KEYWORD, "`capture` was removed — use `let` for a value that changes, `const` for one that does not.");
+}
+/**
+* A namespace is only usable when this file brought it in with `use` (or it is
+* a resource). Loading the whole stdlib must not make `use` optional.
+*/
+function checkTarget(args) {
+	const { node, target, ctx } = args;
+	if (PRELUDE.has(target)) return [];
+	const written = splitTarget(target).namespace;
+	if (ctx.bound.has(written)) return [];
+	if (!ctx.imported.has(written)) return [missingImport(args, written)];
+	const resolved = ctx.registry.action(resolveTarget(target, ctx.aliases));
+	if (!resolved) return [problem$2(node, ctx, CODES.VN2003_UNKNOWN_ACTION, `Unknown action "${target}".`)];
+	return checkOptions({
+		opts: args.opts,
+		params: resolved.action.params,
+		ctx
+	});
+}
+function missingImport(args, namespace) {
+	if (!args.ctx.registry.hasNamespace(namespace)) {
+		const title = `Unknown action "${args.target}" — no loaded plugin provides it.`;
+		return problem$2(args.node, args.ctx, CODES.VN2003_UNKNOWN_ACTION, title);
+	}
+	const title = `"${namespace}" is not imported in this file — add a \`use\` for its package.`;
+	return problem$2(args.node, args.ctx, CODES.VN2007_NAMESPACE_NOT_IMPORTED, title);
+}
+function problem$2(node, ctx, spec, title) {
+	return buildProblem({
+		spec,
+		span: nodeSpan(node, ctx.uri),
+		title
+	});
+}
+//#endregion
+//#region src/check/check-deco-body.ts
+/**
+* Check a node written inside a `deco` body, which is not the program and so is
+* not resolved against the registry: `target.wrap(f)` is a verb on the handle
+* the body was handed, and expansion settles what the rest means. The one
+* refusal this pass can make is a verb from a plugin, which cannot work in a
+* `deco` because a decorator runs before the program exists.
+*
+* @returns The node's problems, or `undefined` when the node is not inside a
+* `deco`, which tells the caller to apply the ordinary document checks instead.
+*/
+function checkInsideDeco(node, ctx) {
+	const deco = enclosingDeco(node);
+	if (!deco) return void 0;
+	const target = calledTarget(node);
+	const refused = target === void 0 ? void 0 : pluginVerb({
+		deco,
+		target,
+		ctx
+	});
+	return refused ? [problem$1(node, ctx, refused)] : [];
+}
+/** The `deco` this node is written inside, if any. */
+function enclosingDeco(node) {
+	for (let at = node; at; at = at.$container) if (isDecoDecl(at)) return at;
+}
+/** The dotted name this statement calls, if calling is what it does. */
+function calledTarget(node) {
+	if (isActionCall(node)) return node.target;
+	if (!isLetStmt(node) || node.args.length === 0 && !node.opts) return void 0;
+	return actionTarget(node.value);
+}
+/**
+* Why this call cannot be made from here, if it cannot. Only a head the file can
+* already account for is refused: an imported namespace, a resource, a namespace
+* some loaded plugin owns. Anything else is a name only expansion resolves, and
+* guessing at it would put an error on every well-written decorator.
+*/
+function pluginVerb(args) {
+	const { namespace } = splitTarget(args.target);
+	if (PRELUDE.has(args.target) || paramNames(args.deco).has(namespace)) return void 0;
+	if (!reachesTheWorld(namespace, args.ctx)) return void 0;
+	return decoCannotCall(args.target);
+}
+function reachesTheWorld(namespace, ctx) {
+	return ctx.imported.has(namespace) || ctx.bound.has(namespace) || ctx.registry.hasNamespace(namespace);
+}
+function paramNames(deco) {
+	return new Set((deco.params?.params ?? []).map((param) => param.name));
+}
+function problem$1(node, ctx, title) {
+	return buildProblem({
+		spec: CODES.VN2016_DECO_IMPURE,
+		span: nodeSpan(node, ctx.uri),
+		title
+	});
+}
+//#endregion
+//#region src/check/check-env.ts
+/** `env.NAME` as it appears inside a `${…}` placeholder. */
+const ENV_READ = /\benv\.([A-Za-z_]\w*)/g;
+/** Always present: the runner sets it to the `--env` that was selected. */
+const BUILT_IN = /* @__PURE__ */ new Set(["name"]);
+/**
+* Match every `env.*` read against what `venn.toml` declares, so a typo is an
+* error rather than an empty string and a puzzling 404.
+*
+* Nothing is reported when the manifest could not be read: a wrong error about a
+* variable that does exist is worse than no error at all.
+*/
+function checkEnv(node, ctx) {
+	if (!isMember(node) || isMember(node.$container)) return [];
+	const path = actionTarget(node);
+	const name = path?.startsWith("env.") ? path.slice(4) : void 0;
+	if (name === void 0 || name.includes(".")) return [];
+	const span = nodeSpan(node, ctx.uri);
+	if (!ctx.imported.has("env")) return [notImported(span)];
+	if (!ctx.env || declared(name, ctx.env)) return [];
+	return [envProblem(name, span, ctx)];
+}
+/**
+* Configuration is brought in like anything else. Reading `env.*` without saying
+* where it comes from is the same hole `use` closes for actions and matchers:
+* the reader should not have to know which names are magic.
+*/
+function notImported(span) {
+	return buildProblem({
+		spec: CODES.VN2007_NAMESPACE_NOT_IMPORTED,
+		span,
+		title: "\"env\" is not imported in this file — add `use \"venn/env\"`."
+	});
+}
+/** The same checks for text the parser never turned into nodes: `"${env.X}"`. */
+function envProblemsIn(source, span, ctx) {
+	const names = [...source.matchAll(ENV_READ)].map((match) => match[1] ?? "").filter(Boolean);
+	if (names.length === 0) return [];
+	if (!ctx.imported.has("env")) return [notImported(span)];
+	const env = ctx.env;
+	if (!env) return [];
+	return names.filter((name) => !declared(name, env)).map((name) => envProblem(name, span, ctx));
+}
+function declared(name, env) {
+	return env.has(name) || BUILT_IN.has(name);
+}
+/** The undeclared-variable problem, with the nearest declared name as a hint. */
+function envProblem(name, span, ctx) {
+	const hint = nearest(name, [...ctx.env ?? []]);
+	const title = hint ? `"env.${name}" is not declared in venn.toml — did you mean "env.${hint}"?` : `"env.${name}" is not declared in venn.toml.`;
+	return buildProblem({
+		spec: CODES.VN2006_UNKNOWN_ENV,
+		span,
+		title
+	});
+}
+function nearest(name, known) {
+	const best = known.map((candidate) => ({
+		candidate,
+		distance: distance(name, candidate)
+	})).sort((left, right) => left.distance - right.distance)[0];
+	const tolerance = Math.max(2, Math.floor(name.length / 3));
+	return best && best.distance <= tolerance ? best.candidate : void 0;
+}
+/** Levenshtein edit distance, kept to two rows because only the score is needed. */
+function distance(left, right) {
+	let previous = Array.from({ length: right.length + 1 }, (_value, index) => index);
+	for (let i = 1; i <= left.length; i += 1) {
+		const current = [i];
+		for (let j = 1; j <= right.length; j += 1) {
+			const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+			current[j] = Math.min((current[j - 1] ?? 0) + 1, (previous[j] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+		}
+		previous = current;
+	}
+	return previous[right.length] ?? 0;
+}
+//#endregion
+//#region src/check/check-fragment-call.ts
+/**
+* Refuse a fragment called as though it were a function.
+*
+* The two look alike where they are written but are different kinds of thing: a
+* `fn` gives back a value, a `fragment` gives back steps, and steps are recorded
+* in the report, can fail and belong to a flow. So a fragment is invoked with
+* `run`. `run entrar(…)` never reaches here: its target is a name, not an
+* expression.
+*
+* @param call The call expression to inspect.
+* @param ctx The document's resolved check context.
+* @returns A `VN3013` problem, or `undefined` when the callee is not a fragment.
+*/
+function checkFragmentCall(call, ctx) {
+	const callee = call.callee;
+	if (!isRef(callee) || !ctx.fragments.has(callee.name)) return void 0;
+	return buildProblem({
+		spec: CODES.VN3013_NOT_CALLABLE,
+		span: nodeSpan(call, ctx.uri),
+		title: `${callee.name} is a fragment, so it cannot be called for a value.`,
+		note: `Invoke it with \`run ${callee.name}(…)\`, which records its steps in the report.`
+	});
+}
+//#endregion
+//#region src/check/check-interpolation.ts
+/**
+* Check each `${…}` placeholder in a string literal and point at the placeholder
+* itself, not at the whole string. A slot that does not parse would otherwise
+* evaluate to an empty string, so a typo inside a URL fails as a puzzling 404.
+*/
+function checkInterpolation(node, ctx) {
+	const cst = node.$cstNode;
+	if (!isStringLit(node) || !cst) return [];
+	return scanInterpolations(cst.text).flatMap((slot) => inSlot(slot, spanOf(slot, {
+		cst,
+		uri: ctx.uri
+	}), ctx));
+}
+/** A URL is where `env` reads live, so they are checked here as well as in the AST. */
+function inSlot(slot, span, ctx) {
+	if (!parseExpression(slot.source)) return [unreadable(slot, span)];
+	return envProblemsIn(slot.source, span, ctx);
+}
+function unreadable(slot, span) {
+	return buildProblem({
+		spec: CODES.VN1002_PARSE,
+		span,
+		title: `Cannot read \`\${${slot.source}}\` — that is not an expression.`
+	});
+}
+/** The span of the placeholder itself: line and column follow the string's own start. */
+function spanOf(slot, target) {
+	const start = target.cst.range?.start;
+	return {
+		uri: target.uri,
+		offset: target.cst.offset + slot.start,
+		length: slot.end - slot.start,
+		line: (start?.line ?? 0) + 1,
+		column: (start?.character ?? 0) + 1 + slot.start
+	};
+}
+//#endregion
+//#region src/check/check-uncalled.ts
+/**
+* A plugin verb named but never called.
+*
+* `let id = data.faker.uuid` runs the verb, because the runtime recognises a
+* bare path that names an action. The same words inside an expression evaluate
+* to the verb itself, so a program meaning to read a value gets a function.
+* Rather than guess which was meant, this asks for the parentheses.
+*/
+function checkUncalledAction(node, ctx) {
+	if (!isMember(node) || !readsAsValue(node)) return void 0;
+	const target = actionTarget(node);
+	if (target === void 0) return void 0;
+	if (!ctx.registry.action(resolveTarget(target, ctx.aliases))) return void 0;
+	return buildProblem({
+		spec: CODES.VN2008_UNCALLED_ACTION,
+		span: nodeSpan(node, ctx.uri),
+		title: `\`${target}\` is a verb, not a value — write \`${target}()\` to call it.`
+	});
+}
+/**
+* Where naming the verb produces the verb. Skipped when it is the head of a
+* longer path or the thing being called, and when it stands as a statement's
+* value, which the runtime calls anyway.
+*/
+function readsAsValue(node) {
+	const parent = node.$container;
+	return !isMember(parent) && !isCall(parent) && !isLetStmt(parent);
+}
+//#endregion
+//#region src/check/check-document.ts
+/**
+* Statically resolve every action, matcher and fragment reference in a parsed
+* document. The errors the runner would otherwise raise mid-run are surfaced all
+* at once, each with its source span.
+*
+* @param args Document, registry, known fragments and the declared `env` names.
+* @returns One `Problem` per unresolved reference; empty when the document is clean.
+*/
+function checkDocument(args) {
+	const ctx = {
+		registry: args.registry,
+		fragments: args.fragments,
+		aliases: collectAliases(args.document, args.registry),
+		imported: collectNamespaces(args.document, args.registry),
+		bound: collectBoundNames(args.document),
+		env: args.env ? new Set(args.env) : void 0,
+		uri: args.uri ?? "memory://inline.vn"
+	};
+	const problems = [];
+	for (const node of walkAst(args.document)) {
+		const inDeco = checkInsideDeco(node, ctx);
+		if (inDeco) problems.push(...inDeco);
+		else problems.push(...everyCheck(node, ctx));
+	}
+	return problems;
+}
+function everyCheck(node, ctx) {
+	return [
+		...checkNode(node, ctx),
+		...checkEnv(node, ctx),
+		...checkInterpolation(node, ctx),
+		...one(checkUncalledAction(node, ctx))
+	];
+}
+function checkNode(node, ctx) {
+	if (isActionCall(node)) return checkAction(node, ctx);
+	if (isLetStmt(node)) return checkLet(node, ctx);
+	if (isCaptureStmt(node)) return [checkCapture(node, ctx)];
+	if (isMatcherClause(node)) return one(checkMatcher(node, ctx));
+	if (isRunStmt(node)) return one(checkFragment(node, ctx));
+	if (isCall(node)) return one(checkFragmentCall(node, ctx));
+	return [];
+}
+function one(problem) {
+	return problem ? [problem] : [];
+}
+/**
+* A matcher comes from a plugin like any action, so the file has to bring that
+* plugin in. Resolving against the whole loaded stdlib would make `use` decorative.
+*/
+function checkMatcher(clause, ctx) {
+	const owner = ctx.registry.matcher(clause.name);
+	if (!owner) return problem(clause, ctx, CODES.VN2004_UNKNOWN_MATCHER, `Unknown matcher "${clause.name}".`);
+	if (ctx.imported.has(owner.plugin.namespace)) return void 0;
+	const title = `"${clause.name}" comes from "${owner.plugin.namespace}", which is not imported in this file.`;
+	return problem(clause, ctx, CODES.VN2007_NAMESPACE_NOT_IMPORTED, title);
+}
+function checkFragment(stmt, ctx) {
+	if (ctx.fragments.has(stmt.target)) return void 0;
+	return problem(stmt, ctx, CODES.VN2005_UNKNOWN_FRAGMENT, `Unknown fragment "${stmt.target}".`);
+}
+function problem(node, ctx, spec, title) {
+	return buildProblem({
+		spec,
+		span: nodeSpan(node, ctx.uri),
+		title
+	});
+}
+//#endregion
+//#region src/check/check-imports.ts
+/**
+* Check every name a file imports against what the file it names publishes.
+* Otherwise a misspelt import stays quietly `undefined` until something calls
+* it, and the run blames the call site rather than the import.
+*
+* @param args The importing document, its URI, and the resolved import graph.
+* @returns One `VN2009` problem per name the target does not publish.
+*/
+function checkImports(args) {
+	const problems = [];
+	for (const decl of args.document.imports) {
+		if (!isValueImport(decl)) continue;
+		const target = args.graph.resolve(args.uri, decl.path);
+		const module = args.graph.modules.get(target);
+		if (module) problems.push(...missing({
+			decl,
+			module,
+			uri: args.uri,
+			path: decl.path
+		}));
+	}
+	return problems;
+}
+function missing(args) {
+	const published = exported(args.module);
+	return args.decl.names.filter((name) => !published.has(name)).map((name) => buildProblem({
+		spec: CODES.VN2009_NOT_EXPORTED,
+		span: nodeSpan(args.decl, args.uri),
+		title: `"${args.path}" does not publish ${name}.`,
+		note: hint(name, args.module)
+	}));
+}
+/**
+* Why it is not there: written but kept private, or not written at all. The two
+* are different mistakes with different fixes, and a reader told only "not
+* published" goes looking for a typo they did not make.
+*/
+function hint(name, module) {
+	return module.decls.some((decl) => (isFnDecl(decl) || isFragmentDecl(decl) || isDecoDecl(decl)) && decl.name === name) ? `It is declared there, but not marked \`pub\`.` : `Nothing of that name is declared there.`;
+}
+/** Everything a file marked `pub`: functions, fragments and decorators alike. */
+function exported(document) {
+	const names = /* @__PURE__ */ new Set();
+	for (const decl of document.decls) {
+		if (!isFnDecl(decl) && !isFragmentDecl(decl) && !isDecoDecl(decl)) continue;
+		if (decl.export) names.add(decl.name);
+	}
+	return names;
+}
+//#endregion
+//#region src/decorators/builtin-decorators.ts
+/** Where each of these may sit. Named once, so a wrong target is caught, not ignored. */
+const RUNNABLE = [
+	"FlowDecl",
+	"StepDecl",
+	"GroupDecl"
+];
+/**
+* The decorators the language ships with, written the same way anyone else's
+* are. They go through the same expansion as a plugin decorator and leave
+* metadata on the node, because `@retry(2)` says something the grammar has no
+* other word for. Keeping them here rather than as special cases in the
+* scheduler is what makes the built-ins a stdlib instead of reserved words.
+*/
+const builtinDecorators = [
+	flag("skip", "Do not run this."),
+	flag("only", "Run this and nothing beside it."),
+	flag("serial", "Never run this alongside another flow."),
+	{
+		name: "tags",
+		doc: "Label this for `--tags`.",
+		targets: [...RUNNABLE],
+		expand: (ctx) => ctx.meta("tags", ctx.args.map(String).filter((tag) => tag !== ""))
+	},
+	{
+		name: "timeout",
+		doc: "Give up after this long.",
+		targets: [...RUNNABLE],
+		expand: (ctx) => ctx.meta("timeout", durationMs(ctx.args[0]))
+	},
+	{
+		name: "retry",
+		doc: "Run again on failure, up to n times.",
+		targets: [...RUNNABLE],
+		expand: (ctx) => ctx.meta("retry", retryOf(ctx))
+	},
+	{
+		name: "lock",
+		doc: "Hold this name for the duration; nothing else holding it runs.",
+		targets: [...RUNNABLE],
+		expand: (ctx) => ctx.meta("lock", ctx.args[0] === void 0 ? void 0 : String(ctx.args[0]))
+	},
+	{
+		name: "flaky",
+		doc: "Tolerate failures up to this ratio.",
+		targets: [...RUNNABLE],
+		expand: (ctx) => ctx.meta("flaky", ratioOf(ctx.args[0]))
+	}
+];
+/** A decorator with nothing to say beyond having been written. */
+function flag(name, doc) {
+	return {
+		name,
+		doc,
+		targets: [...RUNNABLE],
+		expand: (ctx) => ctx.meta(name, true)
+	};
+}
+function retryOf(ctx) {
+	const opts = asRecord(ctx.args[1]);
+	return {
+		attempts: Math.max(0, Math.floor(Number(ctx.args[0]) || 0)),
+		backoffMs: durationMs(opts.backoff) ?? 0,
+		factor: Number(opts.factor ?? 1) || 1
+	};
+}
+/** A bare `@flaky` tolerates everything; a number is the ratio it tolerates. */
+function ratioOf(value) {
+	if (value === void 0) return 1;
+	return typeof value === "number" ? value : 0;
+}
+function durationMs(value) {
+	if (typeof value === "number") return value;
+	const duration = value;
+	return duration?.kind === "duration" ? duration.ms : void 0;
+}
+function asRecord(value) {
+	return typeof value === "object" && value !== null ? value : {};
+}
+//#endregion
+//#region src/decorators/create-decorator-source.ts
+/**
+* Every decorator this run understands: the ones the language ships with, plus
+* whatever the loaded plugins contribute.
+*
+* A plugin's decorator overrides a built-in of the same name on purpose. The
+* built-ins are a stdlib, not a reserved word list, and a project that wants its
+* own `@retry` is entitled to it.
+*
+* @param plugins The plugins loaded for this run, in load order.
+* @returns A source that looks a decorator up by name.
+*/
+function createDecoratorSource(plugins) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const decorator of builtinDecorators) byName.set(decorator.name, decorator);
+	for (const plugin of plugins) for (const decorator of plugin.decorators ?? []) byName.set(decorator.name, decorator);
+	return { get: (name) => byName.get(name) };
+}
+//#endregion
+//#region src/emit/create-emitter.ts
+/** Build the sole emitter: it owns `seq` and stamps `ts` from the runner's clock. */
+function createEmitter(args) {
+	let seq = 0;
+	return { emit: ({ kind, data, node }) => {
+		seq += 1;
+		const ts = new Date(args.clock.now()).toISOString();
+		args.sink.emit({
+			seq,
+			ts,
+			run: args.run,
+			kind,
+			node,
+			data
+		});
+	} };
+}
+//#endregion
+//#region src/emit/run-id.ts
+/**
+* Mint a run id from the host clock and random source, so a seeded run is
+* reproducible. Real ULID minting comes later.
+*/
+function newRunId(args) {
+	const rand = Math.floor(args.random.next() * 1e9).toString(36);
+	return `run-${args.clock.now().toString(36)}-${rand}`;
+}
+//#endregion
+//#region src/eventsink/event-sink.port.ts
+/**
+* The port every run event is written to. Bound at startup by whoever assembles
+* the host: the CLI binds NDJSON on stdout, tests bind the memory double.
+*/
+const EventSinkPort = {
+	id: "venn.port.event-sink",
+	version: 1,
+	requires: [],
+	methods: ["emit"]
+};
+//#endregion
+//#region src/eventsink/memory-sink.ts
+/**
+* In-memory sink (the test double): keeps every envelope for assertions.
+*
+* @returns A sink whose `envelopes` array grows in emission order.
+*/
+function createMemorySink() {
+	const envelopes = [];
+	return {
+		envelopes,
+		emit: (envelope) => {
+			envelopes.push(envelope);
+		}
+	};
+}
+//#endregion
+//#region src/eventsink/ndjson-sink.ts
+/**
+* NDJSON sink: one JSON envelope per line. The `write` sink is injected (the CLI
+* passes stdout) so this file stays neutral and needs no `node:*`.
+*
+* @param args.write Receives each line, newline included.
+* @returns A sink that serialises every envelope it is given.
+*/
+function createNdjsonSink(args) {
+	return { emit: (envelope) => args.write(`${JSON.stringify(envelope)}\n`) };
+}
+//#endregion
+//#region src/ports/create-port-resolver.ts
+/**
+* Resolve ports from a set of bindings, running capability and shape negotiation
+* at the moment of resolution.
+*
+* @param args.bindings Every port the host chose to bind, with its implementation.
+* @param args.caps What this host offers, checked against each port's `requires`.
+* @returns A resolver whose `resolve` throws `VN7002` when the port is unbound,
+* and whatever `bindPort` raises when the capability or shape check fails.
+*/
+function createPortResolver(args) {
+	const byId = new Map(args.bindings.map((binding) => [binding.port.id, binding]));
+	return { resolve: (port) => resolveOne({
+		port,
+		binding: byId.get(port.id),
+		caps: args.caps
+	}) };
+}
+function resolveOne(args) {
+	if (!args.binding) throw unbound(args.port.id);
+	return bindPort({
+		port: args.port,
+		impl: args.binding.impl,
+		caps: args.caps
+	});
+}
+function unbound(id) {
+	return new VennError({
+		code: "VN7002",
+		message: `No implementation bound for port "${id}".`,
+		detail: { port: id }
+	});
+}
+//#endregion
+//#region src/registry/build-registry.ts
+/**
+* Ingest plugins after negotiating each plugin's capabilities against the host.
+*
+* @param args.plugins The plugins to index, in load order; later ones win a clash.
+* @param args.caps The capabilities this host offers.
+* @returns A registry resolving actions, matchers and namespaces.
+* @throws VennError `VN2010` when a plugin requires a capability the host lacks.
+*/
+function buildRegistry(args) {
+	for (const plugin of args.plugins) assertPluginCaps({
+		plugin,
+		caps: args.caps
+	});
+	return indexPlugins(args.plugins);
+}
+function assertPluginCaps(args) {
+	const missing = missingCapabilities({
+		requires: args.plugin.requires ?? [],
+		caps: args.caps
+	});
+	if (missing.length === 0) return;
+	const list = missing.map((cap) => `"${cap}"`).join(", ");
+	throw new VennError({
+		code: "VN2010",
+		message: `Plugin "${args.plugin.name}" requires capability ${list}, absent from this host.`,
+		detail: {
+			plugin: args.plugin.name,
+			missing
+		}
+	});
+}
+function indexPlugins(plugins) {
+	const actions = /* @__PURE__ */ new Map();
+	const matchers = /* @__PURE__ */ new Map();
+	const namespaces = /* @__PURE__ */ new Set();
+	const packages = /* @__PURE__ */ new Map();
+	for (const plugin of plugins) addPlugin({
+		plugin,
+		actions,
+		matchers,
+		namespaces,
+		packages
+	});
+	return {
+		action: ({ namespace, name }) => actions.get(`${namespace}.${name}`),
+		matcher: (name) => matchers.get(name),
+		hasNamespace: (namespace) => namespaces.has(namespace),
+		namespaceOf: (pkg) => packages.get(pkg),
+		actions: () => listActions(actions)
+	};
+}
+function listActions(actions) {
+	return [...actions].map(([key, resolved]) => ({
+		namespace: key.slice(0, key.indexOf(".")),
+		name: key.slice(key.indexOf(".") + 1),
+		action: resolved.action
+	}));
+}
+function addPlugin(args) {
+	const { plugin, actions, matchers, namespaces, packages } = args;
+	namespaces.add(plugin.namespace);
+	packages.set(plugin.name, plugin.namespace);
+	for (const action of plugin.actions ?? []) actions.set(`${plugin.namespace}.${action.name}`, {
+		plugin,
+		action
+	});
+	for (const matcher of plugin.matchers ?? []) matchers.set(matcher.name, {
+		plugin,
+		matcher
+	});
+}
+//#endregion
+//#region src/context/action-context.ts
+/** Build the context an action's `run` receives from the host and port resolver. */
+function createActionContext(args) {
+	return {
+		port: (port) => args.ports.resolve(port),
+		secrets: args.host.secrets,
+		config: args.config ?? {},
+		log: (message) => args.host.log.log({
+			level: "info",
+			message
+		}),
+		redact: () => {},
+		invoke: (fn, values) => invoke(fn, values)
+	};
+}
+//#endregion
+//#region src/run/create-runner.ts
+/**
+* Build a runner: negotiate plugins and wire ports once, then reuse them for
+* every run.
+*
+* @param args The host, the plugins, the event sink and the per-run options.
+* @returns A runner exposing test mode (`run`) and script mode (`script`).
+* @throws VennError `VN2010` when a plugin requires a capability the host lacks.
+*/
+function createRunner(args) {
+	const registry = buildRegistry({
+		plugins: args.plugins,
+		caps: args.host.caps
+	});
+	const resolver = createPortResolver({
+		bindings: args.ports ?? [],
+		caps: args.host.caps
+	});
+	const decorators = createDecoratorSource(args.plugins);
+	const drive = (walk) => (document) => {
+		const expansion = expand({
+			document,
+			decorators,
+			uri: args.uri,
+			imported: args.moduleDecos
+		});
+		return runOnce({
+			args,
+			registry,
+			resolver,
+			document
+		}, walk, expansion.problems);
+	};
+	return {
+		run: drive(runDocument),
+		script: drive(runScript)
+	};
+}
+async function runOnce(input, walk, problems) {
+	const run = newRunId({
+		clock: input.args.host.clock,
+		random: input.args.host.random
+	});
+	const engine = buildEngine(input, run);
+	await absorbExit(engine, () => walk(engine, input.document));
+	return {
+		run,
+		problems,
+		passed: engine.result.passed,
+		failed: engine.result.failed,
+		exitCode: engine.exit
+	};
+}
+function buildEngine(input, run) {
+	const { args, registry } = input;
+	return {
+		registry,
+		emitter: createEmitter({
+			sink: args.sink,
+			run,
+			clock: args.host.clock
+		}),
+		clock: args.host.clock,
+		lock: args.host.lock,
+		uri: args.uri ?? "memory://inline.vn",
+		result: {
+			passed: 0,
+			failed: 0
+		},
+		flaky: /* @__PURE__ */ new Map(),
+		filter: args.filter ?? {},
+		bail: args.bail,
+		cleanup: args.cleanup ?? createCleanupList(),
+		...documentParts(input)
+	};
+}
+/** Everything derived from the document being run: config, fragments, aliases. */
+function documentParts(input) {
+	const { args, registry, resolver, document } = input;
+	const env = args.env ?? {};
+	const config = collectConfig(document, env);
+	return {
+		ctx: createActionContext({
+			host: args.host,
+			ports: resolver,
+			config
+		}),
+		fragments: mergeFragments(collectFragments(document), args.moduleFragments),
+		imports: args.modules,
+		aliases: collectAliases(document, registry),
+		env
+	};
+}
+/** Local fragments take precedence over imported ones of the same name. */
+function mergeFragments(local, imported) {
+	if (!imported) return local;
+	const merged = new Map(imported);
+	for (const [name, fragment] of local) merged.set(name, fragment);
+	return merged;
+}
+//#endregion
+//#region src/run/resolve-imports.ts
+/**
+* Walk the import graph from one document, parsing every `.vn` file it reaches
+* and loading every package it names. A file already seen is skipped, so a cycle
+* ends rather than loops. A file that cannot be read is skipped in silence:
+* whoever tried to read it reports the failure.
+*
+* @param args The entry document, its URI, the source reader and the optional
+* package loader.
+* @returns The exported fragments and decos, the packages, the loaded npm
+* modules and every parsed document, keyed by resolved URI.
+*/
+async function resolveImports(args) {
+	const found = {
+		fragments: /* @__PURE__ */ new Map(),
+		decos: /* @__PURE__ */ new Map()
+	};
+	const packages = /* @__PURE__ */ new Set();
+	const modules = /* @__PURE__ */ new Map();
+	const npm = /* @__PURE__ */ new Map();
+	collectUses(args.document, packages);
+	await loadInto({
+		document: args.document,
+		uri: args.uri,
+		io: args.io,
+		npmLoader: args.npm,
+		found,
+		packages,
+		modules,
+		npm,
+		seen: /* @__PURE__ */ new Set([args.uri])
+	});
+	return {
+		...found,
+		packages,
+		modules,
+		npm
+	};
+}
+/**
+* Add the packages a file declares with `use` to `into`. Collected across the
+* whole graph: a fragment imported from elsewhere calls the verbs *its* file
+* asked for.
+*
+* @param document The file to read `use` declarations from.
+* @param into The accumulating set of package specifiers, mutated in place.
+*/
+function collectUses(document, into) {
+	for (const decl of document.imports) if (isUseDecl(decl)) into.add(decl.pkg);
+}
+async function loadInto(state) {
+	for (const decl of state.document.imports) {
+		if (!isValueImport(decl)) continue;
+		if (isPackageSpecifier(decl.path)) await loadPackage(state, decl.path);
+		else await loadModule(state, decl.path);
+	}
+}
+/**
+* A package that was installed, loaded once however many files name it.
+*
+* A host with no loader has no packages, which is the state of every run in a
+* Web Worker. The import is left unbound and the name reports itself as unknown,
+* rather than the load failing somewhere nobody can see.
+*/
+async function loadPackage(state, spec) {
+	if (state.npm.has(spec) || !state.npmLoader) return;
+	const found = await state.npmLoader.load(spec).catch(() => void 0);
+	if (found) state.npm.set(spec, found);
+}
+async function loadModule(state, spec) {
+	const target = state.io.resolve(state.uri, spec);
+	if (state.seen.has(target)) return;
+	state.seen.add(target);
+	const source = await state.io.read(target).catch(() => void 0);
+	if (source === void 0) return;
+	const { ast } = parse(source, { uri: target });
+	state.modules.set(target, ast);
+	collectExports({
+		document: ast,
+		uri: target,
+		found: state.found
+	});
+	collectUses(ast, state.packages);
+	await loadInto({
+		...state,
+		document: ast,
+		uri: target
+	});
+}
+/** Everything a file marked `pub`. A `deco` keeps its file: its faults are its own. */
+function collectExports(args) {
+	for (const decl of args.document.decls) {
+		if (isFragmentDecl(decl) && decl.export) args.found.fragments.set(decl.name, decl);
+		if (isDecoDecl(decl) && decl.export) args.found.decos.set(decl.name, {
+			decl,
+			uri: args.uri
+		});
+	}
+}
+//#endregion
+//#region src/types/create-type-catalog.ts
+/**
+* Turn what the loaded plugins publish into what the checker can ask.
+*
+* This is the seam the core deliberately does not cross: `@venn-lang/core` knows
+* nothing about plugins and gets told. Names are qualified here, once: a plugin
+* says `Request` and a flow writes `http.Request`.
+*
+* @param plugins The plugins loaded for this run.
+* @returns A catalog answering a type name or an action's signature.
+*/
+function createTypeCatalog(plugins) {
+	const published = {
+		types: /* @__PURE__ */ new Map(),
+		signatures: /* @__PURE__ */ new Map()
+	};
+	for (const plugin of plugins) collect(plugin, published);
+	const reader = createReader(published);
+	return {
+		typeOf: (name) => reader.read(published.types, name),
+		signatureOf: (target) => asFn(reader.read(published.signatures, target))
+	};
+}
+function collect(plugin, into) {
+	for (const [name, spec] of Object.entries(plugin.typeDefs ?? {})) into.types.set(`${plugin.namespace}.${name}`, spec);
+	for (const action of plugin.actions ?? []) {
+		const key = `${plugin.namespace}.${action.name}`;
+		if (action.signature) into.signatures.set(key, action.signature);
+	}
+}
+/**
+* Read a published spec once and keep the result.
+*
+* The same `http.Request` has to be the same object every time it is asked for:
+* inference writes into what it is handed, and two copies would drift apart in
+* the middle of a file. `open` guards a type that refers to itself, so the
+* second visit answers "unknown" rather than recurring forever.
+*/
+function createReader(published) {
+	const cache = /* @__PURE__ */ new Map();
+	const open = /* @__PURE__ */ new Set();
+	const read = (from, name) => {
+		const cached = cache.get(name);
+		if (cached) return cached;
+		const spec = from.get(name);
+		if (!spec || open.has(name)) return void 0;
+		open.add(name);
+		const type = specToType(spec, (ref) => read(published.types, ref));
+		open.delete(name);
+		cache.set(name, type);
+		return type;
+	};
+	return { read };
+}
+function asFn(type) {
+	if (!type) return void 0;
+	const pruned = prune(type);
+	return pruned.kind === "fn" ? pruned : void 0;
+}
+//#endregion
+export { EventSinkPort, buildRegistry, builtinDecorators, checkDocument, checkFragmentCall, checkImports, collectFragments, collectUses, createCleanupList, createDecoratorSource, createEmitter, createMemorySink, createNdjsonSink, createPortResolver, createRunner, createScope, createTypeCatalog, matchesTitle, newRunId, resolveImports };
+
+//# sourceMappingURL=index.js.map